keyfork-user-guide: document porcelain
This commit is contained in:
parent
24cc670b7a
commit
535fccc64f
|
@ -9,8 +9,11 @@
|
||||||
- [Configuration File](./config-file.md)
|
- [Configuration File](./config-file.md)
|
||||||
- [Binaries](./bin/index.md)
|
- [Binaries](./bin/index.md)
|
||||||
- [keyfork](./bin/keyfork/index.md)
|
- [keyfork](./bin/keyfork/index.md)
|
||||||
|
- [derive](./bin/keyfork/derive/index.md)
|
||||||
- [mnemonic](./bin/keyfork/mnemonic/index.md)
|
- [mnemonic](./bin/keyfork/mnemonic/index.md)
|
||||||
- [shard](./bin/keyfork/shard/index.md)
|
- [shard](./bin/keyfork/shard/index.md)
|
||||||
|
- [recover](./bin/keyfork/recover/index.md)
|
||||||
|
- [wizard](./bin/keyfork/wizard/index.md)
|
||||||
- [keyforkd](./bin/keyforkd.md)
|
- [keyforkd](./bin/keyforkd.md)
|
||||||
- [keyfork-shard](./bin/keyfork-shard/index.md)
|
- [keyfork-shard](./bin/keyfork-shard/index.md)
|
||||||
- [keyfork-shard-split-openpgp](./bin/keyfork-shard/openpgp/split.md)
|
- [keyfork-shard-split-openpgp](./bin/keyfork-shard/openpgp/split.md)
|
||||||
|
|
|
@ -0,0 +1,22 @@
|
||||||
|
# `keyfork derive`
|
||||||
|
|
||||||
|
Derive keys of various formats.
|
||||||
|
|
||||||
|
## Common Arguments
|
||||||
|
|
||||||
|
`keyfork derive <format> --account-id=0`
|
||||||
|
|
||||||
|
* `--account-id=0`: The Account ID to append to the derivation request. This
|
||||||
|
allows multiple accounts to be derived per format.
|
||||||
|
|
||||||
|
## `keyfork derive openpgp`
|
||||||
|
|
||||||
|
Generate an OpenPGP keychain with a Certify, Signing, Encryption, and
|
||||||
|
Authentication key. The key is generated with a creation date of `1` to ensure
|
||||||
|
the key fingerprint does not change. The key is set to expire in one day,
|
||||||
|
encouraging users to establish the ability to renew their key when necessary.
|
||||||
|
The primary User ID for the certificate is provided as the first argument to
|
||||||
|
the derivation request, and must contain at least a real name, a username, or
|
||||||
|
an email, but may contain any combination of the three.
|
||||||
|
|
||||||
|
`keyfork derive openpgp "Your Name (Username) <your@email.local>"`
|
|
@ -1,11 +1,37 @@
|
||||||
# keyfork
|
# keyfork
|
||||||
|
|
||||||
The primary interface for interacting with the Keyfork utilities.
|
The primary interface for interacting with Keyfork utilities.
|
||||||
|
|
||||||
## `shard`
|
## `keyfork derive`
|
||||||
|
|
||||||
Utilities for splitting and combining secrets using various formats.
|
Derive keys of various formats. All commands accept an `--account-id` parameter
|
||||||
|
and may accept additional arguments or optional flags depending on the format
|
||||||
|
of the derived data. Each format will have its own first-level derivation path,
|
||||||
|
such as [BIP-0044] or the numeric representation of a textual identifier, such
|
||||||
|
as "pgp" for OpenPGP keys or "shrd" for Shard OpenPGP keys.
|
||||||
|
|
||||||
## `mnemonic`
|
## `keyfork mnemonic`
|
||||||
|
|
||||||
Utilities pertaining to the creation and management of mnemonics.
|
Utilities pertaining to the creation and management of mnemonics. Mnemonics can
|
||||||
|
be generated from system entropy or physical entropy, such as a deck of cards
|
||||||
|
or dice. Once generated, the mnemonic should be stored in a secure location.
|
||||||
|
|
||||||
|
## `keyfork shard`
|
||||||
|
|
||||||
|
Utilities for splitting secrets to, and combining secrets from, a Shard file.
|
||||||
|
The Shard file is encrypted at rest, and can be recovered directly by Keyfork
|
||||||
|
to avoid managing shards or seeds manually.
|
||||||
|
|
||||||
|
## `keyfork recover`
|
||||||
|
|
||||||
|
Recover a derivation seed and start the Keyfork server. Seeds can be recovered
|
||||||
|
from mnemonics, a shard file, or any other supported format. Once the seed has
|
||||||
|
been recovered, the Keyfork server starts, and derivation requests can begin.
|
||||||
|
|
||||||
|
## `keyfork wizard`
|
||||||
|
|
||||||
|
Utilities to automatically manage the setup of Keyfork. This includes
|
||||||
|
generating a seed, splitting it into a Shard file, and provisioning smart cards
|
||||||
|
with the capability to decrypt the shards.
|
||||||
|
|
||||||
|
[BIP-0044]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
Utilities for managing mnemonics.
|
Utilities for managing mnemonics.
|
||||||
|
|
||||||
# `keyfork mnemonic generate`
|
## `keyfork mnemonic generate`
|
||||||
|
|
||||||
Generate a mnemonic using various forms of entropy (default: system). Forms of
|
Generate a mnemonic using various forms of entropy (default: system). Forms of
|
||||||
entropy also include Tarot cards, playing cards, and dice rolls. Because
|
entropy also include Tarot cards, playing cards, and dice rolls. Because
|
||||||
|
@ -12,7 +12,7 @@ requires a system be both offline and running an up-to-date kernel before
|
||||||
generating a mnemonic. However, the command may be run with the variable
|
generating a mnemonic. However, the command may be run with the variable
|
||||||
`INSECURE_HARDWARE_ALLOWED=1` to override system validation.
|
`INSECURE_HARDWARE_ALLOWED=1` to override system validation.
|
||||||
|
|
||||||
## Arguments
|
### Arguments
|
||||||
|
|
||||||
`keyfork mnemonic generate --source=system --size=256`
|
`keyfork mnemonic generate --source=system --size=256`
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,42 @@
|
||||||
|
# `keyfork recover`
|
||||||
|
|
||||||
|
Recover a seed to memory from a mnemonic, shard, or other format, then launch
|
||||||
|
the Keyfork server with the recovered seed.
|
||||||
|
|
||||||
|
## `keyfork recover shard`
|
||||||
|
|
||||||
|
Decrypt a shard file using keys available on the local system. This command
|
||||||
|
should be run when all shardholders are present; otherwise, [`keyfork recover
|
||||||
|
remote-shard`](#keyfork-recover-remote-shard) should be used instead.
|
||||||
|
|
||||||
|
### Arguments
|
||||||
|
|
||||||
|
`keyfork recover shard <shard_file> [key_discovery]`
|
||||||
|
|
||||||
|
* `shard_file`: The file containing the encrypted shards.
|
||||||
|
* `key_discovery`: The location to find OpenPGP Secret Keys, if not using
|
||||||
|
smartcards.
|
||||||
|
|
||||||
|
### Prompts
|
||||||
|
|
||||||
|
The recovery command will prompt several times during the process, to ensure a
|
||||||
|
smart card is plugged in, and to request the PIN to unlock the card.
|
||||||
|
|
||||||
|
## `keyfork recover remote-shard`
|
||||||
|
|
||||||
|
Ensure the transport of transport-encrypted shards and combine them on the
|
||||||
|
current system. This command should be run when a shardholder is not present;
|
||||||
|
otherwise, [`keyfork recover shard`](#keyfork-recover-shard) should be used
|
||||||
|
instead. The command does not take any arguments, as all necessary metadata is
|
||||||
|
stored encrypted alongside the shard.
|
||||||
|
|
||||||
|
The command pairs with [`keyfork shard transport`], which should be run by the
|
||||||
|
shardholders.
|
||||||
|
|
||||||
|
### Prompts
|
||||||
|
|
||||||
|
For every shardholder, the recovery command will prompt 33 words to be sent to
|
||||||
|
the shardholder, followed by an input prompt of 72 words to be received from
|
||||||
|
the shardholder.
|
||||||
|
|
||||||
|
[`keyfork shard transport`]: ../shard/index.md#keyfork-shard-transport
|
|
@ -7,7 +7,9 @@ supporting multiple formats.
|
||||||
|
|
||||||
## Options
|
## Options
|
||||||
|
|
||||||
* `--format`: Either `openpgp` or `p256`, provided anywhere after `split`
|
* `--format`: Either `openpgp` or `p256`, provided anywhere after `split`.
|
||||||
|
Keyfork will make a best-effort attempt to automatically guess the format,
|
||||||
|
and this flag should not be necessary.
|
||||||
|
|
||||||
### Format: OpenPGP
|
### Format: OpenPGP
|
||||||
|
|
||||||
|
@ -93,3 +95,46 @@ keyfork shard combine --format openpgp < shard.pgp | keyfork-mnemonic-from-seed
|
||||||
# Decrypt using on-disk private keys
|
# Decrypt using on-disk private keys
|
||||||
keyfork shard combine --format openpgp key_discovery.pgp < shard.pgp | keyfork-mnemonic-from-seed
|
keyfork shard combine --format openpgp key_discovery.pgp < shard.pgp | keyfork-mnemonic-from-seed
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## `keyfork shard transport`
|
||||||
|
|
||||||
|
Ensure a public key for the shard recipient, decrypt a single shard on the
|
||||||
|
current system, and prepare it for transport for remote shard recovery.
|
||||||
|
|
||||||
|
This command pairs with [`keyfork recover remote-shard`], which should be run
|
||||||
|
by a remote recovery operator.
|
||||||
|
|
||||||
|
### Arguments
|
||||||
|
|
||||||
|
`keyfork shard transport [key_discovery]`
|
||||||
|
|
||||||
|
* `key_discovery`: Either a file or a directory containing public keys.
|
||||||
|
If a file, load all private keys from a file.
|
||||||
|
If a directory, for every file in the directory (non-recursively), load
|
||||||
|
private keys from the file.
|
||||||
|
If the amount of keys found is less than `threshold`, it is up to the format
|
||||||
|
to determine how to discover the keys.
|
||||||
|
|
||||||
|
### Input
|
||||||
|
|
||||||
|
The input of the command is dependent on the format, but should be the exact
|
||||||
|
same as the output from the `split` command previously used.
|
||||||
|
|
||||||
|
### Prompts
|
||||||
|
|
||||||
|
The command will prompt for 33 words from the remote shard recovery operator,
|
||||||
|
prompt for a smart card to be plugged in, prompt for the PIN for the smart
|
||||||
|
card, and display a prompt of 72 words to be sent to the remote shard recovery
|
||||||
|
operator.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# Transport using a smart card
|
||||||
|
keyfork shard transport < shard.pgp
|
||||||
|
|
||||||
|
# Transport using on-disk private keys
|
||||||
|
keyfork shard transport key_discovery.pgp < shard.pgp
|
||||||
|
```
|
||||||
|
|
||||||
|
[`keyfork recover remote-shard`]: ../recover/index.md#keyfork-recover-remote-shard
|
||||||
|
|
|
@ -0,0 +1,32 @@
|
||||||
|
# `keyfork wizard`
|
||||||
|
|
||||||
|
Set up Keyfork using a guided setup process.
|
||||||
|
|
||||||
|
## `keyfork wizard generate-shard-secret`
|
||||||
|
|
||||||
|
Generate a 256-bit seed, derive OpenPGP keys using the seed, provision smart
|
||||||
|
cards using the derived keys, and export a Shard file.
|
||||||
|
|
||||||
|
<div class="warning">
|
||||||
|
This command will <b>factory-reset</b> any smart cards plugged into the system.
|
||||||
|
It is recommended to use smart cards dedicated to the purpose of seed recovery.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
### Arguments
|
||||||
|
|
||||||
|
`keyfork wizard generate-shard-secret --threshold=1 --max=3 --keys-per-shard=1`
|
||||||
|
|
||||||
|
* `threshold`: The minimum amount of shardholders needed to recover the
|
||||||
|
secret.
|
||||||
|
* `max`: The maximum amount of shardholders.
|
||||||
|
* `keys-per-shard`: The amount of smart cardsz to provision per-shardholder.
|
||||||
|
|
||||||
|
### Prompts
|
||||||
|
|
||||||
|
The wizard will prompt for a User PIN and an Admin PIN for every shardholder,
|
||||||
|
and will require `keys-per-shard` smartcards to be provisioned for every
|
||||||
|
shardholder.
|
||||||
|
|
||||||
|
### Output
|
||||||
|
|
||||||
|
An OpenPGP-encrypted Shard file.
|
Loading…
Reference in New Issue