|
| 1 | +# rotatekey Service |
| 2 | + |
| 3 | +Rotates the crypt4gh encryption key of ingested file headers. |
| 4 | + |
| 5 | +## Service Description |
| 6 | + |
| 7 | +The `rotatekey` service re-encrypts the header of a file with the configured target key, and updates the database with the new header and encryption key hash. |
| 8 | + |
| 9 | +When running, rotatekey reads messages from the `rotatekey` RabbitMQ queue. |
| 10 | +For each message, these steps are taken: |
| 11 | + |
| 12 | +1. The message is validated as valid JSON that matches the "rotate-key" schema. |
| 13 | +2. A database look-up is performed for the configured target public key hash. If the look-up fails or the key has been deprecated, the service will exit. |
| 14 | +3. The key hash of the c4gh key with which the file is currently encrypted is fetched from the database and compared with the configured target key. |
| 15 | +4. If these key hashes differ, the reencrypt service is called to re-encrypt the file header with the target key. |
| 16 | +5. The file header entry in the database is updated with the new one. |
| 17 | +6. The key hash entry in the database is updated with the new one (target key). |
| 18 | +7. A re-verify message is compiled, validated and sent to the archived queue so that it is consumed by the `verify` service. |
| 19 | +8. The message is Ack'ed. |
| 20 | + |
| 21 | +In case of any errors during the above process, progress will be halted the message is Nack'ed, an info-error message is sent and the service moves on to the next message. |
| 22 | + |
| 23 | +## Communication |
| 24 | + |
| 25 | +- Rotatekey reads messages from one rabbitmq queue (`rotatekey`). |
| 26 | +- Rotatekey reads file information, headers and key hashes from the database and can not be started without a database connection. |
| 27 | +- Rotatekey makes grpc calls to `reencrypt` service for re-encrypting the header with the target public key. |
| 28 | +- Rotatekey sends messages to the `archived` queue for consumption by the `verify` service. |
| 29 | + |
| 30 | +## Configuration |
| 31 | + |
| 32 | +There are a number of options that can be set for the rotatekey service. |
| 33 | +These settings can be set by mounting a yaml-file at `/config.yaml` with settings. |
| 34 | + |
| 35 | +ex. |
| 36 | + |
| 37 | +```yaml |
| 38 | +log: |
| 39 | + level: "debug" |
| 40 | + format: "json" |
| 41 | +``` |
| 42 | +
|
| 43 | +They may also be set using environment variables like: |
| 44 | +
|
| 45 | +```bash |
| 46 | +export LOG_LEVEL="debug" |
| 47 | +export LOG_FORMAT="json" |
| 48 | +``` |
| 49 | + |
| 50 | +### Public Key file settings |
| 51 | + |
| 52 | +This setting controls which crypt4gh keyfile is loaded. |
| 53 | + |
| 54 | +- `C4GH_ROTATEPUBKEYPATH`: path to the crypt4gh public key to use for reencrypting file headers. |
| 55 | + |
| 56 | +### RabbitMQ broker settings |
| 57 | + |
| 58 | +These settings control how `rotatekey` connects to the RabbitMQ message broker. |
| 59 | + |
| 60 | +- `BROKER_HOST`: hostname of the rabbitmq server |
| 61 | +- `BROKER_PORT`: rabbitmq broker port (commonly `5671` with TLS and `5672` without) |
| 62 | +- `BROKER_QUEUE`: message queue or stream to read messages from (commonly `rotatekey_stream`) |
| 63 | +- `BROKER_USER`: username to connect to rabbitmq |
| 64 | +- `BROKER_PASSWORD`: password to connect to rabbitmq |
| 65 | +- `BROKER_ROUTINGKEY`: routing from a rabbitmq exchange to the rotatekey queue |
| 66 | +- `BROKER_PREFETCHCOUNT`: Number of messages to pull from the message server at the time (default to `2`) |
| 67 | + |
| 68 | +### PostgreSQL Database settings |
| 69 | + |
| 70 | +- `DB_HOST`: hostname for the postgresql database |
| 71 | +- `DB_PORT`: database port (commonly 5432) |
| 72 | +- `DB_USER`: username for the database |
| 73 | +- `DB_PASSWORD`: password for the database |
| 74 | +- `DB_DATABASE`: database name |
| 75 | +- `DB_SSLMODE`: The TLS encryption policy to use for database connections. Valid options are: |
| 76 | + - `disable` |
| 77 | + - `allow` |
| 78 | + - `prefer` |
| 79 | + - `require` |
| 80 | + - `verify-ca` |
| 81 | + - `verify-full` |
| 82 | + |
| 83 | + More information is available |
| 84 | + [in the postgresql documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION) |
| 85 | + |
| 86 | + Note that if `DB_SSLMODE` is set to anything but `disable`, then `DB_CACERT` needs to be set, |
| 87 | + and if set to `verify-full`, then `DB_CLIENTCERT`, and `DB_CLIENTKEY` must also be set. |
| 88 | + |
| 89 | +- `DB_CLIENTKEY`: key file for the database client certificate |
| 90 | +- `DB_CLIENTCERT`: database client certificate file |
| 91 | +- `DB_CACERT`: Certificate Authority (CA) certificate for the database to use |
| 92 | + |
| 93 | +### GRPC settings |
| 94 | + |
| 95 | +- `GRPC_HOST`: Host name of the grpc server |
| 96 | +- `GRPC_PORT`: Port number of the grpc server |
| 97 | +- `GRPC_CACERT`: Certificate Authority (CA) certificate for validating incoming request |
| 98 | +- `GRPC_SERVERCERT`: path to the x509 certificate used by the service |
| 99 | +- `GRPC_SERVERKEY`: path to the x509 private key used by the service |
| 100 | + |
| 101 | + |
| 102 | +### Logging settings |
| 103 | + |
| 104 | +- `LOG_FORMAT` can be set to “json” to get logs in json format. All other values result in text logging |
| 105 | +- `LOG_LEVEL` can be set to one of the following, in increasing order of severity: |
| 106 | + - `trace` |
| 107 | + - `debug` |
| 108 | + - `info` |
| 109 | + - `warn` (or `warning`) |
| 110 | + - `error` |
| 111 | + - `fatal` |
| 112 | + - `panic` |
0 commit comments