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

docs: get mega link file, add rustdoc builder

This commit is contained in:
Ryan Heywood 2024-02-11 19:45:24 -05:00
parent 086e56bef0
commit 38b73b670e
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
28 changed files with 222 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Makefile
View File

@ -10,6 +10,20 @@ define clone-repo
test `git -C $(1) rev-parse HEAD` = $(3)
endef
docs/book: docs/src/links.md $(shell find docs/src -type f -name '*.md')
mdbook build docs
mkdir -p docs/book/rustdoc
cargo doc --no-deps
cp -r ${CARGO_TARGET_DIR}/doc/* docs/book/rustdoc/
docs/src/links.md: docs/src/links.md.template
echo "<!-- DO NOT EDIT THIS FILE MANUALLY, edit links.md.template -->" > $@
envsubst < $< >> $@
.PHONY: touch
touch:
touch docs/src/links.md.template
.PHONY: review
review:
$(eval BASE_REF_PARSED := $(shell git rev-parse $(BASE_REF)))

4
docs/src/INSTALL.md
View File

@ -1,3 +1,5 @@
{{#include links.md}}
## Dependencies
Keyfork has different dependencies depending on the feature set used for
@ -66,5 +68,3 @@ cargo install --index https://git.distrust.co/public/_cargo-index keyfork-entrop
# Confirmed to work as of 2024-01-17.
cargo install --locked --path crates/util/keyfork-entropy --bin keyfork-entropy --features bin
```
[SBOM]: https://en.wikipedia.org/wiki/SBOM

2
docs/src/SUMMARY.md
View File

@ -1,8 +1,10 @@
<!-- vim:set et sts=0 sw=2 ts=2: -->
{{ #include links.md }}
# Summary
# User Guide
- [Introduction to Keyfork](./introduction.md)
- [Installing Keyfork](./INSTALL.md)
- [Security Considerations](./security.md)
- [Shard Commands](./shard.md)

4
docs/src/bin/keyfork-derive-key.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# keyfork-derive-key
Derive a key from a given derivation path.
@ -18,5 +20,3 @@ the shell silently ignoring the single quotes in the derivation path.
Hex-encoded private key. Note that this is not the _extended_ private key, and
can't be used to derive further data.
[`keyforkd`]: ./bin/keyforkd.md

4
docs/src/bin/keyfork-derive-openpgp.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# keyfork-derive-openpgp
Derive a key from a given derivation path.
@ -28,5 +30,3 @@ the shell silently ignoring the single quotes in the derivation path.
## Output
OpenPGP ASCII armored key, signed to be valid for 24 hours.
[`keyforkd`]: ./bin/keyforkd.md

2
docs/src/bin/keyfork-plumbing/entropy.md
View File

@ -1,3 +1,5 @@
{{#include ../../links.md}}
# keyfork-entropy
Retrieve system entropy, output in hex format. The machine must be running a

2
docs/src/bin/keyfork-plumbing/mnemonic-from-seed.md
View File

@ -1,3 +1,5 @@
{{#include ../../links.md}}
# keyfork-mnemonic-from-seed
Generate a mnemonic from a seed passed by input.

10
docs/src/bin/keyfork-shard/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../links.md}}
# keyfork-shard
<!-- Linked to: keyfork-user-guide/src/bin/keyfork/shard/index.md -->
@ -7,13 +9,9 @@ data. All binaries use Shamir's Secret Sharing through the [`sharks`] crate.
## OpenPGP
Keyfork provides OpenPGP compatible [`split`][openpgp-split] and
[`combine`][openpgp-combine] versions of Shard binaries. These binaries use
Keyfork provides OpenPGP compatible [`split`][kshard-opgp-split] and
[`combine`][kshard-opgp-combine] versions of Shard binaries. These binaries use
Sequoia OpenPGP and while they require all the necessary certificates for the
splitting stage, the certificates are included in the payload, and once Keyfork
supports decrypting using OpenPGP smartcards, certificates will not be required
to decrypt the shares.
[`sharks`]: https://docs.rs/sharks/latest/sharks/
[openpgp-split]: ./openpgp/split.md
[openpgp-combine]: ./openpgp/combine.md

6
docs/src/bin/keyfork-shard/openpgp/combine.md
View File

@ -1,6 +1,8 @@
{{#include ../../../links.md}}
# keyfork-shard-combine-openpgp
Combine `threshold` shares into a previously [`split`] secret.
Combine shares into a previously [`split`][kshard-opgp-split] secret.
## Arguments
@ -31,5 +33,3 @@ keyfork-shard-combine-openpgp shard.pgp
# Decrypt using on-disk private keys
keyfork-shard-combine-openpgp key_discovery.pgp shard.pgp
```
[`split`]: ./split.md

2
docs/src/bin/keyfork-shard/openpgp/split.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# keyfork-shard-split-openpgp
<!-- Linked to: keyfork-user-guide/src/bin/keyfork-shard/index.md -->

2
docs/src/bin/keyfork/derive/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# `keyfork derive`
Derive keys of various formats.

4
docs/src/bin/keyfork/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../links.md}}
# keyfork
The primary interface for interacting with Keyfork utilities.
@ -33,5 +35,3 @@ been recovered, the Keyfork server starts, and derivation requests can begin.
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
docs/src/bin/keyfork/mnemonic/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# `keyfork mnemonic`
Utilities for managing mnemonics.

4
docs/src/bin/keyfork/recover/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# `keyfork recover`
Recover a seed to memory from a mnemonic, shard, or other format, then launch
@ -38,5 +40,3 @@ shardholders.
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

4
docs/src/bin/keyfork/shard/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# `keyfork shard`
<!-- Linked to: keyfork-user-guide/src/bin/keyfork-shard/index.md -->
@ -128,5 +130,3 @@ 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

4
docs/src/bin/keyfork/wizard/index.md
View File

@ -1,3 +1,5 @@
{{#include ../../../links.md}}
# `keyfork wizard`
Set up Keyfork using a guided setup process.
@ -63,5 +65,3 @@ shardholder.
An OpenPGP-encrypted Shard file, if not previously configured to be written to
a file using `--output`.
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

7
docs/src/bin/keyforkd.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# keyforkd
Keyforkd is the backend for deriving data using Keyfork. A mnemonic is loaded
@ -13,7 +15,7 @@ are not leaked. In the future, `keyforkd` could implement GUI or TTY approval
for users to approve the path requested by the client, such as `m/44'/0'` being
"Bitcoin", or `m/7366512'` being "OpenPGP".
The protocol for the UNIX socket is a framed, [bincode] format. While it is
The protocol for the UNIX socket is a framed, [`bincode`] format. While it is
custom to Keyfork, it is easy to implement. The crate `keyfork-frame` provides
a sync (`Read`, `Write`) and Tokio-compatible async (`AsyncRead`, `AsyncWrite`)
pair of methods for encoding and decoding frames.
@ -27,6 +29,3 @@ For encoding the data, the process is reversed. A SHA-256 hash is created, and
the length of the hash and the data is encoded to big-endian and written to the
stream. Then, the hash is written to the stream. Lastly, the data itself is
written as-is to the stream.
[bincode]: https://docs.rs/bincode/latest/bincode/
[BIP-0044]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki

2
docs/src/config-file.md
View File

@ -1,3 +1,5 @@
{{#include links.md}}
# Configuration File
The Keyfork configuration file is used to store the integrity of the mnemonic

38
docs/src/dev-guide/auditing.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# Auditing Dependencies
Dependencies must be reviewed before being added to the repository, and must
@ -35,7 +37,7 @@ These dependencies will show up often:
A command line interface for generating, deriving from, and managing secrets.
* [`card-backend-pcsc`]: Interacting with smartcards using PCSC. Used as a card
backend for `openpgp-card`.
backend for [`openpgp-card`].
* [`clap`]: Command line argument parsing, helps building an intuitive command
line interface.
* [`clap_complete`]: Shell autocompletion file generator. Helps the user
@ -221,40 +223,6 @@ Test data for SLIP10/BIP-0032 derivation.
Zero-dependency hex encoding and decoding.
[`aes-gcm`]: https://github.com/RustCrypto/AEADs/tree/master/aes-gcm
[`anyhow`]: https://github.com/dtolnay/anyhow
[`bincode`]: https://github.com/bincode-org/bincode
[`card-backend`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/card-backend
[`card-backend-pcsc`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/pcsc
[`clap`]: https://github.com/clap-rs/clap/
[`clap_complete`]: https://github.com/clap-rs/clap/tree/master/clap_complete
[`digest`]: https://github.com/RustCrypto/traits/tree/master/digest
[`ed25519-dalek`]: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/ed25519-dalek
[`hakari`]: https://docs.rs/cargo-hakari/latest/cargo_hakari/index.html
[`hkdf`]: https://github.com/RustCrypto/KDFs/tree/master/hkdf
[`hmac`]: https://github.com/RustCrypto/MACs/tree/master/hmac
[`image`]: https://github.com/image-rs/image
[`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
[`openpgp-card`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main
[`openpgp-card-sequoia`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/openpgp-card-sequoia
[`pbkdf2`]: https://github.com/RustCrypto/password-hashes/tree/master/pbkdf2
[`ripemd`]: https://github.com/RustCrypto/hashes/tree/master/ripemd
[`rqrr`]: https://github.com/WanzenBug/rqrr/
[`sequoia-openpgp`]: https://gitlab.com/sequoia-pgp/sequoia
[`serde`]: https://github.com/dtolnay/serde
[`sha2`]: https://github.com/RustCrypto/hashes/tree/master/sha2
[`thiserror`]: https://github.com/dtolnay/thiserror
[`tokio`]: https://github.com/tokio-rs/tokio
[`tower`]: https://github.com/tower-rs/tower
[`tracing`]: https://github.com/tokio-rs/tracing
[`tracing-error`]: https://github.com/tokio-rs/tracing/tree/master/tracing-error
[`tracing-subscriber`]: https://github.com/tokio-rs/tracing/tree/master/tracing-subscriber
[`v4l`]: https://github.com/raymanfx/libv4l-rs/
[`zbar`]: https://github.com/mchehab/zbar
[`bindgen`]: https://github.com/rust-lang/rust-bindgen
[`pkg-config`]: https://github.com/rust-lang/pkg-config-rs
[`keyfork-crossterm`]: #keyfork-crossterm
[`keyfork-derive-openpgp`]: #keyfork-derive-openpgp
[`keyfork-derive-path-data`]: #keyfork-derive-path-data

2
docs/src/dev-guide/entropy.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# Entropy Guide
Keyfork provides a `keyfork-entropy` crate for generating entropy. The crate

2
docs/src/dev-guide/handling-data.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# Handling Data
In Rust, it is common to name things `as_*`, `to_*`, and `into_*`. These three

2
docs/src/dev-guide/index.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# Writing Binaries
### Binaries - Porcelain and Plumbing

5
docs/src/dev-guide/provisioners.md
View File

@ -1,3 +1,5 @@
{{#include ../links.md}}
# Developing Provisioners
**Note:** This document makes heavy use of references to OpenPGP and assumes
@ -75,6 +77,3 @@ device. The porcelain provisioner code should make a best-effort attempt to
derive unique keys for each use, such as OpenPGP capabilities or PIV slots.
Additionally, when provisioning to a key, the configuration for that
provisioner should be stored to the configuration file.
[application identifier]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.application_identifier
[cardholder name]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.cardholder_name

14
docs/src/introduction.md Normal file
View File

@ -0,0 +1,14 @@
{{#include links.md}}
# Introduction
Keyfork is a tool to help manage the creation and derivation of binary data
using [BIP-0039] mnemonics. A mnemonic is, in simple terms, a way of encoding a
large number between 128 and 256 bits, as a list of 12 to 24 words that can be
easily stored or memorized. Once a user has a mnemonic, Keyfork utilizes
[BIP-0032] to derive cryptographic keys, which can be utilized by a variety of
applications.
## Rust documentation
Documentation is [automatically built][keyfork-rustdoc].

71
docs/src/links.md Normal file
View File

@ -0,0 +1,71 @@
<!-- DO NOT EDIT THIS FILE MANUALLY, edit links.md.template -->
<!-- vim:set et sw=4 ts=4 tw=79 ft=markdown: -->
[comments]: <> (
Please keep all links contained in this file, so they can be reused if
necessary across multiple pages.
)
[comments]: <> (
External links
)
[application identifier]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.application_identifier
[cardholder name]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.cardholder_name
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
[BIP-0044]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
[SBOM]: https://en.wikipedia.org/wiki/SBOM
[Sequoia]: https://sequoia-pgp.org
[comments]: <> (
Crate source links
)
[`aes-gcm`]: https://github.com/RustCrypto/AEADs/tree/master/aes-gcm
[`anyhow`]: https://github.com/dtolnay/anyhow
[`bincode`]: https://github.com/bincode-org/bincode
[`card-backend`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/card-backend
[`card-backend-pcsc`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/pcsc
[`clap`]: https://github.com/clap-rs/clap/
[`clap_complete`]: https://github.com/clap-rs/clap/tree/master/clap_complete
[`digest`]: https://github.com/RustCrypto/traits/tree/master/digest
[`ed25519-dalek`]: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/ed25519-dalek
[`hakari`]: https://docs.rs/cargo-hakari/latest/cargo_hakari/index.html
[`hkdf`]: https://github.com/RustCrypto/KDFs/tree/master/hkdf
[`hmac`]: https://github.com/RustCrypto/MACs/tree/master/hmac
[`image`]: https://github.com/image-rs/image
[`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
[`openpgp-card`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main
[`openpgp-card-sequoia`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/openpgp-card-sequoia
[`pbkdf2`]: https://github.com/RustCrypto/password-hashes/tree/master/pbkdf2
[`ripemd`]: https://github.com/RustCrypto/hashes/tree/master/ripemd
[`rqrr`]: https://github.com/WanzenBug/rqrr/
[`sequoia-openpgp`]: https://gitlab.com/sequoia-pgp/sequoia
[`serde`]: https://github.com/dtolnay/serde
[`sha2`]: https://github.com/RustCrypto/hashes/tree/master/sha2
[`sharks`]: https://github.com/c0dearm/sharks
[`thiserror`]: https://github.com/dtolnay/thiserror
[`tokio`]: https://github.com/tokio-rs/tokio
[`tower`]: https://github.com/tower-rs/tower
[`tracing`]: https://github.com/tokio-rs/tracing
[`tracing-error`]: https://github.com/tokio-rs/tracing/tree/master/tracing-error
[`tracing-subscriber`]: https://github.com/tokio-rs/tracing/tree/master/tracing-subscriber
[`v4l`]: https://github.com/raymanfx/libv4l-rs/
[`zbar`]: https://github.com/mchehab/zbar
[`bindgen`]: https://github.com/rust-lang/rust-bindgen
[`pkg-config`]: https://github.com/rust-lang/pkg-config-rs
[comments]: <> (
Internal links, based on root path
)
[`keyforkd`]: /bin/keyforkd.md
[`keyfork shard transport`]: /bin/keyfork/shard/index.md#keyfork-shard-transport
[`keyfork recover remote-shard`]: /bin/keyfork/recover/index.md#keyfork-recover-remote-shard
[kshard-opgp-split]: /bin/keyfork-shard/openpgp/split.md
[kshard-opgp-combine]: /bin/keyfork-shard/openpgp/combine.md
[keyfork-rustdoc]: ./rustdoc/keyfork/index.html

70
docs/src/links.md.template Normal file
View File

@ -0,0 +1,70 @@
<!-- vim:set et sw=4 ts=4 tw=79 ft=markdown: -->
[comments]: <> (
Please keep all links contained in this file, so they can be reused if
necessary across multiple pages.
)
[comments]: <> (
External links
)
[application identifier]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.application_identifier
[cardholder name]: https://docs.rs/openpgp-card-sequoia/latest/openpgp_card_sequoia/struct.Card.html#method.cardholder_name
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
[BIP-0044]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
[SBOM]: https://en.wikipedia.org/wiki/SBOM
[Sequoia]: https://sequoia-pgp.org
[comments]: <> (
Crate source links
)
[`aes-gcm`]: https://github.com/RustCrypto/AEADs/tree/master/aes-gcm
[`anyhow`]: https://github.com/dtolnay/anyhow
[`bincode`]: https://github.com/bincode-org/bincode
[`card-backend`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/card-backend
[`card-backend-pcsc`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/pcsc
[`clap`]: https://github.com/clap-rs/clap/
[`clap_complete`]: https://github.com/clap-rs/clap/tree/master/clap_complete
[`digest`]: https://github.com/RustCrypto/traits/tree/master/digest
[`ed25519-dalek`]: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/ed25519-dalek
[`hakari`]: https://docs.rs/cargo-hakari/latest/cargo_hakari/index.html
[`hkdf`]: https://github.com/RustCrypto/KDFs/tree/master/hkdf
[`hmac`]: https://github.com/RustCrypto/MACs/tree/master/hmac
[`image`]: https://github.com/image-rs/image
[`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
[`openpgp-card`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main
[`openpgp-card-sequoia`]: https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/openpgp-card-sequoia
[`pbkdf2`]: https://github.com/RustCrypto/password-hashes/tree/master/pbkdf2
[`ripemd`]: https://github.com/RustCrypto/hashes/tree/master/ripemd
[`rqrr`]: https://github.com/WanzenBug/rqrr/
[`sequoia-openpgp`]: https://gitlab.com/sequoia-pgp/sequoia
[`serde`]: https://github.com/dtolnay/serde
[`sha2`]: https://github.com/RustCrypto/hashes/tree/master/sha2
[`sharks`]: https://github.com/c0dearm/sharks
[`thiserror`]: https://github.com/dtolnay/thiserror
[`tokio`]: https://github.com/tokio-rs/tokio
[`tower`]: https://github.com/tower-rs/tower
[`tracing`]: https://github.com/tokio-rs/tracing
[`tracing-error`]: https://github.com/tokio-rs/tracing/tree/master/tracing-error
[`tracing-subscriber`]: https://github.com/tokio-rs/tracing/tree/master/tracing-subscriber
[`v4l`]: https://github.com/raymanfx/libv4l-rs/
[`zbar`]: https://github.com/mchehab/zbar
[`bindgen`]: https://github.com/rust-lang/rust-bindgen
[`pkg-config`]: https://github.com/rust-lang/pkg-config-rs
[comments]: <> (
Internal links, based on root path
)
[`keyforkd`]: ${ROOT_PATH}/bin/keyforkd.md
[`keyfork shard transport`]: ${ROOT_PATH}/bin/keyfork/shard/index.md#keyfork-shard-transport
[`keyfork recover remote-shard`]: ${ROOT_PATH}/bin/keyfork/recover/index.md#keyfork-recover-remote-shard
[kshard-opgp-split]: ${ROOT_PATH}/bin/keyfork-shard/openpgp/split.md
[kshard-opgp-combine]: ${ROOT_PATH}/bin/keyfork-shard/openpgp/combine.md
[keyfork-rustdoc]: ./rustdoc/keyfork/index.html

4
docs/src/shard.md
View File

@ -1,3 +1,5 @@
{{#include links.md}}
# Keyfork Shard Commands
Sharding a seed allows "M-of-N" recovery of the seed, which is useful for
@ -77,5 +79,3 @@ 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

5
docs/src/usage.md
View File

@ -1,3 +1,5 @@
{{#include links.md}}
# Common Usage
Keyfork is a tool to help manage the creation and derivation of binary data
@ -74,6 +76,3 @@ the following command for an OpenPGP certificate with one of each subkey:
```sh
keyfork derive openpgp "John Doe <jdoe@example.com>"
```
[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki