public
/
keyfork
5
0
Fork 0
Code Issues 23 Pull Requests 1 Packages Projects Releases Wiki Activity

keyfork-user-guide: tidy up more docs

This commit is contained in:
Ryan Heywood 2024-01-10 13:42:48 -05:00
parent 155de0ce31
commit 09c3e1bda8
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
2 changed files with 42 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
keyfork-user-guide/src/dev-guide/provisioners.md
View File

@ -37,6 +37,28 @@ provisioned to, avoiding ambiguities when (for example) multiple devices are
plugged into a host. A plumbing crate may provide a binary to list identifiers
for potential targets, if possible.
### Deriving Data
A quick example is provided to show how data can be requested from the Keyfork
server. The response contains the bytes representing the private key; the chain
code, depth, and algorithm are also included in the response, and can be used
for further derivation if required.
```rs
use keyfork_derive_util::{
request::{DerivationAlgorithm, DerivationRequest, DerivationResponse},
DerivationIndex, DerivationPath,
};
use keyforkd_client::Client;
let path = DerivationPath::from_str("m/44'/0'/0'")?;
let request = DerivationRequest::new(DerivationAlgorithm::Secp256k1, &path);
let response: DerivationResponse = Client::discover_socket()?
.request(&request.into())?
.try_into()?;
let derived_key = response.data;
```
## Porcelain
Once the plumbing crates have been written, porcelain subcommands should be

29
keyfork-user-guide/src/shard.md
View File

@ -1,4 +1,11 @@
# Creating a Seed and Shard File
# Keyfork Shard Commands
Sharding a seed allows "M-of-N" recovery of the seed, which is useful for
disaster recovery situations, avoiding the case where a single person may be
left in charge of the seed. Keyfork provides utilities to help with the
management of seeds through sharding.
## Creating a Seed and Shard File
If using smartcards dedicated to this use case, Keyfork offers a wizard to
generate a seed and encrypt it to multiple factory-reset smartcards. Assuming
@ -13,7 +20,7 @@ Keyfork will prompt for keys to be inserted and for PINs to be configured for
the smartcards. The shards file should be copied to every system intended to
decrypt shards.
# Starting Keyfork using a single system
## Starting Keyfork using a single system
If all shardholders are present, the following command can be run to start the
Keyfork server process:
@ -25,7 +32,7 @@ keyfork recover shard shards.pgp
Keyfork will prompt for keys to be inserted and for the User PINs for the keys
to be entered. Once the shard is decrypted, the Keyfork server will start.
# Starting Keyfork using remote systems
## Starting Keyfork using remote systems
A line of communication should be established with the shardholders, but can be
public and/or insecure. On the system intended to run the Keyfork server, the
@ -47,17 +54,21 @@ keyfork shard transport < shards.pgp
This command will read in 33 words, prompt for a smartcard PIN, and prompt 72
words, followed by a QR code containing the words.
# Deriving an OpenPGP key
This command should be run on a system without persistent storage to avoid
persisting the cold storage key to disk.
## Example: Deriving an OpenPGP key for Encryption
Once the Keyfork server has started, Keyfork can be used to derive an OpenPGP
key:
key, and [Sequoia] can be used to extract the public portions:
```sh
keyfork derive openpgp "Cold Storage Key" > cold_storage.pgp
keyfork derive openpgp "Storage Key" | sq key extract-cert > storage.pgp
```
The final argument should be a descriptive name for the key, as that name will
likely be used by any program encrypting data to the public key.
The key, including the secret portions, can be retrieved by running the command
without the `sq` portion, but should not be run on a system with a persistent
filesystem, to avoid keeping the key on written memory for longer than
necessary.
[Sequoia]: https://sequoia-pgp.org