Crate bip32

Expand description

§BIP32: HD Wallets

BIP32 hierarchical key derivation implemented in a generic, no_std-friendly manner. Supports deriving keys using the pure Rust k256 crate or the C library-backed secp256k1 crate.

Diagram

Documentation

§About

BIP32 is an algorithm for generating a hierarchy of elliptic curve keys, a.k.a. “wallets”, from a single seed value. A related algorithm also implemented by this crate, BIP39, provides a way to derive the seed value from a set of 24-words from a preset list, a.k.a. a “mnemonic”.

§Minimum Supported Rust Version

Rust 1.65 or newer.

In the future, we reserve the right to change MSRV (i.e. MSRV is out-of-scope for this crate’s SemVer guarantees), however when we do it will be accompanied by a minor version bump.

§License

bip32.rs is distributed under the terms of either the MIT license or the Apache License (Version 2.0), at your option.

See LICENSE-APACHE (Apache License, Version 2.0) and LICENSE-MIT for further details.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

§Backends

This crate provides a generic implementation of BIP32 which can be used with any backing provider which implements the PrivateKey and PublicKey traits. The following providers are built into this crate, under the following crate features:

secp256k1 (enabled by default): support for the pure Rust k256 crate, with XPrv and XPub type aliases.
secp256k1-ffi: support for Bitcoin Core’s libsecp256k1 C library, as wrapped by the secp256k1 Rust crate.

§Limitations and further work

Only 24-word BIP39 mnemonics are supported
BIP43, BIP44, BIP49, BIP84 not yet properly supported

§Usage

The following is an end-to-end example of how to generate a random BIP39 mnemonic and use it to derive child keys according to a provided BIP32 derivation path.

§Accessing `OsRng`

The following example uses OsRng for cryptographically secure random number generation. To use it, you need to include rand_core with the std feature by adding the following to Cargo.toml:

rand_core = { version = "0.6", features = ["std"] }

(on embedded platforms, you will need to supply our own RNG)

§Rust code example

use bip32::{Mnemonic, Prefix, XPrv};
use rand_core::OsRng;

// Generate random Mnemonic using the default language (English)
let mnemonic = Mnemonic::random(&mut OsRng, Default::default());

// Derive a BIP39 seed value using the given password
let seed = mnemonic.to_seed("password");

// Derive the root `XPrv` from the `seed` value
let root_xprv = XPrv::new(&seed)?;
assert_eq!(root_xprv, XPrv::derive_from_path(&seed, &"m".parse()?)?);

// Derive a child `XPrv` using the provided BIP32 derivation path
let child_path = "m/0/2147483647'/1/2147483646'";
let child_xprv = XPrv::derive_from_path(&seed, &child_path.parse()?)?;

// Get the `XPub` associated with `child_xprv`.
let child_xpub = child_xprv.public_key();

// Serialize `child_xprv` as a string with the `xprv` prefix.
let child_xprv_str = child_xprv.to_string(Prefix::XPRV);
assert!(child_xprv_str.starts_with("xprv"));

// Serialize `child_xpub` as a string with the `xpub` prefix.
let child_xpub_str = child_xpub.to_string(Prefix::XPUB);
assert!(child_xpub_str.starts_with("xpub"));

// Get the ECDSA/secp256k1 signing and verification keys for the xprv and xpub
let signing_key = child_xprv.private_key();
let verification_key = child_xpub.public_key();

// Sign and verify an example message using the derived keys.
use bip32::secp256k1::ecdsa::{
    signature::{Signer, Verifier},
    Signature
};

let example_msg = b"Hello, world!";
let signature: Signature = signing_key.sign(example_msg);
assert!(verification_key.verify(example_msg, &signature).is_ok());

Re-exports§

pub use k256 as secp256k1;secp256k1

Structs§

ChildNumber: Index of a particular child key for a given (extended) private key.
DerivationPathalloc: Derivation paths within a hierarchical keyspace.
ExtendedKey: Serialized extended key (e.g. xprv and xpub).
ExtendedKeyAttrs: Extended key attributes: fields common to extended keys including depth, fingerprints, child numbers, and chain codes.
ExtendedPrivateKey: Extended private keys derived using BIP32.
ExtendedPublicKey: Extended public keys derived using BIP32.
Mnemonicmnemonic and bip39: BIP39 mnemonic phrases: sequences of words representing cryptographic keys.
Prefix: BIP32 extended key prefixes a.k.a. “versions” (e.g. xpub, xprv)
Seedbip39 and mnemonic: BIP39 seeds.

Enums§

Error: Error type.
Languagemnemonic and bip39: Supported languages.

Constants§

KEY_SIZE: Size of input key material and derived keys.

Traits§

PrivateKey: Trait for key types which can be derived using BIP32.
PublicKey: Trait for key types which can be derived using BIP32.

Type Aliases§

ChainCode: Chain code: extension for both private and public keys which provides an additional 256-bits of entropy.
Depth: Derivation depth.
KeyFingerprint: BIP32 key fingerprints.
PrivateKeyBytes: Bytes which represent a private key.
PublicKeyBytes: Bytes which represent a public key.
Result: Result type.
Version: BIP32 “versions”: integer representation of the key prefix.
XPrvsecp256k1: Extended private secp256k1 ECDSA signing key.
XPubsecp256k1: Extended public secp256k1 ECDSA verification key.

Crate bip32Copy item path