diff --git a/Cargo.toml b/Cargo.toml index 4e7a3c1..2733c45 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "curve25519-dalek" -version = "0.3.0" +version = "0.4.0" authors = ["Isis Lovecruft ", "Henry de Valence "] readme = "README.md" @@ -8,6 +8,7 @@ license = "CC0-1.0" repository = "https://code.ciph.re/isis/curve25519-dalek" homepage = "https://code.ciph.re/isis/curve25519-dalek" documentation = "https://docs.rs/curve25519-dalek" +categories = ["cryptography", "no-std"] keywords = ["cryptography", "curve25519", "elliptic", "curve", "ECC"] description = "A low-level cryptographic library for point, group, field, and scalar operations on a curve isomorphic to the twisted Edwards curve defined by -x²+y² = 1 - 121665/121666 x²y² over GF(2²⁵⁵ - 19)." exclude = [ @@ -34,7 +35,7 @@ lto = false # controls `-C lto` for binaries and staticlibs debug-assertions = true # controls whether debug assertions are enabled codegen-units = 1 # controls whether the compiler passes `-C codegen-units` # `codegen-units` is ignored when `lto = true` - panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort' +panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort' # The release profile, used for `cargo build --release`. [profile.release] diff --git a/README.md b/README.md index 2c0b3ef..d6dd6e2 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Extensive documentation is available [here](https://docs.rs/curve25519-dalek). To install, add the following to the dependencies section of your project's `Cargo.toml`: - curve25519-dalek = "^0.2" + curve25519-dalek = "^0.4" Then, in your library or executable source, add: diff --git a/src/constants.rs b/src/constants.rs index 0b927d3..71417d8 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -21,6 +21,7 @@ use field::FieldElement; use curve::PreComputedPoint; use curve::CompressedEdwardsY; +use scalar::Scalar; pub const d: FieldElement = FieldElement([ -10913610, 13857413, -15372611, 6949391, 114729, @@ -66,6 +67,20 @@ pub const BASE_CMPRSSD: CompressedEdwardsY = 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66]); +/// `l` is the order of base point, i.e. 2^252 + +/// 27742317777372353535851937790883648493, in little-endian form +pub const l: Scalar = Scalar([ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, + 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10 ]); + +/// `lminus1` is the order of base point minus one, i.e. 2^252 + +/// 27742317777372353535851937790883648493 - 1, in little-endian form +pub const lminus1: Scalar = Scalar([ 0xec, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, + 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10 ]); + pub const bi: [PreComputedPoint; 8] = [ PreComputedPoint{ y_plus_x: FieldElement([25967493, -14356035, 29566456, 3660896, -12694345, 4014787, 27544626, -11754271, -6079156, 2047605]), diff --git a/src/curve.rs b/src/curve.rs index b0732ae..9dc6f22 100644 --- a/src/curve.rs +++ b/src/curve.rs @@ -80,13 +80,15 @@ use core::fmt::Debug; use core::iter::Iterator; use core::ops::{Add, Sub, Neg, Index}; -use core::cmp::{PartialEq, Eq}; use constants; use field::FieldElement; use scalar::Scalar; -use util::bytes_equal_ct; -use util::CTAssignable; +use subtle::arrays_equal_ct; +use subtle::bytes_equal_ct; +use subtle::CTAssignable; +use subtle::CTEq; +use subtle::CTNegatable; // ------------------------------------------------------------------------ // Compressed points @@ -98,7 +100,7 @@ use util::CTAssignable; /// /// The first 255 bits of a CompressedEdwardsY represent the /// y-coordinate. The high bit of the 32nd byte gives the sign of `x`. -#[derive(Copy, Clone)] +#[derive(Copy, Clone, Eq, PartialEq)] pub struct CompressedEdwardsY(pub [u8; 32]); impl Debug for CompressedEdwardsY { @@ -107,18 +109,6 @@ impl Debug for CompressedEdwardsY { } } -impl Eq for CompressedEdwardsY {} -impl PartialEq for CompressedEdwardsY { - /// Determine if this `CompressedEdwardsY` is equal to another. - /// - /// # Warning - /// - /// This function is NOT constant time. - fn eq(&self, other: &CompressedEdwardsY) -> bool { - return self.0 == other.0; - } -} - impl Index for CompressedEdwardsY { type Output = u8; @@ -238,7 +228,7 @@ pub struct CachedPoint { // Constructors // ------------------------------------------------------------------------ -/// Trait for curve point types that have an identity constructor. +/// Trait for curve point types which have an identity constructor. pub trait Identity { /// Returns the identity element of the curve. /// Can be used as a constructor. @@ -303,6 +293,37 @@ impl CTAssignable for PreComputedPoint { } } +// ------------------------------------------------------------------------ +// Constant-time Equality +// ------------------------------------------------------------------------ + +impl CTEq for ExtendedPoint { + fn ct_eq(&self, other: &ExtendedPoint) -> u8 { + arrays_equal_ct(&self.compress().0, &other.compress().0) + } +} + +/// Trait for testing if a curve point is equivalent to the identity point. +pub trait IsIdentity { + /// Return true if this element is the identity element of the curve. + fn is_identity(&self) -> bool; +} + +/// Implement generic identity equality testing for a point representations +/// which have constant-time equality testing and a defined identity +/// constructor. +impl IsIdentity for T where T: CTEq + Identity { + fn is_identity(&self) -> bool { + let identity: T = T::identity(); + + if self.ct_eq(&identity) == 1u8 { + return true; + } else { + return false; + } + } +} + // ------------------------------------------------------------------------ // Point conversions // ------------------------------------------------------------------------ @@ -666,6 +687,25 @@ impl ExtendedPoint { r = s.double(); return r.to_extended(); } + + /// Determine if this point is of small order. + /// + /// The order of the group of points on the curve Ɛ is |Ɛ| = 8q. Thus, to + /// check if a point P is of small order, we multiply by 8 and then test + /// if the result is equal to the identity. + /// + /// # Return + /// + /// True if it is of small order; false otherwise. + pub fn is_small_order(&self) -> bool { + let p8: ExtendedPoint = self.mult_by_pow_2(3); + + if p8.is_identity() { + return true; + } else { + return false; + } + } } /// Given a point `A` and scalars `a` and `b`, compute the point @@ -746,9 +786,8 @@ fn select_precomputed_point(x: i8, points: &[T; 8]) -> T } // Now t == |x| * P. - let minus_t = -(&t); let neg_mask = (xmask & 1) as u8; - t.conditional_assign(&minus_t, neg_mask); + t.conditional_negate(neg_mask); // Now t == x * P. t @@ -825,7 +864,7 @@ mod test { use test::Bencher; use field::FieldElement; use scalar::Scalar; - use util::CTAssignable; + use subtle::CTAssignable; use constants; use constants::BASE_CMPRSSD; use super::*; @@ -946,6 +985,20 @@ mod test { assert_eq!( bp_added.compress(), BASE2_CMPRSSD); } + #[test] + fn test_extended_point_equality() { + let two = [2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]; + let id1 = ExtendedPoint::identity(); + let id2 = ExtendedPoint{ + X: FieldElement::zero(), + Y: FieldElement::from_bytes(&two), + Z: FieldElement::from_bytes(&two), + T: FieldElement::zero()}; + + assert!(id1.ct_eq(&id2) == 1u8); + } + /// Sanity check for conversion to precomputed points #[test] fn test_convert_to_precomputed() { @@ -1057,6 +1110,20 @@ mod test { assert_eq!(p1.xy2d, p2.xy2d); } + #[test] + fn test_is_small_order() { + let p1: ExtendedPoint = ExtendedPoint::identity(); + let p2: ExtendedPoint = BASE_CMPRSSD.decompress().unwrap(); + + assert!(p1.is_small_order() == true); + assert!(p2.is_small_order() == false); + } + + #[test] + fn test_is_identity() { + assert!(ExtendedPoint::identity().is_identity()); + } + #[bench] fn bench_basepoint_mult(b: &mut Bencher) { b.iter(|| ExtendedPoint::basepoint_mult(&A_SCALAR)); diff --git a/src/field.rs b/src/field.rs index 0ef58c2..7d5bc44 100644 --- a/src/field.rs +++ b/src/field.rs @@ -24,8 +24,12 @@ use core::ops::{Index, IndexMut}; use core::cmp::{Eq, PartialEq}; use core::ops::Neg; -use util::byte_is_nonzero; -use util::CTAssignable; +use subtle::arrays_equal_ct; +use subtle::byte_is_nonzero; +use subtle::CTAssignable; +use subtle::CTEq; + +use utils::{load3, load4}; /// FieldElements are represented as an array of ten "Limbs", which are radix /// 25.5, that is, each Limb of a FieldElement alternates between being @@ -40,6 +44,7 @@ pub type Limb = i32; #[derive(Copy, Clone)] pub struct FieldElement(pub [Limb; 10]); +impl Eq for FieldElement {} impl PartialEq for FieldElement { /// Test equality between two FieldElements by converting them to bytes. /// @@ -48,10 +53,10 @@ impl PartialEq for FieldElement { /// This comparison is *not* constant time. It could easily be /// made to be, but the main use of an `Eq` implementation is for /// branching, so it seems pointless. - /// - /// XXX it would be good to encode constant-time considerations - /// (no data flow from secret information) into Rust's type - /// system. + // + // XXX it would be good to encode constant-time considerations + // (no data flow from secret information) into Rust's type + // system. fn eq(&self, other: &FieldElement) -> bool { let self_bytes = self.to_bytes(); let other_bytes = other.to_bytes(); @@ -63,7 +68,16 @@ impl PartialEq for FieldElement { } } -impl Eq for FieldElement {} +impl CTEq for FieldElement { + /// Test equality between two `FieldElement`s by converting them to bytes. + /// + /// # Returns + /// + /// `1u8` if the two `FieldElement`s are equal, and `0u8` otherwise. + fn ct_eq(&self, other: &FieldElement) -> u8 { + arrays_equal_ct(&self.to_bytes(), &other.to_bytes()) + } +} impl Debug for FieldElement { fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result { @@ -150,7 +164,7 @@ impl CTAssignable for FieldElement { /// /// ``` /// # use curve25519_dalek::field::FieldElement; - /// # use curve25519_dalek::util::CTAssignable; + /// # use curve25519_dalek::subtle::CTAssignable; /// let f = FieldElement([1,1,1,1,1,1,1,1,1,1]); /// let g = FieldElement([2,2,2,2,2,2,2,2,2,2]); /// let mut h = FieldElement([1,1,1,1,1,1,1,1,1,1]); @@ -162,7 +176,7 @@ impl CTAssignable for FieldElement { /// /// ``` /// # use curve25519_dalek::field::FieldElement; - /// # use curve25519_dalek::util::CTAssignable; + /// # use curve25519_dalek::subtle::CTAssignable; /// # let f = FieldElement([1,1,1,1,1,1,1,1,1,1]); /// # let g = FieldElement([2,2,2,2,2,2,2,2,2,2]); /// # let mut h = FieldElement([1,1,1,1,1,1,1,1,1,1]); @@ -181,25 +195,6 @@ impl CTAssignable for FieldElement { } } -/// Convert an array of (at least) three bytes into an i64. -#[inline] -#[allow(dead_code)] -pub fn load3(input: &[u8]) -> i64 { - (input[0] as i64) - | ((input[1] as i64) << 8) - | ((input[2] as i64) << 16) -} - -/// Convert an array of (at least) four bytes into an i64. -#[inline] -#[allow(dead_code)] -pub fn load4(input: &[u8]) -> i64 { - (input[0] as i64) - | ((input[1] as i64) << 8) - | ((input[2] as i64) << 16) - | ((input[3] as i64) << 24) -} - impl FieldElement { /// Invert the sign of this field element pub fn negate(&mut self) { @@ -711,7 +706,7 @@ impl FieldElement { /// XXX This returns an extra intermediate to save computation in /// finding inverses, at the cost of an extra copy when it's not /// used (e.g., when raising to (p-1)/2 or (p-5)/8). Good idea? - fn pow22501(&self) -> (FieldElement,FieldElement) { + fn pow22501(&self) -> (FieldElement, FieldElement) { // Instead of managing which temporary variables are used // for what, we define as many as we need and trust the // compiler to reuse stack space as appropriate. @@ -803,6 +798,7 @@ impl FieldElement { mod test { use field::*; use test::Bencher; + use subtle::CTNegatable; #[bench] fn bench_fieldelement_a_mul_a(b: &mut Bencher) { @@ -932,4 +928,17 @@ mod test { // high bit is set to zero in to_bytes assert!(test_bytes[31] == (B_BYTES[31] & 127u8)); } + + #[test] + fn test_conditional_negate() { + let one = FieldElement([ 1,0,0,0,0,0,0,0,0,0]); + let minus_one = FieldElement([-1,0,0,0,0,0,0,0,0,0]); + let mut x = one; + x.conditional_negate(1u8); + assert_eq!(x, minus_one); + x.conditional_negate(0u8); + assert_eq!(x, minus_one); + x.conditional_negate(1u8); + assert_eq!(x, one); + } } diff --git a/src/lib.rs b/src/lib.rs index 36e3a05..7855923 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -47,9 +47,10 @@ pub mod field; pub mod curve; pub mod scalar; -// Utilities module. +// Constant-time functions and other miscelaneous utilities. -pub mod util; +pub mod subtle; +pub mod utils; // Low-level curve and point constants, as well as pre-computed curve group elements. diff --git a/src/scalar.rs b/src/scalar.rs index f98881b..85c77be 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -29,23 +29,61 @@ //! between two scalars, the `UnpackedScalar` struct is stored as //! limbs. +use core::cmp::{Eq, PartialEq}; use core::ops::{Index, IndexMut}; +use core::ops::{Neg}; #[cfg(feature = "std")] use rand::Rng; -// XXX should these be in a utility module ? -use field::{load3, load4}; -use util::CTAssignable; +use constants; +use utils::{load3, load4}; +use subtle::CTAssignable; +use subtle::CTEq; +use subtle::arrays_equal_ct; /// The `Scalar` struct represents an element in ℤ/lℤ, where /// /// l = 2^252 + 27742317777372353535851937790883648493 /// /// is the order of the basepoint. The `Scalar` is stored as bytes. -#[derive(Copy,Clone)] +#[derive(Copy, Clone)] pub struct Scalar(pub [u8; 32]); +impl Eq for Scalar{} +impl PartialEq for Scalar { + /// Test equality between two `Scalar`s. + /// + /// # Warning + /// + /// This function is *not* guaranteed to be constant time and should only be + /// used for debugging purposes. + /// + /// # Returns + /// + /// True if they are equal, and false otherwise. + fn eq(&self, other: &Self) -> bool { + let equal: u8 = arrays_equal_ct(&self.0, &other.0); + + if equal == 1u8 { + return true; + } else { + return false; + } + } +} + +impl CTEq for Scalar { + /// Test equality between two `Scalar`s in constant time. + /// + /// # Returns + /// + /// `1u8` if they are equal, and `0u8` otherwise. + fn ct_eq(&self, other: &Self) -> u8 { + arrays_equal_ct(&self.0, &other.0) + } +} + impl Index for Scalar { type Output = u8; @@ -62,12 +100,21 @@ impl IndexMut for Scalar { } } +impl Neg for Scalar { + type Output = Scalar; + + /// Negate this scalar by computing (l - 1) * self - 0 (mod l). + fn neg(self) -> Scalar { + Scalar::multiply_add(&constants::lminus1, &self, &Scalar::zero()) + } +} + impl CTAssignable for Scalar { /// Conditionally assign another Scalar to this one. /// /// ``` /// # use curve25519_dalek::scalar::Scalar; - /// # use curve25519_dalek::util::CTAssignable; + /// # use curve25519_dalek::subtle::CTAssignable; /// let a = Scalar([0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, /// 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]); /// let b = Scalar([1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, @@ -627,4 +674,13 @@ mod test { assert!(test_red[i] == reduced[i]); } } + + // Negating a scalar twice should result in the original scalar. + #[test] + fn test_scalar_neg() { + let negative_x: Scalar = -X; + let orig: Scalar = -negative_x; + + assert!(orig == X); + } } diff --git a/src/util.rs b/src/subtle.rs similarity index 60% rename from src/util.rs rename to src/subtle.rs index 1391ef8..098733f 100644 --- a/src/util.rs +++ b/src/subtle.rs @@ -9,7 +9,9 @@ // - Isis Agora Lovecruft // - Henry de Valence -//! Utility functions and tools for constant-time comparisons. +//! Constant-time traits and utility functions. + +use core::ops::Neg; /// Trait for items which can be conditionally assigned in constant time. pub trait CTAssignable { @@ -19,11 +21,41 @@ pub trait CTAssignable { fn conditional_assign(&mut self, other: &Self, choice: u8); } +/// Trait for items whose equality to another item may be tested in constant time. +pub trait CTEq { + /// Determine if two items are equal in constant time. + /// + /// # Returns + /// + /// `1u8` if the two items are equal, and `0u8` otherwise. + fn ct_eq(&self, other: &Self) -> u8; +} + +/// Trait for items which can be conditionally negated in constant time. +/// +/// Note: it is not necessary to implement this trait, as a generic +/// implementation is provided. +pub trait CTNegatable +{ + /// Conditionally negate an element if `choice == 1u8`. + fn conditional_negate(&mut self, choice: u8); +} + +impl CTNegatable for T + where T: CTAssignable, for<'a> &'a T: Neg +{ + fn conditional_negate(&mut self, choice: u8) { + // Need to cast to eliminate mutability + let self_neg: T = -(self as &T); + self.conditional_assign(&self_neg, choice); + } +} + /// Check equality of two bytes in constant time. /// /// # Return /// -/// Returns 1 if `a == b` and 0 otherwise. +/// Returns `1u8` if `a == b` and `0u8` otherwise. #[inline(always)] pub fn bytes_equal_ct(a: u8, b: u8) -> u8 { let mut x: u8; @@ -62,10 +94,8 @@ pub fn byte_is_nonzero(b: u8) -> u8 { /// /// # Return /// -/// Returns 1 if `a == b` and 0 otherwise. +/// Returns `1u8` if `a == b` and `0u8` otherwise. #[inline(always)] -// We don't use this in curve25519-dalek, but it's useful for e.g. an ed25519 implementation. -#[allow(dead_code)] pub fn arrays_equal_ct(a: &[u8; 32], b: &[u8; 32]) -> u8 { let mut x: u8 = 0; diff --git a/src/utils.rs b/src/utils.rs new file mode 100644 index 0000000..ad53166 --- /dev/null +++ b/src/utils.rs @@ -0,0 +1,31 @@ +// -*- mode: rust; -*- +// +// To the extent possible under law, the authors have waived all copyright and +// related or neighboring rights to curve25519-dalek, using the Creative +// Commons "CC0" public domain dedication. See +// for full details. +// +// Authors: +// - Isis Agora Lovecruft +// - Henry de Valence + +//! Miscellaneous common utility function. + +/// Convert an array of (at least) three bytes into an i64. +#[inline] +//#[allow(dead_code)] +pub fn load3(input: &[u8]) -> i64 { + (input[0] as i64) + | ((input[1] as i64) << 8) + | ((input[2] as i64) << 16) +} + +/// Convert an array of (at least) four bytes into an i64. +#[inline] +//#[allow(dead_code)] +pub fn load4(input: &[u8]) -> i64 { + (input[0] as i64) + | ((input[1] as i64) << 8) + | ((input[2] as i64) << 16) + | ((input[3] as i64) << 24) +}