Struct schnorrkel::keys::Keypair

source ·
pub struct Keypair {
    pub secret: SecretKey,
    pub public: PublicKey,
}
Expand description

A Ristretto Schnorr keypair.

Fields§

§secret: SecretKey

The secret half of this keypair.

§public: PublicKey

The public half of this keypair.

Implementations§

source§

impl Keypair

source

pub fn to_bytes(&self) -> [u8; 96]

Serialize Keypair to bytes.

Returns

A byte array [u8; KEYPAIR_LENGTH] consisting of first a SecretKey serialized cannonically, and next the Ristterro PublicKey

Examples
use schnorrkel::{Keypair, KEYPAIR_LENGTH};

let keypair: Keypair = Keypair::generate();
let bytes: [u8; KEYPAIR_LENGTH] = keypair.to_bytes();
let keypair_too = Keypair::from_bytes(&bytes[..]).unwrap();
assert_eq!(&bytes[..], & keypair_too.to_bytes()[..]);
source

pub fn from_bytes(bytes: &[u8]) -> SignatureResult<Keypair>

Deserialize a Keypair from bytes.

Inputs
  • bytes: an &[u8] consisting of byte representations of first a SecretKey and then the corresponding ristretto PublicKey.
Examples
use schnorrkel::{Keypair, KEYPAIR_LENGTH};
use hex_literal::hex;

// TODO: Fix test vector
// let keypair_bytes = hex!("28b0ae221c6bb06856b287f60d7ea0d98552ea5a16db16956849aa371db3eb51fd190cce74df356432b410bd64682309d6dedb27c76845daf388557cbac3ca3446ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a");
// let keypair: Keypair = Keypair::from_bytes(&keypair_bytes[..]).unwrap();
// assert_eq!(&keypair_bytes[..], & keypair.to_bytes()[..]);
Returns

A Result whose okay value is an EdDSA Keypair or whose error value is an SignatureError describing the error that occurred.

source

pub fn to_half_ed25519_bytes(&self) -> [u8; 96]

Serialize Keypair to bytes with Ed25519 secret key format.

Returns

A byte array [u8; KEYPAIR_LENGTH] consisting of first a SecretKey serialized like Ed25519, and next the Ristterro PublicKey

source

pub fn from_half_ed25519_bytes(bytes: &[u8]) -> SignatureResult<Keypair>

Deserialize a Keypair from bytes with Ed25519 style SecretKey format.

Inputs
  • bytes: an &[u8] representing the scalar for the secret key, and a compressed Ristretto point, both as bytes.
Examples
use schnorrkel::{Keypair, KEYPAIR_LENGTH};
use hex_literal::hex;

let keypair_bytes = hex!("28b0ae221c6bb06856b287f60d7ea0d98552ea5a16db16956849aa371db3eb51fd190cce74df356432b410bd64682309d6dedb27c76845daf388557cbac3ca3446ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a");
let keypair: Keypair = Keypair::from_half_ed25519_bytes(&keypair_bytes[..]).unwrap();
assert_eq!(&keypair_bytes[..], & keypair.to_half_ed25519_bytes()[..]);
Returns

A Result whose okay value is an EdDSA Keypair or whose error value is an SignatureError describing the error that occurred.

source

pub fn generate_with<R>(csprng: R) -> Keypairwhere R: CryptoRng + RngCore,

Generate a Ristretto Schnorr Keypair directly, bypassing the MiniSecretKey layer.

Example

use rand::{Rng, rngs::OsRng};
use schnorrkel::Keypair;
use schnorrkel::Signature;

let keypair: Keypair = Keypair::generate_with(OsRng);
Input

A CSPRNG with a fill_bytes() method, e.g. rand_chacha::ChaChaRng.

We generate a SecretKey directly bypassing MiniSecretKey, so our secret keys do not satisfy the high bit “clamping” impoised on Ed25519 keys.

source

pub fn generate() -> Keypair

Generate a Ristretto Schnorr Keypair directly, from a user suplied csprng, bypassing the MiniSecretKey layer.

source§

impl Keypair

source

pub fn sign<T: SigningTranscript>(&self, t: T) -> Signature

Sign a transcript with this keypair’s secret key.

Requires a SigningTranscript, normally created from a SigningContext and a message. Returns a Schnorr signature.

Examples

Internally, we manage signature transcripts using a 128 bit secure STROBE construction based on Keccak, which itself is extremly fast and secure. You might however influence performance or security by prehashing your message, like

use schnorrkel::{Signature,Keypair};
use rand::prelude::*; // ThreadRng,thread_rng
use sha3::Shake128;
use sha3::digest::{Input};

