Merge remote-tracking branch 'origin/feat/quorum-kms'
This commit is contained in:
commit
5438f99c9c
GPG Key ID:
8E47A1EC35A1551D
|
|
@ -0,0 +1 @@
|
||||||
|
book/
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# Quorum Key Management (QKM)
|
||||||
|
|
||||||
|
Quorum Key Management (QKM) is an open source system of playbooks and tooling which
|
||||||
|
facilitates the creation and maintenance of highly resilient Quorum-based Key
|
||||||
|
Management Systems based on a strict threat model which can be used for a
|
||||||
|
variety of different cryptographic algorithms.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
In order to read the `mdbook` run the following commands:
|
||||||
|
|
||||||
|
```
|
||||||
|
cargo install mdbook
|
||||||
|
mdbook serve
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
[book]
|
||||||
|
authors = ["Anton Livaja", "Lance R. Vick", "Ryan Heywood"]
|
||||||
|
language = "en"
|
||||||
|
multilingual = false
|
||||||
|
src = "src"
|
||||||
|
title = "Quorum Key Management (QKM)"
|
||||||
|
|
@ -0,0 +1,43 @@
|
||||||
|
# Summary
|
||||||
|
* [Introduction](intro.md)
|
||||||
|
* [Threat Model](threat-model.md)
|
||||||
|
* [Selecting a Quorum](selecting-quorum.md)
|
||||||
|
* [Software](software.md)
|
||||||
|
* [Hardware](hardware.md)
|
||||||
|
* [Glossary](glossary.md)
|
||||||
|
|
||||||
|
* [Preparations]()
|
||||||
|
* [Repeat Use]()
|
||||||
|
* [Flash PureBoot to Librem](flash-pureboot-firmware.md)
|
||||||
|
* [Initialize PureBoot Smart Card](initialize-pureboot-smart-card.md)
|
||||||
|
* [Change Smart Card PINs](setting-smart-card-pins.md)
|
||||||
|
* [PureBoot Restricted Boot](enable-pure-boot-restricted-boot.md)
|
||||||
|
* [AirgapOS Setup](repeat-use-airgapos.md)
|
||||||
|
* [`autorun.sh` Setup](autorun-sh-setup.md)
|
||||||
|
* [Secure Boot Sequence](secure-boot-sequence.md)
|
||||||
|
* [Selecting Locations](locations.md)
|
||||||
|
|
||||||
|
* [One Time Use]()
|
||||||
|
* [Procure Hardware](one-time-use-hardware-procurement.md)
|
||||||
|
* [AirgapOS Setup](one-time-use-airgapos.md)
|
||||||
|
* [Repository Setup](one-time-repository-setup.md)
|
||||||
|
* [Selecting Locations](one-time-use-locations.md)
|
||||||
|
|
||||||
|
* [Key Ceremonies]()
|
||||||
|
* [Ceremony Log Template](ceremony-log-template.md)
|
||||||
|
* [Root Entropy Ceremonies](root-entropy-ceremonies.md)
|
||||||
|
* [Local Key Provisioning](local-key-provisioning.md)
|
||||||
|
* [Hybrid Key Provisioning](hybrid-key-provisioning.md)
|
||||||
|
* [Remote Key Provisioning](remote-key-provisioning.md)
|
||||||
|
|
||||||
|
* [Additional Key Ceremonies]()
|
||||||
|
* [Operator Key Provisioning](operator-key-provisioning.md)
|
||||||
|
* [Location Key Provisioning](location-key-provisioning.md)
|
||||||
|
|
||||||
|
* [Post Ceremony]()
|
||||||
|
* [Online Artifact Storage](public-ceremony-artifact-storage.md)
|
||||||
|
* [Physical Artifact Storage](physical-artifact-storage.md)
|
||||||
|
|
||||||
|
* [Lifecycle Management]()
|
||||||
|
* [Destroying Hardware](hardware-destruction.md)
|
||||||
|
* [Storage Device Management](storage-device-management.md)
|
||||||
|
|
@ -0,0 +1,44 @@
|
||||||
|
# `autorun.sh` Setup
|
||||||
|
|
||||||
|
This document describes how `autorun.sh`, a file that AirgapOS automatically
|
||||||
|
boots and runs should be set up.
|
||||||
|
|
||||||
|
This setup can be done on any machine.
|
||||||
|
|
||||||
|
1. Create a file called `autorun.sh` that has the following contents:
|
||||||
|
|
||||||
|
You may accomplish this by doing the following:
|
||||||
|
|
||||||
|
* In your Terminal use this command:
|
||||||
|
`vi autorun.sh`
|
||||||
|
* Once you are in the editor press "i" to enter "insert mode"
|
||||||
|
* Type in the contents, replacing <N> and <M> with your chosen threshold
|
||||||
|
numbers according to your [Quorum](selecting-quorum.md):
|
||||||
|
```sh
|
||||||
|
#!/bin/sh
|
||||||
|
keyfork wizard generate-shard-secret --threshold <M> --max <N> --output shards.pgp
|
||||||
|
```
|
||||||
|
* Press "esc"
|
||||||
|
* Press ":"
|
||||||
|
* Press "x"
|
||||||
|
* Press Enter
|
||||||
|
|
||||||
|
2. Hash the file
|
||||||
|
The file should be hashed by using the following command:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
sha256sum autorun.sh
|
||||||
|
```
|
||||||
|
Make note of the hash on a piece of paper
|
||||||
|
|
||||||
|
3. Copy the file to the Storage Device which contains AirgapOS.
|
||||||
|
|
||||||
|
a. If you don't have a Storage Device set up with AirgapOS use [this guide](repeat-use-airgapos.md)
|
||||||
|
to do so.
|
||||||
|
|
||||||
|
b. Mount the AirgapOS Storage Device using [this guide](storage-device-management.md#mounting-a-storage-device)
|
||||||
|
|
||||||
|
c. Copy the `autorun.sh` file to the Storage Device
|
||||||
|
|
||||||
|
4. Make note of this hash on a piece of paper or print it as you will need it to
|
||||||
|
verify the file during Ceremonies.
|
||||||
|
|
@ -0,0 +1,62 @@
|
||||||
|
# Ceremony Log Template
|
||||||
|
|
||||||
|
This template is to be used during the ceremony in order to keep track of events
|
||||||
|
that take place during the Key Derivation Ceremony.
|
||||||
|
|
||||||
|
Capture as much information as possible - more data is always better than less,
|
||||||
|
this means being specific about the exact location, full names of participants,
|
||||||
|
exact models of equipment used etc.
|
||||||
|
|
||||||
|
## Date
|
||||||
|
|
||||||
|
```
|
||||||
|
2024-08-03
|
||||||
|
```
|
||||||
|
|
||||||
|
## Individuals Present
|
||||||
|
Individuals may be Operators or Witnesses. Include the individual's full legal
|
||||||
|
name
|
||||||
|
|
||||||
|
```
|
||||||
|
Max Rockatansky - Witness
|
||||||
|
Paul Atreides - Operator
|
||||||
|
```
|
||||||
|
|
||||||
|
## Location
|
||||||
|
Specify exact location, including details such as the floor, room etc.
|
||||||
|
|
||||||
|
```
|
||||||
|
12 Grimmauld Place, Islington, London
|
||||||
|
2nd floor, first room on the left when coming up the stairs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Equipment
|
||||||
|
|
||||||
|
### Type of Laptop Used
|
||||||
|
|
||||||
|
```
|
||||||
|
Purism Librem 14
|
||||||
|
```
|
||||||
|
|
||||||
|
### Type of SD Card Used
|
||||||
|
|
||||||
|
```
|
||||||
|
SD Card: Kingston SDCIT2/8GBSP
|
||||||
|
```
|
||||||
|
|
||||||
|
## Software
|
||||||
|
Specify the exact version / commit
|
||||||
|
|
||||||
|
```
|
||||||
|
AirgapOS: https://git.distrust.co/public/airgap/commit/df223e6deb2833a8160c836f435ee01f7b776e87
|
||||||
|
```
|
||||||
|
|
||||||
|
## Chronological Timeline
|
||||||
|
Ensure to capture as much details as possible, even if it seems trivial.
|
||||||
|
|
||||||
|
* 2024-01-01:0900: The team assembles at the airport and selects the location
|
||||||
|
from a pre-made list of potential locations
|
||||||
|
* 2024-01-01:1030: The team arrives at location and inspects the premises for
|
||||||
|
cameras and ensures that the location criteria are adhered to
|
||||||
|
* 2024-01-01:1440: The hardware is set up and the software and firmware are
|
||||||
|
verified
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# Enable PureBoot Restricted Boot
|
||||||
|
|
||||||
|
With PureBoot Restricted Boot, you can lock down your boot firmware to only boot
|
||||||
|
trusted, signed executables both on a local disk and USB, so you control the
|
||||||
|
keys.
|
||||||
|
|
||||||
|
In order to enable Restricted Boot, the user may follow the Purism guide found
|
||||||
|
[here](https://docs.puri.sm/PureBoot/Restricted.html).
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
# Flash Pureboot Firmware
|
||||||
|
|
||||||
|
The version required for being able to complete all steps for setting up the
|
||||||
|
Ceremony Machine using a Librem 14:
|
||||||
|
* https://source.puri.sm/firmware/releases/-/blob/PureBoot-Release-24-L14JackDetect-1/librem_14/pureboot-librem_14-Release-24-L14JackDetect-1.rom.gz?ref_type=heads
|
||||||
|
|
||||||
|
If another type of hardware is used you may have to try different versions of
|
||||||
|
the PureBoot firmware as some have issues with the `/etc/gui_functions` and `/etc/functions` which are used during the [Secure Boot Sequence](secure-boot-sequence.md)
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Download the [.rom](https://source.puri.sm/firmware/releases/-/blob/PureBoot-Release-24-L14JackDetect-1/librem_14/pureboot-librem_14-Release-24-L14JackDetect-1.rom.gz?ref_type=heads) file
|
||||||
|
|
||||||
|
2. Put the `.rom` file on a Storage Device
|
||||||
|
|
||||||
|
3. Plug the Storage Device with the `.rom` file into the Librem 14
|
||||||
|
|
||||||
|
4. During boot, press *any* key when prompted
|
||||||
|
|
||||||
|
5. Select "Options -->", press Enter
|
||||||
|
|
||||||
|
6. Select "Flash/Update the BIOS -->", press Enter
|
||||||
|
|
||||||
|
7. Select "Flash the firmware with a new ROM, retain settings"
|
||||||
|
|
||||||
|
8. "You will need to insert a USB drive containing your BIOS image (*.rom...)
|
||||||
|
After you select this file, this program will reflash your BIOS.
|
||||||
|
Do you want to proceed?"
|
||||||
|
|
||||||
|
* Select "Yes", Press Enter
|
||||||
|
|
||||||
|
9. Select the `.rom` file and press Enter
|
||||||
|
|
||||||
|
10. Do you wish to proceed?
|
||||||
|
|
||||||
|
* Select "Yes", Press Enter
|
||||||
|
|
@ -0,0 +1,21 @@
|
||||||
|
4. Flash ISO Image to a Storage Device
|
||||||
|
|
||||||
|
a. Select a new Storage Device which can be overwritten entirely
|
||||||
|
|
||||||
|
b. Find the name of the Storage Device using [this guide](storage-device-management.md#finding-a-storage-device-name)
|
||||||
|
|
||||||
|
d. Use the `dd` utility in the Terminal to flash AirgapOS to it. You will need
|
||||||
|
to replace `<your_storage_device>` with the name of your device.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo dd bs=4M if=~/airgap/dist/airgap.iso of=/dev/<your_thumb_drive> status=progress
|
||||||
|
```
|
||||||
|
|
||||||
|
In the example, the name of the device is `sda` so the complete command would look like this:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo dd bs=4M if=~/airgap/dist/airgap.iso of=/dev/sda status=progress
|
||||||
|
```
|
||||||
|
|
||||||
|
Once this step is complete, you have successfully set up a Storage Device
|
||||||
|
with AirgapOS.
|
||||||
|
|
@ -0,0 +1,108 @@
|
||||||
|
# Glossary
|
||||||
|
|
||||||
|
## Ciphertext
|
||||||
|
In cryptography, ciphertext is the result of encryption performed on plaintext
|
||||||
|
using an algorithm, called a cipher.
|
||||||
|
|
||||||
|
## Quorum Key Management (QKM)
|
||||||
|
A set of highly specified processes and tooling used for setting up a highly
|
||||||
|
resilient quorum-based key management system.
|
||||||
|
|
||||||
|
## Operator
|
||||||
|
An individual who manages an [Operator Key](#operator-key) which is used for
|
||||||
|
protecting the passphrase of a Location key and participates in different
|
||||||
|
aspects of the lifecycle management of the QKM system.
|
||||||
|
|
||||||
|
## Operator Key
|
||||||
|
An asymmetric key used for protecting the passphrase of a Location key
|
||||||
|
|
||||||
|
## Quorum
|
||||||
|
The chosen M of N threshold used to achieve "quorum", which is a type of
|
||||||
|
agreement or consensus between a group of individuals. In the context of
|
||||||
|
Shamir's Secret Sharing, it refers to the minimum number of shards required to
|
||||||
|
reassemble the [Root Entropy](#root-entripy-re).
|
||||||
|
|
||||||
|
#### Wrench Factor
|
||||||
|
How many people are required to be put under duress (via smacking them with a
|
||||||
|
wrench repeatedly or otherwise to get access to their Shard) before the Disaster
|
||||||
|
Recover Key is compromised.
|
||||||
|
|
||||||
|
#### Bus Factor
|
||||||
|
How many members of the Quorum can meet an untimely demise without irretrievably
|
||||||
|
locking access to the Distrust Quroum system.
|
||||||
|
|
||||||
|
## Root Entropy (RE)
|
||||||
|
The main entropy/randomness which is used for hierarchical deterministic key
|
||||||
|
derivation of a variety of cryptographic algorithms.
|
||||||
|
|
||||||
|
## Shard
|
||||||
|
Crytpographic shard created using Shamir's Secret Sharing algorithm.
|
||||||
|
|
||||||
|
## Shamir's Secret Sharing (SSS)
|
||||||
|
An algorithm used to split cryptographic material into shards which can be
|
||||||
|
used to reassemble a secret. The shards can be combined according to a threshold
|
||||||
|
which is set at the time of initial sharding, expressed as M of N, or in other
|
||||||
|
words M shards of the total N shards in existence are required to reveal the
|
||||||
|
secret.
|
||||||
|
|
||||||
|
## Workstation
|
||||||
|
Highly secure computer which is used for sensitive operations, typically in the
|
||||||
|
context of [Production Engineering](TODO).
|
||||||
|
|
||||||
|
#### Minimum
|
||||||
|
In order to set up a Workstation, as part of a [Production Engineering](TODO) setup,
|
||||||
|
a separate computer only used for carrying out sensitive operations should be used.
|
||||||
|
|
||||||
|
#### Recommended
|
||||||
|
Setting up a computer with QubesOS is recommended as it makes it easy to create
|
||||||
|
purpose built environments with minimal surface area for attacks, on the OS, and
|
||||||
|
networking level.
|
||||||
|
|
||||||
|
## Air-Gapped
|
||||||
|
Hardware which has no access to radio frequency or cable based networking
|
||||||
|
capabilities in order to reduce area for surface attacks. Typically Air-Gapped
|
||||||
|
computers are laptops which are never connected to the internet or any other
|
||||||
|
networks, and have had their radio frequency hardware permanently disabled or
|
||||||
|
ideally removed.
|
||||||
|
|
||||||
|
## Key Derivation Ceremony
|
||||||
|
Highly specified process which is used to secure derivation of cryptographic
|
||||||
|
material, with a focus on ensuring no single party has access to the Disaster
|
||||||
|
Recovery Key. The ceremony includes witnesses who can help attest to the fact
|
||||||
|
that the ceremony was executed properly, as well as instructions on hardware,
|
||||||
|
software and location that should be used. Each step of the ceremony is
|
||||||
|
carefully planned, and executed accordingly.
|
||||||
|
|
||||||
|
## Location Key
|
||||||
|
Is a asymmetric key pair which is used for encrypting shards which are used to
|
||||||
|
re-assemble the Root Entropy. Location Keys are stored in [Locations](locations.md)
|
||||||
|
which adhere to a strict set of criteria to maximize their security. The location
|
||||||
|
smart card passphrase is encrypted to a Operator Key in order to secure access
|
||||||
|
to it.
|
||||||
|
|
||||||
|
## M of N
|
||||||
|
M is the minimum number of shards required to reassemble the secret, and N is the
|
||||||
|
total number of shards that exist. The minimum recommended threshold is 2-of-3.
|
||||||
|
|
||||||
|
## Organization
|
||||||
|
An organization which owns the QKM and is responsible for funding the setup and
|
||||||
|
maintenance. The organization is also responsible for ensuring that the
|
||||||
|
[Warehouse](#warehouse) is properly maintained in order to ensure that the
|
||||||
|
ciphertext blobs associated with the system are redundantly stored and
|
||||||
|
protected.
|
||||||
|
|
||||||
|
## Witness
|
||||||
|
An individual who attests the ceremony was performed according to specification
|
||||||
|
in order to have additional assurances the cryptographic material, most
|
||||||
|
importantly the Root Entropy was never exposed.
|
||||||
|
|
||||||
|
## Warehouse
|
||||||
|
* Online storage for encrypted data replicated across multiple providers
|
||||||
|
* All data in DR Warehouse can only be decrypted by the DR Key
|
||||||
|
* Tolerate loss of any single provider by duplicating data to all of them
|
||||||
|
* Storage backends can be any combination of the following:
|
||||||
|
* S3 Compatible object stores:
|
||||||
|
* AWS, Google Cloud, DigitalOcean, Azure, etc.
|
||||||
|
* [Version Control Systems](software.md#version-control-system-vcs):
|
||||||
|
* We tolerate a loss of all but one DR storage backend
|
||||||
|
* A minimum of three storage backends should be maintained
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Destroying Hardware
|
||||||
|
|
||||||
|
Destroying hardware should be done by using a combination of:
|
||||||
|
|
||||||
|
* Degaussing
|
||||||
|
|
||||||
|
* Burning
|
||||||
|
|
||||||
|
* Shredding
|
||||||
|
|
||||||
|
All three methods should be used because of the efficacy of using electron
|
||||||
|
microscopy to read data from storage drives which have not been completely
|
||||||
|
destroyed.
|
||||||
|
|
||||||
|
Drilling through the storage drive, a common hardware destruction method, is not
|
||||||
|
considered to be secure.
|
||||||
|
|
||||||
|
In the best case scenario, the hardware should be melted in a foundry, as this
|
||||||
|
makes it impossible to retrieve any data by any means.
|
||||||
|
|
@ -0,0 +1,98 @@
|
||||||
|
# Hardware
|
||||||
|
|
||||||
|
This page describes different equipment which is required, and makes opinionated
|
||||||
|
recommendations as well as alternatives. One may improve the overall security
|
||||||
|
of their system by using a variety of hardware in order to benefit from their
|
||||||
|
diversity, by reducing the likelihood that all hardware has suffered the same
|
||||||
|
kind of hardware supply chain compromise, has the same vulnerability present, or
|
||||||
|
has the same type of hardware failure issue.
|
||||||
|
|
||||||
|
Based on the decided upon [Quorum](selecting-quorum.md), the amount of equipment
|
||||||
|
required to set up a [QKM](glossary.md#quroum-kms-QKM) will
|
||||||
|
vary. In order to figure out what equipment is required, decide on a Quorum,
|
||||||
|
which is expressed as "N of M". Once you know your M, the required equipment list
|
||||||
|
is the following:
|
||||||
|
|
||||||
|
* M x 4 Smart Cards
|
||||||
|
|
||||||
|
* It is recommended to use two Smart Cards for storing each key pair
|
||||||
|
|
||||||
|
* Ideally two different types of hardware are used in order to reduce the
|
||||||
|
risk of simultaneous failure
|
||||||
|
|
||||||
|
* At least 1 Smart Card is required for each Operator Key and 1 Smart Card
|
||||||
|
for each Location Key
|
||||||
|
|
||||||
|
* The number of Operator Keys is M, and the number of Location Keys is also
|
||||||
|
M, hence the minimum of 2 x M Smart Cards, with the recommendation of using
|
||||||
|
two smart cards for each, resulting in 4 x M Smart Cards
|
||||||
|
|
||||||
|
* 2 + X Storage Devices
|
||||||
|
|
||||||
|
* 1 Storage Device for [AirgapOS](repeat-use-airgapos.md)
|
||||||
|
|
||||||
|
* 1 Storage Device for storing [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
|
||||||
|
|
||||||
|
* X, or *any* number of additional Storage Devices to duplicate the data, a
|
||||||
|
good measure would be to have at least 3 Storage Devices for the ceremony
|
||||||
|
|
||||||
|
* Librem 14 Laptop
|
||||||
|
|
||||||
|
* Get as many laptops as desired to satisfy your operational needs
|
||||||
|
|
||||||
|
* For each Librem 14, get a Librem Smart Card used for [PureBoot](initialize-pureboot-smart-card.md)
|
||||||
|
|
||||||
|
## Smart Cards
|
||||||
|
|
||||||
|
Smart Cards are primarily used for storing OpenPGP cryptographic keys which are
|
||||||
|
used as a building block for security controls. These smart cards hold OpenPGP
|
||||||
|
keys which are derived in secure environments.
|
||||||
|
|
||||||
|
There are two primary requirements for smart cards:
|
||||||
|
|
||||||
|
* FIPS 140-2
|
||||||
|
|
||||||
|
* Support for Ed25519 OpenPGP
|
||||||
|
|
||||||
|
* Touch for enacting operations
|
||||||
|
|
||||||
|
Some options include:
|
||||||
|
|
||||||
|
* NitroKey 3 - because of its open source approach which helps improve the
|
||||||
|
overall security of the products
|
||||||
|
|
||||||
|
* YubiKey 5 - because of the widespread use and battle-tested reliability
|
||||||
|
|
||||||
|
* Librem Key - because of the manufacturer's approach to hardware supply chain
|
||||||
|
security and verifiable software
|
||||||
|
|
||||||
|
## Air-Gapped Computer
|
||||||
|
[Air-Gapped](glossary.md#Air-Gapped) computers are used for the lifecycle management
|
||||||
|
of cryptographic material that is part of QKM.
|
||||||
|
|
||||||
|
The primary hardware recommendation for a Air-Gapped Computer is the [Librem 14](https://puri.sm/products/librem-14/), manufactured by [Purism](puri.sm). Purism specializes in reducing hardware and
|
||||||
|
firmware security risks, especially via their [Anti-Interdiction Service](https://puri.sm/posts/anti-interdiction-services/) and [PureBoot](https://docs.puri.sm/PureBoot.html)
|
||||||
|
and as such is an excellent choice for hardware which high integrity assurance is
|
||||||
|
required for.
|
||||||
|
|
||||||
|
#### Alternative
|
||||||
|
|
||||||
|
An alternative approach is to use an off-the-shelf computer that is randomly
|
||||||
|
selected right before the ceremony, removing the radio cards from it, using it
|
||||||
|
to conduct a Ceremony, and then destroying the laptop using sufficiently
|
||||||
|
adequate method to ensure that no data forensics can be used to recover the data
|
||||||
|
from the drive, or memory. This can be achieved by using a combination of
|
||||||
|
incineration, degaussing, shredding and drilling. Special care should be taken
|
||||||
|
to completely destroy all components of the computer that are able to store data,
|
||||||
|
even if it's only in ephemeral form as some forensic methods all extraction of
|
||||||
|
data from components with "temporary memory".
|
||||||
|
|
||||||
|
Three letter agencies are known to collect and exploit physical destroyed drives,
|
||||||
|
as data can still be extracted from them using methods such as electron
|
||||||
|
microscopy, therefore a combination of degaussing, shredding and burning should
|
||||||
|
be used, and the remaining debris should be spread out across multiple disposal
|
||||||
|
locations.
|
||||||
|
|
||||||
|
## Storage Device
|
||||||
|
Can be an SD Card or USB Drive but should be procured from a vendor with
|
||||||
|
a good reputation, and ideally hardware of industrial grade should be prioritized.
|
||||||
|
|
@ -0,0 +1,77 @@
|
||||||
|
# Hybrid Key Provisioning
|
||||||
|
|
||||||
|
This document contains instructions on how Operators collaborate to set up
|
||||||
|
QKM where the Operator Keys and Location Keys were generated before this
|
||||||
|
ceremony and only the PGP Public Certificates of the Location keys are brought
|
||||||
|
to the ceremony which are used to shard the Root Entropy. This is useful
|
||||||
|
when conducting the ceremony in a lower trust environment, and where not all
|
||||||
|
aspects of the ceremony can be controlled to the desired degree.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Prior to the ceremony, set up a git repository with relevant artifacts in it,
|
||||||
|
and create Ceremony Notes according to [this](one-time-repository-setup.md)
|
||||||
|
guide.
|
||||||
|
|
||||||
|
2. Ensure there are additional witnesses for the ceremony, outside of the
|
||||||
|
operators to assist in monitoring and verifying the integrity of the process.
|
||||||
|
|
||||||
|
* Designate at least 1 individual to keep notes on the ceremony based
|
||||||
|
on the [Ceremony Log Template](ceremony-log-template.md)
|
||||||
|
|
||||||
|
3. Ensure that no participants have brought digital devices other than ones
|
||||||
|
necessary for the ceremony. A faraday bag may be used to hold any such devices
|
||||||
|
for the duration of the ceremony.
|
||||||
|
|
||||||
|
4. Procure a laptop and SD cards (3) from a randomly selected store and
|
||||||
|
ensure at least 2 people are in line of sight of all the hardware until the
|
||||||
|
ceremony is executed. It may be worthwhile to try booting from the SD card at
|
||||||
|
the store. Dell laptops tend to support booting from SD cards while Lenovo
|
||||||
|
don't. More notes on selecting hardware can be found [here](one-time-use-hardware-procurement.md)
|
||||||
|
|
||||||
|
5. Secure a [Location](one-time-use-locations.md)
|
||||||
|
|
||||||
|
6. Each member needs to bring their:
|
||||||
|
|
||||||
|
* Ceremony Notes
|
||||||
|
|
||||||
|
* Ceremony SD Card
|
||||||
|
|
||||||
|
* Airgap SD Card (only 1 member needs to bring this - set up according to
|
||||||
|
[One Time Use / AirgapOS Setup](one-time-use-airgapos.md)).
|
||||||
|
|
||||||
|
7. Verify the SD card by either:
|
||||||
|
|
||||||
|
* Booting a separate AirgapOS to the machine used for the ceremony in order
|
||||||
|
to verify the SD card is not writeable and the hash matches using the steps
|
||||||
|
from the [One Time Use/ AirgapOS Setup](one-time-use-airgapos.md) guide.
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
* Mounting the SD card to a separate machine and verifying it's not
|
||||||
|
writeable and verify the hash matches using steps from the [One Time Use/AirgapOS Setup](one-time-use-airgapos.md) guide.
|
||||||
|
|
||||||
|
* NOTE: It is essential that the SD card remain in line of sight from the
|
||||||
|
moment it is verified to the moment is is used.
|
||||||
|
|
||||||
|
8. Plug in and boot from Airgap SD card:
|
||||||
|
|
||||||
|
* Boot from internal SD card reader or USB device reader
|
||||||
|
|
||||||
|
* Verify the `sha256sum ceremony.sh` hash matches each of the Operator's
|
||||||
|
"Ceremony Notes"
|
||||||
|
|
||||||
|
9. Button mash to ensure adequate entropy on the OS
|
||||||
|
|
||||||
|
10. Set the system time as it has to be after the PGP
|
||||||
|
public certificates were created, and before they expire:
|
||||||
|
|
||||||
|
* `date -s "YYYY-MM-DD HH:MM:SS"`
|
||||||
|
|
||||||
|
10. Run `ceremony.sh`
|
||||||
|
|
||||||
|
11. Back up the `shardfile`, and `pub.asc` to 3 separate SD cards,
|
||||||
|
one for each operator
|
||||||
|
|
||||||
|
12. Destroy the computer according to [Hardware Destruction](hardware-destruction.md)
|
||||||
|
guide.
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
|
|
@ -0,0 +1,151 @@
|
||||||
|
# PureBoot Setup
|
||||||
|
|
||||||
|
This guide walks the user through setting up a machine which relies on
|
||||||
|
[PureBoot](https://source.puri.sm/firmware/pureboot) to verify the authenticity
|
||||||
|
of the .iso image which is being booted, as well to ensure that firmware of the
|
||||||
|
machine has not been tampered with between uses.
|
||||||
|
|
||||||
|
This guide assumes the use of a Purism machine, with a Librem Key.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
* 1 Storage Device
|
||||||
|
|
||||||
|
* 1 Librem Smart Card
|
||||||
|
|
||||||
|
* 1 Librem 14 Computer with [PureBoot firmware installed](flash-pureboot-firmware.md).
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
After you complete this setup, the Librem Smart Card will be provisioned with a
|
||||||
|
new GPG key pair, which will be used for signing the BIOS, as well as any `.iso`
|
||||||
|
images which will be booted using the [Restricted Boot](https://docs.puri.sm/PureBoot/Restricted.html)
|
||||||
|
mode.
|
||||||
|
|
||||||
|
At the end of this guide you will have:
|
||||||
|
|
||||||
|
* 1 Librem Smart Card
|
||||||
|
|
||||||
|
* With a newly generated GPG key pair
|
||||||
|
|
||||||
|
* With a newly generated HOTP secret
|
||||||
|
|
||||||
|
* 1 storage device with the public key of the newly generated GPG key
|
||||||
|
|
||||||
|
* This GPG key will be used to sign `.iso` files booted on the machine
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Plug in the Librem Smart Card into the machine
|
||||||
|
|
||||||
|
2. Turn on the machine
|
||||||
|
|
||||||
|
3. Wait for the prompt that says "Automatic boot in 5 seconds unless interrupted
|
||||||
|
by keypress..."
|
||||||
|
|
||||||
|
* Press *any* key
|
||||||
|
|
||||||
|
4. Select "Options -->"
|
||||||
|
|
||||||
|
* Press Enter
|
||||||
|
|
||||||
|
5. Select "GPG Options" -->
|
||||||
|
|
||||||
|
* Press Enter
|
||||||
|
|
||||||
|
6. Select "Generate GPG keys manually on a Librem Key"
|
||||||
|
|
||||||
|
* Press Enter
|
||||||
|
|
||||||
|
7. Please Confirm that your GPG card is inserted [Y/n/]
|
||||||
|
|
||||||
|
* Input "Y", press Enter
|
||||||
|
|
||||||
|
8. $ gpg/card>
|
||||||
|
|
||||||
|
* Input `admin`, press Enter
|
||||||
|
|
||||||
|
9. $ gpg/card>
|
||||||
|
|
||||||
|
* Inpuut `generate`, press Enter
|
||||||
|
|
||||||
|
10. Make off-card backup of encryption key (Y/n):
|
||||||
|
|
||||||
|
* Input "n", Press Enter
|
||||||
|
|
||||||
|
11. Replace existing keys? (y/n):
|
||||||
|
|
||||||
|
* Input "y", press Enter
|
||||||
|
|
||||||
|
12. PIN: <user pin> (default is 123456)
|
||||||
|
|
||||||
|
* Input `user_pin`, press Enter
|
||||||
|
|
||||||
|
13. Key is valid for? (0):
|
||||||
|
|
||||||
|
* Press Enter
|
||||||
|
|
||||||
|
14. Key does not expire at all. Is this correct? (y/N):
|
||||||
|
|
||||||
|
* Input "y", press Enter
|
||||||
|
|
||||||
|
15. Real name: <name>
|
||||||
|
|
||||||
|
* Note: You must supply at least one of the "Real name", "Email address"
|
||||||
|
or "Comment"
|
||||||
|
* Input one of the values, and press Enter
|
||||||
|
|
||||||
|
16. Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?
|
||||||
|
|
||||||
|
* Input "O", press Enter
|
||||||
|
|
||||||
|
17. Admin PIN: <admin pin> (default is 12345678)
|
||||||
|
|
||||||
|
* Input `admin_pin`, press Enter
|
||||||
|
|
||||||
|
18. After step q, the generation of the key will take some time then you will
|
||||||
|
see a prompt:
|
||||||
|
```
|
||||||
|
gpg: key<ID> market as ultimately trusted
|
||||||
|
gpg: directory '//.gnupg/openpgp-revocs.d' created
|
||||||
|
gpg: recovation certificate stored as '//.gnupg/openpgp-revocs.d/<ID>.rev'
|
||||||
|
public and secret key created and signed
|
||||||
|
```
|
||||||
|
|
||||||
|
19. $ gpg/card>
|
||||||
|
|
||||||
|
* Input "quit", press Enter
|
||||||
|
|
||||||
|
20. "Would you like to copy the GPG public key you generated to a USB disk?
|
||||||
|
You may need it, if you want to use it outside of Heads later.
|
||||||
|
The file will show up as <ID>.asc"
|
||||||
|
|
||||||
|
* Ensure a USB drive is connected
|
||||||
|
|
||||||
|
* Select "Yes", press Enter
|
||||||
|
|
||||||
|
21. "Would you like to add the GPG public key you generated to the BIOS?
|
||||||
|
This makes it a trusted key used to sign files in /boot"
|
||||||
|
|
||||||
|
* Select "Yes", press Enter
|
||||||
|
|
||||||
|
22. "Would you like to update the checksum and sign all of the files in /boot?
|
||||||
|
You will need your GPG key to continue and this will modify your disk
|
||||||
|
Otherwise the system will reboot immediately."
|
||||||
|
|
||||||
|
* Select "Yes", press Enter
|
||||||
|
|
||||||
|
23. Please confirm that your GPG card is inserted [Y/n]:
|
||||||
|
|
||||||
|
* Input "Y", press Enter
|
||||||
|
|
||||||
|
24. After the computer reboots you will be faced with an error:
|
||||||
|
"ERROR: PureBoot couldn't generate the TOTP code."
|
||||||
|
|
||||||
|
* Select "Generate new HOTP/TOTP secret", press Enter
|
||||||
|
|
||||||
|
25. "This will erase your old secret and replace it with a new one! Do you want
|
||||||
|
to proceed?"
|
||||||
|
|
||||||
|
* Select "Yes", press Enter
|
||||||
|
|
||||||
|
|
@ -0,0 +1,69 @@
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
Quorum Key Management (QKM) is an open source system of playbooks and
|
||||||
|
tooling which facilitates the creation and maintenance of highly resilient
|
||||||
|
Quorum-based Key Management Systems based on a strict [threat model](threat-model.md)
|
||||||
|
which can be used for a variety of different cryptographic algorithms. The
|
||||||
|
system was designed and developed by [Distrust](https://distrust.co), with the
|
||||||
|
generous support of the following sponsors: TODO.
|
||||||
|
|
||||||
|
The basic premise of QKM is that primary cryptographic material akin to a root
|
||||||
|
certificate, called Root Entropy, is derived during a secure key derivation
|
||||||
|
ceremony, and then used to derive chosen cryptographic material via different
|
||||||
|
algorithms such as PGP keys, digital asset wallets, web certificates and more.
|
||||||
|
The system was designed with extensibility in mind.
|
||||||
|
|
||||||
|
The Root Entropy is sharded using [Shamir's Secret Sharing](glossary.md#shamirs-secret-sharing-sss) to a [Quorum](glossary.md#quorum) in order to
|
||||||
|
protect it from single points of failure, requiring cooperation of multiple
|
||||||
|
individuals - a quorum, and use of cryptographic material stored in separate
|
||||||
|
physical locations with significant access controls in order to reconstruct the
|
||||||
|
secret material, namely the Root Entropy.
|
||||||
|
|
||||||
|
## Use Cases
|
||||||
|
|
||||||
|
QKM can be used for a wide range of use-cases which span but are not limited
|
||||||
|
to:
|
||||||
|
|
||||||
|
* Deriving a PGP key pair whose public key can be used as a "one-way deposit
|
||||||
|
box" - for example a company can back up keys for their digital asset wallets by
|
||||||
|
encrypting them to the public key and storing the encrypted ciphertext blobs on
|
||||||
|
multiple cloud storage platforms, or on offline hard drives for redundancy.
|
||||||
|
|
||||||
|
* Deriving PGP keys for multiple individual users in a deterministic manner.
|
||||||
|
|
||||||
|
* Deriving wallets for digital assets using BIP-0032 style derivation as part of
|
||||||
|
a cold signing setup.
|
||||||
|
|
||||||
|
* Decrypting data in a secure, quorum protected, air-gapped environment.
|
||||||
|
|
||||||
|
* Generating digital certificates
|
||||||
|
|
||||||
|
## Playbooks
|
||||||
|
|
||||||
|
QKM can be set up by using a set of highly opinionated playbooks which outline
|
||||||
|
the process. The documentation should be read in its entirety by all
|
||||||
|
participants in the ceremony in order to ensure that the system is well
|
||||||
|
understood by all in order to ensure that the integrity of the process is
|
||||||
|
preserved and enforced by all participants.
|
||||||
|
|
||||||
|
## Directives
|
||||||
|
|
||||||
|
The documentation provides directives in order to specify the importance of
|
||||||
|
adhering to parts of the specification as follows to achieve high levels of
|
||||||
|
security:
|
||||||
|
|
||||||
|
* **MUST** - not adhering to this will result in significant deterioration of
|
||||||
|
security properties of the system
|
||||||
|
|
||||||
|
* **SHOULD** - is recommended and may impact the security of the system
|
||||||
|
depending on the context
|
||||||
|
|
||||||
|
* **MAY** - is typically a design decision with no significant impact to the
|
||||||
|
overall security of the system
|
||||||
|
|
||||||
|
## Method
|
||||||
|
|
||||||
|
The reader is encouraged to read through the entire body of documents which
|
||||||
|
should not take more than 30 minutes. If any parts are unclear, they may contact
|
||||||
|
Distrust for clarification, which is welcomed as it will aid improving the
|
||||||
|
documentation.
|
||||||
|
|
@ -0,0 +1,53 @@
|
||||||
|
# Local Key Provisioning
|
||||||
|
|
||||||
|
This document contains instructions on how Operators collaborate to set up
|
||||||
|
QKM which requires an N-of-M quorum to be reconstituted. The encrypted shards
|
||||||
|
which result from this ceremony are stored in separate physical
|
||||||
|
[Locations](locations.md) which contain [Location Keys](glossary.md#location-key)
|
||||||
|
to which shards are encrypted, and whose passphrases are protected using
|
||||||
|
[Operator Keys](glossary#operator-key).
|
||||||
|
|
||||||
|
|
||||||
|
### Requirements
|
||||||
|
|
||||||
|
* [Smart Card](hardware.md#smart-cards): whatever number of smart
|
||||||
|
cards you would like to have seeded for each Operator, usually 2 per Operator is
|
||||||
|
recommended - one NitroKey 3 and 1 YubiKey Series 5.
|
||||||
|
|
||||||
|
* [Storage Devices](hardware.md#storage-device): as many storage
|
||||||
|
devices as you would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
|
||||||
|
|
||||||
|
* Storage Device loaded with
|
||||||
|
* [airgap.iso](repeat-use-airgapos.md)
|
||||||
|
* [airgap.iso.asc](repeat-use-airgapos.md)
|
||||||
|
* [autorun.sh](autorun-sh-setup.md)
|
||||||
|
|
||||||
|
* All participants need Ceremony Notes which contain a record of which they
|
||||||
|
verified and wrote down themselves:
|
||||||
|
* The SHA256 hash of airgap.iso
|
||||||
|
* The SHA256 hash of autorun.sh
|
||||||
|
|
||||||
|
### Steps
|
||||||
|
|
||||||
|
1. Bring the Ceremony Machine and [Quorum Team](quorum-team.md) into the
|
||||||
|
established [Location](locations.md)
|
||||||
|
|
||||||
|
2. Ensure that no participants have brought digital devices other than ones
|
||||||
|
necessary for the ceremony. A faraday bag may be used to hold any such devices
|
||||||
|
for the duration of the ceremony.
|
||||||
|
|
||||||
|
3. Plug in a new Storage Device
|
||||||
|
|
||||||
|
4. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
|
||||||
|
|
||||||
|
5. As prompted plug in new Smart Cards
|
||||||
|
|
||||||
|
6. Once the ceremony is complete, make as many copies of the Storage Device
|
||||||
|
from Step 3 as desired.
|
||||||
|
|
||||||
|
7. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
|
||||||
|
for storage of the Operator Smart Cards and Location Smart Cards
|
||||||
|
|
||||||
|
8. Follow the [Public Ceremony Artifacts Storage](public-ceremony-artifact-storage.md)
|
||||||
|
guide for all public artifacts produced during the ceremony
|
||||||
|
|
||||||
|
|
@ -0,0 +1,119 @@
|
||||||
|
# Location Key Provisioning
|
||||||
|
|
||||||
|
## Description
|
||||||
|
This ceremony is for generating Location Keys. Location Keys are typically
|
||||||
|
stored in vaults as prescribed in the [Secure Storage Guidelines](secure-storage-guidelines.md).
|
||||||
|
Location Keys are keypairs to which the Root Entropy of a QKM is sharded. The
|
||||||
|
keypairs are stored exclusively on Smart Cards, and the PINs which protect the
|
||||||
|
Smart Cards are encrypted to Operator Keys.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
* Smart Card(s): whatever number of smart cards you would like to have seeded
|
||||||
|
for each Operator, usually 2 per Operator is recommended - one NitroKey 3 and
|
||||||
|
1 YubiKey Series 5.
|
||||||
|
|
||||||
|
* [Storage Devices](equipment.md#storage-device): as many storage devices as you
|
||||||
|
would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Bring the Ceremony Machine and [Quorum Team](quorum-team.md) into the
|
||||||
|
established [Location](locations.md)
|
||||||
|
|
||||||
|
2. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
|
||||||
|
or the [One Time Use Airgap-OS](one-time-use-airgapos.md)
|
||||||
|
|
||||||
|
3. Provision new key in the selected secure environment
|
||||||
|
|
||||||
|
* Set system time to date greater than operator key creation but less than
|
||||||
|
operator key expiry
|
||||||
|
|
||||||
|
* `date -s "YYYY-MM-DD HH:MM:SS"`
|
||||||
|
|
||||||
|
* Load your personal PGP certificate which will be used as the Operator
|
||||||
|
Key in to the local keyring
|
||||||
|
|
||||||
|
* `gpg --import /media/<operator_key_id>`
|
||||||
|
|
||||||
|
* Generate the mnemonic:
|
||||||
|
|
||||||
|
* `keyfork mnemonic generate --size 256 > mnemonic.txt`
|
||||||
|
|
||||||
|
* Write the mnemonic on a small piece of paper as you will need to enter the
|
||||||
|
words in the next step. After entering the words, set the piece of paper
|
||||||
|
on fire (that's why it should be small enough - to make burning it easy)
|
||||||
|
|
||||||
|
* In a new terminal window start `keyfork` daemon with the mnemonic:
|
||||||
|
|
||||||
|
* `export KEYFORKD_SOCKET_PATH=/tmp/keyforkd.socket`
|
||||||
|
|
||||||
|
* `keyfork recover mnemonic`
|
||||||
|
|
||||||
|
* ctrl + z
|
||||||
|
|
||||||
|
* `bg`
|
||||||
|
|
||||||
|
* Derive PGP keypair:
|
||||||
|
|
||||||
|
* `keyfork derive openpgp "Location Key: Distrust Disaster Recovery" > location.priv.asc`
|
||||||
|
|
||||||
|
* Provision two YubiKey:
|
||||||
|
|
||||||
|
* To get the `smart_card_id`: `oct list`
|
||||||
|
|
||||||
|
* `oct admin --card <smart_card_id> import location.priv.asc`
|
||||||
|
|
||||||
|
* `keyfork mnemonic generate --size 256 | awk '{ print $1, $2, $3, $4, $5 }' > smart-card-pin.txt`
|
||||||
|
|
||||||
|
* `cat smart-card-pin.txt`
|
||||||
|
|
||||||
|
* `oct pin --card <smart_card_id> set-user`
|
||||||
|
|
||||||
|
* Enter the <smart_card_pin>
|
||||||
|
|
||||||
|
* `oct pin --card <smart_card_id> set-admin`
|
||||||
|
|
||||||
|
* Enter the <smart_card_pin>
|
||||||
|
|
||||||
|
* Import PGP key into keyring
|
||||||
|
|
||||||
|
* `gpg --import location.priv.asc`
|
||||||
|
|
||||||
|
* Encrypt and back up the `mnemonic.txt`
|
||||||
|
|
||||||
|
* `gpg -er <operator_key_id> mnemonic.txt`
|
||||||
|
|
||||||
|
* `cp mnemonic.txt.gpg /media`
|
||||||
|
|
||||||
|
* Encrypt and back up the `smart-card-pin`
|
||||||
|
|
||||||
|
* `gpg -er <operator_key_id> smart-card-pin.txt`
|
||||||
|
|
||||||
|
* `cp smart-card-pin.txt.gpg /media`
|
||||||
|
|
||||||
|
* Export and back up `location.pub.asc`
|
||||||
|
|
||||||
|
* `gpg --armor --export <location_key_id> > location.pub.asc`
|
||||||
|
|
||||||
|
* `cp location.pub.asc /media`
|
||||||
|
|
||||||
|
* Duplicate all backup files to a second SD card:
|
||||||
|
|
||||||
|
* `mnemonic.txt.gpg`, `smart-card-pin.gpg`, `location.pub.asc`
|
||||||
|
|
||||||
|
* Copy the `location.pub.asc` to the SD card that was used to bring over
|
||||||
|
the operator key. This will be used to bring the public key to the Hybrid
|
||||||
|
Ceremony Later on:
|
||||||
|
|
||||||
|
* `cp location.pub.asc /media`
|
||||||
|
|
||||||
|
* For posterity, delete all the generated assets before shutting down
|
||||||
|
computer:
|
||||||
|
|
||||||
|
* `rm -rf *`
|
||||||
|
|
||||||
|
4. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
|
||||||
|
for storage of the Operator Smart Cards and Location Smart Cards
|
||||||
|
|
||||||
|
5. Follow the [Public Ceremony Artifacts Storage](public-ceremony-artifact-storage.md)
|
||||||
|
guide for all public artifacts produced during the ceremony
|
||||||
|
|
@ -0,0 +1,72 @@
|
||||||
|
# Location
|
||||||
|
|
||||||
|
Locations refer to physical points in space which are used for storing
|
||||||
|
cryptographic material or performing actions related to the DRK lifecycle and
|
||||||
|
adhere to a set of criteria which focus on achieving a high level of security -
|
||||||
|
specifically with respect to:
|
||||||
|
|
||||||
|
* Protecting access to devices which store cryptographic material
|
||||||
|
|
||||||
|
* Mitigating the risk stemming from natural disaster and other black swan events
|
||||||
|
such as civil unrest or war.
|
||||||
|
|
||||||
|
* Reducing the risk of exposing cryptographic material, for example via
|
||||||
|
side-channel attacks
|
||||||
|
|
||||||
|
There are three sub-types of Locations, one which is used for performing
|
||||||
|
any actions related to the management of the cryptographic material life-cycle
|
||||||
|
and is referred to as the Management Location, one for long term secure
|
||||||
|
storage of cryptographic material such as Smart Cards which are used to decrypt
|
||||||
|
[Shards](glossary.md#shard), referred to as a Storage Location, and a location
|
||||||
|
for Ceremonies, known as the Ceremony Location.
|
||||||
|
|
||||||
|
The Storage Location has a shorter list of requirements while the Management
|
||||||
|
and Ceremony locations have a number of additional requirements. The Management
|
||||||
|
and Ceremony Location may be one and the same.
|
||||||
|
|
||||||
|
## All Locations
|
||||||
|
|
||||||
|
* MUST have physical access restrictions which require identification
|
||||||
|
|
||||||
|
* MUST have the ability to require more than 1 person to gain access
|
||||||
|
|
||||||
|
* This control can be both physical, for example in vaults which require 2
|
||||||
|
keys for access AND/OR process level, where the personnel of the facility
|
||||||
|
may verify the identity of one or more individuals
|
||||||
|
|
||||||
|
* SHOULD have anti-fire systems
|
||||||
|
|
||||||
|
* SHOULD have anti-flood systems
|
||||||
|
|
||||||
|
|
||||||
|
## Management & Ceremony Locations
|
||||||
|
|
||||||
|
* MUST not have cameras installed
|
||||||
|
|
||||||
|
* MUST not have windows with direct line of sight to monitors
|
||||||
|
|
||||||
|
* MUST have all walls protected with EM shielding which adheres to the TEMPEST
|
||||||
|
standard NATO SDIP-27 Level A
|
||||||
|
|
||||||
|
* SHOULD be organizations which are ideally immune to being legally subpoenaed
|
||||||
|
|
||||||
|
* SHOULD NOT be susceptible to being subpoenaed
|
||||||
|
|
||||||
|
## Storage Location
|
||||||
|
|
||||||
|
* MUST have anti-fire systems
|
||||||
|
|
||||||
|
* MUST have anti-flood systems
|
||||||
|
|
||||||
|
* MUST have 24/7 security monitoring
|
||||||
|
|
||||||
|
* MUST be in different geographic locations
|
||||||
|
|
||||||
|
* This ensures that natural disasters are not likely to impact multiple
|
||||||
|
locations simultaneously
|
||||||
|
|
||||||
|
* SHOULD be facilities owned by different organizations to reduce the risk of
|
||||||
|
collusion unless the organization who owns the DRK has their own facility such
|
||||||
|
as a SCIF (Secure Compartmentalized Information Facility)
|
||||||
|
|
||||||
|
* SHOULD have seismic detectors
|
||||||
|
|
@ -0,0 +1,54 @@
|
||||||
|
# Repository Setup
|
||||||
|
|
||||||
|
Before the one time ceremony, a git repository should be set up which contains
|
||||||
|
several items which will be relevant to the ceremony. Namely the following:
|
||||||
|
|
||||||
|
* PGP public certificates of the Location Keys which will be used for the
|
||||||
|
ceremony. The key ids of these certificates will be verified during the
|
||||||
|
ceremony.
|
||||||
|
|
||||||
|
* `ceremony.sh` a script which imports the PGP public certificates of the
|
||||||
|
location keys, and displays their ids so that Operators can verify that they are
|
||||||
|
the correct ones. This script will also execute the appropriate `keyfork`
|
||||||
|
command with a desired threshold:
|
||||||
|
```
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
script_dir="$(dirname "$(realpath "$0")")"
|
||||||
|
|
||||||
|
read -p "Provide the absoute path to PGP certificates which will be used for the ceremony: " directory_path
|
||||||
|
|
||||||
|
if [ ! -d "$directory_path" ]; then
|
||||||
|
echo "Directory does not exist. Please enter a valid directory path."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
for file in "$directory_path"/*; do
|
||||||
|
if [ -f "$file" ]; then
|
||||||
|
echo "Processing file: $file"
|
||||||
|
gpg --import --import-options import-show $file
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
read -p "Do the PGP key IDs match what you expect? (y/n): " matches_expectation
|
||||||
|
|
||||||
|
if [ $matches_expectation != "y" ]; then
|
||||||
|
echo "Ceasing ceremony as PGP key IDs don't match"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
keyfork wizard bottoms-up --threshold 2 --output-cert /media/cert --output-shardfile /media/shardfile --user-id "Distrust Key Ceremony" public-certificates/
|
||||||
|
```
|
||||||
|
|
||||||
|
* The `airgap.iso` which is to be used during the ceremony
|
||||||
|
|
||||||
|
* Each operator should produce Ceremony Notes which contain:
|
||||||
|
|
||||||
|
* `sha256sum` of `airgap.iso`
|
||||||
|
|
||||||
|
* The AirgapOS commit and date for the version that was used
|
||||||
|
|
||||||
|
* `sha256sum` of `ceremony.sh`
|
||||||
|
|
||||||
|
* Key ID of each PGP Public Certificate located in `public-certificates`
|
||||||
|
in the ceremony repository
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
# Set up AirgapOS
|
||||||
|
|
||||||
|
Because without a Librem 14 there is no easy way to have a secure boot sequence,
|
||||||
|
instead the AirgapOS `.iso` image is flashed to an SD card, locked using
|
||||||
|
`sdtool` and then verified using any machine.
|
||||||
|
|
||||||
|
## Setup Steps
|
||||||
|
|
||||||
|
* Clone the latest AirgapOS version:
|
||||||
|
|
||||||
|
* `git clone git@distrust.co:public/airgap.git`
|
||||||
|
|
||||||
|
* Build the image:
|
||||||
|
|
||||||
|
* `cd airgap && make`
|
||||||
|
|
||||||
|
* Flash `airgap.iso` to an SD Card:
|
||||||
|
|
||||||
|
* `dd if=out/airgap.iso of=/dev/<your_device> bs=4M status=progress oflag=direct`
|
||||||
|
|
||||||
|
* Use the `sdtool` to lock the SD Card:
|
||||||
|
|
||||||
|
* `git clone git@github.com:BertoldVdb/sdtool.git`
|
||||||
|
|
||||||
|
* `cd sdtool`
|
||||||
|
|
||||||
|
* `make`
|
||||||
|
|
||||||
|
* `./sdtool /dev/mmcblk permlock`
|
||||||
|
|
||||||
|
* Test that the card can't be written to:
|
||||||
|
|
||||||
|
* `dd if=out/airgap.iso of=/dev/sdb bs=1M conv=sync status=progress`
|
||||||
|
|
||||||
|
* Verify that the hash of `airgap.iso` matches what's flashed on the SD card:
|
||||||
|
|
||||||
|
* `head -c $(stat -c '%s' out/airgap.iso) /dev/sdb | sha256sum`
|
||||||
|
* `sha256sum out/airgap.iso`
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
# Procure Hardware
|
||||||
|
|
||||||
|
* Procure a laptop, and SD cards from a randomly selected store. A randomly
|
||||||
|
selected store is used in order to reduce the possibility of a malicious actor
|
||||||
|
having time to plant compromised hardware at the store, and/or make arrangements
|
||||||
|
by coercing store staff to sell compromised hardware to the quroum team. Of
|
||||||
|
course, there still may be hardware that's compromised being sold, but not
|
||||||
|
specifically targeting the specific quorum group.
|
||||||
|
|
||||||
|
* Ensure at least 2 people are in line of sight of access to all of the
|
||||||
|
equipment, for example a bag carried in hand, until the ceremony is executed.
|
||||||
|
This is done in order to eliminate the possibility of the equipment being
|
||||||
|
swapped for compromised hardware.
|
||||||
|
|
||||||
|
* The laptop should ideally support booting from an SD card and have a built in
|
||||||
|
micro or standard SD card reader built in; if this is not possible, you will
|
||||||
|
also need to purchase a USB SD card reader.
|
||||||
|
|
||||||
|
* Dell laptops tend to have support for booting from SD cards so they are a
|
||||||
|
good option.
|
||||||
|
|
||||||
|
* The store and laptop model should be selected on the spot via consensu of at
|
||||||
|
least 2 members of the Quorum. This is done for several reasons:
|
||||||
|
|
||||||
|
* To ensure that no time is given to a malicious actor to deploy
|
||||||
|
compromised hardware to the store
|
||||||
|
|
||||||
|
* To reduce likelihood that arrangements can be made by a malicious actor
|
||||||
|
for the store to sell compromised hardware to the Quroum team
|
||||||
|
|
||||||
|
* Note that a secondary computer, or secondary SD card with bootable OS will be
|
||||||
|
required in order to be able to verify the flashed AirgapOS SD card right before
|
||||||
|
the ceremony.
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# Selecting Locations
|
||||||
|
|
||||||
|
Secure a location that is randomly selected that has a private space with EM
|
||||||
|
shielding, or no electronics in at least a 10 m radius. A moving vehicle (eg.
|
||||||
|
car, bus, train, ferris wheel) is also a viable alternative. Additionally, the
|
||||||
|
ceremony may be conducted in an open outdoor space, such as a forest, or a
|
||||||
|
desert, at a location that is not near any human made buildings. The point of
|
||||||
|
narrowing the location selection to these spaces is that it makes it hard for a
|
||||||
|
malicious actor to prepare for the ceremony and deploy equipment for
|
||||||
|
side-channel attacks - with the intent of stealing the cryptographic material
|
||||||
|
which is produced or managed during key ceremonies.
|
||||||
|
|
||||||
|
The location should be selected immediately before the ceremony in order to
|
||||||
|
eliminate the possibility of a malicious actor having time to infiltrate and
|
||||||
|
compromise the space ahead of the ceremony. The location may be compromised
|
||||||
|
anyways, as a malicious actor may have done so with another target in mind, or a
|
||||||
|
more broad campaign, for example in the case for three letter agencies may plant
|
||||||
|
cameras and microphones in hotels for intel gathering.
|
||||||
|
|
@ -0,0 +1,44 @@
|
||||||
|
# Operator Key Provisioning
|
||||||
|
|
||||||
|
## Description
|
||||||
|
This guide can be used for provisioning Operator key pairs, and the output of
|
||||||
|
the ceremony is a set of the following for each Operator:
|
||||||
|
* Smart Card(s) seeded with PGP keys
|
||||||
|
* Storage Device with a backup of:
|
||||||
|
* PGP key pair public key
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
* Smart Card(s): whatever number of smart cards you would like to have seeded
|
||||||
|
for each Operator, usually 2 per Operator is recommended - one NitroKey 3 and
|
||||||
|
1 YubiKey Series 5.
|
||||||
|
|
||||||
|
* [Storage Devices](hardware.md#storage-device): as many storage devices as you
|
||||||
|
would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
|
||||||
|
|
||||||
|
## Playbook
|
||||||
|
|
||||||
|
### Steps
|
||||||
|
This playbook allows the setup of any number of Operator Keys. For each Operator,
|
||||||
|
the steps that follow need to be repeated.
|
||||||
|
|
||||||
|
1. Bring the Ceremony Machine and [Quorum](selecting-quorum.md) team into the
|
||||||
|
established [Location](locations.md)
|
||||||
|
|
||||||
|
2. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
|
||||||
|
|
||||||
|
3. Plug in a new Storage Device
|
||||||
|
|
||||||
|
4. Run `keyfork wizard operator` TODO: this command is not part of `keyfork` yet
|
||||||
|
|
||||||
|
5. As prompted plug in new Smart Cards
|
||||||
|
|
||||||
|
6. Once the ceremony is complete, make as many copies of the Storage Device
|
||||||
|
from Step 3 as desired.
|
||||||
|
|
||||||
|
7. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
|
||||||
|
for storage of the Operator Smart Cards and Location Smart Cards
|
||||||
|
|
||||||
|
8. Follow the [Online Artifacts Storage](public-ceremony-artifact-storage.md)
|
||||||
|
guide for all public artifacts produced during the ceremony
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,44 @@
|
||||||
|
# Physical Artifact Storage
|
||||||
|
|
||||||
|
QKM requires that some of the hardware containing cryptographic material be
|
||||||
|
securely stored in physical locations. The two primary cases where physical
|
||||||
|
storage is necessary are the storage of Location Key Smart Cards, and Operator
|
||||||
|
Key Smart Cards. These Smart Cards are necessary to successfully execute a
|
||||||
|
ceremony.
|
||||||
|
|
||||||
|
There are two primary physical artifacts which need to be stored properly:
|
||||||
|
|
||||||
|
* Operator Smart Cards
|
||||||
|
|
||||||
|
* Location Smart Cards
|
||||||
|
|
||||||
|
## Operator Smart Cards
|
||||||
|
|
||||||
|
These cards should be stored by Operators in personal vaults using a high
|
||||||
|
quality hidden safe, or in a vaulting facility such as a bank vault, or a
|
||||||
|
private vaulting provider.
|
||||||
|
|
||||||
|
## Location Smart Cards
|
||||||
|
|
||||||
|
These cards should only be stored in secure vaults which meet the criteria
|
||||||
|
outlined for Storage Locations in the [Location](locations.md) document.
|
||||||
|
|
||||||
|
## Additional Criteria
|
||||||
|
|
||||||
|
* MUST apply glitter nail polish to screws/seams of hardware casing, and take
|
||||||
|
photographs. It's best to use nail polish where the glitter is of different
|
||||||
|
sizes and colors.
|
||||||
|
|
||||||
|
* MAY put the hardware in a vacuum sealed bag with confetti, and take
|
||||||
|
photographs.
|
||||||
|
|
||||||
|
* MUST place smart cards in a tamper proof bag, whose picture is taken upon
|
||||||
|
sealing, and stored along with other [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
|
||||||
|
|
||||||
|
* SHOULD provision all GPG keys to at least two smart cards, ideally made
|
||||||
|
by different manufacturers in order to decrease the likelihood that they both
|
||||||
|
simultaneously experience a hardware failure.
|
||||||
|
|
||||||
|
* SHOULD place the smart cards in anti-static bags
|
||||||
|
|
||||||
|
* SHOULD place the smart cards in a faraday bag
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
# Redundant Storage of Ceremony Artifacts
|
||||||
|
|
||||||
|
Ceremony Artifacts consist of data which is not sensitive in nature, but
|
||||||
|
essential to ongoing operation of a QKM.
|
||||||
|
|
||||||
|
The primary artifacts which are produced during the ceremony are:
|
||||||
|
|
||||||
|
* PGP Key Certificates
|
||||||
|
|
||||||
|
* Shard Files
|
||||||
|
|
||||||
|
* Pin Files
|
||||||
|
|
||||||
|
* Pictures of tamper proof measures such as tamper proof bags, glitter applied
|
||||||
|
to bags, or hardware, such as screws on the bottoms of laptops etc. Pictures
|
||||||
|
should be cryptographically signed to prevent tampering.
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
* MUST verify that all Public Artifacts generated during the Ceremonies are
|
||||||
|
present in the Ceremony Artifacts bundle.
|
||||||
|
|
||||||
|
* MUST store all Ceremony Artifacts in at least 2 different cloud storage
|
||||||
|
systems. Some options are:
|
||||||
|
|
||||||
|
* AWS S3
|
||||||
|
|
||||||
|
* Google Cloud Platform Storage
|
||||||
|
|
||||||
|
* Azure Storage
|
||||||
|
|
||||||
|
* GitHub
|
||||||
|
|
||||||
|
* The data SHOULD have proper access controls, and only be accessible to
|
||||||
|
authorized personnel who are part of the organization.
|
||||||
|
|
@ -0,0 +1,40 @@
|
||||||
|
# Quorum Team
|
||||||
|
|
||||||
|
The Quorum Team is a team of individuals who are selected to perform different
|
||||||
|
roles related to a QKM. Some of the Quorum Team members have ongoing roles,
|
||||||
|
while others may participate in a partial manner.
|
||||||
|
|
||||||
|
Depending on the type of actions performed, some or all of the members of the
|
||||||
|
Quorum may be required to participate. For example, it is recommended that there
|
||||||
|
is at least 1 witness for all sensitive actions, but having 3 witnesses during
|
||||||
|
the primary Key Derivation Ceremony can give better assurances that the most
|
||||||
|
crucial part of the ceremony was properly conducted.
|
||||||
|
|
||||||
|
The roles which are required for the Quorum Team are the following:
|
||||||
|
|
||||||
|
## Operator
|
||||||
|
Operators are individuals who protect [Smart Cards](equipment.md) which
|
||||||
|
store a [GPG Key Certificate](glossary.md#gpg-certificate), which is used
|
||||||
|
for encrypting information, such as the [Location Key](glossary.md#location-key)
|
||||||
|
PINs as well as other [Ceremony Artifacts](reduntant-storage-of-ceremony-artifacts.md).
|
||||||
|
They are also individuals who participate in Ceremonies in order to Reconstitute
|
||||||
|
the key and perform actions with it.
|
||||||
|
|
||||||
|
## Controller
|
||||||
|
Controllers are an additional optional role which can be used to protect access
|
||||||
|
to the physical locations which hold the Location Keys. Some vaulting solutions
|
||||||
|
allow for requiring more than 1 individual in order to access a vault. Multiple
|
||||||
|
Controllers may be used to protect access to physical locations - according to
|
||||||
|
risk appetite.
|
||||||
|
|
||||||
|
## Witness
|
||||||
|
Witnesses are individuals who are familiar with the QKM specification, and can
|
||||||
|
ensure that the different aspects of the system are set up correctly, and
|
||||||
|
processes carried out as they should be. The main objective of the witnesses is
|
||||||
|
to monitor and attest that processes such as the ceremonies are done according
|
||||||
|
to the strictly prescribed rules.
|
||||||
|
|
||||||
|
## Courier
|
||||||
|
This role can be fulfilled by members of the Quorum Team and their main role is
|
||||||
|
getting materials to their designated locations - the main task being getting
|
||||||
|
the Location Keys securely to their physical location.
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
# Remote Key Provisioning
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
@ -0,0 +1,61 @@
|
||||||
|
# AirgapOS Setup
|
||||||
|
This section can be completed on any machine.
|
||||||
|
|
||||||
|
AirgapOS has `keyfork` built into it for cryptographic operations such as key
|
||||||
|
derivation.
|
||||||
|
|
||||||
|
1. Clone the `AirgapOS` repository locally or download it as a zip
|
||||||
|
|
||||||
|
To clone use the following command in the terminal:
|
||||||
|
```
|
||||||
|
cd ~
|
||||||
|
git clone git@distrust.co:public/airgap.git
|
||||||
|
```
|
||||||
|
|
||||||
|
To download as a ZIP from https://git.distrust.co/public/airgap:
|
||||||
|
|
||||||
|
|
||||||
|
2. Navigate into the `airgap` repository locally, and build the iso image.
|
||||||
|
```
|
||||||
|
cd ~/airgap
|
||||||
|
make reproduce
|
||||||
|
```
|
||||||
|
The resulting iso will be located in `airgap/out/`
|
||||||
|
|
||||||
|
3. Place signed .iso on a storage device
|
||||||
|
|
||||||
|
a. Import the public key for the PureBoot Smart Card from [Initialize PureBoot Smart Card](initialize-pureboot-smart-card.md) guide.
|
||||||
|
```
|
||||||
|
gpg --import <ID>.asc
|
||||||
|
```
|
||||||
|
|
||||||
|
b. Get the GPG key ID using the command:
|
||||||
|
```
|
||||||
|
gpg --list-keys
|
||||||
|
```
|
||||||
|
It should look something like `6B61ECD76088748C70590D55E90A401336C8AAA9`
|
||||||
|
|
||||||
|
c. Sign the `airgap.iso` image using the "PureBoot Smart Card", which is
|
||||||
|
set up in [Initalize PureBoot Smart Card](initialize-pureboot-smart-card.md)
|
||||||
|
guide.
|
||||||
|
```
|
||||||
|
gpg --detach-sign --armor --default-key <ID> airgap.iso
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Copy `airgap.iso` and detached signature to a storage device
|
||||||
|
a. Select a new Storage Device which has no other files on it and plug it
|
||||||
|
into the machine that has the `airgap.iso` file and the detached GPG signature.
|
||||||
|
|
||||||
|
b. Find the name of the Storage Device using [this guide](storage-device-management.md#finding-a-storage-device-name)
|
||||||
|
|
||||||
|
d. Use the `mount` command to mount the drive
|
||||||
|
|
||||||
|
e. Copy both the `airgap.iso` and detached signature to the drive.
|
||||||
|
|
||||||
|
5. Make sure to note the `sha256sum` hash of the `airgap.iso` and write it
|
||||||
|
down on a piece of paper.
|
||||||
|
|
||||||
|
6. Multiple members of your team should build the `airgap.iso` image
|
||||||
|
independently and use `sha256sum airgap.iso` in order to hash it, then record
|
||||||
|
the value for later use. This value will be checked during Ceremonies before
|
||||||
|
booting the ISO image to ensure it can be trusted.
|
||||||
|
|
@ -0,0 +1,14 @@
|
||||||
|
# Root Entropy Ceremonies
|
||||||
|
|
||||||
|
There are 3 primary types of [Root Entropy](glossary.md#root-entropy-re)
|
||||||
|
derivation ceremonies:
|
||||||
|
|
||||||
|
* "Local": where all cryptographic material, including the Operator Keys,
|
||||||
|
Location Keys, and the Root Entropy are all generated during a single in-person
|
||||||
|
ceremony
|
||||||
|
|
||||||
|
* "Hybrid": where the Operator Keys and Location Keys are generated separately
|
||||||
|
prior to the in-person ceremony where the Root Entropy is generated
|
||||||
|
|
||||||
|
* "Remote": where all cryptographic material is generated in a decentralized
|
||||||
|
manner, remotely.
|
||||||
|
|
@ -0,0 +1,40 @@
|
||||||
|
# Secure Boot Sequence
|
||||||
|
|
||||||
|
1. Plug in the [PureBoot Smart Card](initialize-pureboot-smart-card.md)
|
||||||
|
|
||||||
|
2. Plug in [AirgapOS Storage Device](repeat-use-airgapos.md)
|
||||||
|
|
||||||
|
3. Turn on the machine
|
||||||
|
|
||||||
|
4. Press space when the message "Automatic boot in 5 seconds unless interrupted by keypress..."
|
||||||
|
|
||||||
|
5. Once in the PureBoot Boot Menu, navigate to "Options -->" and press Enter
|
||||||
|
|
||||||
|
6. Navigate to "Exit to recovery shell" and press enter
|
||||||
|
|
||||||
|
7. Use the command `source /etc/gui_functions` to load gui functions
|
||||||
|
|
||||||
|
8. Use the command `mount_usb` to mount the Storage Device which contains `airgap.iso` and the detached GPG signature.
|
||||||
|
|
||||||
|
9. Type `sha256sum /media/airgap.iso.asc`
|
||||||
|
|
||||||
|
10. Verify the hash that appears using whatever number of witnesses the Quroum
|
||||||
|
agreed are necessary for witnessing key parts of the Ceremony. Each witness
|
||||||
|
should bring their own piece of paper with the hash written out based on the
|
||||||
|
binary they built on their own system according to the [AirgapOS Setup Playbook](repeat-use-airgapos.md).
|
||||||
|
|
||||||
|
12. Once everyone is satisfied that the hash matches, the computer should be
|
||||||
|
be restarted.
|
||||||
|
|
||||||
|
13. Press space when the message "Automatic boot in 5 seconds unless interrupted by keypress..."
|
||||||
|
|
||||||
|
14. Once in the PureBoot Boot Menu, navigate to "Options -->" and press Enter
|
||||||
|
|
||||||
|
15. Navigate to "Boot Options -->" and press enter
|
||||||
|
|
||||||
|
16. Navigate to "USB boot" and press enter
|
||||||
|
|
||||||
|
17. Ensure that `/media/airgap.iso` is selected and press Enter
|
||||||
|
|
||||||
|
18. Once booted, verify the version of the software matches the AirgapOS Hash
|
||||||
|
which was noted during the [AirgapOS Setup](repeat-use-airgapos.md).
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
# Selecting a Quorum
|
||||||
|
|
||||||
|
The backbone of the Distrust Quroum system is a Quorum which is used to
|
||||||
|
reconstitute or re-assemble cryptographic material, and approve actions.
|
||||||
|
Quorum is a general term referring to a system which requires the collaboration
|
||||||
|
of multiple individuals in order to achieve something, and it is based on a
|
||||||
|
Threshold which determines how many Members of a Quorum there are in total, and
|
||||||
|
the Quorum, which is how Members are required to reach consensus.
|
||||||
|
|
||||||
|
The following is a simple Quorum example. Let's assume there are 3 trusted
|
||||||
|
individuals who will be part of Quorum and at least 2 of the Members of the
|
||||||
|
Quorum should be required to reach consensus. In that case the chosen Quorum
|
||||||
|
would be "2 of 3" - in other words, 2 of the total of 3 are required to achieve
|
||||||
|
consensus. These numbers may be adjusted in order to optimize risk tolerance
|
||||||
|
along two axis:
|
||||||
|
|
||||||
|
* Tolerating loss of X members aka "Bus Factor"
|
||||||
|
|
||||||
|
* Tolerating duress of Y members aka "Wrench Factor"
|
||||||
|
|
||||||
|
In a "2 of 3" Quorum, the **Bus Factor** is 1 as we can only afford to lose 1
|
||||||
|
member of the Quorum before the ability to reach consensus is lost permanently.
|
||||||
|
For that same Quorum, the **Wrench Factor** is 2, as an adversary has to use
|
||||||
|
their wrench on two different Quorum Members to force them to give them access
|
||||||
|
to their shards before the system is compromised (this is an over-simplification
|
||||||
|
as there are additional security controls in place such as the physical
|
||||||
|
locations which hold Location Keys, and as such the Wrench Factor is hardened).
|
||||||
|
|
||||||
|
It is recommended to use a "2 of 3" Threshold at a minimum, but many organizations
|
||||||
|
may choose to go with more resilient Threshold such as "3 of 5", "2 of 6", or
|
||||||
|
"5 of 7", depending on considerations pertaining to:
|
||||||
|
|
||||||
|
* Availability requirements
|
||||||
|
|
||||||
|
* Bus Factor requirements
|
||||||
|
|
||||||
|
* Wrench Factor requirements
|
||||||
|
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
# Setting Smart Card Pins
|
||||||
|
|
||||||
|
In order to protect unauthorized use of smart cards, we can leverage PINs.
|
||||||
|
|
||||||
|
There are two pins with different levels of authorization for making changes
|
||||||
|
to the smart card:
|
||||||
|
|
||||||
|
* User PIN
|
||||||
|
|
||||||
|
* Admin PIN
|
||||||
|
|
||||||
|
Both PINs support alphanumeric characters and typically need to be at least 6
|
||||||
|
characters long.
|
||||||
|
|
||||||
|
For Operator Keys it is recommended to use the default PINs, while for Location
|
||||||
|
Keys, PINs are generated by the `keyfork` utility and have high entropy.
|
||||||
|
|
||||||
|
## Guide
|
||||||
|
|
||||||
|
To set the smart card pins you may use the `gpg` utility.
|
||||||
|
|
||||||
|
1. Plug the smart card into a computer which has the `gpg` utility intalled
|
||||||
|
2. Use the command `gpg --edit-card` to enter edit mode
|
||||||
|
3. gpg/card>
|
||||||
|
* Input `admin`, press Enter
|
||||||
|
4. Your selection?
|
||||||
|
* Input 1, press Enter
|
||||||
|
5. Please enter the PIN:
|
||||||
|
* Enter old PIN (default is 123456), press Enter
|
||||||
|
6. New PIN:
|
||||||
|
* Enter the new PIN, press Enter
|
||||||
|
7. Repeat this PIN:
|
||||||
|
* Enter the new PIN, press Enter
|
||||||
|
|
||||||
|
8. For the Admin PIN, the steps are the same, except in step 4, input "3", then
|
||||||
|
press Enter.
|
||||||
|
|
||||||
|
9. Once done, shut down the computer
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
# Software
|
||||||
|
This page outlines the software used for setting up a QKM. All software used in
|
||||||
|
the setup is open source and audited by security firms in order to ensure their
|
||||||
|
security. Furthermore, all software is built in a deterministic manner and
|
||||||
|
reproduced by multiple individuals on diverse hardware to minimize the risks
|
||||||
|
associated with supply chain attacks.
|
||||||
|
|
||||||
|
To achieve this, [StageX](https://codeberg.org/stagex/stagex)
|
||||||
|
is used - a toolchain for building software using a fully bootstrapped compiler,
|
||||||
|
which itself is built deterministically, and multi-reproduced.
|
||||||
|
## [AirgapOS](https://git.distrust.co/public/airgap)
|
||||||
|
|
||||||
|
AirgapOS is an operating system built for those that want to be -really- sure
|
||||||
|
that sensitive cryptographic material is managed in a clean environment with an
|
||||||
|
"air gap" between the machine and the internet with high integrity on the supply
|
||||||
|
chain of the firmware and OS used. This OS is hardened and specifically designed
|
||||||
|
as an appliance for working with cryptographic material.
|
||||||
|
|
||||||
|
The software was developed by [Distrust](https://distrust.co) and has undergone
|
||||||
|
an [audit](https://git.distrust.co/public/airgap/src/branch/main/audits) by
|
||||||
|
Cure53 with no significant vulnerabilities found and has since then undergone
|
||||||
|
additional hardening.
|
||||||
|
|
||||||
|
The [AirgapOS Setup](repeat-use-airgapos.md) guides the user through verifying and
|
||||||
|
setting up AirgapOS on a bootable disk to use as part of the [Key Derivation
|
||||||
|
Ceremony](glossary.md#key-derivation-ceremony)
|
||||||
|
|
||||||
|
## [Keyfork](https://git.distrust.co/public/keyfork)
|
||||||
|
|
||||||
|
Keyfork is an opinionated and modular toolchain for generating and managing a
|
||||||
|
wide range of cryptographic keys offline and on Smart Cards from a shared
|
||||||
|
BIP-0039 mnemonic phrase. BIP-0039 phrases are used to calculate a BIP-0032
|
||||||
|
seed, which is used for hierarchical deterministic key derivation.
|
||||||
|
|
||||||
|
This software is the backbone for all cryptographic actions performed as part
|
||||||
|
of QKM. It was developed by [Distrust](https://distrust.co) and is included
|
||||||
|
with AirgapOS and has been audited by two firms, NCC and Cure53 with no
|
||||||
|
significant vulnerabilities found.
|
||||||
|
|
@ -0,0 +1,53 @@
|
||||||
|
# Storage Device Management
|
||||||
|
|
||||||
|
In order to interact with a USB device on a Linux system it first has to be
|
||||||
|
`mounted`. In order to mount a USB device, one must first identify the device
|
||||||
|
name, and then use the `mount` command.
|
||||||
|
|
||||||
|
## Finding a Storage Device Name
|
||||||
|
USB devices are assigned names when they are connected to a Linux operating
|
||||||
|
system. The first storage device is assigned the name `sda` (storage device a),
|
||||||
|
the second `sdb`, the third `sdc` and so on.
|
||||||
|
|
||||||
|
One may use the `lsblk` to list the detected storage devices for a system, which
|
||||||
|
will output something like this:
|
||||||
|
```
|
||||||
|
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||||
|
xvda 202:0 1 50G 0 disk
|
||||||
|
├─xvda1 202:1 1 200M 0 part
|
||||||
|
├─xvda2 202:2 1 2M 0 part
|
||||||
|
└─xvda3 202:3 1 49.8G 0 part /
|
||||||
|
xvdb 202:16 1 1.9T 0 disk /rw
|
||||||
|
xvdc 202:32 1 10G 0 disk
|
||||||
|
├─xvdc1 202:33 1 1G 0 part [SWAP]
|
||||||
|
└─xvdc3 202:35 1 9G 0 part
|
||||||
|
xvdd 202:48 1 526.8M 1 disk
|
||||||
|
```
|
||||||
|
|
||||||
|
Then after plugging in the Storage Device run `lsblk` and look for what's
|
||||||
|
different. In this example, the newly detected storage device is `sdb`:
|
||||||
|
```
|
||||||
|
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||||
|
sdb 8:16 1 14.5G 0 disk
|
||||||
|
xvda 202:0 1 50G 0 disk
|
||||||
|
├─xvda1 202:1 1 200M 0 part
|
||||||
|
├─xvda2 202:2 1 2M 0 part
|
||||||
|
└─xvda3 202:3 1 49.8G 0 part /
|
||||||
|
xvdb 202:16 1 1.9T 0 disk /rw
|
||||||
|
xvdc 202:32 1 10G 0 disk
|
||||||
|
├─xvdc1 202:33 1 1G 0 part [SWAP]
|
||||||
|
└─xvdc3 202:35 1 9G 0 part
|
||||||
|
xvdd 202:48 1 526.8M 1 disk
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mounting a Storage Device
|
||||||
|
In order to mount a device, first ensure that the directory you will mount to
|
||||||
|
exists by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mkdir -p /media/usb
|
||||||
|
```
|
||||||
|
|
||||||
|
Then run the following command to mount the storage device:
|
||||||
|
```sh
|
||||||
|
sudo mount /dev/<usb_device_name> /media/usb
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
# Threat Model
|
||||||
|
|
||||||
|
QKM is designed according to a high-assurance threat model which ers on the
|
||||||
|
side of making exaggerated, rather than conservative assumptions in order to
|
||||||
|
build a resilient system.
|
||||||
|
|
||||||
|
The assumption is made that attackers who target QKM are extremely
|
||||||
|
sophisticated, well funded and patient attackers, and as such, the full arsenal
|
||||||
|
of attacks is on the table. This means that the attacker can purchase and
|
||||||
|
weaponize multiple 0day vulnerabilities, execute physical attacks or deploy
|
||||||
|
moles, target different supply chains of hardware, firmware and software used,
|
||||||
|
and generally attack the system using an array of known and unknown attacks.
|
||||||
|
|
||||||
|
One of the guiding principles in the design is the elimination of Single Points
|
||||||
|
of Failure (SPOFs), and relies on a number of different control mechanisms which
|
||||||
|
help reduce risk of any one individual being able to compromise the system,
|
||||||
|
whether it's maintainers of software used in the system, the firmware that's
|
||||||
|
used, or the individuals or locations that hold secret material which is the
|
||||||
|
backbone of the system.
|
||||||
|
|
||||||
|
To achieve this, the QKM focuses on reducing the risk by:
|
||||||
|
|
||||||
|
* Only using fully open source software and firmware to allow full verification
|
||||||
|
of their security
|
||||||
|
|
||||||
|
* Creating custom purpose specific tooling which eliminates dependencies in
|
||||||
|
order to reduce supply chain attacks, and adds desirable security properties
|
||||||
|
|
||||||
|
* Using a fully bootstrapped and deterministically built compiler for building
|
||||||
|
all software that's used
|
||||||
|
|
||||||
|
* Building all of the software and firmware deterministically
|
||||||
|
|
||||||
|
* Using computers which either have a hard switch for disabling networking or
|
||||||
|
which had radio networking cards (bluetooth, wifi etc.) removed
|
||||||
|
|
||||||
|
* Leveraging smart cards (personal HSMs) to protect cryptographic material
|
||||||
|
|
||||||
|
* Leveraging sharding in order to physically separate cryptographic material
|
||||||
|
|
||||||
|
* Leveraging tamper evident controls to protect hardware
|
||||||
|
|
||||||
|
## General Threat Model Assumptions
|
||||||
|
|
||||||
|
Some additional assumptions are made to help contextualize the threat model:
|
||||||
|
|
||||||
|
* All screens are visible to an adversary
|
||||||
|
|
||||||
|
* All keyboards are logging to an adversary
|
||||||
|
|
||||||
|
* Any firmware/boot-loaders not verified on every boot are compromised
|
||||||
|
|
||||||
|
* Any host OS with network access is compromised
|
||||||
|
|
||||||
|
* Any guest OS used for any purpose other than prod access is compromised
|
||||||
|
|
||||||
|
* At least one member of the PRODUCTION team is always compromised
|
||||||
|
|
||||||
|
* At least one maintainer of third party used in the system is compromised
|
||||||
|
|
||||||
|
* Physical attacks are viable and likely
|
||||||
|
|
||||||
|
|
||||||
|
## Additional Threat Model Notes
|
||||||
|
|
||||||
|
### Smart Cards
|
||||||
|
|
||||||
|
The Operator Smart Card uses the default PIN because it is meant to be something
|
||||||
|
a user "has", rather than "knows". On the other hand, the Location Smart Card
|
||||||
|
is protected by a complex PIN, which can only be decrypted using the PGP keys
|
||||||
|
stored on the Operator Smart Card. This is done in order to protect the access
|
||||||
|
to the Location key by anyone except the Operator, but also to allow for adding
|
||||||
|
controls which require more than one individual to access a Location Smart Card.
|
||||||
|
In this way, there is an additional "quorum" which needs to be achieved to
|
||||||
|
access the Location key - more on this in the [Location](locations.md) section.
|
||||||
|
|
||||||
|
The Smart Cards are used as they are an HSM (Hardware Security Module) which
|
||||||
|
provides excellent protection for the cryptographic material stored on it, and
|
||||||
|
they are portable, which makes them suitable for creating systems where the
|
||||||
|
cards are in separate physical locations, and need to be brought together in
|
||||||
|
order to re-assemble secret material.
|
||||||
Loading…
Reference in New Issue