Crate bip32[][src]

Expand description

Pure Rust implementation of BIP-0032: Hierarchical Deterministic Wallets.

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

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:

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_xprv_str.starts_with("xprv"));

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

Mnemonicbip39

BIP39 mnemonic phrases: sequences of words representing cryptographic keys.

Prefix

BIP32 extended key prefixes a.k.a. “versions” (e.g. xpub, xprv)

Seedbip39

BIP39 seeds.

Enums

Error

Error type.

Languagebip39

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.