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
impl Keypair
sourcepub fn to_bytes(&self) -> [u8; 96]
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()[..]);
sourcepub fn from_bytes(bytes: &[u8]) -> SignatureResult<Keypair>
pub fn from_bytes(bytes: &[u8]) -> SignatureResult<Keypair>
Deserialize a Keypair
from bytes.
Inputs
bytes
: an&[u8]
consisting of byte representations of first aSecretKey
and then the corresponding ristrettoPublicKey
.
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.
sourcepub fn to_half_ed25519_bytes(&self) -> [u8; 96]
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
sourcepub fn from_half_ed25519_bytes(bytes: &[u8]) -> SignatureResult<Keypair>
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.
sourcepub fn generate_with<R>(csprng: R) -> Keypairwhere
R: CryptoRng + RngCore,
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§impl Keypair
impl Keypair
sourcepub fn sign<T: SigningTranscript>(&self, t: T) -> Signature
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));
sourcepub fn sign_simple(&self, ctx: &[u8], msg: &[u8]) -> Signature
pub fn sign_simple(&self, ctx: &[u8], msg: &[u8]) -> Signature
Sign a message with this keypair’s secret key.
sourcepub fn verify<T: SigningTranscript>(
&self,
t: T,
signature: &Signature
) -> SignatureResult<()>
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() );
sourcepub fn verify_simple(
&self,
ctx: &[u8],
msg: &[u8],
signature: &Signature
) -> SignatureResult<()>
pub fn verify_simple( &self, ctx: &[u8], msg: &[u8], signature: &Signature ) -> SignatureResult<()>
Verify a signature by keypair’s public key on a message.
sourcepub fn sign_doublecheck<T>(&self, t: T) -> SignatureResult<Signature>where
T: SigningTranscript + Clone,
pub fn sign_doublecheck<T>(&self, t: T) -> SignatureResult<Signature>where T: SigningTranscript + Clone,
Sign a message with this SecretKey
, but doublecheck the result.
sourcepub fn sign_simple_doublecheck(
&self,
ctx: &[u8],
msg: &[u8]
) -> SignatureResult<Signature>
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
impl Keypair
sourcepub fn vrf_create_hash<T: VRFSigningTranscript>(&self, t: T) -> VRFInOut
pub fn vrf_create_hash<T: VRFSigningTranscript>(&self, t: T) -> VRFInOut
Evaluate the VRF on the given transcript.
source§impl Keypair
impl Keypair
sourcepub fn dleq_proove<T>(
&self,
t: T,
p: &VRFInOut,
kusama: bool
) -> (VRFProof, VRFProofBatchable)where
T: SigningTranscript,
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.
sourcepub fn vrf_sign<T>(&self, t: T) -> (VRFInOut, VRFProof, VRFProofBatchable)where
T: VRFSigningTranscript,
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.
sourcepub fn vrf_sign_extra<T, E>(
&self,
t: T,
extra: E
) -> (VRFInOut, VRFProof, VRFProofBatchable)where
T: VRFSigningTranscript,
E: SigningTranscript,
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.
sourcepub fn vrf_sign_after_check<T, F>(
&self,
t: T,
check: F
) -> Option<(VRFInOut, VRFProof, VRFProofBatchable)>where
T: VRFSigningTranscript,
F: FnMut(&VRFInOut) -> bool,
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.
sourcepub 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>,
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.
sourcepub fn vrfs_sign<T, I>(
&self,
ts: I
) -> (Box<[VRFInOut]>, VRFProof, VRFProofBatchable)where
T: VRFSigningTranscript,
I: IntoIterator<Item = T>,
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.
sourcepub 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>,
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
impl Keypair
sourcepub fn hard_derive_mini_secret_key<B: AsRef<[u8]>>(
&self,
cc: Option<ChainCode>,
i: B
) -> (MiniSecretKey, ChainCode)
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 ChainCode
s or ExtendedKey
s 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.
sourcepub fn derive_secret_key<T>(
&self,
t: T,
cc: ChainCode
) -> (SecretKey, ChainCode)where
T: SigningTranscript,
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
impl Keypair
sourcepub fn issue_ecqv_cert<T>(
&self,
t: T,
seed_public_key: &PublicKey
) -> ECQVCertSecretwhere
T: SigningTranscript,
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
impl Keypair
sourcepub fn issue_self_ecqv_cert<T>(&self, t: T) -> (ECQVCertPublic, SecretKey)where
T: SigningTranscript + Clone,
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
impl Keypair
sourcepub fn musig<'k, T>(&'k self, t: T) -> MuSig<T, CommitStage<&'k Keypair>>where
T: SigningTranscript + Clone,
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 Derivation for Keypair
impl Derivation for Keypair
source§fn derived_key<T>(&self, t: T, cc: ChainCode) -> (Keypair, ChainCode)where
T: SigningTranscript,
fn derived_key<T>(&self, t: T, cc: ChainCode) -> (Keypair, ChainCode)where T: SigningTranscript,
SigningTranscript
, and a chain code.