From 8809db6f7f0e41a3c85a11d81558122378c6fcff Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 18 Oct 2023 13:24:07 -0500 Subject: [PATCH] keyfork-user-guide: add dev guide --- keyfork-user-guide/src/SUMMARY.md | 1 + keyfork-user-guide/src/dev-guide/index.md | 37 +++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 keyfork-user-guide/src/dev-guide/index.md diff --git a/keyfork-user-guide/src/SUMMARY.md b/keyfork-user-guide/src/SUMMARY.md index 0652333..3579e0e 100644 --- a/keyfork-user-guide/src/SUMMARY.md +++ b/keyfork-user-guide/src/SUMMARY.md @@ -11,3 +11,4 @@ - [keyfork-mnemonic-from-seed](./bin/keyfork-plumbing/mnemonic-from-seed.md) - [keyfork-derive-key](./bin/keyfork-derive-key.md) - [keyfork-derive-openpgp](./bin/keyfork-derive-openpgp.md) +- [Development Guide](./dev-guide/index.md) diff --git a/keyfork-user-guide/src/dev-guide/index.md b/keyfork-user-guide/src/dev-guide/index.md new file mode 100644 index 0000000..c7a2028 --- /dev/null +++ b/keyfork-user-guide/src/dev-guide/index.md @@ -0,0 +1,37 @@ +# Development Guide + +### Binaries - Porcelain and Plumbing + +Binaries are split into two categories, porcelain (such as `keyfork`) and +plumbing (just about everything else). Porcelain binaries include what can be +called "the kitchen sink". They offer support for everything - an intuitive +interface, automatic `keyforkd` management, interconnectivity between +derivation utilities and provisioning utilities, and the ability to read from +and write to a configuration file. Plumbing binaries, on the other hand, are +often very rough around the edges and pull in as few dependencies as possible. +Usually, only cryptographic functionality (such as `sequoia-openpgp` or +`dalek-ed25519`) or hardware integration libraries (such as `openpgp-card`) are +included. + +### Auditing Dependencies + +Dependencies must be reviewed before being added to the repository, and must +not be added for pure convenience. There are few exceptions, such as `clap` and +`thiserror`, which provide derivation macros that are used heavily throughout +`keyfork` and the codebase as a whole. Any dependency added must be reviewed at +least on a surface level to ensure no malicious actions are performed with the +data the library will be responsible for handling. For example, any use of +`std::process` in a crate providing cryptographic functions should be heavily +scrutinized, and any crate that loads arbitrary code or performs networking +requests should have an incredibly important reason for doing so. + +Dependencies should be restricted such that the least amount of dead code is +enabled. For instance, a crate such as `keyfork_derive_openpgp` can only make +use of the `ed25519` algorithm, so it exports its own `derive_util` that only +includes the crates required for that library. This can then be used by +programs such as `keyfork-shard`'s OpenPGP mode or `keyfork provision openpgp` +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. + +[`hakari`]: https://docs.rs/cargo-hakari/latest/cargo_hakari/index.html