From c5682b871fd8d4a29b22f894c05a7c59bea5edbf Mon Sep 17 00:00:00 2001 From: Anton Livaja Date: Wed, 15 Jan 2025 12:39:02 -0500 Subject: [PATCH] add procurer role and lots of refactoring --- notes-from-lance.txt | 92 +++++++++++++++++ quorum-key-management/src/SUMMARY.md | 33 ++----- .../ceremony-repository.md | 2 + .../src/component-documents/openpgp-setup.md | 2 +- .../tamper-evidence-methods.md | 5 +- .../level-2/basic-requirements.md | 14 +++ .../coins/pyth-spl/sign-transaction.md | 54 +++++++--- .../level-2/fixed-location/operator/index.md | 11 +++ .../operator/pgp-key-provisioning.md | 6 +- .../operator/root-entropy-generation.md | 7 +- .../level-2/fixed-location/procurer/index.md | 27 +++++ .../procure-facility.md} | 2 +- .../procurer/procure-hardware.md | 49 +++++++++ .../procure-tamper-proofing-equipment.md | 25 +++++ ...on-pgp-signing-keys-on-board-smart-card.md | 11 +++ .../provisioner/air-gapped-bundle.md | 17 ++++ .../fixed-location/provisioner/index.md | 27 +---- .../provisioner/pgp-key-bootstrapping.md | 99 ------------------- .../provision-air-gapped-bundle.md | 13 --- .../provisioner/provision-airgapos.md | 16 ++- .../provisioner/provision-computer.md | 24 +++-- .../provisioner/provision-sd-card.md | 14 ++- .../provision-tamper-proofing-equipment.md | 17 ---- .../generated-documents/level-2/hardware.md | 4 +- .../level-2/operator-requirements.md | 18 ++++ quorum-key-management/src/key-types.md | 34 +++++++ 26 files changed, 407 insertions(+), 216 deletions(-) create mode 100644 notes-from-lance.txt create mode 100644 quorum-key-management/src/generated-documents/level-2/basic-requirements.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/operator/index.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/index.md rename quorum-key-management/src/generated-documents/level-2/fixed-location/{provisioner/provision-facility.md => procurer/procure-facility.md} (96%) create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/provision-pgp-signing-keys-on-board-smart-card.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md delete mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/pgp-key-bootstrapping.md delete mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-air-gapped-bundle.md delete mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-tamper-proofing-equipment.md create mode 100644 quorum-key-management/src/generated-documents/level-2/operator-requirements.md create mode 100644 quorum-key-management/src/key-types.md diff --git a/notes-from-lance.txt b/notes-from-lance.txt new file mode 100644 index 0000000..ba88822 --- /dev/null +++ b/notes-from-lance.txt @@ -0,0 +1,92 @@ +# Distrust meet 2025-01-13 + +1. choose location + a. random location + b. if shipped, neutral location, picked up by both + +* barrel jacks are more secure + +Level 0 + * key import from unknown trust level + * key export to unknown trust level + * use any tools you want +level 1 + * icepick level 1 + * sealing or vault + * self custody (by design) + * trust single person + * portable ceremonies are this level + * doesn't matter where they do it, a single individual is trusted + * they use tamper evidence because they don't trust others + * level 2 assumes witnesses + +- [ ] move paragraph above procedures in provisioner/index +- [ ] add more steps to the docs to make it more explicit +- [ ] gotta fix the mnemonic word + +--- + +break out the requirements for bootstrapping into separate prep doc +o + +* assume every ceremony will be done by different people + +* you need to be able to do this ceremony to pass + * if u wanna be a multi party operator you need to have a personal computer + + +* personal operator key provisioning +* provisioning computer + +* provisioner should just buy a laptop and tamper proof it + * operators should be gutting laptops + +* num of laptops + * redundant primary laptop + * redundant operator laptops + * spare bundles for ceremonies + +* all levels need hardware procurement + +* commit inventory to a repo, ceremonies repo is fine, +it can be a text file + +## procurer + +* obtain numbers of needed items, quantity of each item +* tamper proof all hardware, sd cards, laptops, etc. +* tamper proof booster pack of 5 sd cards + +- [ ] specner you can go and do these cermonies right now + +operator + * gets equipment from ceremony inventory + +* get both Spencer and Herve to use a laptop from inventory with airgapos to set up their pgp keys + +* provisioned hardware (that's what provisioners do) can write label on bundles + + * operator kits + * ceremony kits + +* safes and vaults + * everything labelled + * didn't use tamper evident bags because they had big vaults + +* CSA tamper evident safes + +* Spencer tries first, then gets Herve to do it once it's smooth + +* could write some data layer stuff in rust + +- [ ] track down bug for keyfork mnemonic + +* use docs as a way to decide what features to implement + * lighter use + * +- [ ] look ahead at other coins + * shell script to make tx + +- [ ] do level 0 doc + +- [ ] hide document components diff --git a/quorum-key-management/src/SUMMARY.md b/quorum-key-management/src/SUMMARY.md index 2154594..bac9780 100644 --- a/quorum-key-management/src/SUMMARY.md +++ b/quorum-key-management/src/SUMMARY.md @@ -3,43 +3,30 @@ * [Threat Model](threat-model.md) * [Selecting a Quorum](selecting-quorum.md) * [System Roles](system-roles.md) + * [Key Types](key-types.md) * [Software](software.md) * [Location](locations.md) * [Glossary](glossary.md) * [Generated Documents]() * [Level 2]() * [Fixed-Location]() + * [Procurer](generated-documents/level-2/fixed-location/procurer/index.md) + * [Procure Facility](generated-documents/level-2/fixed-location/procurer/procure-facility.md) + * [Provision PGP Signing Keys On-Board Smart Card](generated-documents/level-2/fixed-location/procurer/provision-pgp-signing-keys-on-board-smart-card.md) + * [Procure Tamper Proofing Equipment](generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md) + * [Procure Hardware](generated-documents/level-2/fixed-location/procurer/procure-hardware.md) * [Provisioner](generated-documents/level-2/fixed-location/provisioner/index.md) - * [Bootstrapping PGP Keys + Air-Gapped Bundle](generated-documents/level-2/fixed-location/provisioner/pgp-key-bootstrapping.md) - * [Provision Computer](generated-documents/level-2/fixed-location/provisioner/provision-computer.md) * [Provision Ceremony Repository](generated-documents/level-2/fixed-location/provisioner/provision-ceremonies-repository.md) + * [Provision Computer](generated-documents/level-2/fixed-location/provisioner/provision-computer.md) * [Provision SD Card](generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md) - * [Provision Tamper Proofing Equipment](generated-documents/level-2/fixed-location/provisioner/provision-tamper-proofing-equipment.md) * [Provision AirgapOS](generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md) - * [Provision Facility](generated-documents/level-2/fixed-location/provisioner/provision-facility.md) - * [Provision Airgapped Bundle](generated-documents/level-2/fixed-location/provisioner/provision-air-gapped-bundle.md) * [Copy Shardfile SD Card](generated-documents/level-2/fixed-location/provisioner/copy-shardfile-sd-card.md) + * [Provision Air-Gapped Bundle](generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md) * [Proposer](system-roles.md) * [Propose Transaction](generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md) * [Approver](system-roles.md) * [Transaction Approval](generated-documents/level-2/fixed-location/approver/approve-transaction.md) - * [Operator](system-roles.md) + * [Operator](generated-documents/level-2/fixed-location/operator/index.md) * [PGP Key Provisioning](generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md) * [Root Entropy Generation](generated-documents/level-2/fixed-location/operator/root-entropy-generation.md) - * [PYTH-SLN - Sign Transaction](generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md) -* [Document Components]() - * [Ceremony Repository](./component-documents/ceremony-repository.md) - * [Keychain Repository](./component-documents/keychain-repository.md) - * [Git Commit Signing](./component-documents/git-commit-signing.md) - * [OpenPGP Setup](./component-documents/openpgp-setup.md) - * [Verifying Signatures](./component-documents/verifying-signatures.md) - * [Tamper Evidence Methods](./component-documents/tamper-evidence-methods.md) - * [Change Smart Card PINs](./component-documents/setting-smart-card-pins.md) - * [Online Machine Provisioning](./component-documents/online-machine-provisioning.md) - * [Hardware Destruction](./component-documents/hardware-destruction.md) - * [Storage Device Management](./component-documents/storage-device-management.md) - * [Procurement & Chain of Custody](./component-documents/hardware-procurement-and-chain-of-custody.md) - * [Online Artifact Storage](./component-documents/public-ceremony-artifact-storage.md) - * [Physical Artifact Storage](./component-documents/physical-artifact-storage.md) - * [`autorun.sh` Setup](./component-documents/autorun-sh-setup.md) - * [Hardware Models](./component-documents/hardware-models.md) \ No newline at end of file + * [PYTH-SLN - Sign Transaction](generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md) \ No newline at end of file diff --git a/quorum-key-management/src/component-documents/ceremony-repository.md b/quorum-key-management/src/component-documents/ceremony-repository.md index a2b2a5e..cd7ceca 100644 --- a/quorum-key-management/src/component-documents/ceremony-repository.md +++ b/quorum-key-management/src/component-documents/ceremony-repository.md @@ -12,6 +12,8 @@ This repository holds data pertaining to ceremonies. The primary data consists o * Policies (such as spending rules) +* Trusted PGP keys + * Participants ## Directives diff --git a/quorum-key-management/src/component-documents/openpgp-setup.md b/quorum-key-management/src/component-documents/openpgp-setup.md index 141dfc8..35c47cb 100644 --- a/quorum-key-management/src/component-documents/openpgp-setup.md +++ b/quorum-key-management/src/component-documents/openpgp-setup.md @@ -121,7 +121,7 @@ Setting up a PGP key pair is necessary for a number of different aspects of QVS. 1. When prompted, specify if you want to make an off-card backup of your encryption key. - * Note: This is a shim backup of the private key, not a full backup, and cannot be used to restore the key. + * Note: This is a shim backup of the private key, not a full backup, and cannot be used to restore the key. 1. Specify how long the key should be valid for (specify the number in days, weeks, months, or years). diff --git a/quorum-key-management/src/component-documents/tamper-evidence-methods.md b/quorum-key-management/src/component-documents/tamper-evidence-methods.md index 77c1e43..c81017d 100644 --- a/quorum-key-management/src/component-documents/tamper-evidence-methods.md +++ b/quorum-key-management/src/component-documents/tamper-evidence-methods.md @@ -107,13 +107,14 @@ Sealing bags of standard size objects which need to be protected can fit in. The * [Vacuum plastic roll](tamper-evidence-methods.md#vacuum-sealers) -* [Filler](tamper-evidence-methods.md#adequate-filler) +{{ #include tamper-evidence-methods.md:vsbwf-filler }} + // ANCHOR_END: vsbwf-equipment #### Sealing // ANCHOR: vsbwf-procedure-sealing -1. Insert object into plastic bag +1. Insert object(s) into plastic bag 1. Fill bag with enough plastic beads that all of the object is surrounded diff --git a/quorum-key-management/src/generated-documents/level-2/basic-requirements.md b/quorum-key-management/src/generated-documents/level-2/basic-requirements.md new file mode 100644 index 0000000..1345b40 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/basic-requirements.md @@ -0,0 +1,14 @@ +/* ANCHOR: all */ +# Basic Requirements + +## For Quorum Based Operations +// ANCHOR: requirements + +* 2 individuals with appropriate role + +* [Personal PGP key pair](../../key-types.md#personal-pgp-keypair) + +* Tamper-proofing equipment + +// ANCHOR_END: requirements +/* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md index d93aa93..bff0444 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md @@ -2,16 +2,34 @@ ## Requirements -* Ensure both primary operators have their [Operator Keys](../../pgp-key-provisioning.md) +* 2 Operators + +* Ensure both primary operators have their [Shard-Bearer Keys](../../pgp-key-provisioning.md) * Both operators should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object. * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys (found in ceremonies repo) +* Shardfile on SD card + +* Keychain SD card + +* Air-gapped bundle + +* Tamper proofing equipment + +* Ceremony notes + + * AirgapOS hash + + * Trusted PGP key fingeprints IDs + ## Procedure 1. Verify all transactions for the ceremony in the `ceremonies` repository, ensuring that all the transactions are properly signed by the proposer and the approver using PGP keys which have been checked into ceremonies repository. +1. Copy the transactions and signatures to an SD card + 1. Enter the designated location with the 2 operators and all required equipment 1. Lock access to the location - there should be no inflow or outflow of people during the ceremony @@ -19,22 +37,28 @@ 1. Retrieve sealed Air-Gapped bundle and polaroid from locked storage ### Unsealing Tamper Proofing + {{ #include ../../../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}} -### Secure Boot Procedure -1. Plug PureBoot smart card into air-gapped machine +### Ceremony -1. Plug in SD card labelled "AirgapOS" +1. Plug in SD card labelled "AirgapOS" into the air-gapped machine 1. Boot the computer and verify the hash of the version of AirgapOS that's booted 1. Plug in SD card labelled "Keychain" - * Load well known PGP keys of proposer and approver along with detached signatures of the keys (NOT IMPLEMENTED) + * Load well known PGP keys of proposer and approver along with detached signatures of the keys * `gpg --import ` -1. Insert SD card labelled "shardfile" +1. Plug in the SD card with transactions and signatures + +1. For each transaction, verify that the signature is made by trusted keys that are loaded in the gpg keyring: + + * `gpg --verify ` + +1. Insert SD card labelled "Shardfile" 1. `keyfork recover shard --daemon` @@ -46,14 +70,6 @@ * Follow on screen prompts -### Obtain Transaction Request - -1. Turn on online machine - -1. Get transaction request(s) - - * TODO define means (could just be email?) - 1. Run `icepick workflow sol-broadcast` command * Wait for prompt and plug in fresh SD card @@ -98,5 +114,15 @@ #### Sealing +1. Gather all the original items that were in the air-gapped bundle: + + * Air-gapped computer + + * AirgapOS SD card + + * Shardfile SD card + + * Keychain SD card + {{ #include ../../../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/index.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/index.md new file mode 100644 index 0000000..f55c088 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/index.md @@ -0,0 +1,11 @@ +# Operator + +## Responsibilities + +* Executing ceremonies + +* Managing Shard-bearer PGP keys + + * In addition to signing material, these keys are used for decrypting shards + + diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md index fdb7202..f0047ce 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md @@ -2,14 +2,14 @@ ## Requirements +{{ #include ../../operator-requirements.md:requirements }} + * For each new key to be provisioned: - * New smart card + * 2 new smart cards * 2 new SD cards -* Tamper proofing evidence photographs - ## Procedure 1. Enter the facility with all personnel and required equipment diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/root-entropy-generation.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/root-entropy-generation.md index 652a361..6032abb 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/root-entropy-generation.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/root-entropy-generation.md @@ -4,11 +4,8 @@ This is a ceremony for generating root entropy. ## Requirements -* Ensure both primary operators have their [Operator Keys](../../pgp-key-provisioning.md) +{{ #include ../../operator-requirements.md:requirements }} -* Both operators should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object. - - * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in "ceremonies" repo * Each member needs to bring their: @@ -26,9 +23,11 @@ This is a ceremony for generating root entropy. 1. Retrieve sealed laptop and polaroid from locked storage ### Unsealing Tamper Proofing + {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}} ### Generating Entropy + 1. Boot AirgapOS on the airgapped machine 1. Verify the hash of the AirgapOS version once it's booted diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/index.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/index.md new file mode 100644 index 0000000..4d3f3f8 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/index.md @@ -0,0 +1,27 @@ +# Procurer + +The procurer is responsible for: + +* Procuring equipment + + * Tamper proofing equipment + + * Hardware (computers, sd cards, sd card adapters, smart cards, cameras etc.) + +* Ensuring equipment is properly tamper proofed + +* Ensuring inventory is updated properly + +* Maintaining stock of supplies in the inventory + +* Minimizing hardware supply chain security risks + +## Order of Operations + +1. Provisioning [Signing PGP Keys](./provision-pgp-signing-keys-on-board-smart-card.md) + +1. Procuring a [facility](./procure-facility.md) + +1. Procuring [tamper proofing equipment](./procure-tamper-proofing-equipment.md) + +1. Procuring [hardware](./procure-hardware.md) diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-facility.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md similarity index 96% rename from quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-facility.md rename to quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md index 097f15b..e163026 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-facility.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md @@ -1,4 +1,4 @@ -# Provision Facility +# Procure Facility 1. Identify a location which is suitable for Level 2 ceremonies: diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md new file mode 100644 index 0000000..606ac55 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md @@ -0,0 +1,49 @@ +# Hardware Procurement + +## Requirements + +{{ #include ../../basic-requirements.md:requirements }} + +* Sealable plastic bag is required for this procedure: + + * {{ #include ../../../../component-documents/hardware-models.md:sealable-plastic-bags }} + +## Procedure + +{{ #include ../../../../component-documents/hardware-procurement-and-chain-of-custody.md:steps}} + +## Tamper Proofing + +All hardware: + +* MUST be procured using dual custody methods + +* MUST be tamper proofed using vacuum sealing / stored in tamper evident vault + +* MUST be properly labelled + +* MUST be added to cryptographically signed inventory + +### Procedure + +{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing }} + +## Equipment Models + +### Computers Models + +For [Level 2](../../../../threat-model.md#level-2) security, air-gapped computers which are used for cryptographic material management and operations are required. + +{{ #include ../../hardware.md:computer-models }} + +### SD Cards & Adapters + +SD cards can be tamper proofed in packs of 4 to reduce the amount of tamper proofing that needs to be done. + +Any high quality SD equipment can be used but below are some recommended products: + +{{ #include ../../../../component-documents/hardware-models.md:sd-models }} + +### Smart Cards + +{{ #include ../../../../component-documents/hardware-models.md:smart-cards }} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md new file mode 100644 index 0000000..ca9df73 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md @@ -0,0 +1,25 @@ +# Procure Tamper Proofing Equipment + +The facility will require tamper proofing equipment which will be used to tamper proof items before they are stored in inventory. + +These items don't require dual custody and can be purchased at any location. + +### Vacuum Sealer, plastic roll, filler + +{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-equipment}} + +### Digital camera + +{{ #include ../../hardware.md:camera-models}} + +### Polaroid camera + +{{ #include ../../../../component-documents/tamper-evidence-methods.md:polaroid-cameras}} + +### Label Printer + +There are two options: + +* Hand-held label printer with a built in keyboard + +* Non-standalone label printer that needs a computer to send it the file to print \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/provision-pgp-signing-keys-on-board-smart-card.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/provision-pgp-signing-keys-on-board-smart-card.md new file mode 100644 index 0000000..b211839 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/procurer/provision-pgp-signing-keys-on-board-smart-card.md @@ -0,0 +1,11 @@ +# Provision Bootstrapping Personal PGP Keys On-Board Smart Card + +## Requirements + +* Smart card + +* Any computer + +## Procedure + +{{ #include ../../../../component-documents/openpgp-setup.md:steps-on-key-gen }} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md new file mode 100644 index 0000000..5f047b2 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md @@ -0,0 +1,17 @@ +# Air-Gapped Bundle + +## Requirements + +{{ #include ../../basic-requirements.md:basic }} + +* AirgapOS SD Card + +* Air-gapped computer + +* Keychain SD Card + +## Procedure + +{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} + +1. Update inventory to indicate a new air-gapped bundle is available \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/index.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/index.md index ce476a6..24aefe9 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/index.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/index.md @@ -2,37 +2,18 @@ The provisioner is responsible for: -* Facilitating bootstrapping the system +* Provisioning hardware -* Procuring equipment +* Provisioning SD Cards (AirapOS, Keychain, Shardfiles etc.) -* Setting up the facility - -* Maintaining stock of supplies in the facility - -* Minimizing hardware supply chain security risks - -## Directives - -* MUST maintain chain of custody for all hardware until after it's properly stored or where necessary tamper-proofed - -The different procedures are ordered in chronological preference, to improve the efficiency of setting up the system. +* Provisioning ceremony bundles ## Procedures -The first task is to bootstrap the operator keys as they are an essential part of building a chain of trust. To achieve this, a bootstrapping ceremony can be used in order to procure hardware and generate keys in one continuous session. This ensures that the chain of custody is maintained for the hardware, and then that hardware is used to generate and seed PGP keys to smart cards, which can then be committed to the keychain repository, and used to sign tamper proofing evidence. - -[Initial Bootstrapping Ceremony](./pgp-key-bootstrapping.md) - -### Procedures Without Prerequisites -* [Provision Facility](./provision-facility.md) * [Provision SD Card](./provision-sd-card.md) -* [Provision Tamper Proofing Equipment](./provision-tamper-proofing-equipment.md) * [Provision Ceremonies Repository](./provision-ceremonies-repository.md) * [Provision AirgapOS](./provision-airgapos.md) - -### Procedures With Prerequisites -* [Procure Computer](./procure-computer.md) +* [Provision Computer](./procure-computer.md) * Requires tamper proofing equipment to be available * [Provision Air Gapped Bundle](./provision-air-gapped-bundle.md) * Requires operators to have smart cards with PGP keys, tamper proofing equipment, AirgapOS SD card diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/pgp-key-bootstrapping.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/pgp-key-bootstrapping.md deleted file mode 100644 index 16b6eb0..0000000 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/pgp-key-bootstrapping.md +++ /dev/null @@ -1,99 +0,0 @@ -# Operator - Provisioning PGP Keypair - -The initial setup requires the provisioner and operator to do all of these in a continuous session ensuring dual custody. Ensure that all participants are familiar with the sub-processes so that the ceremony can be completed in one working day. - -## Requirements - -* 3 individuals in order to have the flexibility for washroom breaks, fetching food and drinks etc. - - * 1 Operator - - * 1 Provisioner - - * 1 person to witness, but should be familiar with the process - -* [AirgapOS SD Card](./provision-airgapos.md) - -* [Tamper Proofing Equipment](./provision-tamper-proofing-equipment.md) - -* [Smart Cards](../../../../component-documents/hardware-models.md#smart-cards) - - * 2 per PGP keypair (more than 2 smart cards can be provisioned per keypair if desired, for redundancy) - -* SD Cards: [Provisioning Guide](./provision-sd-card.md) - - * 3 per PGP keypair (for backups) - - * 2 additional SD cards for Keychain SD cards - -* Designated [facility](./provision-facility.md) - -* Sealable plastic bag: {{ #include ../../../../component-documents/hardware-models.md:sealable-plastic-bags }} - * For hardware procurement - -* Tin can + lighter (HACK, this goes away when we fix keyfork) - - * This is used for burning materials produced during the ceremony which contain sensitive information - -## Procedure - -### Procure Computer (AirgapOS Compatible) - -#### Compatible Hardware - -{{ #include ../../hardware.md:computer-models }} - -#### Procedure - -{{ #include ../../../../component-documents/hardware-procurement-and-chain-of-custody.md:steps }} - - * In this case, wait until later steps where further instructions on how to tamper proof the computer - -### Ceremony - -1. Enter the designated facility with all participants and required equipment - -1. Lock access to the facility - there should be no inflow of new people during the ceremony if avoidable. - -1. Remove all unnecessary parts from the laptop before using it to reduce side-channel and data remnance attack risk: radio cards, speakers, microphones, storage drive. - * While this is not required for Level 2 security, it MAY be done in order to improve security of the system. - -1. Boot AirgapOS from verified SD card - -1. Check AirgapOS hashes when it's booted - -#### Generating PGP Keys and Seeding Cards - -Repeat these steps for each keypair: - -{{ #include ../../../../component-documents/openpgp-setup.md:steps-keyfork}} - -1. Do not turn off the computer as you will need to use the keys that are loaded for signing in the following section - -### Signing Keys - -Once the keys are generated, cross-sign all keys, for example: -``` -gpg --clearsign --default-key= .asc - -gpg --clearsign --default-key= .asc -``` -1. Store both public keys and both signatures on an SD card and repeat the process so that there are 2 backup SD cards. - - * Label both cards "Keychain " - -1. Upload these keys and signatures to the ceremonies repository after the airgapped machine is shut down. - -### Air-Gapped Bundle - -The following objects should be in the bundle: - -* AirgapOS SD Card - -* Air-gapped computer - -* Keychain SD Card - -#### Procedure - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-air-gapped-bundle.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-air-gapped-bundle.md deleted file mode 100644 index 60bfc26..0000000 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-air-gapped-bundle.md +++ /dev/null @@ -1,13 +0,0 @@ -## Provision Air-gapped Bundle - -* Tamper proof together the following objects: - - * [Air-gapped machine](./provision-computer.md) - - * [AirgapOS SD card](./provision-airgapos.md) - - * [Shardfile SD card](../operator/root-entropy-generation.md) - -### Procedure - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing }} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md index c521555..fd6d6e5 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md @@ -1,7 +1,17 @@ -## AirgapOS (SD Card) +# AirgapOS -An SD card with AirgapOS written to it will be required to run ceremonies. +## Requirements -The AirgapOS SD Card once provisioned will be used in creating the [tamper proofed airgap bundle](#air-gapped-bundle) +{{ #include ../../basic-requirements.md:requirements }} + +* Tamper proofing evidence (photographs) + +* Fresh SD card(s) + + * Bring however many SD cards should be provisioned + +## Procedure + +{{ #include ../../../../component-documents/sd-formatting.md:steps }} {{ #include ../../../../component-documents/one-time-use-airgapos.md:steps }} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md index 61a7970..12aa6de 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md @@ -1,15 +1,25 @@ # Provision Computer -For [Level 2](../../../../threat-model.md#level-2) security, air-gapped computers which are used for cryptographic material management and operations are required. +## Requirements -Sealable plastic bag is required for this procedure: +{{ #include ../../basic-requirements.md:requirements }} -{{ #include ../../../../component-documents/hardware-models.md:sealable-plastic-bags }} +* Tamper proofing evidence (photographs) -### Models +* Non-provisioned computer -{{ #include ../../hardware.md:computer-models }} +## Procedure -### Procedure +1. Retrieve non-provisioned laptop from inventory -{{ #include ../../../../component-documents/hardware-procurement-and-chain-of-custody.md:steps}} \ No newline at end of file +1. Enter facility with required items and personnel and lock the facility + +1. Follow a given model manual to remove all radio cards, storage drive, speakers, and microphone + +{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing }} + +1. Apply a new label which indicates the laptop has been provisioned + +1. Return the provisioned laptop to inventory + +1. Update inventory to reflect that this hardware has ben provisioned \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md index a5415ae..3b875d0 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md @@ -1,11 +1,15 @@ -## Preparing SD Cards +# Provisioning SD Cards -SD cards don't require special chain of custody, but ideally should be purchased from a reputable supplier. +## Requirements -### SD Card Models +{{ #include ../../basic-requirements.md:requirements }} -{{ #include ../../../../component-documents/hardware-models.md:sd-models }} +* Tamper proofing evidence (photographs) -### Procedure: formatting SD Card to `fat32` +* Fresh SD card(s) + + * Bring however many SD cards should be provisioned + +## Procedure: formatting SD Card to `fat32` {{ #include ../../../../component-documents/sd-formatting.md:steps }} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-tamper-proofing-equipment.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-tamper-proofing-equipment.md deleted file mode 100644 index ff47638..0000000 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/provision-tamper-proofing-equipment.md +++ /dev/null @@ -1,17 +0,0 @@ -# Provision Tamper Proofing Equipment - -### Vacuum Sealer and roll - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-equipment}} - -### Colored beads - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-filler}} - -### Digital camera - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:digital-cameras}} - -### Polaroid camera - -{{ #include ../../../../component-documents/tamper-evidence-methods.md:polaroid-cameras}} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/hardware.md b/quorum-key-management/src/generated-documents/level-2/hardware.md index e1af281..395035f 100644 --- a/quorum-key-management/src/generated-documents/level-2/hardware.md +++ b/quorum-key-management/src/generated-documents/level-2/hardware.md @@ -26,9 +26,11 @@ // ANCHOR_END: computer-models ## Digital Camera +// ANCHOR: camera-models * MUST have >10MP -- [ ] TODO amazon links are not ideal, more reliable and vetted hardware providers should be established + +// ANCHOR_END: camera-models ### Models // ANCHOR:digital-cameras diff --git a/quorum-key-management/src/generated-documents/level-2/operator-requirements.md b/quorum-key-management/src/generated-documents/level-2/operator-requirements.md new file mode 100644 index 0000000..8e5525c --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/operator-requirements.md @@ -0,0 +1,18 @@ +/* ANCHOR: all */ +# Base Requirements + +## For Quorum Based Operations +// ANCHOR: requirements + +* Adequate quorum (M individuals of a M of N quorum) + +* [Operator PGP key pairs](../../key-types.md#operator-pgp-keypair) + +* Tamper-proofing equipment + +* Both operators should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object. + + * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the "ceremonies" repo + +// ANCHOR_END: requirements +/* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-key-management/src/key-types.md b/quorum-key-management/src/key-types.md new file mode 100644 index 0000000..44f1faf --- /dev/null +++ b/quorum-key-management/src/key-types.md @@ -0,0 +1,34 @@ +# Key Types + +## Personal PGP Keypair + +Used for day to day operations such as signing keys being added to keychain, signing tamper evidence, signing transaction requests and approvals etc. + +### Requirements + +* MUST not be transferred + +* MUST be generated offline + +* MUST have the root key offline + +* MUST have subkeys maintained on a smartcard + +## Operator PGP Keypair + +Only used in ceremonies for decrypting shardfile material. + +### Requirements + +* MUST use smart-card within air-gapped ceremonies + +* MUST not have PII attached to them + +* MUST be generated in a witnessed ceremony + +* MUST only be backed up to a quorum + +* MUST not be transferred in level 4 + +* MAY be transferred in levels 1-3 +