keyfork-derive-util: add README / lib.rs docs

This commit is contained in:
Ryan Heywood 2024-02-10 23:58:25 -05:00
parent 5096df993e
commit 7817c3514e
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
3 changed files with 56 additions and 4 deletions

View File

@ -0,0 +1,52 @@
# Keyfork Derive: BIP-0032 Key Derivation
Keyfork offers a [BIP-0032] based hierarchial key derivation system enabling
the ability to create keys based on a [BIP-0032] seed, a value between 128 to
512 bits. The keys can be made using any algorithm supported by Keyfork Derive.
Newtypes can be added to wrap around foreign key types that aren't supported by
Keyfork.
Keys derived with the same parameters, from the same seed, will _always_ return
the same value. This makes Keyfork a reliable backend for generating encryption
or signature keys, as every key can be recovered using the previously used
derivation algorithm. However, this may be seen as a concern, as all an
attacker may need to recreate all previously-used seeds would be the original
derivation seed. For this reason, it is recommended to use the Keyfork server
for derivation from the root seed. The Keyfork server will ensure the root seed
and any highest-level keys (such as BIP-44, BIP-85, etc.) keys are not leaked.
The primary use case of Keyfork Derive will be the creation of Derivation
Requests, to be used by Keyforkd Client. In the included example, derivation is
performed directly on a master seed. This is how Keyforkd works internally.
## Example
```rust
use std::str::FromStr;
use keyfork_mnemonic_util::Mnemonic;
use keyfork_derive_util::{*, request::*};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mnemonic = Mnemonic::from_str(
"enter settle kiwi high shift absorb protect sword talent museum lazy okay"
)?;
let path = DerivationPath::from_str("m/44'/0'/0'/0/0")?;
let request = DerivationRequest::new(
DerivationAlgorithm::Secp256k1,
&path
);
let key1 = request.derive_with_mnemonic(&mnemonic)?;
let seed = mnemonic.seed(None)?;
let key2 = request.derive_with_master_seed(seed)?;
assert_eq!(key1, key2);
Ok(())
}
```
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

View File

@ -1,6 +1,6 @@
#![allow(clippy::module_name_repetitions, clippy::must_use_candidate)] #![allow(clippy::module_name_repetitions, clippy::must_use_candidate)]
//! BIP-0032 derivation utilities. #![doc = include_str!("../README.md")]
/// ///
pub mod extended_key; pub mod extended_key;

View File

@ -31,7 +31,7 @@ pub type Result<T, E = DerivationError> = std::result::Result<T, E>;
/// The algorithm to derive a key for. The choice of algorithm will result in a different resulting /// The algorithm to derive a key for. The choice of algorithm will result in a different resulting
/// derivation. /// derivation.
#[derive(Serialize, Deserialize, Clone, Debug)] #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
#[non_exhaustive] #[non_exhaustive]
pub enum DerivationAlgorithm { pub enum DerivationAlgorithm {
#[allow(missing_docs)] #[allow(missing_docs)]
@ -94,7 +94,7 @@ impl std::str::FromStr for DerivationAlgorithm {
} }
/// A derivation request. /// A derivation request.
#[derive(Serialize, Deserialize, Clone, Debug)] #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct DerivationRequest { pub struct DerivationRequest {
algorithm: DerivationAlgorithm, algorithm: DerivationAlgorithm,
path: DerivationPath, path: DerivationPath,
@ -211,7 +211,7 @@ impl DerivationRequest {
} }
/// A response to a [`DerivationRequest`] /// A response to a [`DerivationRequest`]
#[derive(Serialize, Deserialize, Clone, Debug)] #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct DerivationResponse { pub struct DerivationResponse {
/// The algorithm used to derive the data. /// The algorithm used to derive the data.
pub algorithm: DerivationAlgorithm, pub algorithm: DerivationAlgorithm,