Compare commits
No commits in common. "5438f99c9c8a174334cd45623a9b09143ead79c3" and "ab1e3ca5e5f780d6290486c350004be6a13ae28c" have entirely different histories.
5438f99c9c
...
ab1e3ca5e5
|
|
@ -1 +0,0 @@
|
||||||
book/
|
|
||||||
|
|
@ -1,15 +0,0 @@
|
||||||
# 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
|
|
||||||
```
|
|
||||||
|
|
@ -1,6 +0,0 @@
|
||||||
[book]
|
|
||||||
authors = ["Anton Livaja", "Lance R. Vick", "Ryan Heywood"]
|
|
||||||
language = "en"
|
|
||||||
multilingual = false
|
|
||||||
src = "src"
|
|
||||||
title = "Quorum Key Management (QKM)"
|
|
||||||
|
|
@ -1,43 +0,0 @@
|
||||||
# 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)
|
|
||||||
|
|
@ -1,44 +0,0 @@
|
||||||
# `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.
|
|
||||||
|
|
@ -1,62 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,8 +0,0 @@
|
||||||
# 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).
|
|
||||||
|
|
@ -1,36 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,21 +0,0 @@
|
||||||
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.
|
|
||||||
|
|
@ -1,108 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,19 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,98 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,77 +0,0 @@
|
||||||
# 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.
|
Before Width: | Height: | Size: 85 KiB |
|
|
@ -1,151 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
@ -1,69 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,53 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
@ -1,119 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,72 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,54 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
# 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`
|
|
||||||
|
|
@ -1,33 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,18 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,44 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,44 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,35 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
# Remote Key Provisioning
|
|
||||||
|
|
||||||
TODO
|
|
||||||
|
|
@ -1,61 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,14 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
# 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).
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,53 +0,0 @@
|
||||||
# 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
|
|
||||||
|
|
@ -1,81 +0,0 @@
|
||||||
# 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