Crate bip32

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.

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

Copyright © 2020-2023 iqlusion

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;

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 Definitions

• 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.