Struct SessionSecretRand 

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

Session secret randomness for a MuSig signing session.

Implementations

impl SessionSecretRand

pub fn display_secret(&self) -> DisplaySecret

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

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

Examples

use secp256k1::musig::SessionSecretRand;

let secret = SessionSecretRand::assume_uniformly_random([0x01; 32]);
// Here we explicitly display the secret value:
assert_eq!(
    format!("{}", secret.display_secret()),
    "0101010101010101010101010101010101010101010101010101010101010101"
);
// Also, we can explicitly display with `Debug`:
assert_eq!(
    format!("{:?}", secret.display_secret()),
    format!("DisplaySecret(\"{}\")", secret.display_secret())
);

impl SessionSecretRand

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 SessionSecretRand

pub fn assume_unique_per_nonce_gen( inner: [u8; 32], sk: &SecretKey, ) -> SessionSecretRand

Creates a new SessionSecretRand with the given bytes mixed with secret key material.

Special care must be taken that inner is unique for every call to this method made with the same sk: reusing a value produces a repeated nonce, which leaks the secret key. The simplest recommendation is to use a cryptographically random 32-byte value.

Because sk is mixed into the returned value, inner itself does not need to be unpredictable or kept secret; a non-repeating counter or similar weak value is sufficient. If you have access to a non-repeating counter, consider new_nonce_pair_counter or KeyAggCache::nonce_gen, which key the nonce derivation directly. If you cannot provide a secret key, but have access to uniformly random bytes, then see SessionSecretRand::assume_uniformly_random.

The mixing is the same as the one done by libsecp256k1’s nonce function when it is given a secret key, as specified in BIP-327’s NonceGen: the returned value is SHA256_tagged("MuSig/aux", inner) XOR sk.

If the rand feature is enabled, [SessionSecretRand::from_rng] can be used to generate a random session secret.

Panics

Panics if the value mixed with sk is the all-zeros string, i.e., if the tagged hash of inner equals the secret bytes of sk. An all-zeros session secret is disallowed by the upstream library. This cannot occur in practice unless the input was deliberately constructed from the secret key.

pub fn assume_uniformly_random(inner: [u8; 32]) -> SessionSecretRand

Creates a new SessionSecretRand directly from the given bytes, without mixing in any secret key material.

The input to this function must be UNIFORMLY RANDOM AND KEPT SECRET, even from the other signers. If a co-signer can predict these bytes, they can recompute your secret nonce and extract your secret key from your partial signature. Prefer [SessionSecretRand::from_rng], or SessionSecretRand::assume_unique_per_nonce_gen which mixes in secret key material and therefore only requires uniqueness. If you do not have access to a random number generator, but do have access to a non-repeating counter, use new_nonce_pair_counter or KeyAggCache::nonce_gen instead.

Panics

Panics if passed the all-zeros string. This is disallowed by the upstream library.

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

Obtains the inner bytes of the SessionSecretRand.

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

Obtains a reference to the inner bytes of the SessionSecretRand.

Trait Implementations

impl Debug for SessionSecretRand

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

Formats the value using the given formatter.