# Set up a Debusine signing worker

## Introduction

`debusine-signing` is a signing service for Debusine, holding private keys and using them to sign data on behalf of Debusine. It is a daemon that connects (via HTTP API and WebSockets) to a Debusine server, waits for tasks and executes tasks locally.

## Notes for production deployments

`debusine-signing` manages sensitive data: an attacker with the ability to extract private keys in the clear would be able to construct intermediary attacks that could go undetected for long periods of time. None of `debusine-signing`’s interfaces allow extracting private keys, but deployments that involve high-value keys should take some extra care.

- The signing worker uses its own database, which should not be accessible by the Debusine server. In a small deployment it can be local to the signing worker, but if it is on a separate system then that should be distinct from the system hosting the Debusine server’s database.

- Limit direct user access as much as possible.

- Apply strict firewall rules. `debusine-signing` does not require any inbound connections.

- You may need to back up `/etc/debusine/signing/*.key`; these keys allow decrypting private keys stored in the signing database, so avoid storing backups of the signing database and these keys in the same place.

- The signing database includes audit logs. In the event of an attack that is not suspected of having been able to extract private key material directly, these audit logs may be useful in determining which keys need to be rotated.

## Initial setup

Install the `debusine-signing` package. The Initial setup using Debusine server has the instructions how to add the Debusine repository.

>     $ sudo apt install postgresql  # if you need to install PostgreSQL
>     $ sudo apt install debusine-signing

To know what the package does during installation see the What the package does on installation section. Follow the steps below to finalize the set-up.

> 1. By default, the package is configured to use a PostgreSQL database using the default local Unix socket and the authentication is done at the user level. The package creates a “debusine-signing” Unix account.

>    The database configuration can be edited in `/etc/debusine/signing/db_postgresql.py` .

> 2. Create the file `/etc/debusine/signing/config.ini` . Use `/usr/share/doc/debusine-signing/examples/config.ini` as an example:

>        $ sudo cp /usr/share/doc/debusine-signing/examples/config.ini /etc/debusine/signing/
>        $ sudo editor /etc/debusine/signing/config.ini

>    Change the `api-url` in the configuration file as needed. Note that it must be HTTPS: see Configure Nginx with an HTTPS certificate for how to set this up, especially if you are using a local self-signed certificate.

> 3. Generate a private key to be used to encrypt other private keys:

>        $ sudo debusine-signing generate_service_key /etc/debusine/signing/0.key

> 4. Restart `debusine-signing` with the new configuration and group:

>        $ sudo systemctl restart debusine-signing

>    View the signing worker logs:

>        $ journalctl -u debusine-signing.service

> 5. Following the restart, the token will appear in `/etc/debusine/signing/token`. The Debusine admin should approve the tokens pending for approval. Nothing needs to be done from the side of debusine-signing.

## Managing `debusine-signing`

Use the `systemctl` command to start (done automatically by the package), stop or restart debusine-signing:

    $ sudo systemctl start debusine-signing
    $ sudo systemctl stop debusine-signing
    $ sudo systemctl status debusine-signing

The default configuration logs to stderr, which is captured by systemd’s journal. The log level can be changed in `/etc/debusine/signing/config.ini`.

## Troubleshooting

Information about the state of debusine-signing can be found via:

> 1. `systemctl status debusine-signing` to verify that the service is running

> 2. `journalctl -u debusine-signing.service -f` to follow logs live

> 3. `journalctl -u debusine-signing.service -b` to see logs from current boot

To change the settings of `debusine-signing`, for example to increase the logging level:

    $ sudo editor /etc/debusine/signing/config.ini # change log-level
    $ sudo systemctl restart debusine-signing

`debusine-signing` can be launched without systemd which might be useful for troubleshooting. For example:

    $ sudo systemctl stop debusine-signing

    # adjust log-level if needed
    $ sudo editor /etc/debusine/signing/config.ini

    # execute it directly
    $ sudo debusine-signing signing_worker

`debusine-signing` can also be launched using a different user for debugging purposes. The configuration (`config.ini` and `token` files) in the directory `$HOME/.config/debusine/signing` have higher priority than the global configuration, `/etc/debusine/signing` .

## What the package does on installation

- Creates the `debusine-signing` user

- Installs a systemd service (named debusine-signing)

- Creates the directories `/etc/debusine/signing` and `/var/lib/debusine-signing`.