saymrwulf/curve25519-dalek-source
1
0
Fork 0
mirror of https://github.com/saymrwulf/curve25519-dalek-source.git synced 2026-09-04 20:24:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

UPPERCASE_GLOBALS and add documentation

Browse source
This commit is contained in:
Henry de Valence 2017-10-30 17:13:25 -07:00
parent 089efbbbbe
commit a7835a1246
7 changed files with 91 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
src/constants.rs
View file

@ -11,11 +11,22 @@
//! This module contains various constants (such as curve parameters
//! and useful field elements like `sqrt(-1)`), as well as
//! lookup tables of pre-computed points.
//!
//! Most of the constants are given with
//! `LONG_DESCRIPTIVE_UPPER_CASE_NAMES`, but they can be brought into
//! scope using a `let` binding:
//!
//! ```
//! use curve25519_dalek::constants;
//! use curve25519_dalek::edwards::IsIdentity;
//!
//! let B = &constants::RISTRETTO_BASEPOINT_TABLE;
//! let l = &constants::BASEPOINT_ORDER;
//!
//! let A = l * B;
//! assert!(A.is_identity());
//! ```
#![allow(dead_code)]
#![allow(non_snake_case)]
#![allow(non_upper_case_globals)]
#![allow(missing_docs)]
#![allow(non_snake_case)]
use edwards::CompressedEdwardsY;
@ -50,26 +61,30 @@ pub const BASE_COMPRESSED_MONTGOMERY: CompressedMontgomeryU =
/// `_TABLE`, which provides fast scalar multiplication.
pub const RISTRETTO_BASEPOINT_POINT: RistrettoPoint = RistrettoPoint(ED25519_BASEPOINT_POINT);
/// `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 ]);
/// `BASEPOINT_ORDER` is the order of base point, i.e. `l = 2^252 +
/// 27742317777372353535851937790883648493`, in little-endian bytes.
pub const BASEPOINT_ORDER: 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,
]);
/// `l_minus_1` is the order of base point minus one, i.e. 2^252 +
/// 27742317777372353535851937790883648493 - 1, in little-endian form
pub const l_minus_1: 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 ]);
/// `BASEPOINT_ORDER_MINUS_1` is the order of base point minus one, i.e. `l-1`, in little-endian bytes.
pub const BASEPOINT_ORDER_MINUS_1: 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,
]);
/// `lminus1` is the order of base point minus two, i.e. 2^252 +
/// 27742317777372353535851937790883648493 - 2, in little-endian form
pub const l_minus_2: Scalar = Scalar([ 0xeb, 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 ]);
/// `BASEPOINT_ORDER_MINUS_2` is the order of base point minus two, i.e. `l-2`, in little-endian bytes.
pub const BASEPOINT_ORDER_MINUS_2: Scalar = Scalar([
0xeb, 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,
]);
/// The Ed25519 basepoint, as a RistrettoPoint
pub const RISTRETTO_BASEPOINT_TABLE: RistrettoBasepointTable
@ -166,8 +181,8 @@ mod test {
let b = FieldElement32([ 121666,0,0,0,0,0,0,0,0,0]);
let d = &a * &b.invert();
let d2 = &d + &d;
assert_eq!(d, constants::d);
assert_eq!(d2, constants::d2);
assert_eq!(d, constants::EDWARDS_D);
assert_eq!(d2, constants::EDWARDS_D2);
}
/// Test that d = -121665/121666
@ -179,15 +194,15 @@ mod test {
let b = FieldElement64([121666,0,0,0,0]);
let d = &a * &b.invert();
let d2 = &d + &d;
assert_eq!(d, constants::d);
assert_eq!(d2, constants::d2);
assert_eq!(d, constants::EDWARDS_D);
assert_eq!(d2, constants::EDWARDS_D2);
}
#[test]
fn test_sqrt_ad_minus_one() {
let a = FieldElement::minus_one();
let ad_minus_one = &(&a * &constants::d) + &a;
let should_be_ad_minus_one = constants::sqrt_ad_minus_one.square();
let ad_minus_one = &(&a * &constants::EDWARDS_D) + &a;
let should_be_ad_minus_one = constants::SQRT_AD_MINUS_ONE.square();
assert_eq!(should_be_ad_minus_one, ad_minus_one);
}