let mut csprng: ThreadRng = thread_rng();
let keypair: Keypair = Keypair::generate_with(&mut csprng);
let message: &[u8] = b"All I want is to pet all of the dogs.";

// Create a hash digest object and feed it the message:
let prehashed = Shake128::default().chain(message);

We require a “context” string for all signatures, which should be chosen judiciously for your project. It should represent the role the signature plays in your application. If you use the context in two purposes, and the same key, then a signature for one purpose can be substituted for the other.

let ctx = signing_context(b"My Signing Context");

let sig: Signature = keypair.sign(ctx.xof(prehashed));
source

pub fn sign_simple(&self, ctx: &[u8], msg: &[u8]) -> Signature

Sign a message with this keypair’s secret key.

source

pub fn verify<T: SigningTranscript>( &self, t: T, signature: &Signature ) -> SignatureResult<()>

Verify a signature by keypair’s public key on a transcript.

Requires a SigningTranscript, normally created from a SigningContext and a message, as well as the signature to be verified.

Examples
use schnorrkel::{Keypair,Signature,signing_context};
use rand::prelude::*; // ThreadRng,thread_rng

let mut csprng: ThreadRng = thread_rng();
let keypair: Keypair = Keypair::generate_with(&mut csprng);
let message: &[u8] = b"All I want is to pet all of the dogs.";

let ctx = signing_context(b"Some context string");

let sig: Signature = keypair.sign(ctx.bytes(message));

assert!( keypair.public.verify(ctx.bytes(message), &sig).is_ok() );
source

pub fn verify_simple( &self, ctx: &[u8], msg: &[u8], signature: &Signature ) -> SignatureResult<()>

Verify a signature by keypair’s public key on a message.

source

pub fn sign_doublecheck<T>(&self, t: T) -> SignatureResult<Signature>where T: SigningTranscript + Clone,

Sign a message with this SecretKey, but doublecheck the result.

source

pub fn sign_simple_doublecheck( &self, ctx: &[u8], msg: &[u8] ) -> SignatureResult<Signature>

Sign a message with this SecretKey, but doublecheck the result.

source§

impl Keypair

source

pub fn vrf_create_hash<T: VRFSigningTranscript>(&self, t: T) -> VRFInOut

Evaluate the VRF on the given transcript.

source§

impl Keypair

source

pub fn dleq_proove<T>( &self, t: T, p: &VRFInOut, kusama: bool ) -> (VRFProof, VRFProofBatchable)where T: SigningTranscript,

Produce DLEQ proof.

We assume the VRFInOut paramater has been computed correctly by multiplying every input point by self.secret, like by using one of the vrf_create_* methods on SecretKey. If so, we produce a proof that this multiplication was done correctly.

source

pub fn vrf_sign<T>(&self, t: T) -> (VRFInOut, VRFProof, VRFProofBatchable)where T: VRFSigningTranscript,

Run VRF on one single input transcript, producing the outpus and correspodning short proof.

There are schemes like Ouroboros Praos in which nodes evaluate VRFs repeatedly until they win some contest. In these case, you should probably use vrf_sign_n_check to gain access to the VRFInOut from vrf_create_hash first, and then avoid computing the proof whenever you do not win.

source

pub fn vrf_sign_extra<T, E>( &self, t: T, extra: E ) -> (VRFInOut, VRFProof, VRFProofBatchable)where T: VRFSigningTranscript, E: SigningTranscript,

Run VRF on one single input transcript and an extra message transcript, producing the outpus and correspodning short proof.

source

pub fn vrf_sign_after_check<T, F>( &self, t: T, check: F ) -> Option<(VRFInOut, VRFProof, VRFProofBatchable)>where T: VRFSigningTranscript, F: FnMut(&VRFInOut) -> bool,

Run VRF on one single input transcript, producing the outpus and correspodning short proof only if the result first passes some check.

There are schemes like Ouroboros Praos in which nodes evaluate VRFs repeatedly until they win some contest. In these case, you might use this function to short circuit computing the full proof.

source

pub fn vrf_sign_extra_after_check<T, E, F>( &self, t: T, check: F ) -> Option<(VRFInOut, VRFProof, VRFProofBatchable)>where T: VRFSigningTranscript, E: SigningTranscript, F: FnMut(&VRFInOut) -> Option<E>,

Run VRF on one single input transcript, producing the outpus and correspodning short proof only if the result first passes some check, which itself returns an extra message transcript.

source

pub fn vrfs_sign<T, I>( &self, ts: I ) -> (Box<[VRFInOut]>, VRFProof, VRFProofBatchable)where T: VRFSigningTranscript, I: IntoIterator<Item = T>,

Run VRF on several input transcripts, producing their outputs and a common short proof.

