keyfork-derive-util: add README / lib.rs docs
This commit is contained in:
parent
5096df993e
commit
7817c3514e
|
@ -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
|
|
@ -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;
|
||||||
|
|
|
@ -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,
|
||||||
|
|
Loading…
Reference in New Issue