This HOWTO describes the process of generating root keypairs for a Rugged repository. The root keys are by far the most important, as they form the root of trust for the whole system.
Under standard Rugged operation, the root keys would be generated offline and kept secure to ensure the trustworthiness of the TUF repository. Typically this is done with OpenSSL or a Hardware Security Module (HSM).
There are two main methods for generating keypairs:
If we are using an HSM, we need to have a YubiHSM2 hardware token, and a
computer with the yubihsm-shell command-line tool installed.
With the hardware token attached, we can validate that we can interact with it by requesting the device info (see DEVICE INFO command:
yubihsm-shell --action=get-device-info
From here, we need to first Generate an authentication key for the YubiHSM2 device itself, and then generate signing and verification keys as an asymmetric keypair to be used by Rugged.
First create a password to associate with the authentication key which will
unlock your access to the YubiHSM2. You will use this at the end of the PUT
AUTHENTICATION
KEY
command (substitute for <NEW-PASSWORD> below).
yubihsm-shell \
--action=put-authentication-key \
--object-id=2 \
--label=new_authentication_key \
--domains=all \
--capabilities=all \
--delegated=all \
--algorithm=ecp256 \
--password=password \
--new-password=<NEW PASSWORD>
You should also delete the factory-default authentication key from the YubiHSM2, using the DELETE OBJECT command:
yubihsm-shell \
--action=delete-object \
--object-id=1 \
--object-type=authentication-key \
--authkey=2
yubihsm-shell --authkey=2 -a list-objects -i 1
This will prompt you again for your new authentication key password
(<NEW-PASSWORD> from above), and then confirm you no longer have the original
authentication key (with object-id 1)
With our authentication key in place securing our access to the YubiHSM2 hardware token, we can now use it to generate an asymmetric keypair for our use as Rugged signing and verification keys, using the GENERATE ASYMMETRIC KEY commnand.
yubihsm-shell \
--action=generate-asymmetric-key \
--object-id=100 \
--label=label_ecdsa_sign \
--domains=1,2,3 \
--capabilities=exportable-under-wrap,sign-eddsa \
--algorithm=ed25519 \
--authkey=2
Once again, this will prompt you for the authentication key password
(<NEW-PASSWORD> from above) to access the YubiHSM2’s services, and then
generate a new asymmetric keypair.
From here, we can export the verification key (the “public” half of the keypair), in order to provision it into our Rugged repository.
yubihsm-shell \
--action=get-public-key \
--object-id=100 \
--out=/var/rugged/tuf_repo/tmp/rootA_public.pem \
--outformat=PEM \
--authkey=2
In this case, we’ll generate our root key in a tmp directory under the tuf_repo in the DDEV container:
export RUGGED_TMP=/var/rugged/tuf_repo/tmp; ddev exec sudo mkdir -p $RUGGED_TMP
Using typical OpenSSL commands, we generate a keypair for each of the root keys we’ve configured:
ddev exec sudo /usr/local/ssl/bin/openssl genpkey -algorithm ED25519 -out $RUGGED_TMP/rootA_private.pem
ddev exec sudo /usr/local/ssl/bin/openssl pkey -in $RUGGED_TMP/rootA_private.pem -pubout -out $RUGGED_TMP/rootA_public.pem
Now add the verification key for the root keypairs we generated:
ddev rugged add-verification-key root /var/rugged/tuf_repo/tmp/rootA_public.pem --key-type=pem