We merge the VRF outputs using variable time arithmetic, so if even the hash of the message being signed is sensitive then you might reimplement some constant time variant.

source

pub fn vrfs_sign_extra<T, E, I>( &self, ts: I, extra: E ) -> (Box<[VRFInOut]>, VRFProof, VRFProofBatchable)where T: VRFSigningTranscript, E: SigningTranscript, I: IntoIterator<Item = T>,

Run VRF on several input transcripts and an extra message transcript, producing their outputs and a common short proof.

We merge the VRF outputs using variable time arithmetic, so if even the hash of the message being signed is sensitive then you might reimplement some constant time variant.

source§

impl Keypair

source

pub fn hard_derive_mini_secret_key<B: AsRef<[u8]>>( &self, cc: Option<ChainCode>, i: B ) -> (MiniSecretKey, ChainCode)

Vaguely BIP32-like “hard” derivation of a MiniSecretKey from a SecretKey

We do not envision any “good reasons” why these “hard” derivations should ever be used after the soft Derivation trait. We similarly do not believe hard derivations make any sense for ChainCodes or ExtendedKeys types. Yet, some existing BIP32 workflows might do these things, due to BIP32’s de facto stnadardization and poor design. In consequence, we provide this method to do “hard” derivations in a way that should work with all BIP32 workflows and any permissible mutations of SecretKey. This means only that we hash the SecretKey’s scalar, but not its nonce becuase the secret key remains valid if the nonce is changed.

source

pub fn derive_secret_key<T>( &self, t: T, cc: ChainCode ) -> (SecretKey, ChainCode)where T: SigningTranscript,

Derive a secret key and new chain code from a key pair and chain code.

We expect the trait methods of Keypair as Derivation to be more useful since signing anything requires the public key too.

source§

impl Keypair

source

pub fn issue_ecqv_cert<T>( &self, t: T, seed_public_key: &PublicKey ) -> ECQVCertSecretwhere T: SigningTranscript,

Issue an ECQV implicit certificate

Aside from the issuing Keypair supplied as self, you provide both (1) a SigningTranscript called t that incorporates both the context and the certificate requester’s identity, and (2) the seed_public_key supplied by the certificate recipient in their certificate request. We return an ECQVCertSecret which the issuer sent to the certificate requester, ans from which the certificate requester derives their certified key pair.

source§

impl Keypair

source

pub fn issue_self_ecqv_cert<T>(&self, t: T) -> (ECQVCertPublic, SecretKey)where T: SigningTranscript + Clone,

Issue an ECQV Implicit Certificate for yourself

We can issue an implicit certificate to ourselves if we merely want to certify an associated public key. We should prefer this option over “hierarchical deterministic” key derivation because compromizing the resulting secret key does not compromize the issuer’s secret key.

In this case, we avoid the entire interactive protocol described by issue_ecqv_cert and accept_ecqv_cert by hiding it an all managment of the ephemeral Keypair inside this function.

Aside from the issuing secret key supplied as self, you provide only a digest h that incorporates any context and metadata pertaining to the issued key.

source§

impl Keypair

source

pub fn musig<'k, T>(&'k self, t: T) -> MuSig<T, CommitStage<&'k Keypair>>where T: SigningTranscript + Clone,

Initialize a multi-signature aka cosignature protocol run.

We borrow the keypair here to discurage keeping too many copies of the private key, but the MuSig::new method can create an owned version, or use Rc or Arc.

Trait Implementations§

source§

impl Clone for Keypair

source§

fn clone(&self) -> Keypair

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Keypair

source§

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

Formats the value using the given formatter. Read more
source§

impl Derivation for Keypair

source§

fn derived_key<T>(&self, t: T, cc: ChainCode) -> (Keypair, ChainCode)where T: SigningTranscript,

Derive key with subkey identified by a byte array presented via a SigningTranscript, and a chain code.
source§

fn derived_key_simple<B: AsRef<[u8]>>( &self, cc: ChainCode, i: B ) -> (Self, ChainCode)

Derive key with subkey identified by a byte array and a chain code. We do not include a context here becuase the chain code could serve this purpose.
source§

fn derived_key_simple_rng<B, R>( &self, cc: ChainCode, i: B, rng: R ) -> (Self, ChainCode)where B: AsRef<[u8]>, R: RngCore + CryptoRng,

Derive key with subkey identified by a byte array and a chain code, and with external ranodmnesses.
source§

impl Drop for Keypair

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl From<SecretKey> for Keypair

source§

fn from(secret: SecretKey) -> Keypair

Converts to this type from the input type.
source§

impl Zeroize for Keypair

source§

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

source§

fn vzip(self) -> V