Compare commits

..

20 Commits

Author SHA1 Message Date
Lance Vick 5438f99c9c
Merge remote-tracking branch 'origin/feat/quorum-kms' 2024-08-05 20:39:34 -07:00
Anton Livaja 0df2c9ce08
fix: remove duplicate command 2024-08-05 21:39:48 -04:00
Anton Livaja ebe07875b7
fix: improve tampering docs 2024-08-05 19:34:25 -04:00
Anton Livaja 51fcd742a3
fix: simplify deletion instruction at the end of the ceremony 2024-08-05 16:45:13 -04:00
Anton Livaja 7044041772
fix: add system time setting and copying pub key to operator pub key SD card 2024-08-05 16:35:09 -04:00
Anton Livaja 265add34f5
fix: update location key ceremony 2024-08-05 15:55:11 -04:00
Anton Livaja 52ebb41eb8
fix: rename location key 2024-08-05 14:13:28 -04:00
Anton Livaja d8eacdaa5b
feat: add details about tamper proofing hardware 2024-08-05 13:47:28 -04:00
Anton Livaja 46358df51e
fix: minor location key ceremony update 2024-08-05 13:47:08 -04:00
Anton Livaja e8e649983c
feat: add instructions for impregnating a smart card with seed 2024-08-04 22:27:20 -04:00
Anton Livaja 2308513309
fix: add note about setting system time 2024-08-04 20:14:42 -04:00
Anton Livaja 65d0e0269d
fix: update paths in ceremony.sh script for hybrid ceremony 2024-08-04 20:14:23 -04:00
Anton Livaja 9f8297bd0e
fix: ceremony.sh script keyfork command and pub certs path 2024-08-04 19:28:16 -04:00
Anton Livaja 25516fcd7f
fix: specify smart cards must have openpgp ed25519 support 2024-08-04 14:31:08 -04:00
Anton Livaja 18cbd8ff69
fix: minor cleanup of root-entropy-ceremonies file 2024-08-03 19:07:55 -04:00
Anton Livaja a813634432
fix: rename to Quorum Key Management (QKM) 2024-08-03 19:02:38 -04:00
Anton Livaja 8ce53c2b7b
fix links 2024-08-03 18:59:25 -04:00
Anton Livaja b1d4682001
fix: rename from Quroum-KMS to Quorum Key Management System (QKMS) 2024-08-03 17:53:52 -04:00
Anton Livaja 6002939ff9
fix: remove unused docs and add back storage device management guide 2024-08-03 17:50:07 -04:00
Anton Livaja d6a607a5cf
initial commit of QKMS docs 2024-08-03 17:23:14 -04:00
36 changed files with 1674 additions and 0 deletions

1
quorum-key-management/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
book/

View File

@ -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
```

View File

@ -0,0 +1,6 @@
[book]
authors = ["Anton Livaja", "Lance R. Vick", "Ryan Heywood"]
language = "en"
multilingual = false
src = "src"
title = "Quorum Key Management (QKM)"

View File

@ -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)

View File

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

View File

@ -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

View File

@ -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).

View File

@ -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

View File

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

View File

@ -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

View File

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

View File

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

View File

@ -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

View File

@ -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

View File

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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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`

View File

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

View File

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

View File

@ -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

View File

@ -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

View File

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

View File

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

View File

@ -0,0 +1,3 @@
# Remote Key Provisioning
TODO

View File

@ -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:
![Downloading AirgapOS as ZIP](img/download-airgap-os.png)
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.

View File

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

View File

@ -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).

View File

@ -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

View File

@ -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

View File

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

View File

@ -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

View File

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