History

Ryan Heywood e441ef520f keyforkd: appropriately handle or debug disconnects		2024-02-12 03:08:54 -05:00
..
src	keyforkd: appropriately handle or debug disconnects	2024-02-12 03:08:54 -05:00
Cargo.toml	keyforkd: impl test_util::run_test	2024-02-12 01:28:04 -05:00
README.md	keyforkd, keyfork-shard: add README.md	2024-01-20 01:17:56 -05:00

README.md

The Keyfork Server

The server uses a keyfork_frame'd bincode'd request+response format and can be interacted with by using the keyforkd_client crate.

All requests made to Keyfork are required to list at least two derivation paths. This helps prevent cases where the master seed or the general protocol seed are leaked by a client. An example is BIP-0044, where the path used is m/44'/0' for Bitcoin, and often m/44'/60' is used for Ethereum. To prevent an Ethereum wallet from deriving the Bitcoin coin seed, and to prevent leaking the master seed in general, all requests must contain at least two paths.

Additionally, this ensures that keys are not reused across separate purposes. Because keys are required to have at least two indexes, they are drawn to the pattern of using the first index as the key's purpose, such as m/ pgp' for OpenPGP.

Usage

The Keyfork server can be started by running the keyfork recover porcelain binary or by running keyforkd directly and entering a mnemonic. Once started, the Keyfork server will bind to a socket in XDG_RUNTIME_DIR by default, or KEYFORK_SOCKET_PATH pointing directly to where a socket will be bound. Upon the server's termination, the socket will be removed. The socket will not be removed by default when the server is starting.

Once started, the Keyfork server can be interacted with using the keyfork derive subcommand or individual keyfork-derive commands, such as keyfork-derive-openpgp. The former offers a more intuitive interface, but the latter may offer a lower dependency surface. These clients will connect to the server, typically using the keyforkd-client crate, and request a derived key. Once the server has received the derivation request, the server will log the request, as well as its best-effort guess on what path is being derived (using the keyfork-derive-path-data crate), to inform the user of what keys are requested. Once the server sends the client the new extended private key, the client can then choose to use the key as-is, or derive further keys.