26
src/constants_32bit.rs
View file

@ -12,10 +12,6 @@
//! and useful field elements like `sqrt(-1)`), as well as
//! lookup tables of pre-computed points.
#![allow(dead_code)]
#![allow(non_snake_case)]
#![allow(non_upper_case_globals)]
#![allow(missing_docs)]
#![allow(non_snake_case)]
use field_32bit::FieldElement32;
@ -23,19 +19,23 @@ use edwards::ExtendedPoint;
use edwards::AffineNielsPoint;
use edwards::EdwardsBasepointTable;
pub const d: FieldElement32 = FieldElement32([
/// Edwards `d` value, equal to `-121665/121666 mod p`.
pub const EDWARDS_D: FieldElement32 = FieldElement32([
-10913610, 13857413, -15372611, 6949391, 114729,
-8787816, -6275908, -3247719, -18696448, -12055116, ]);
pub const d2: FieldElement32 = FieldElement32([
/// Edwards `2*d` value, equal to `2*(-121665/121666) mod p`.
pub const EDWARDS_D2: FieldElement32 = FieldElement32([
-21827239, -5839606, -30745221, 13898782, 229458,
15978800, -12551817, -6495438, 29715968, 9444199, ]);
pub const sqrt_ad_minus_one: FieldElement32 = FieldElement32([
/// `= sqrt(a*d - 1)`, where `a = -1 (mod p)`, `d` are the Edwards curve parameters.
pub const SQRT_AD_MINUS_ONE: FieldElement32 = FieldElement32([
24849947, -153582, -23613485, 6347715, -21072328, -667138, -25271143, -15367704, -870347, 14525639
]);
pub const invsqrt_a_minus_d: FieldElement32 = FieldElement32([
/// `= 1/sqrt(a-d)`, where `a = -1 (mod p)`, `d` are the Edwards curve parameters.
pub const INVSQRT_A_MINUS_D: FieldElement32 = FieldElement32([
6111485, 4156064, -27798727, 12243468, -25904040,
120897, 20826367, -7060776, 6093568, -1986012
]);
@ -52,7 +52,7 @@ pub const MSQRT_M1: FieldElement32 = FieldElement32([
272473, 25146209, 2005654, -326686, -11406482, ]);
/// In Montgomery form y² = x³+Ax²+x, Curve25519 has A=486662.
pub const A: FieldElement32 = FieldElement32([
pub const MONTGOMERY_A: FieldElement32 = FieldElement32([
486662, 0, 0, 0, 0, 0, 0, 0, 0, 0, ]);
/// `APLUS2_OVER_FOUR` is (A+2)/4. (This is used internally within the Montgomery ladder.)
@ -63,8 +63,9 @@ pub const SQRT_MINUS_APLUS2: FieldElement32 = FieldElement32([
-12222970, -8312128, -11511410, 9067497, -15300785,
-241793, 25456130, 14121551, -12187136, 3972024]);
/// Basepoint has y = 4/5. This is called `_POINT` to distinguish it from `_TABLE`, which should
/// be used for scalar multiplication (it's much faster).
/// The Ed25519 basepoint has y = 4/5. This is called `_POINT` to
/// distinguish it from `_TABLE`, which should be used for scalar
/// multiplication (it's much faster).
pub const ED25519_BASEPOINT_POINT: ExtendedPoint = ExtendedPoint{
X: FieldElement32([-14297830, -7645148, 16144683, -16471763, 27570974, -2696100, -26142465, 8378389, 20764389, 8758491]),
Y: FieldElement32([-26843541, -6710886, 13421773, -13421773, 26843546, 6710886, -13421773, 13421773, -26843546, -6710886]),
@ -130,7 +131,8 @@ pub const EIGHT_TORSION: [ExtendedPoint; 8] = [
},
];
pub const bi: [AffineNielsPoint; 8] = [
/// Odd multiples of the basepoint `[B, 3B, 5B, 7B, 9B, 11B, 13B, 15B]`.
pub const AFFINE_ODD_MULTIPLES_OF_BASEPOINT: [AffineNielsPoint; 8] = [
AffineNielsPoint{
y_plus_x: FieldElement32([25967493, -14356035, 29566456, 3660896, -12694345, 4014787, 27544626, -11754271, -6079156, 2047605]),
y_minus_x: FieldElement32([-12545711, 934262, -2722910, 3049990, -727428, 9406986, 12720692, 5043384, 19500929, -15469378]),

26
src/constants_64bit.rs
View file

@ -12,10 +12,6 @@
//! and useful field elements like `sqrt(-1)`), as well as
//! lookup tables of pre-computed points.
#![allow(dead_code)]
#![allow(non_snake_case)]
#![allow(non_upper_case_globals)]
#![allow(missing_docs)]
#![allow(non_snake_case)]
use field_64bit::FieldElement64;
@ -23,15 +19,19 @@ use edwards::ExtendedPoint;
use edwards::AffineNielsPoint;
use edwards::EdwardsBasepointTable;
pub const d: FieldElement64 = FieldElement64([929955233495203, 466365720129213, 1662059464998953, 2033849074728123, 1442794654840575]);
/// Edwards `d` value, equal to `-121665/121666 mod p`.
pub const EDWARDS_D: FieldElement64 = FieldElement64([929955233495203, 466365720129213, 1662059464998953, 2033849074728123, 1442794654840575]);
pub const d2: FieldElement64 = FieldElement64([1859910466990425, 932731440258426, 1072319116312658, 1815898335770999, 633789495995903]);
/// Edwards `2*d` value, equal to `2*(-121665/121666) mod p`.
pub const EDWARDS_D2: FieldElement64 = FieldElement64([1859910466990425, 932731440258426, 1072319116312658, 1815898335770999, 633789495995903]);
pub const sqrt_ad_minus_one: FieldElement64 = FieldElement64([
/// `= sqrt(a*d - 1)`, where `a = -1 (mod p)`, `d` are the Edwards curve parameters.
pub const SQRT_AD_MINUS_ONE: FieldElement64 = FieldElement64([
2241493124984347, 425987919032274, 2207028919301688, 1220490630685848, 974799131293748
]);
pub const invsqrt_a_minus_d: FieldElement64 = FieldElement64([
/// `= 1/sqrt(a-d)`, where `a = -1 (mod p)`, `d` are the Edwards curve parameters.
pub const INVSQRT_A_MINUS_D: FieldElement64 = FieldElement64([
278908739862762, 821645201101625, 8113234426968, 1777959178193151, 2118520810568447
]);
@ -43,7 +43,7 @@ pub const SQRT_M1: FieldElement64 = FieldElement64([1718705420411056, 2349088835
pub const MSQRT_M1: FieldElement64 = FieldElement64([533094393274173, 2016890930128738, 18285341111199, 134597186663265, 1486323764102114]);
/// In Montgomery form y² = x³+Ax²+x, Curve25519 has A=486662.
pub const A: FieldElement64 = FieldElement64([486662, 0, 0, 0, 0]);
pub const MONTGOMERY_A: FieldElement64 = FieldElement64([486662, 0, 0, 0, 0]);
/// `APLUS2_OVER_FOUR` is (A+2)/4. (This is used internally within the Montgomery ladder.)
pub const APLUS2_OVER_FOUR: FieldElement64 = FieldElement64([121666, 0, 0, 0, 0]);
@ -51,8 +51,9 @@ pub const APLUS2_OVER_FOUR: FieldElement64 = FieldElement64([121666, 0, 0, 0, 0]
/// `SQRT_MINUS_APLUS2` is sqrt(-486664)
pub const SQRT_MINUS_APLUS2: FieldElement64 = FieldElement64([1693982333959686, 608509411481997, 2235573344831311, 947681270984193, 266558006233600]);
/// Basepoint has y = 4/5. This is called `_POINT` to distinguish it from `_TABLE`, which should
/// be used for scalar multiplication (it's much faster).
/// The Ed25519 basepoint has y = 4/5. This is called `_POINT` to
/// distinguish it from `_TABLE`, which should be used for scalar
/// multiplication (it's much faster).
pub const ED25519_BASEPOINT_POINT: ExtendedPoint = ExtendedPoint{
X: FieldElement64([1738742601995546, 1146398526822698, 2070867633025821, 562264141797630, 587772402128613]),
Y: FieldElement64([1801439850948184, 1351079888211148, 450359962737049, 900719925474099, 1801439850948198]),
@ -125,7 +126,8 @@ pub const EIGHT_TORSION: [ExtendedPoint; 8] = [
}
];
pub const bi: [AffineNielsPoint; 8] = [
/// Odd multiples of the basepoint `[B, 3B, 5B, 7B, 9B, 11B, 13B, 15B]`.
pub const AFFINE_ODD_MULTIPLES_OF_BASEPOINT: [AffineNielsPoint; 8] = [
AffineNielsPoint {
y_plus_x: FieldElement64([1288382639258501, 245678601348599, 269427782077623, 1462984067271730, 137412439391563]),
y_minus_x: FieldElement64([62697248952638, 204681361388450, 631292143396476, 338455783676468, 1213667448819585]),

17
src/edwards.rs
View file

@ -135,8 +135,8 @@ impl CompressedEdwardsY {
let Y = FieldElement::from_bytes(self.as_bytes());
let Z = FieldElement::one();
let YY = Y.square();
let u = &YY - &Z; // u = y²-1
let v = &(&YY * &constants::d) + &Z; // v = dy²+1
let u = &YY - &Z; // u = y²-1
let v = &(&YY * &constants::EDWARDS_D) + &Z; // v = dy²+1
let (is_nonzero_square, mut X) = FieldElement::sqrt_ratio(&u, &v);
if is_nonzero_square != 1u8 { return None; }
@ -342,7 +342,7 @@ impl ValidityCheck for ProjectivePoint {
let ZZ = self.Z.square();
let ZZZZ = ZZ.square();
let lhs = &(&YY - &XX) * &ZZ;
let rhs = &ZZZZ + &(&constants::d * &(&XX * &YY));
let rhs = &ZZZZ + &(&constants::EDWARDS_D * &(&XX * &YY));
lhs == rhs
}
@ -518,7 +518,7 @@ impl ExtendedPoint {
Y_plus_X: &self.Y + &self.X,
Y_minus_X: &self.Y - &self.X,
Z: self.Z,
T2d: &self.T * &constants::d2,
T2d: &self.T * &constants::EDWARDS_D2,
}
}
@ -541,7 +541,7 @@ impl ExtendedPoint {
let recip = self.Z.invert();
let x = &self.X * &recip;
let y = &self.Y * &recip;
let xy2d = &(&x * &y) * &constants::d2;
let xy2d = &(&x * &y) * &constants::EDWARDS_D2;
AffineNielsPoint{
y_plus_x: &y + &x,
y_minus_x: &y - &x,
@ -1233,6 +1233,7 @@ pub mod vartime {
}
let odd_multiples_of_A = OddMultiples::create(A);
let odd_multiples_of_B = &constants::AFFINE_ODD_MULTIPLES_OF_BASEPOINT;
let mut r = ProjectivePoint::identity();
loop {
@ -1245,9 +1246,9 @@ pub mod vartime {
}
if b_naf[i] > 0 {
t = &t.to_extended() + &constants::bi[( b_naf[i]/2) as usize];
t = &t.to_extended() + &odd_multiples_of_B[( b_naf[i]/2) as usize];
} else if b_naf[i] < 0 {
t = &t.to_extended() - &constants::bi[(-b_naf[i]/2) as usize];
t = &t.to_extended() - &odd_multiples_of_B[(-b_naf[i]/2) as usize];
}
r = t.to_projective();
@ -1431,7 +1432,7 @@ mod test {
#[test]
fn basepoint_mult_by_basepoint_order() {
let B = &constants::ED25519_BASEPOINT_TABLE;
let should_be_id = B * &constants::l;
let should_be_id = B * &constants::BASEPOINT_ORDER;
assert!(should_be_id.is_identity());
}

3
src/montgomery.rs
View file

@ -146,8 +146,9 @@ impl CompressedMontgomeryU {
/// actually a square and `0` if otherwise, along with a `FieldElement`: the
/// Montgomery `v` corresponding to this `u`.
pub fn to_montgomery_v(u: &FieldElement) -> (u8, FieldElement) {
let A = &constants::MONTGOMERY_A;
let one: FieldElement = FieldElement::one();
let v_squared: FieldElement = u * &(&u.square() + &(&(&constants::A * u) + &one));
let v_squared: FieldElement = u * &(&u.square() + &(&(A * u) + &one));
let (okay, v_inv) = v_squared.invsqrt();
let v = &v_inv * &v_squared;

10
src/ristretto.rs
View file

@ -462,7 +462,7 @@ impl CompressedRistretto {
let yden = &one + &ss; // 1 - a*s^2
let ynum = &one - &ss; // 1 + a*s^2
let yden_sqr = yden.square();
let xden_sqr = &(&(-&constants::d) * &ynum.square()) - &yden_sqr;
let xden_sqr = &(&(-&constants::EDWARDS_D) * &ynum.square()) - &yden_sqr;
let (ok, invsqrt) = (&xden_sqr * &yden_sqr).invsqrt();
@ -639,7 +639,7 @@ impl RistrettoPoint {
let iX = &X * &constants::SQRT_M1;
let iY = &Y * &constants::SQRT_M1;
let ristretto_magic = &constants::invsqrt_a_minus_d;
let ristretto_magic = &constants::INVSQRT_A_MINUS_D;
let enchanted_denominator = &i1 * ristretto_magic;
let rotate = (T * &z_inv).is_negative();
@ -673,7 +673,7 @@ impl RistrettoPoint {
/// This method is not public because it's just used for hashing
/// to a point -- proper elligator support is deferred for now.
pub fn elligator_ristretto_flavour(r_0: &FieldElement) -> RistrettoPoint {
let (i, d) = (&constants::SQRT_M1, &constants::d);
let (i, d) = (&constants::SQRT_M1, &constants::EDWARDS_D);
let one = FieldElement::one();
let r = i * &r_0.square();
@ -706,7 +706,7 @@ impl RistrettoPoint {
let s_sq = s.square();
let P = CompletedPoint{
X: &(&s + &s) * &D,
Z: &T * &constants::sqrt_ad_minus_one,
Z: &T * &constants::SQRT_AD_MINUS_ONE,
Y: &FieldElement::one() - &s_sq,
T: &FieldElement::one() + &s_sq,
};
@ -1061,7 +1061,7 @@ mod test {
#[test]
fn decompress_negative_s_fails() {
// constants::d is neg, so decompression should fail as |d| != d.
let bad_compressed = CompressedRistretto(constants::d.to_bytes());
let bad_compressed = CompressedRistretto(constants::EDWARDS_D.to_bytes());
assert!(bad_compressed.decompress().is_none());
}

8
src/scalar.rs
View file

@ -136,7 +136,7 @@ impl<'a, 'b> Add<&'b Scalar> for &'a Scalar {
impl<'b> SubAssign<&'b Scalar> for Scalar {
fn sub_assign(&mut self, _rhs: &'b Scalar) {
// (l-1)*_rhs + self = self - _rhs
*self = Scalar::multiply_add(&constants::l_minus_1, _rhs, self);
*self = Scalar::multiply_add(&constants::BASEPOINT_ORDER_MINUS_1, _rhs, self);
}
}
@ -144,14 +144,14 @@ impl<'a, 'b> Sub<&'b Scalar> for &'a Scalar {
type Output = Scalar;
fn sub(self, _rhs: &'b Scalar) -> Scalar {
// (l-1)*_rhs + self = self - _rhs
Scalar::multiply_add(&constants::l_minus_1, _rhs, self)
Scalar::multiply_add(&constants::BASEPOINT_ORDER_MINUS_1, _rhs, self)
}
}
impl<'a> Neg for &'a Scalar {
type Output = Scalar;
fn neg(self) -> Scalar {
self * &constants::l_minus_1
self * &constants::BASEPOINT_ORDER_MINUS_1
}
}
@ -900,7 +900,7 @@ mod test {
#[test]
fn impl_sub() {
let should_be_one = &constants::l - &constants::l_minus_1;
let should_be_one = &constants::BASEPOINT_ORDER - &constants::BASEPOINT_ORDER_MINUS_1;
assert_eq!(should_be_one, Scalar::one());
}