ciphersuite/
lib.rs

1#![cfg_attr(docsrs, feature(doc_auto_cfg))]
2#![doc = include_str!("lib.md")]
3#![cfg_attr(not(feature = "std"), no_std)]
4
5use core::fmt::Debug;
6#[cfg(any(feature = "alloc", feature = "std"))]
7#[allow(unused_imports)]
8use std_shims::prelude::*;
9#[cfg(any(feature = "alloc", feature = "std"))]
10use std_shims::io::{self, Read};
11
12use rand_core::{RngCore, CryptoRng};
13
14use zeroize::Zeroize;
15use subtle::ConstantTimeEq;
16
17use digest::{core_api::BlockSizeUser, Digest, HashMarker};
18use transcript::SecureDigest;
19
20pub use group;
21use group::{
22  ff::{Field, PrimeField, PrimeFieldBits},
23  Group, GroupOps,
24  prime::PrimeGroup,
25};
26#[cfg(any(feature = "alloc", feature = "std"))]
27use group::GroupEncoding;
28
29#[cfg(feature = "dalek")]
30mod dalek;
31#[cfg(feature = "ristretto")]
32pub use dalek::Ristretto;
33#[cfg(feature = "ed25519")]
34pub use dalek::Ed25519;
35
36#[cfg(feature = "kp256")]
37mod kp256;
38#[cfg(feature = "secp256k1")]
39pub use kp256::Secp256k1;
40#[cfg(feature = "p256")]
41pub use kp256::P256;
42
43#[cfg(feature = "ed448")]
44mod ed448;
45#[cfg(feature = "ed448")]
46pub use ed448::*;
47
48/// Unified trait defining a ciphersuite around an elliptic curve.
49pub trait Ciphersuite:
50  'static + Send + Sync + Clone + Copy + PartialEq + Eq + Debug + Zeroize
51{
52  /// Scalar field element type.
53  // This is available via G::Scalar yet `C::G::Scalar` is ambiguous, forcing horrific accesses
54  type F: PrimeField + PrimeFieldBits + Zeroize;
55  /// Group element type.
56  type G: Group<Scalar = Self::F> + GroupOps + PrimeGroup + Zeroize + ConstantTimeEq;
57  /// Hash algorithm used with this curve.
58  // Requires BlockSizeUser so it can be used within Hkdf which requires that.
59  type H: Send + Clone + BlockSizeUser + Digest + HashMarker + SecureDigest;
60
61  /// ID for this curve.
62  const ID: &'static [u8];
63
64  /// Generator for the group.
65  // While group does provide this in its API, privacy coins may want to use a custom basepoint
66  fn generator() -> Self::G;
67
68  /// Hash the provided domain-separation tag and message to a scalar. Ciphersuites MAY naively
69  /// prefix the tag to the message, enabling transpotion between the two. Accordingly, this
70  /// function should NOT be used in any scheme where one tag is a valid substring of another
71  /// UNLESS the specific Ciphersuite is verified to handle the DST securely.
72  ///
73  /// Verifying specific ciphersuites have secure tag handling is not recommended, due to it
74  /// breaking the intended modularity of ciphersuites. Instead, component-specific tags with
75  /// further purpose tags are recommended ("Schnorr-nonce", "Schnorr-chal").
76  #[allow(non_snake_case)]
77  fn hash_to_F(dst: &[u8], msg: &[u8]) -> Self::F;
78
79  /// Generate a random non-zero scalar.
80  #[allow(non_snake_case)]
81  fn random_nonzero_F<R: RngCore + CryptoRng>(rng: &mut R) -> Self::F {
82    let mut res;
83    while {
84      res = Self::F::random(&mut *rng);
85      res.ct_eq(&Self::F::ZERO).into()
86    } {}
87    res
88  }
89
90  /// Read a canonical scalar from something implementing std::io::Read.
91  #[cfg(any(feature = "alloc", feature = "std"))]
92  #[allow(non_snake_case)]
93  fn read_F<R: Read>(reader: &mut R) -> io::Result<Self::F> {
94    let mut encoding = <Self::F as PrimeField>::Repr::default();
95    reader.read_exact(encoding.as_mut())?;
96
97    // ff mandates this is canonical
98    let res = Option::<Self::F>::from(Self::F::from_repr(encoding))
99      .ok_or_else(|| io::Error::other("non-canonical scalar"));
100    encoding.as_mut().zeroize();
101    res
102  }
103
104  /// Read a canonical point from something implementing std::io::Read.
105  ///
106  /// The provided implementation is safe so long as `GroupEncoding::to_bytes` always returns a
107  /// canonical serialization.
108  #[cfg(any(feature = "alloc", feature = "std"))]
109  #[allow(non_snake_case)]
110  fn read_G<R: Read>(reader: &mut R) -> io::Result<Self::G> {
111    let mut encoding = <Self::G as GroupEncoding>::Repr::default();
112    reader.read_exact(encoding.as_mut())?;
113
114    let point = Option::<Self::G>::from(Self::G::from_bytes(&encoding))
115      .ok_or_else(|| io::Error::other("invalid point"))?;
116    if point.to_bytes().as_ref() != encoding.as_ref() {
117      Err(io::Error::other("non-canonical point"))?;
118    }
119    Ok(point)
120  }
121}
ciphersuite/lib.rs

ciphersuite/
lib.rs
