psf-tuf-runbook

This repository contains a runbook and supporting program for the Python Software Foundation's TUF key generation and signing ceremonies.

Due to COVID-19, this document has been modified for a two person, remote ceremony.

Notation

This document is designed to be read as a runbook -- a collection of discrete instructions with remediation steps that, if followed correctly, should result in the intended effects.

We use the following notation:

DO actions: Perform the following actions.
IF condition THEN actions: If condition is met, then perform the following actions.
GO TO heading: Go to the referenced heading in the runbook and perform the stated actions thereon.
END: You've reached an end state.

Start

DO GO TO Prepare the environment.

Prepare the environment

DO perform the pre-ceremony.
IF you have a phone or other personal devices, THEN set them on airplane mode.
DO boot the trusted offline machine, and log into it using the credentials provided during the pre-ceremony.

DO mount the flash storage stick:

$ sudo mount -t vfat /dev/sda1 /media/ceremony-products -o umask=000

DO change directory to the runbook directory:
```
$ cd ~/psf-tuf-runbook
```
DO take pictures of each HSM, in their tamper-evident bags.
DO remove YubiHSM2-1 from its tamper-evident bag and GO TO Provisioning the Provisioning the YubiHSM 2
DO remove YubiHSM2-2 from its tamper-evident bag and GO TO Provisioning the Provisioning the YubiHSM 2
DO remove YubiHSM2-3 from its tamper-evident bag and GO TO Provisioning the Provisioning the YubiHSM 2
DO remove Nitrokey HSM-4 from its tamper-evident bag and GO TO Provisioning the Provisioning the Nitrokey HSM
DO remove Nitrokey HSM-5 from its tamper-evident bag and GO TO Provisioning the Provisioning the Nitrokey HSM
DO remove Nitrokey HSM-6 from its tamper-evident bag and GO TO Provisioning the Provisioning the Nitrokey HSM
DO copy the ceremony products to the flash storage stick:
```
cp -R ./ceremony-products /media/ceremony-products
```

DO unmount the flash storage stick:

$ sync
$ sudo umount /media/ceremony-products

END

Provisioning the YubiHSM 2

Time estimate: 10 minutes.

DO locate and write down the serial number printed on the YubiHSM 2. Refer to the picture below:

In this picture, the serial number is 7550054. Note that in later steps the serial number will be 0-padded to 10 digits, like 0007550054.
IF the YubiHSM 2 is being reprovisioned due to a compromise or failed ceremony, THEN you must perform a physical reset.
1. DO touch and hold the metal contact of the YubiHSM 2 for ten (10) seconds as you insert it into the trusted offline computer.
IF the YubiHSM 2 is being provisioned for the first time, THEN insert it into the trusted offline computer.
DO ensure that exactly 1 (one) YubiHSM 2 is inserted into the trusted offline computer.
DO run the yubihsm-provision binary, using your key type according to the following rules:
- IF your keytype is "P-256", THEN pass --type p256
- IF your keytype is "P-384", THEN pass --type p384
```
$ yubihsm-provision --type KEY-TYPE
```

DO wait for this prompt:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!                    DANGER!                    !!!
!!!                                               !!!
!!!   This program will reset and reprovision     !!!
!!!   your YubiHSM 2 for TUF purposes.            !!!
!!!                                               !!!
!!!   Make sure to read the runbook before        !!!
!!!   using this program. Failure to do so        !!!
!!!   will cause PERMANENT key loss.              !!!
!!!                                               !!!
!!!   Hit "y" (case insensitive) to continue.     !!!
!!!                                               !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

DO hit y once ready to continue.

DO wait for the following output and prompt:

Discovered a Yubico YubiHSM with serial number XXXXXXXXXX
We've successfully authenticated with the HSM!
Continue with factory reset? This step is IRREVERSIBLE! [y/N]

DO confirm that the serial number in the output matches the serial number written down.
DO hit y once ready to continue.

DO wait for the following output and prompt:

Success! Giving the HSM 10 seconds to come back online...

#####################################################
###                                               ###
###   We're going to create a new "auth key"      ###
###   on your YubiHSM.                            ###
###                                               ###
###   This "auth key" will                        ###
###   have a password that you MUST remember      ###
###   OR store securely and will protect the      ###
###   TUF keys that are going to be created.      ###
###                                               ###
###   Hit "y" (case insensitive) to continue.     ###
###                                               ###
#####################################################

DO hit y once ready to continue.
DO enter the new authentication key password generated for this YubiHSM during the pre-ceremony.
DO re-enter the authentication key password.

DO wait for the following output:

Success! Provisioned a new authentication key as object 2 and deleted the default key
Success!
We're creating our TUF keys and attestation certificates now.

DO re-enter the authentication key password.
DO wait for the program to exit.

DO check for the following files in the runbook directory:

