Struct bitcoin::SecretKey

pub struct SecretKey(_);

Expand description

Secret 256-bit key used as x in an ECDSA signature.

Side channel attacks

We have attempted to reduce the side channel attack surface by implementing a constant time eq method. For similar reasons we explicitly do not implement PartialOrd, Ord, or Hash on SecretKey. If you really want to order secrets keys then you can use AsRef to get at the underlying bytes and compare them - however this is almost certainly a bad idea.

Serde support

Implements de/serialization with the serde feature enabled. We treat the byte value as a tuple of 32 u8s for non-human-readable formats. This representation is optimal for for some formats (e.g. bincode) however other formats may be less optimal (e.g. cbor).

Examples

Basic usage:

use secp256k1::{rand, Secp256k1, SecretKey};

let secp = Secp256k1::new();
let secret_key = SecretKey::new(&mut rand::thread_rng());

Implementations§

§

impl SecretKey

pub fn display_secret(&self) -> DisplaySecret

Formats the explicit byte value of the secret key kept inside the type as a little-endian hexadecimal string using the provided formatter.

This is the only method that outputs the actual secret key value, and, thus, should be used with extreme caution.

Examples

use secp256k1::SecretKey;
let key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001").unwrap();

// Normal debug hides value (`Display` is not implemented for `SecretKey`).
// E.g., `format!("{:?}", key)` prints "SecretKey(#2518682f7819fb2d)".

// Here we explicitly display the secret value:
assert_eq!(
    "0000000000000000000000000000000000000000000000000000000000000001",
    format!("{}", key.display_secret())
);
// Also, we can explicitly display with `Debug`:
assert_eq!(
    format!("{:?}", key.display_secret()),
    format!("DisplaySecret(\"{}\")", key.display_secret())
);

§

impl SecretKey

pub fn non_secure_erase(&mut self)

Attempts to erase the contents of the underlying array.

Note, however, that the compiler is allowed to freely copy or move the contents of this array to other places in memory. Preventing this behavior is very subtle. For more discussion on this, please see the documentation of the zeroize crate.

§

impl SecretKey

pub fn new<R>(rng: &mut R) -> SecretKeywhere R: Rng + ?Sized,

Generates a new random secret key.

Examples

use secp256k1::{rand, SecretKey};
let secret_key = SecretKey::new(&mut rand::thread_rng());

pub fn from_slice(data: &[u8]) -> Result<SecretKey, Error>

Converts a SECRET_KEY_SIZE-byte slice to a secret key.

Examples

use secp256k1::SecretKey;
let sk = SecretKey::from_slice(&[0xcd; 32]).expect("32 bytes, within curve order");

pub fn from_keypair(keypair: &KeyPair) -> SecretKey

Creates a new secret key using data from BIP-340 KeyPair.

Examples

use secp256k1::{rand, Secp256k1, SecretKey, KeyPair};

let secp = Secp256k1::new();
let key_pair = KeyPair::new(&secp, &mut rand::thread_rng());
let secret_key = SecretKey::from_keypair(&key_pair);

pub fn from_hashed_data<H>(data: &[u8]) -> SecretKeywhere H: ThirtyTwoByteHash + Hash,

Constructs a SecretKey by hashing data with hash algorithm H.

Requires the feature bitcoin_hashes to be enabled.

Examples

use secp256k1::hashes::{sha256, Hash};
use secp256k1::SecretKey;

let sk1 = SecretKey::from_hashed_data::<sha256::Hash>("Hello world!".as_bytes());
// is equivalent to
let sk2 = SecretKey::from(sha256::Hash::hash("Hello world!".as_bytes()));

assert_eq!(sk1, sk2);

pub fn secret_bytes(&self) -> [u8; 32]

Returns the secret key as a byte value.

pub fn negate(self) -> SecretKey

Negates the secret key.

pub fn add_tweak(self, tweak: &Scalar) -> Result<SecretKey, Error>

Tweaks a SecretKey by adding tweak modulo the curve order.

Errors

Returns an error if the resulting key would be invalid.

pub fn mul_tweak(self, tweak: &Scalar) -> Result<SecretKey, Error>

Tweaks a SecretKey by multiplying by tweak modulo the curve order.

Errors

Returns an error if the resulting key would be invalid.

pub fn keypair<C>(&self, secp: &Secp256k1<C>) -> KeyPairwhere C: Signing,

Returns the KeyPair for this SecretKey.

This is equivalent to using KeyPair::from_secret_key.

pub fn public_key<C>(&self, secp: &Secp256k1<C>) -> PublicKeywhere C: Signing,

Returns the PublicKey for this SecretKey.

This is equivalent to using PublicKey::from_secret_key.

pub fn x_only_public_key<C>( &self, secp: &Secp256k1<C> ) -> (XOnlyPublicKey, Parity)where C: Signing,

Returns the XOnlyPublicKey (and it’s Parity) for this SecretKey.

This is equivalent to XOnlyPublicKey::from_keypair(self.keypair(secp)).

Trait Implementations§

§

impl AsRef<[u8; 32]> for SecretKey

§

fn as_ref(&self) -> &[u8; 32]

Gets a reference to the underlying array.

Side channel attacks

Using ordering functions (PartialOrd/Ord) on a reference to secret keys leaks data because the implementations are not constant time. Doing so will make your code vulnerable to side channel attacks. SecretKey::eq is implemented using a constant time algorithm, please consider using it to do comparisons of secret keys.

§