From c8f255f0aa78ce5cda1022b4c1606440b49a99b7 Mon Sep 17 00:00:00 2001 From: ryan Date: Mon, 15 Jan 2024 01:36:30 -0500 Subject: [PATCH] docs: add list of dependencies and why they're used --- docs/src/SUMMARY.md | 2 +- docs/src/dev-guide/auditing.md | 250 +++++++++++++++++++++++++++++++++ 2 files changed, 251 insertions(+), 1 deletion(-) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 771ec27..8bfde2b 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -27,4 +27,4 @@ - [Writing Binaries](./dev-guide/index.md) - [Provisioners](./dev-guide/provisioners.md) -- [Auditing](./dev-guide/auditing.md) +- [Auditing Dependencies](./dev-guide/auditing.md) diff --git a/docs/src/dev-guide/auditing.md b/docs/src/dev-guide/auditing.md index 196aa0c..57556fc 100644 --- a/docs/src/dev-guide/auditing.md +++ b/docs/src/dev-guide/auditing.md @@ -19,4 +19,254 @@ to ensure only the required dependencies are enabled. This reduces the burden of auditors, but it does mean we can't use projects such as [`hakari`] to optimize full-project builds. +Below is a list of all immediate dependencies enabled by default, and why they +have been used, as of 2024-01-15. + +### Common Dependencies + +These dependencies will show up often: + +* [`serde`]: Rust-native serialization and deserialization of types. +* [`thiserror`]: Automatic generation of error types. +* [`sequoia-openpgp`]: An OpenPGP interface. + +## `keyfork` + +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`. +* [`clap`]: Command line argument parsing, helps building an intuitive command + line interface. +* [`clap_complete`]: Shell autocompletion file generator. Helps the user + experience. Can be disabled. +* [`keyfork-derive-openpgp`] +* [`keyfork-derive-util`] +* [`keyfork-entropy`] +* [`keyfork-mnemonic-util`] +* [`keyfork-prompt`] +* [`keyfork-qrcode`] +* [`keyfork-shard`] +* [`keyforkd`] +* [`keyforkd-client`] +* [`openpgp-card`]: Managing OpenPGP smart cards. +* [`openpgp-card-sequoia`]: Managing OpenPGP smart cards with Sequoia OpenPGP. +* [`sequoia-openpgp`]: Manage OpenPGP features across Keyfork crates. +* [`serde`] +* [`smex`] +* [`thiserror`] +* [`tokio`]: Starting and running the Keyfork server. + +## `keyforkd` + +A server to handle derivation requests without providing access to the root +seed or close-to-root derivations. + +* [`bincode`]: Compact data serialization. +* [`keyfork-derive-path-data`] +* [`keyfork-derive-util`] +* [`keyfork-frame`] +* [`keyfork-mnemonic-util`] +* [`keyforkd-models`] +* [`serde`] +* [`thiserror`] +* [`tokio`]: An async framework, used for handling many UNIX server clients. +* [`tower`]: Framework traits for providing a Service. +* [`tracing`]: Trace requests made to Keyforkd. +* [`tracing-error`]: Error capture support for tracing. +* [`tracing-subscriber`]: Configure logging and span-capture rules for tracing. + +## keyforkd-client + +A client for [`keyforkd`]. + +* [`bincode`]: Compact data serialization. +* [`keyfork-derive-util`] +* [`keyfork-frame`] +* [`keyforkd-models`] +* [`thiserror`] + +## `keyforkd-models` + +Types used by keyforkd and keyforkd-client + +* [`keyfork-derive-util`] +* [`serde`] +* [`thiserror`] + +## `keyfork-derive-key` + +Derivation of arbitrary data using Keyfork. + +* [`keyfork-derive-util`] +* [`keyforkd-client`] +* [`smex`] +* [`thiserror`] + +## `keyfork-derive-openpgp` + +Derivation of OpenPGP Keys using Keyfork. + +* [`anyhow`]: Create errors accepted by Sequoia. +* [`ed25519-dalek`]: Ed25519 key parsing. +* [`keyfork-derive-util`] +* [`keyforkd-client`] +* [`sequoia-openpgp`]: Creation of OpenPGP Keys from provided derived keys. + +## `keyfork-derive-path-data` + +Guessing possible meanings for BIP-0032 derivation paths. + +* [`keyfork-derive-util`] + +## `keyfork-derive-util` + +BIP-0032 derivation. + +* [`digest`]: Hash digest creation. +* [`ed25519-dalek`]: Ed25519 key parsing and arithmetic. +* [`hmac`]: Derivation of keys using HMAC. +* [`k256`]: secp256k1 (K-256) key parsing and arithmetic. +* [`keyfork-mnemonic-util`] +* [`ripemd`]: Generating hash for fingerprinting of BIP-0032 derived data. +* [`serde`] +* [`sha2`]: Generating hashes for fingerprinting and derivation of data. +* [`thiserror`] + +## `keyfork-shard` + +M-of-N recombination of secret data using Shamir's Secret Sharing. + +* [`aes-gcm`]: Transport encryption for Shamir shares. +* [`anyhow`]: Create errors accepted by Sequoia. +* [`card-backend`]: OpenPGP card backend management. +* [`card-backend-pcsc`]: PCSC support for OpenPGP-card. +* [`hkdf`]: Key derivation for transport encryption keys. +* [`keyfork-derive-openpgp`] +* [`keyfork-mnemonic-util`]: Encoding encrypted shards using mnemonics. +* [`keyfork-prompt`] +* [`keyfork-qrcode`]: Encoding and decoding of encrypted shards using QR codes. +* [`openpgp-card`]: OpenPGP card support. +* [`openpgp-card-sequoia`]: Sequoia-OpenPGP support for openpgp-card. +* [`sequoia-openpgp`] + +## `keyfork-qrcode` + +Encoding and decoding of QR codes + +* [`image`]: Parse image data, to be sent to rqrr. +* [`rqrr`]: Rust native QR decoding +* [`thiserror`] +* [`v4l`]: Read video frames from a camera device. + +## `keyfork-zbar` + +ZBar bindings and Rustic interface. + +* [`image`]: Transformation from `image::Image` to a ZBar `Image`. +* [`keyfork-zbar-sys`] + +## `keyfork-zbar-sys` + +Generated bindings for [`zbar`] + +### Build dependencies + +* [`bindgen`]: Automatic binding generation. +* [`pkg-config`]: Probe for zbar system libary. + +## `keyfork-crossterm` + +Fork of: https://github.com/rust-lang/pkg-config-rs + +## `keyfork-entropy` + +Load entropy from a secure source on the current system. + +## `keyfork-frame` + +Frame data in a length-storing checksum-verified format. + +* [`sha2`]: Generate and verify checksum of framed data +* [`thiserror`] +* [`tokio`]: Read and write from AsyncRead and AsyncWrite sources. + +## `keyfork-mnemonic-util` + +* [`hmac`]: Hash utilities. +* [`sha2`]: Checksum of mnemonic data and hash for pbkdf2 +* [`pbkdf2`]: BIP-0032 seed generation + +## `keyfork-prompt` + +* [`keyfork-crossterm`]: Interacting with the terminal. +* [`keyfork-mnemonic-util`] +* [`thiserror`] + +## `keyfork-plumbing` + +Binaries for `keyfork-entropy` and `keyfork-mnemonic-from-seed`. + +* [`keyfork-entropy`] +* [`keyfork-mnemonic-util`] +* [`smex`] + +## `keyfork-slip10-test-data` + +Test data for SLIP10/BIP-0032 derivation. + +* [`smex`] + +## `smex` + +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 +[`keyfork-derive-util`]: #keyfork-derive-util +[`keyfork-entropy`]: #keyfork-entropy +[`keyfork-frame`]: #keyfork-frame +[`keyfork-mnemonic-util`]: #keyfork-mnemonic-util +[`keyfork-prompt`]: #keyfork-prompt +[`keyfork-qrcode`]: #keyfork-qrcode +[`keyfork-shard`]: #keyfork-shard +[`keyfork-zbar-sys`]: #keyfork-zbar-sys +[`keyforkd`]: #keyforkd +[`keyforkd-client`]: #keyforkd-client +[`keyforkd-models`]: #keyforkd-models +[`smex`]: #smex