ceremony-products/XXXXXXXXXX/XXXXXXXXXX_cert.der
ceremony-products/XXXXXXXXXX/XXXXXXXXXX_root_attestation.der
ceremony-products/XXXXXXXXXX/XXXXXXXXXX_root_pubkey.pub
ceremony-products/XXXXXXXXXX/XXXXXXXXXX_targets_attestation.der
ceremony-products/XXXXXXXXXX/XXXXXXXXXX_targets_pubkey.pub

Where XXXXXXXXXX is the 0-prefixed serial number.

DO change directories to the products directory for the current HSM:
```
cd ceremony-products/XXXXXXXXXX
```
Where XXXXXXXXXX is the 0-prefixed serial number.
DO run the raw-ec-points-to-pem script with each public key generated above, using your key type according to the following rules:
- IF your keytype is "P-256", THEN pass --type p256
- IF your keytype is "P-384", THEN pass --type p384
```
$ raw-ec-points-to-pem --type KEY-TYPE XXXXXXXXXX_root_pubkey.pub
$ raw-ec-points-to-pem --type KEY-TYPE XXXXXXXXXX_targets_pubkey.pub
```
DO change directories back to the runbook directory.
```
cd ~/psf-tuf-runbook
```
DO remove the HSM.
DO seal the provisioned HSM and folded authentication key password in a tamper-evident bag.
DO label the bag with the HSM's signing body ID and 0-prefixed serial number.
DO hold the sealed tamper-evident bag up to the camera of the communication computer.

Provisioning the Nitrokey HSM

Time estimate: 10 minutes.

DO determine the current Security Officer PIN ("SO-PIN"):
1. IF the Nitrokey has not been provisioned before, THEN the SO-PIN is 3537363231383830.
2. IF the Nitrokey has been previously provisioned, THEN the SO-PIN should have been retained from the previous provisoning.
DO insert the Nitrokey HSM into the trusted offline computer.
DO ensure that exactly one (1) Nitrokey HSM is inserted into the trusted offline computer.
DO run the nitrohsm-provision script, using your SO-PIN:
```
$ nitrohsm-provision --so-pin SO-PIN
```

DO wait for this prompt:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!                    DANGER!                    !!!
!!!                                               !!!
!!!   This program will reset and reprovision     !!!
!!!   your Nitrokey HSM for TUF purposes.         !!!
!!!                                               !!!
!!!   Make sure to read the runbook before        !!!
!!!   using this program. Failure to do so        !!!
!!!   will cause PERMANENT key loss and MAY       !!!
!!!   leave your HSM in an unusable state.        !!!
!!!                                               !!!
!!!   Hit "y" (case insensitive) to continue.     !!!
!!!                                               !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

DO hit y once ready to continue.

DO wait for the following output and prompt:

Successfully discovered a Nitrokey HSM with Slot #0
Continue with factory reset? This step is IRREVERSIBLE! [y/N]

DO hit y once ready to continue.

DO wait for the following output and prompt:

Success! Reinitialized the HSM.
Enter your NEW Security Officer PIN:

DO enter the new Security Officer PIN generated for this Nitrokey during the pre-ceremony.

DO wait for the following prompt:

Re-enter your NEW Security Officer PIN:

DO re-enter the new Security Officer PIN.
DO wait for the following prompt:
```
Enter your NEW user PIN:
```
DO enter the new user PIN generated for this Nitrokey during the pre-ceremony.
DO wait for the following prompt:
```
Re-enter your NEW user PIN:
```
DO re-enter the new user PIN.

DO wait for the following output:

Success! We've reinitialized the Nitrokey with a new SO PIN and user PIN.
Use this serial number when doing key generation: XXXXXXXXXXX

DO write down the serial number printed above on a separate piece of loose-leaf.
DO run the generate-nitrohsm-keys script, using your key type according to the following rules:
- IF your keytype is "P-256", THEN pass --type p256
- IF your keytype is "P-384", THEN pass --type p384
```
$ generate-nitrohsm-keys --type KEY-TYPE --serial XXXXXXXXXXX
```
DO wait for the following prompt:
```
Enter your user PIN:
```
DO enter the new user PIN.

DO check for the following files in the runbook directory:

ceremony-products/XXXXXXXXXXX/XXXXXXXXXXX_root_pubkey.pub
ceremony-products/XXXXXXXXXXX/XXXXXXXXXXX_root_pubkey.pem
ceremony-products/XXXXXXXXXXX/XXXXXXXXXXX_targets_pubkey.pub
ceremony-products/XXXXXXXXXXX/XXXXXXXXXXX_targets_pubkey.pem

DO remove the HSM.
DO seal the provisioned HSM and folded Security Officer and user PINs in a tamper-evident bag.
DO label the bag with the HSM's signing body ID and serial number.
DO hold the sealed tamper-evident bag up to the camera of the communication computer.

nealmcb/psf-tuf-runbook

psf-tuf-runbook

Notation

Start

Prepare the environment

Provisioning the YubiHSM 2

Provisioning the Nitrokey HSM