keyfork-user-guide: add dev guide
This commit is contained in:
parent
9599734bd6
commit
8809db6f7f
|
@ -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)
|
||||
|
|
|
@ -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
|
Loading…
Reference in New Issue