raire-service

Java implementation of RAIRE

This is designed to run as the IRV support module of
colorado-rla. Colorado-rla runs the audit, and calls out to raire-service for assertion generation, assertion download, and some reports.

The instructions below describe how to compile and run the raire-service, which you can test as a standalone service. The last section describes secure deployment as part of an audit with colorado-rla.

PreReq: Java, Maven. This requires Java at least version 21.

The Springboot tests in RAIREMicroserviceAPITests.java additionally require libtcnative.

Compiling

This project depends on another project, raire-java, as a library. Therefore, you first have to compile raire-java.

git clone https://github.com/DemocracyDevelopers/raire-java.git
cd raire-java
mvn install
cd ..

This will make raire-java available to other maven projects on your computer.

Now you can compile raire-service:

git clone https://github.com/DemocracyDevelopers/raire-service.git
cd raire-service
mvn compile
cd ..

Running the raire service

Run instructions:

• Option 1:
  • Go to au.org.democracydevelopers.raise.RaireJavaApplication class and run the main method from an IDE
  • If there are compile issues you might need to:
    1. Right-click on raire-java/pom.xml (the sub-project pom.xml) and add it as a Maven project,
    2. Right-click on raire-service/pom.xml (the parent project pom.xml) and Maven -> reload,
    3. Then recompile.
• Option 2:
  • Go to the home directory of the service and run following command ./mvnw spring-boot:run

This will run the application on port 8080. (If you want to change the port, reset server in application.yml.)

Running the tests

The tests in src/test/java require Docker. You will need to Install Docker if you haven't got it already.

On Linux platforms, you need to add yourself to the docker group. This effectively grants root-level privileges to the user. If that's not what you want (and it's probably not) you can run docker without root privileges.

Deployment with colorado-rla

To run an audit, clone and deploy colorado-rla by following the developer instructions..

colorado-rla's raire_url property tells it where to find raire. The default (http://localhost:8080) is set up so that both can run on the same machine without any change to the addresses or ports.

If you are running raire-service somewhere different, set

raire_url = [your new location]

in src/test/resources/test.properties, src/main/resources/us/freeandfair/corla/default.properties, src/main/resources/us/freeandfair/corla/default.properties and src/main/resources/us/freeandfair/corla/default.properties depending on which one of these you are using.

Deployment security

In production, authentication between raire-service and colorado-rla MUST be mutual. Raire-service MUST NOT accept connections from any process other than colorado-rla, and colorado-rla MUST verify that it is communicating with the correct raire-service.

If both services are running on the same host, enforcement is operating-system specific and may require some changes to raire-service's endpoint authentication.

If raire-service is running on a separate machine, the easiest method is probably to put raire-service behind a TLS reverse proxy and then

• pin raire-service's TLS certificate in colorado-rla (or get it signed by a Certificate Authority),
• generate a TLS client certificate for colorado-rla,
• configure colorado-rla's http client to send the client certificate when communicating with raire-service,
• configure the raire-service's TLS proxy to accept colorado-rla's client certificate.

This could alternatively be done programmatically in Java.

Whether the mutual authentication is done via a TLS proxy, or directly in Java, there is no particular need to get the certificates signed by an external CA, because neither side of the connection needs to be authenticated by any third parties. A properly-pinned self-signed certificate, or a certificate generated by a private CA, is sufficient.

There are many different tools available for creating and managing TLS certificates. See RedHat's documentation for an example using Openssl on Linux.

There are also various tools for deploying reverse proxies. Nginx on Linux is one popular option, but there are many others.