From 2cae76a306e55eff262ecff1f6cc48817e060c57 Mon Sep 17 00:00:00 2001 From: vteague Date: Wed, 4 Sep 2024 15:36:37 +1000 Subject: [PATCH] Update README with deployment instructions and security notes. --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 658c6ff5..49ccfdd7 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # raire-service Java implementation of RAIRE -This is a work in progress. If you're interested in running it with colorado-rla, please try -[the prototype](https://github.com/DemocracyDevelopers/raire-service/tree/prototype) of this service and our [prototype updates to colorado-rla](https://github.com/DemocracyDevelopers/colorado-rla/tree/prototype). They are designed to work together. +This is designed to run as the IRV support module of +[colorado-rla](https://github.com/DemocracyDevelopers/colorado-rla). Colorado-rla runs the audit, +and calls out to raire-service for assertion generation, assertion download, and some reports. -If you are interested in running and testing this raire-service as a standalone assertion-generation -service, follow the instructions below. +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. @@ -52,3 +53,47 @@ This will run the application on port 8080. (If you want to change the port, re The tests in src/test/java require Docker. You will need to [Install Docker](https://docs.docker.com/get-docker/) if you haven't got it already. On Linux platforms, you need to [add yourself to the docker group](https://docs.docker.com/engine/install/linux-postinstall/). 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](https://docs.docker.com/engine/security/rootless/). + +## Deployment with colorado-rla +To run an audit, clone and deploy colorado-rla by following the [developer instructions.](https://github.com/DemocracyDevelopers/colorado-rla/blob/main/docs/25_developer.md#install-and-setup). + +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 +```angular2html +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]( +https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/securing_networks/creating-and-managing-tls-keys-and-certificates_securing-networks#using-a-private-ca-to-issue-certificates-for-csrs-with-gnutls_creating-and-managing-tls-keys-and-certificates) +for an example using Openssl on Linux. + +There are also various tools for deploying reverse proxies. +[Nginx on Linux](https://www.digitalocean.com/community/tutorials/how-to-configure-nginx-as-a-reverse-proxy-on-ubuntu-22-04) +is one popular option, but there are many others.