@noble/curves 1.4.2 → 1.5.0

package/src/abstract/edwards.ts

@@ -3,7 +3,7 @@
 import { AffinePoint, BasicCurve, Group, GroupConstructor, validateBasic, wNAF } from './curve.js';
 import { mod } from './modular.js';
 import * as ut from './utils.js';
-import { ensureBytes, FHash, Hex } from './utils.js';
+import { ensureBytes, FHash, Hex, memoized, abool } from './utils.js';
 
 // Be friendly to bad ECMAScript parsers by not using bigint literals
 // prettier-ignore
@@ -72,6 +72,10 @@ export interface ExtPointConstructor extends GroupConstructor<ExtPointType> {
   fromPrivateKey(privateKey: Hex): ExtPointType;
 }
 
+/**
+ * Edwards Curve interface.
+ * Main methods: `getPublicKey(priv)`, `sign(msg, priv)`, `verify(sig, msg, pub)`.
+ */
 export type CurveFn = {
   CURVE: ReturnType<typeof validateOpts>;
   getPublicKey: (privateKey: Hex) => Uint8Array;
@@ -95,7 +99,13 @@ export type CurveFn = {
   };
 };
 
-// It is not generic twisted curve for now, but ed25519/ed448 generic implementation
+/**
+ * Creates Twisted Edwards curve with EdDSA signatures.
+ * @example
+ * import { Field } from '@noble/curves/abstract/modular';
+ * // Before that, define BigInt-s: a, d, p, n, Gx, Gy, h
+ * const curve = twistedEdwards({ a, d, Fp: Field(p), n, Gx, Gy, h })
+ */
 export function twistedEdwards(curveDef: CurveType): CurveFn {
   const CURVE = validateOpts(curveDef) as ReturnType<typeof validateOpts>;
   const {
@@ -124,25 +134,53 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
   const domain =
     CURVE.domain ||
     ((data: Uint8Array, ctx: Uint8Array, phflag: boolean) => {
+      abool('phflag', phflag);
       if (ctx.length || phflag) throw new Error('Contexts/pre-hash are not supported');
       return data;
     }); // NOOP
-  const inBig = (n: bigint) => typeof n === 'bigint' && _0n < n; // n in [1..]
-  const inRange = (n: bigint, max: bigint) => inBig(n) && inBig(max) && n < max; // n in [1..max-1]
-  const in0MaskRange = (n: bigint) => n === _0n || inRange(n, MASK); // n in [0..MASK-1]
-  function assertInRange(n: bigint, max: bigint) {
-    // n in [1..max-1]
-    if (inRange(n, max)) return n;
-    throw new Error(`Expected valid scalar < ${max}, got ${typeof n} ${n}`);
+  // 0 <= n < MASK
+  // Coordinates larger than Fp.ORDER are allowed for zip215
+  function aCoordinate(title: string, n: bigint) {
+    ut.aInRange('coordinate ' + title, n, _0n, MASK);
   }
-  function assertGE0(n: bigint) {
-    // n in [0..CURVE_ORDER-1]
-    return n === _0n ? n : assertInRange(n, CURVE_ORDER); // GE = prime subgroup, not full group
-  }
-  const pointPrecomputes = new Map<Point, Point[]>();
-  function isPoint(other: unknown) {
+
+  function assertPoint(other: unknown) {
     if (!(other instanceof Point)) throw new Error('ExtendedPoint expected');
   }
+  // Converts Extended point to default (x, y) coordinates.
+  // Can accept precomputed Z^-1 - for example, from invertBatch.
+  const toAffineMemo = memoized((p: Point, iz?: bigint): AffinePoint<bigint> => {
+    const { ex: x, ey: y, ez: z } = p;
+    const is0 = p.is0();
+    if (iz == null) iz = is0 ? _8n : (Fp.inv(z) as bigint); // 8 was chosen arbitrarily
+    const ax = modP(x * iz);
+    const ay = modP(y * iz);
+    const zz = modP(z * iz);
+    if (is0) return { x: _0n, y: _1n };
+    if (zz !== _1n) throw new Error('invZ was invalid');
+    return { x: ax, y: ay };
+  });
+  const assertValidMemo = memoized((p: Point) => {
+    const { a, d } = CURVE;
+    if (p.is0()) throw new Error('bad point: ZERO'); // TODO: optimize, with vars below?
+    // Equation in affine coordinates: ax² + y² = 1 + dx²y²
+    // Equation in projective coordinates (X/Z, Y/Z, Z):  (aX² + Y²)Z² = Z⁴ + dX²Y²
+    const { ex: X, ey: Y, ez: Z, et: T } = p;
+    const X2 = modP(X * X); // X²
+    const Y2 = modP(Y * Y); // Y²
+    const Z2 = modP(Z * Z); // Z²
+    const Z4 = modP(Z2 * Z2); // Z⁴
+    const aX2 = modP(X2 * a); // aX²
+    const left = modP(Z2 * modP(aX2 + Y2)); // (aX² + Y²)Z²
+    const right = modP(Z4 + modP(d * modP(X2 * Y2))); // Z⁴ + dX²Y²
+    if (left !== right) throw new Error('bad point: equation left != right (1)');
+    // In Extended coordinates we also have T, which is x*y=T/Z: check X*Y == Z*T
+    const XY = modP(X * Y);
+    const ZT = modP(Z * T);
+    if (XY !== ZT) throw new Error('bad point: equation left != right (2)');
+    return true;
+  });
+
   // Extended Point works in extended coordinates: (x, y, z, t) ∋ (x=x/z, y=y/z, t=xy).
   // https://en.wikipedia.org/wiki/Twisted_Edwards_curve#Extended_coordinates
   class Point implements ExtPointType {
@@ -155,10 +193,11 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
       readonly ez: bigint,
       readonly et: bigint
     ) {
-      if (!in0MaskRange(ex)) throw new Error('x required');
-      if (!in0MaskRange(ey)) throw new Error('y required');
-      if (!in0MaskRange(ez)) throw new Error('z required');
-      if (!in0MaskRange(et)) throw new Error('t required');
+      aCoordinate('x', ex);
+      aCoordinate('y', ey);
+      aCoordinate('z', ez);
+      aCoordinate('t', et);
+      Object.freeze(this);
     }
 
     get x(): bigint {
@@ -171,7 +210,8 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     static fromAffine(p: AffinePoint<bigint>): Point {
       if (p instanceof Point) throw new Error('extended point not allowed');
       const { x, y } = p || {};
-      if (!in0MaskRange(x) || !in0MaskRange(y)) throw new Error('invalid affine point');
+      aCoordinate('x', x);
+      aCoordinate('y', y);
       return new Point(x, y, _1n, modP(x * y));
     }
     static normalizeZ(points: Point[]): Point[] {
@@ -179,41 +219,19 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
       return points.map((p, i) => p.toAffine(toInv[i])).map(Point.fromAffine);
     }
 
-    // We calculate precomputes for elliptic curve point multiplication
-    // using windowed method. This specifies window size and
-    // stores precomputed values. Usually only base point would be precomputed.
-    _WINDOW_SIZE?: number;
-
     // "Private method", don't use it directly
     _setWindowSize(windowSize: number) {
-      this._WINDOW_SIZE = windowSize;
-      pointPrecomputes.delete(this);
+      wnaf.setWindowSize(this, windowSize);
     }
     // Not required for fromHex(), which always creates valid points.
     // Could be useful for fromAffine().
     assertValidity(): void {
-      const { a, d } = CURVE;
-      if (this.is0()) throw new Error('bad point: ZERO'); // TODO: optimize, with vars below?
-      // Equation in affine coordinates: ax² + y² = 1 + dx²y²
-      // Equation in projective coordinates (X/Z, Y/Z, Z):  (aX² + Y²)Z² = Z⁴ + dX²Y²
-      const { ex: X, ey: Y, ez: Z, et: T } = this;
-      const X2 = modP(X * X); // X²
-      const Y2 = modP(Y * Y); // Y²
-      const Z2 = modP(Z * Z); // Z²
-      const Z4 = modP(Z2 * Z2); // Z⁴
-      const aX2 = modP(X2 * a); // aX²
-      const left = modP(Z2 * modP(aX2 + Y2)); // (aX² + Y²)Z²
-      const right = modP(Z4 + modP(d * modP(X2 * Y2))); // Z⁴ + dX²Y²
-      if (left !== right) throw new Error('bad point: equation left != right (1)');
-      // In Extended coordinates we also have T, which is x*y=T/Z: check X*Y == Z*T
-      const XY = modP(X * Y);
-      const ZT = modP(Z * T);
-      if (XY !== ZT) throw new Error('bad point: equation left != right (2)');
+      assertValidMemo(this);
     }
 
     // Compare one point to another.
     equals(other: Point): boolean {
-      isPoint(other);
+      assertPoint(other);
       const { ex: X1, ey: Y1, ez: Z1 } = this;
       const { ex: X2, ey: Y2, ez: Z2 } = other;
       const X1Z2 = modP(X1 * Z2);
@@ -223,7 +241,7 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
       return X1Z2 === X2Z1 && Y1Z2 === Y2Z1;
     }
 
-    protected is0(): boolean {
+    is0(): boolean {
       return this.equals(Point.ZERO);
     }
 
@@ -258,7 +276,7 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     // https://hyperelliptic.org/EFD/g1p/auto-twisted-extended.html#addition-add-2008-hwcd
     // Cost: 9M + 1*a + 1*d + 7add.
     add(other: Point) {
-      isPoint(other);
+      assertPoint(other);
       const { a, d } = CURVE;
       const { ex: X1, ey: Y1, ez: Z1, et: T1 } = this;
       const { ex: X2, ey: Y2, ez: Z2, et: T2 } = other;
@@ -303,12 +321,14 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     }
 
     private wNAF(n: bigint): { p: Point; f: Point } {
-      return wnaf.wNAFCached(this, pointPrecomputes, n, Point.normalizeZ);
+      return wnaf.wNAFCached(this, n, Point.normalizeZ);
     }
 
     // Constant-time multiplication.
     multiply(scalar: bigint): Point {
-      const { p, f } = this.wNAF(assertInRange(scalar, CURVE_ORDER));
+      const n = scalar;
+      ut.aInRange('scalar', n, _1n, CURVE_ORDER); // 1 <= scalar < L
+      const { p, f } = this.wNAF(n);
       return Point.normalizeZ([p, f])[0];
     }
 
@@ -317,7 +337,8 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     // an exposed private key e.g. sig verification.
     // Does NOT allow scalars higher than CURVE.n.
     multiplyUnsafe(scalar: bigint): Point {
-      let n = assertGE0(scalar); // 0 <= scalar < CURVE.n
+      const n = scalar;
+      ut.aInRange('scalar', n, _0n, CURVE_ORDER); // 0 <= scalar < L
       if (n === _0n) return I;
       if (this.equals(I) || n === _1n) return this;
       if (this.equals(G)) return this.wNAF(n).p;
@@ -341,15 +362,7 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     // Converts Extended point to default (x, y) coordinates.
     // Can accept precomputed Z^-1 - for example, from invertBatch.
     toAffine(iz?: bigint): AffinePoint<bigint> {
-      const { ex: x, ey: y, ez: z } = this;
-      const is0 = this.is0();
-      if (iz == null) iz = is0 ? _8n : (Fp.inv(z) as bigint); // 8 was chosen arbitrarily
-      const ax = modP(x * iz);
-      const ay = modP(y * iz);
-      const zz = modP(z * iz);
-      if (is0) return { x: _0n, y: _1n };
-      if (zz !== _1n) throw new Error('invZ was invalid');
-      return { x: ax, y: ay };
+      return toAffineMemo(this, iz);
     }
 
     clearCofactor(): Point {
@@ -364,18 +377,17 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
       const { d, a } = CURVE;
       const len = Fp.BYTES;
       hex = ensureBytes('pointHex', hex, len); // copy hex to a new array
+      abool('zip215', zip215);
       const normed = hex.slice(); // copy again, we'll manipulate it
       const lastByte = hex[len - 1]; // select last byte
       normed[len - 1] = lastByte & ~0x80; // clear last bit
       const y = ut.bytesToNumberLE(normed);
-      if (y === _0n) {
-        // y=0 is allowed
-      } else {
-        // RFC8032 prohibits >= p, but ZIP215 doesn't
-        if (zip215)
-          assertInRange(y, MASK); // zip215=true [1..P-1] (2^255-19-1 for ed25519)
-        else assertInRange(y, Fp.ORDER); // zip215=false [1..MASK-1] (2^256-1 for ed25519)
-      }
+
+      // RFC8032 prohibits >= p, but ZIP215 doesn't
+      // zip215=true:  0 <= y < MASK (2^256 for ed25519)
+      // zip215=false: 0 <= y < P (2^255-19 for ed25519)
+      const max = zip215 ? MASK : Fp.ORDER;
+      ut.aInRange('pointHex.y', y, _0n, max);
 
       // Ed25519: x² = (y²-1)/(dy²+1) mod p. Ed448: x² = (y²-1)/(dy²-1) mod p. Generic case:
       // ax²+y²=1+dx²y² => y²-1=dx²y²-ax² => y²-1=x²(dy²-a) => x²=(y²-1)/(dy²-a)
@@ -451,7 +463,7 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     const R = G.multiply(r).toRawBytes(); // R = rG
     const k = hashDomainToScalar(options.context, R, pointBytes, msg); // R || A || PH(M)
     const s = modN(r + k * scalar); // S = (r + k * s) mod L
-    assertGE0(s); // 0 <= s < l
+    ut.aInRange('signature.s', s, _0n, CURVE_ORDER); // 0 <= s < l
     const res = ut.concatBytes(R, ut.numberToBytesLE(s, Fp.BYTES));
     return ensureBytes('result', res, nByteLength * 2); // 64-byte signature
   }
@@ -462,6 +474,7 @@ export function twistedEdwards(curveDef: CurveType): CurveFn {
     const len = Fp.BYTES; // Verifies EdDSA signature against message and public key. RFC8032 5.1.7.
     sig = ensureBytes('signature', sig, 2 * len); // An extended group equation is checked.
     msg = ensureBytes('message', msg);
+    if (zip215 !== undefined) abool('zip215', zip215);
     if (prehash) msg = prehash(msg); // for ed25519ph, etc
 
     const s = ut.bytesToNumberLE(sig.slice(len, 2 * len));

package/src/abstract/modular.ts

@@ -195,7 +195,6 @@ export function FpSqrt(P: bigint) {
     //   return Fp.cmov(tv1, tv2, e3); //  10.  z = CMOV(tv1, tv2, e3)  # Select the sqrt from tv1 and tv2
     // }
   }
-
   // Other cases: Tonelli-Shanks algorithm
   return tonelliShanks(P);
 }
@@ -314,11 +313,19 @@ export function FpDiv<T>(f: IField<T>, lhs: T, rhs: T | bigint): T {
   return f.mul(lhs, typeof rhs === 'bigint' ? invert(rhs, f.ORDER) : f.inv(rhs));
 }
 
+export function FpLegendre(order: bigint) {
+  // (a | p) ≡ 1    if a is a square (mod p), quadratic residue
+  // (a | p) ≡ -1   if a is not a square (mod p), quadratic non residue
+  // (a | p) ≡ 0    if a ≡ 0 (mod p)
+  const legendreConst = (order - _1n) / _2n; // Integer arithmetic
+  return <T>(f: IField<T>, x: T): T => f.pow(x, legendreConst);
+}
+
 // This function returns True whenever the value x is a square in the field F.
 export function FpIsSquare<T>(f: IField<T>) {
-  const legendreConst = (f.ORDER - _1n) / _2n; // Integer arithmetic
+  const legendre = FpLegendre(f.ORDER);
   return (x: T): boolean => {
-    const p = f.pow(x, legendreConst);
+    const p = legendre(f, x);
     return f.eql(p, f.ZERO) || f.eql(p, f.ONE);
   };
 }
@@ -339,6 +346,9 @@ type FpField = IField<bigint> & Required<Pick<IField<bigint>, 'isOdd'>>;
  * * a) denormalized operations like mulN instead of mul
  * * b) same object shape: never add or remove keys
  * * c) Object.freeze
+ * NOTE: operations don't check 'isValid' for all elements for performance reasons,
+ * it is caller responsibility to check this.
+ * This is low-level code, please make sure you know what you doing.
  * @param ORDER prime positive bigint
  * @param bitLen how many bits the field consumes
  * @param isLE (def: false) if encoding / decoding should be in little-endian

package/src/abstract/montgomery.ts

@@ -1,6 +1,12 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import { mod, pow } from './modular.js';
-import { bytesToNumberLE, ensureBytes, numberToBytesLE, validateObject } from './utils.js';
+import {
+  aInRange,
+  bytesToNumberLE,
+  ensureBytes,
+  numberToBytesLE,
+  validateObject,
+} from './utils.js';
 
 const _0n = BigInt(0);
 const _1n = BigInt(1);
@@ -75,12 +81,6 @@ export function montgomery(curveDef: CurveType): CurveFn {
     return [x_2, x_3];
   }
 
-  // Accepts 0 as well
-  function assertFieldElement(n: bigint): bigint {
-    if (typeof n === 'bigint' && _0n <= n && n < P) return n;
-    throw new Error('Expected valid scalar 0 < scalar < CURVE.P');
-  }
-
   // x25519 from 4
   // The constant a24 is (486662 - 2) / 4 = 121665 for curve25519/X25519
   const a24 = (CURVE.a - BigInt(2)) / BigInt(4);
@@ -90,11 +90,12 @@ export function montgomery(curveDef: CurveType): CurveFn {
    * @param scalar by which the point would be multiplied
    * @returns new Point on Montgomery curve
    */
-  function montgomeryLadder(pointU: bigint, scalar: bigint): bigint {
-    const u = assertFieldElement(pointU);
+  function montgomeryLadder(u: bigint, scalar: bigint): bigint {
+    aInRange('u', u, _0n, P);
+    aInRange('scalar', scalar, _0n, P);
     // Section 5: Implementations MUST accept non-canonical values and process them as
     // if they had been reduced modulo the field prime.
-    const k = assertFieldElement(scalar);
+    const k = scalar;
     const x_1 = u;
     let x_2 = _1n;
     let z_2 = _0n;