Struct SecretKey 

pub struct SecretKey(/* private fields */);

Secret key - a 256-bit key used to create ECDSA and Taproot signatures.

This value should be generated using a cryptographically secure pseudorandom number generator.

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 or Ord on SecretKey. If you really want to order secret keys then you can use as_secret_bytes 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 some formats (e.g. bincode) however other formats may be less optimal (e.g. cbor).

Examples

Basic usage:

use secp256k1::{rand, SecretKey};

let secret_key = SecretKey::new(&mut rand::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 to_secret_bytes(&self) -> [u8; 32]

Returns the secret key as a byte value.

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.

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

Returns a reference to the secret key as a byte array.

See note on Self::to_secret_bytes.

pub fn from_secret_bytes(data: [u8; 32]) -> Result<SecretKey, Error>

Converts a 32-byte array to a secret key.

See note on Self::to_secret_bytes.

Errors

Returns an error when the secret key is invalid: when it is all-zeros or would exceed the curve order when interpreted as a big-endian unsigned integer.

Examples

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

impl SecretKey

pub fn new<R>(rng: &mut R) -> SecretKey

where R: Rng + ?Sized,

Available on crate feature rand only.

Generates a new random secret key.

Examples

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

pub fn from_byte_array(data: [u8; 32]) -> Result<SecretKey, Error>

👎Deprecated since 0.33.0:

use from_secret_bytes instead

Converts a 32-byte array to a secret key.

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

Creates a new secret key using data from BIP-340 [Keypair].

Examples

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

let keypair = Keypair::new(&mut rand::rng());
let secret_key = SecretKey::from_keypair(&keypair);

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

👎Deprecated since 0.33.0:

use to_secret_bytes instead

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 sign_ecdsa(&self, msg: impl Into<Message>) -> Signature

Constructs an ECDSA signature for msg.

pub fn keypair(&self) -> Keypair

Returns the [Keypair] for this SecretKey.

This is equivalent to using [Keypair::from_secret_key].

pub fn public_key(&self) -> PublicKey

Returns the [PublicKey] for this SecretKey.

This is equivalent to using [PublicKey::from_secret_key].

pub fn x_only_public_key(&self) -> (XOnlyPublicKey, Parity)

Returns the [XOnlyPublicKey] (and its [Parity]) for this SecretKey.

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

Trait Implementations

impl<'a> Arbitrary<'a> for SecretKey

Available on crate feature arbitrary only.

fn arbitrary(u: &mut Unstructured<'a>) -> Result<SecretKey, Error>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl CPtr for SecretKey

type Target = u8

fn as_c_ptr(&self) -> *const <SecretKey as CPtr>::Target

fn as_mut_c_ptr(&mut self) -> *mut <SecretKey as CPtr>::Target

impl Clone for SecretKey

fn clone(&self) -> SecretKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SecretKey

impl Debug for SecretKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SecretKey

Available on crate feature serde only.

fn deserialize<D>(d: D) -> Result<SecretKey, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl EnrKey for SecretKey

type PublicKey = PublicKey

fn sign_v4(&self, msg: &[u8]) -> Result<Vec<u8>, SigningError>

Performs ENR-specific signing for the v4 identity scheme.

fn public(&self) -> <SecretKey as EnrKey>::PublicKey

Returns the public key associated with current key pair.

fn enr_to_public( content: &BTreeMap<Vec<u8>, Bytes>, ) -> Result<<SecretKey as EnrKey>::PublicKey, Error>

Provides a method to decode a raw public key from an ENR BTreeMap to a useable public key.

impl EnrKeyUnambiguous for SecretKey

fn decode_public( bytes: &[u8], ) -> Result<<SecretKey as EnrKey>::PublicKey, Error>

Decode raw bytes as corresponding public key.

impl Eq for SecretKey

impl<'a> From<&'a Keypair> for SecretKey

fn from(pair: &'a Keypair) -> SecretKey

Converts to this type from the input type.

impl From<Keypair> for SecretKey

fn from(pair: Keypair) -> SecretKey

Converts to this type from the input type.

impl FromStr for SecretKey

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<SecretKey, <SecretKey as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for SecretKey

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<I> Index<I> for SecretKey

where [u8]: Index<I>,

type Output = <[u8] as Index<I>>::Output

The returned type after indexing.

fn index(&self, index: I) -> &<SecretKey as Index<I>>::Output

Performs the indexing (container[index]) operation.

impl PartialEq for SecretKey

fn eq(&self, other: &SecretKey) -> bool

This implementation is designed to be constant time to help prevent side channel attacks.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for SecretKey

Available on crate feature serde only.

fn serialize<S>( &self, s: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 32 bytes