psf-tuf-runbook

This repository contains a runbook and supporting program for the Python Software Foundation's TUF key generation and signing ceremonies. The procedures documented here are designed to implement the security policies for offline keys defined in PEP 458 - Secure PyPI downloads with signed repository metadata

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.

In addition, this document uses RFC 2119 to describe optional and mandatory steps.

Start

1. DO GO TO Prepare the environment.

Prepare the environment

1. DO perform the pre-ceremony.

2. DO Start streaming the ceremony using the communication computer.

3. IF you have a phone or other personal devices, THEN set them on airplane mode.

4. DO boot the trusted offline machine (the Raspberry Pi "ceremony computer"), and log into it using the credentials provided during the pre-ceremony.

5. DO mount the flash storage stick:

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

6. DO change directory to the runbook directory:

   $ cd ~/psf-tuf-runbook

7. DO take pictures of each HSM, in their tamper-evident bags.

8. DO remove YubiHSM2-1 (keytype: P-256) from its tamper-evident bag and GO TO Provisioning the YubiHSM 2

9. DO remove YubiHSM2-2 (keytype: P-384) from its tamper-evident bag and GO TO Provisioning the YubiHSM 2

10. DO remove YubiHSM2-3 (keytype: P-256) from its tamper-evident bag and GO TO Provisioning the YubiHSM 2

11. DO remove Nitrokey HSM-4 (keytype: P-384) from its tamper-evident bag and GO TO Provisioning the Nitrokey HSM

12. DO remove Nitrokey HSM-5 (keytype: P-256) from its tamper-evident bag and GO TO Provisioning the Nitrokey HSM

13. DO remove Nitrokey HSM-6 (keytype: P-384) from its tamper-evident bag and GO TO Provisioning the Nitrokey HSM

14. DO copy the ceremony products to the flash storage stick:

    cp -R ./ceremony-products /media/ceremony-products

15. DO unmount the flash storage stick:

    $ sync
    $ sudo umount /media/ceremony-products

16. DO perform the post-ceremony steps.

17. END

Provisioning the YubiHSM 2

Time estimate: 10 minutes.

1. 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.

2. 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.

3. IF the YubiHSM 2 is being provisioned for the first time, THEN insert it into the trusted offline computer.

4. DO ensure that exactly 1 (one) YubiHSM 2 is inserted into the trusted offline computer.

5. 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

6. 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.     !!!
   !!!                                               !!!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   

7. DO hit y once ready to continue.

8. 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]
   

9. DO confirm that the serial number in the output matches the serial number written down.

10. DO hit y once ready to continue.

11. 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.     ###
    ###                                               ###
    #####################################################
    

12. DO hit y once ready to continue.

13. DO enter the new authentication key password generated for this YubiHSM during the pre-ceremony.

14. DO re-enter the authentication key password.

15. 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.
    

16. DO re-enter the authentication key password.

17. DO wait for the program to exit.

18. 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.

19. DO change directories to the products directory for the current HSM:

    cd ceremony-products/XXXXXXXXXX

    Where XXXXXXXXXX is the 0-prefixed serial number.

20. 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

21. DO confirm that the following files have been generated:

    ceremony-products/XXXXXXXXXX/XXXXXXXXXX_root_pubkey.pem
    ceremony-products/XXXXXXXXXX/XXXXXXXXXX_targets_pubkey.pem
    

22. DO change directories back to the runbook directory.

    cd ~/psf-tuf-runbook

23. DO remove the HSM.

24. DO label a tamper-evident bag with the HSM's signing body ID and 0-prefixed serial number.

25. DO seal the provisioned HSM and folded authentication key password in the tamper-evident bag.

26. DO hold the sealed tamper-evident bag up to the camera of the communication computer.

Provisioning the Nitrokey HSM

Time estimate: 10 minutes.

1. 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.

2. DO insert the Nitrokey HSM into the trusted offline computer.

3. DO ensure that exactly one (1) Nitrokey HSM is inserted into the trusted offline computer.

4. DO run the nitrohsm-provision script, using your SO-PIN:

   $ nitrohsm-provision --so-pin SO-PIN

5. 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.     !!!
   !!!                                               !!!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   

6. DO hit y once ready to continue.

7. 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]
   

8. DO hit y once ready to continue.

9. DO wait for the following output and prompt:

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

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

11. DO wait for the following prompt:

    Re-enter your NEW Security Officer PIN:
    

12. DO re-enter the new Security Officer PIN.

13. DO wait for the following prompt:

    Enter your NEW user PIN:
    

14. DO enter the new user PIN generated for this Nitrokey during the pre-ceremony.

15. DO wait for the following prompt:

    Re-enter your NEW user PIN:
    

16. DO re-enter the new user PIN.

17. 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
    

18. DO write down the serial number printed above on a separate piece of loose-leaf.

19. 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

20. DO wait for the following prompt:

    Enter your user PIN:
    

21. DO enter the new user PIN.

22. 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
    

23. DO remove the HSM.

24. DO label a tamper-evident bag with the HSM's signing body ID and serial number.

25. DO seal the provisioned HSM and folded Security Officer and user PINs in the tamper-evident bag.

26. DO hold the sealed tamper-evident bag up to the camera of the communication computer.

Post-ceremony

1. DO insert the flash stick into the communication computer.

2. DO navigate to the runbook repository in a new terminal.

3. DO create a new branch:

   git checkout -b ceremony-YYYY-MM-DD

   Where YYYY-MM-DD is the current date.

4. DO create the following new subdirectories:

   mkdir -p ceremony/YYYY-MM-DD/ceremony-products
   mkdir -p ceremony/YYYY-MM-DD/images

   Where YYYY-MM-DD is the current date.

5. DO copy the contents of the ceremony flash stick into the ceremony-products subdirectory.

6. DO copy all images taken of the HSMs and tamper-evident bags into the images subdirectory.

7. DO commit the results, signing with a publicly announced PGP key:

   git add ceremony/YYYY-MM-DD
   git commit -S

   Where YYYY-MM-DD is the current date.

8. DO push the branch to psf/psf-tuf-runbook and open a PR for review.

   git push origin ceremony-YYYY-MM-DD

   Where YYYY-MM-DD is the current date.

9. DO await for PR approval, and confirm that the branch is merged into the main branch.

   • You MAY delete the original ceremony branch once merged.

10. DO securely destroy the SD card used for the runbook image OR zero it:

    $ diskutil unmountDisk /dev/rdiskN
    $ sudo dd bs=4m if=/dev/zero of=/dev/rdiskN