@noble/curves 1.4.2 → 1.6.0

package/esm/abstract/weierstrass.js

@@ -1,9 +1,15 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 // Short Weierstrass curve. The formula is: y² = x³ + ax + b
-import { validateBasic, wNAF } from './curve.js';
+import { validateBasic, wNAF, pippenger, } from './curve.js';
 import * as mod from './modular.js';
 import * as ut from './utils.js';
-import { ensureBytes } from './utils.js';
+import { ensureBytes, memoized, abool } from './utils.js';
+function validateSigVerOpts(opts) {
+    if (opts.lowS !== undefined)
+        abool('lowS', opts.lowS);
+    if (opts.prehash !== undefined)
+        abool('prehash', opts.prehash);
+}
 function validatePointOpts(curve) {
     const opts = validateBasic(curve);
     ut.validateObject(opts, {
@@ -31,8 +37,14 @@ function validatePointOpts(curve) {
     }
     return Object.freeze({ ...opts });
 }
-// ASN.1 DER encoding utilities
 const { bytesToNumberBE: b2n, hexToBytes: h2b } = ut;
+/**
+ * ASN.1 DER encoding utilities. ASN is very complex & fragile. Format:
+ *
+ *     [0x30 (SEQUENCE), bytelength, 0x02 (INTEGER), intLength, R, 0x02 (INTEGER), intLength, S]
+ *
+ * Docs: https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/, https://luca.ntop.org/Teaching/Appunti/asn1.html
+ */
 export const DER = {
     // asn.1 DER encoding utils
     Err: class DERErr extends Error {
@@ -40,54 +52,103 @@ export const DER = {
             super(m);
         }
     },
-    _parseInt(data) {
-        const { Err: E } = DER;
-        if (data.length < 2 || data[0] !== 0x02)
-            throw new E('Invalid signature integer tag');
-        const len = data[1];
-        const res = data.subarray(2, len + 2);
-        if (!len || res.length !== len)
-            throw new E('Invalid signature integer: wrong length');
-        // https://crypto.stackexchange.com/a/57734 Leftmost bit of first byte is 'negative' flag,
-        // since we always use positive integers here. It must always be empty:
-        // - add zero byte if exists
-        // - if next byte doesn't have a flag, leading zero is not allowed (minimal encoding)
-        if (res[0] & 0b10000000)
-            throw new E('Invalid signature integer: negative');
-        if (res[0] === 0x00 && !(res[1] & 0b10000000))
-            throw new E('Invalid signature integer: unnecessary leading zero');
-        return { d: b2n(res), l: data.subarray(len + 2) }; // d is data, l is left
+    // Basic building block is TLV (Tag-Length-Value)
+    _tlv: {
+        encode: (tag, data) => {
+            const { Err: E } = DER;
+            if (tag < 0 || tag > 256)
+                throw new E('tlv.encode: wrong tag');
+            if (data.length & 1)
+                throw new E('tlv.encode: unpadded data');
+            const dataLen = data.length / 2;
+            const len = ut.numberToHexUnpadded(dataLen);
+            if ((len.length / 2) & 128)
+                throw new E('tlv.encode: long form length too big');
+            // length of length with long form flag
+            const lenLen = dataLen > 127 ? ut.numberToHexUnpadded((len.length / 2) | 128) : '';
+            return `${ut.numberToHexUnpadded(tag)}${lenLen}${len}${data}`;
+        },
+        // v - value, l - left bytes (unparsed)
+        decode(tag, data) {
+            const { Err: E } = DER;
+            let pos = 0;
+            if (tag < 0 || tag > 256)
+                throw new E('tlv.encode: wrong tag');
+            if (data.length < 2 || data[pos++] !== tag)
+                throw new E('tlv.decode: wrong tlv');
+            const first = data[pos++];
+            const isLong = !!(first & 128); // First bit of first length byte is flag for short/long form
+            let length = 0;
+            if (!isLong)
+                length = first;
+            else {
+                // Long form: [longFlag(1bit), lengthLength(7bit), length (BE)]
+                const lenLen = first & 127;
+                if (!lenLen)
+                    throw new E('tlv.decode(long): indefinite length not supported');
+                if (lenLen > 4)
+                    throw new E('tlv.decode(long): byte length is too big'); // this will overflow u32 in js
+                const lengthBytes = data.subarray(pos, pos + lenLen);
+                if (lengthBytes.length !== lenLen)
+                    throw new E('tlv.decode: length bytes not complete');
+                if (lengthBytes[0] === 0)
+                    throw new E('tlv.decode(long): zero leftmost byte');
+                for (const b of lengthBytes)
+                    length = (length << 8) | b;
+                pos += lenLen;
+                if (length < 128)
+                    throw new E('tlv.decode(long): not minimal encoding');
+            }
+            const v = data.subarray(pos, pos + length);
+            if (v.length !== length)
+                throw new E('tlv.decode: wrong value length');
+            return { v, l: data.subarray(pos + length) };
+        },
+    },
+    // https://crypto.stackexchange.com/a/57734 Leftmost bit of first byte is 'negative' flag,
+    // since we always use positive integers here. It must always be empty:
+    // - add zero byte if exists
+    // - if next byte doesn't have a flag, leading zero is not allowed (minimal encoding)
+    _int: {
+        encode(num) {
+            const { Err: E } = DER;
+            if (num < _0n)
+                throw new E('integer: negative integers are not allowed');
+            let hex = ut.numberToHexUnpadded(num);
+            // Pad with zero byte if negative flag is present
+            if (Number.parseInt(hex[0], 16) & 0b1000)
+                hex = '00' + hex;
+            if (hex.length & 1)
+                throw new E('unexpected assertion');
+            return hex;
+        },
+        decode(data) {
+            const { Err: E } = DER;
+            if (data[0] & 128)
+                throw new E('Invalid signature integer: negative');
+            if (data[0] === 0x00 && !(data[1] & 128))
+                throw new E('Invalid signature integer: unnecessary leading zero');
+            return b2n(data);
+        },
     },
     toSig(hex) {
         // parse DER signature
-        const { Err: E } = DER;
+        const { Err: E, _int: int, _tlv: tlv } = DER;
         const data = typeof hex === 'string' ? h2b(hex) : hex;
         ut.abytes(data);
-        let l = data.length;
-        if (l < 2 || data[0] != 0x30)
-            throw new E('Invalid signature tag');
-        if (data[1] !== l - 2)
-            throw new E('Invalid signature: incorrect length');
-        const { d: r, l: sBytes } = DER._parseInt(data.subarray(2));
-        const { d: s, l: rBytesLeft } = DER._parseInt(sBytes);
-        if (rBytesLeft.length)
+        const { v: seqBytes, l: seqLeftBytes } = tlv.decode(0x30, data);
+        if (seqLeftBytes.length)
+            throw new E('Invalid signature: left bytes after parsing');
+        const { v: rBytes, l: rLeftBytes } = tlv.decode(0x02, seqBytes);
+        const { v: sBytes, l: sLeftBytes } = tlv.decode(0x02, rLeftBytes);
+        if (sLeftBytes.length)
             throw new E('Invalid signature: left bytes after parsing');
-        return { r, s };
+        return { r: int.decode(rBytes), s: int.decode(sBytes) };
     },
     hexFromSig(sig) {
-        // Add leading zero if first byte has negative bit enabled. More details in '_parseInt'
-        const slice = (s) => (Number.parseInt(s[0], 16) & 0b1000 ? '00' + s : s);
-        const h = (num) => {
-            const hex = num.toString(16);
-            return hex.length & 1 ? `0${hex}` : hex;
-        };
-        const s = slice(h(sig.s));
-        const r = slice(h(sig.r));
-        const shl = s.length / 2;
-        const rhl = r.length / 2;
-        const sl = h(shl);
-        const rl = h(rhl);
-        return `30${h(rhl + shl + 4)}02${rl}${r}02${sl}${s}`;
+        const { _tlv: tlv, _int: int } = DER;
+        const seq = `${tlv.encode(0x02, int.encode(sig.r))}${tlv.encode(0x02, int.encode(sig.s))}`;
+        return tlv.encode(0x30, seq);
     },
 };
 // Be friendly to bad ECMAScript parsers by not using bigint literals
@@ -96,6 +157,7 @@ const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3), _4n =
 export function weierstrassPoints(opts) {
     const CURVE = validatePointOpts(opts);
     const { Fp } = CURVE; // All curves has same field / group length as for now, but they can differ
+    const Fn = mod.Field(CURVE.n, CURVE.nBitLength);
     const toBytes = CURVE.toBytes ||
         ((_c, point, _isCompressed) => {
             const a = point.toAffine();
@@ -128,16 +190,12 @@ export function weierstrassPoints(opts) {
         throw new Error('bad generator point: equation left != right');
     // Valid group elements reside in range 1..n-1
     function isWithinCurveOrder(num) {
-        return typeof num === 'bigint' && _0n < num && num < CURVE.n;
-    }
-    function assertGE(num) {
-        if (!isWithinCurveOrder(num))
-            throw new Error('Expected valid bigint: 0 < bigint < curve.n');
+        return ut.inRange(num, _1n, CURVE.n);
     }
     // Validates if priv key is valid and converts it to bigint.
     // Supports options allowedPrivateKeyLengths and wrapPrivateKey.
     function normPrivateKeyToScalar(key) {
-        const { allowedPrivateKeyLengths: lengths, nByteLength, wrapPrivateKey, n } = CURVE;
+        const { allowedPrivateKeyLengths: lengths, nByteLength, wrapPrivateKey, n: N } = CURVE;
         if (lengths && typeof key !== 'bigint') {
             if (ut.isBytes(key))
                 key = ut.bytesToHex(key);
@@ -157,15 +215,61 @@ export function weierstrassPoints(opts) {
             throw new Error(`private key must be ${nByteLength} bytes, hex or bigint, not ${typeof key}`);
         }
         if (wrapPrivateKey)
-            num = mod.mod(num, n); // disabled by default, enabled for BLS
-        assertGE(num); // num in range [1..N-1]
+            num = mod.mod(num, N); // disabled by default, enabled for BLS
+        ut.aInRange('private key', num, _1n, N); // num in range [1..N-1]
         return num;
     }
-    const pointPrecomputes = new Map();
     function assertPrjPoint(other) {
         if (!(other instanceof Point))
             throw new Error('ProjectivePoint expected');
     }
+    // Memoized toAffine / validity check. They are heavy. Points are immutable.
+    // Converts Projective point to affine (x, y) coordinates.
+    // Can accept precomputed Z^-1 - for example, from invertBatch.
+    // (x, y, z) ∋ (x=x/z, y=y/z)
+    const toAffineMemo = memoized((p, iz) => {
+        const { px: x, py: y, pz: z } = p;
+        // Fast-path for normalized points
+        if (Fp.eql(z, Fp.ONE))
+            return { x, y };
+        const is0 = p.is0();
+        // If invZ was 0, we return zero point. However we still want to execute
+        // all operations, so we replace invZ with a random number, 1.
+        if (iz == null)
+            iz = is0 ? Fp.ONE : Fp.inv(z);
+        const ax = Fp.mul(x, iz);
+        const ay = Fp.mul(y, iz);
+        const zz = Fp.mul(z, iz);
+        if (is0)
+            return { x: Fp.ZERO, y: Fp.ZERO };
+        if (!Fp.eql(zz, Fp.ONE))
+            throw new Error('invZ was invalid');
+        return { x: ax, y: ay };
+    });
+    // NOTE: on exception this will crash 'cached' and no value will be set.
+    // Otherwise true will be return
+    const assertValidMemo = memoized((p) => {
+        if (p.is0()) {
+            // (0, 1, 0) aka ZERO is invalid in most contexts.
+            // In BLS, ZERO can be serialized, so we allow it.
+            // (0, 0, 0) is wrong representation of ZERO and is always invalid.
+            if (CURVE.allowInfinityPoint && !Fp.is0(p.py))
+                return;
+            throw new Error('bad point: ZERO');
+        }
+        // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
+        const { x, y } = p.toAffine();
+        // Check if x, y are valid field elements
+        if (!Fp.isValid(x) || !Fp.isValid(y))
+            throw new Error('bad point: x or y not FE');
+        const left = Fp.sqr(y); // y²
+        const right = weierstrassEquation(x); // x³ + ax + b
+        if (!Fp.eql(left, right))
+            throw new Error('bad point: equation left != right');
+        if (!p.isTorsionFree())
+            throw new Error('bad point: not in prime-order subgroup');
+        return true;
+    });
     /**
      * Projective Point works in 3d / projective (homogeneous) coordinates: (x, y, z) ∋ (x=x/z, y=y/z)
      * Default Point works in 2d / affine coordinates: (x, y)
@@ -182,6 +286,7 @@ export function weierstrassPoints(opts) {
                 throw new Error('y required');
             if (pz == null || !Fp.isValid(pz))
                 throw new Error('z required');
+            Object.freeze(this);
         }
         // Does not validate if the point is on-curve.
         // Use fromHex instead, or call assertValidity() later.
@@ -226,32 +331,17 @@ export function weierstrassPoints(opts) {
         static fromPrivateKey(privateKey) {
             return Point.BASE.multiply(normPrivateKeyToScalar(privateKey));
         }
+        // Multiscalar Multiplication
+        static msm(points, scalars) {
+            return pippenger(Point, Fn, points, scalars);
+        }
         // "Private method", don't use it directly
         _setWindowSize(windowSize) {
-            this._WINDOW_SIZE = windowSize;
-            pointPrecomputes.delete(this);
+            wnaf.setWindowSize(this, windowSize);
         }
         // A point on curve is valid if it conforms to equation.
         assertValidity() {
-            if (this.is0()) {
-                // (0, 1, 0) aka ZERO is invalid in most contexts.
-                // In BLS, ZERO can be serialized, so we allow it.
-                // (0, 0, 0) is wrong representation of ZERO and is always invalid.
-                if (CURVE.allowInfinityPoint && !Fp.is0(this.py))
-                    return;
-                throw new Error('bad point: ZERO');
-            }
-            // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
-            const { x, y } = this.toAffine();
-            // Check if x, y are valid field elements
-            if (!Fp.isValid(x) || !Fp.isValid(y))
-                throw new Error('bad point: x or y not FE');
-            const left = Fp.sqr(y); // y²
-            const right = weierstrassEquation(x); // x³ + ax + b
-            if (!Fp.eql(left, right))
-                throw new Error('bad point: equation left != right');
-            if (!this.isTorsionFree())
-                throw new Error('bad point: not in prime-order subgroup');
+            assertValidMemo(this);
         }
         hasEvenY() {
             const { y } = this.toAffine();
@@ -378,28 +468,25 @@ export function weierstrassPoints(opts) {
             return this.equals(Point.ZERO);
         }
         wNAF(n) {
-            return wnaf.wNAFCached(this, pointPrecomputes, n, (comp) => {
-                const toInv = Fp.invertBatch(comp.map((p) => p.pz));
-                return comp.map((p, i) => p.toAffine(toInv[i])).map(Point.fromAffine);
-            });
+            return wnaf.wNAFCached(this, n, Point.normalizeZ);
         }
         /**
          * Non-constant-time multiplication. Uses double-and-add algorithm.
          * It's faster, but should only be used when you don't care about
          * an exposed private key e.g. sig verification, which works over *public* keys.
          */
-        multiplyUnsafe(n) {
+        multiplyUnsafe(sc) {
+            ut.aInRange('scalar', sc, _0n, CURVE.n);
             const I = Point.ZERO;
-            if (n === _0n)
+            if (sc === _0n)
                 return I;
-            assertGE(n); // Will throw on 0
-            if (n === _1n)
+            if (sc === _1n)
                 return this;
             const { endo } = CURVE;
             if (!endo)
-                return wnaf.unsafeLadder(this, n);
+                return wnaf.unsafeLadder(this, sc);
             // Apply endomorphism
-            let { k1neg, k1, k2neg, k2 } = endo.splitScalar(n);
+            let { k1neg, k1, k2neg, k2 } = endo.splitScalar(sc);
             let k1p = I;
             let k2p = I;
             let d = this;
@@ -429,12 +516,11 @@ export function weierstrassPoints(opts) {
          * @returns New point
          */
         multiply(scalar) {
-            assertGE(scalar);
-            let n = scalar;
+            const { endo, n: N } = CURVE;
+            ut.aInRange('scalar', scalar, _1n, N);
             let point, fake; // Fake point is used to const-time mult
-            const { endo } = CURVE;
             if (endo) {
-                const { k1neg, k1, k2neg, k2 } = endo.splitScalar(n);
+                const { k1neg, k1, k2neg, k2 } = endo.splitScalar(scalar);
                 let { p: k1p, f: f1p } = this.wNAF(k1);
                 let { p: k2p, f: f2p } = this.wNAF(k2);
                 k1p = wnaf.constTimeNegate(k1neg, k1p);
@@ -444,7 +530,7 @@ export function weierstrassPoints(opts) {
                 fake = f1p.add(f2p);
             }
             else {
-                const { p, f } = this.wNAF(n);
+                const { p, f } = this.wNAF(scalar);
                 point = p;
                 fake = f;
             }
@@ -468,20 +554,7 @@ export function weierstrassPoints(opts) {
         // Can accept precomputed Z^-1 - for example, from invertBatch.
         // (x, y, z) ∋ (x=x/z, y=y/z)
         toAffine(iz) {
-            const { px: x, py: y, pz: z } = this;
-            const is0 = this.is0();
-            // If invZ was 0, we return zero point. However we still want to execute
-            // all operations, so we replace invZ with a random number, 1.
-            if (iz == null)
-                iz = is0 ? Fp.ONE : Fp.inv(z);
-            const ax = Fp.mul(x, iz);
-            const ay = Fp.mul(y, iz);
-            const zz = Fp.mul(z, iz);
-            if (is0)
-                return { x: Fp.ZERO, y: Fp.ZERO };
-            if (!Fp.eql(zz, Fp.ONE))
-                throw new Error('invZ was invalid');
-            return { x: ax, y: ay };
+            return toAffineMemo(this, iz);
         }
         isTorsionFree() {
             const { h: cofactor, isTorsionFree } = CURVE;
@@ -500,10 +573,12 @@ export function weierstrassPoints(opts) {
             return this.multiplyUnsafe(CURVE.h);
         }
         toRawBytes(isCompressed = true) {
+            abool('isCompressed', isCompressed);
             this.assertValidity();
             return toBytes(Point, this, isCompressed);
         }
         toHex(isCompressed = true) {
+            abool('isCompressed', isCompressed);
             return ut.bytesToHex(this.toRawBytes(isCompressed));
         }
     }
@@ -533,14 +608,18 @@ function validateOpts(curve) {
     });
     return Object.freeze({ lowS: true, ...opts });
 }
+/**
+ * Creates short weierstrass curve and ECDSA signature methods for it.
+ * @example
+ * import { Field } from '@noble/curves/abstract/modular';
+ * // Before that, define BigInt-s: a, b, p, n, Gx, Gy
+ * const curve = weierstrass({ a, b, Fp: Field(p), n, Gx, Gy, h: 1n })
+ */
 export function weierstrass(curveDef) {
     const CURVE = validateOpts(curveDef);
     const { Fp, n: CURVE_ORDER } = CURVE;
     const compressedLen = Fp.BYTES + 1; // e.g. 33 for 32
     const uncompressedLen = 2 * Fp.BYTES + 1; // e.g. 65 for 32
-    function isValidFieldElement(num) {
-        return _0n < num && num < Fp.ORDER; // 0 is banned since it's not invertible FE
-    }
     function modN(a) {
         return mod.mod(a, CURVE_ORDER);
     }
@@ -553,6 +632,7 @@ export function weierstrass(curveDef) {
             const a = point.toAffine();
             const x = Fp.toBytes(a.x);
             const cat = ut.concatBytes;
+            abool('isCompressed', isCompressed);
             if (isCompressed) {
                 return cat(Uint8Array.from([point.hasEvenY() ? 0x02 : 0x03]), x);
             }
@@ -567,7 +647,7 @@ export function weierstrass(curveDef) {
             // this.assertValidity() is done inside of fromHex
             if (len === compressedLen && (head === 0x02 || head === 0x03)) {
                 const x = ut.bytesToNumberBE(tail);
-                if (!isValidFieldElement(x))
+                if (!ut.inRange(x, _1n, Fp.ORDER))
                     throw new Error('Point is not on curve');
                 const y2 = weierstrassEquation(x); // y² = x³ + ax + b
                 let y;
@@ -628,11 +708,8 @@ export function weierstrass(curveDef) {
             return new Signature(r, s);
         }
         assertValidity() {
-            // can use assertGE here
-            if (!isWithinCurveOrder(this.r))
-                throw new Error('r must be 0 < r < CURVE.n');
-            if (!isWithinCurveOrder(this.s))
-                throw new Error('s must be 0 < s < CURVE.n');
+            ut.aInRange('r', this.r, _1n, CURVE_ORDER); // r in [1..N]
+            ut.aInRange('s', this.s, _1n, CURVE_ORDER); // s in [1..N]
         }
         addRecoveryBit(recovery) {
             return new Signature(this.r, this.s, recovery);
@@ -775,10 +852,7 @@ export function weierstrass(curveDef) {
      * Converts to bytes. Checks if num in `[0..ORDER_MASK-1]` e.g.: `[0..2^256-1]`.
      */
     function int2octets(num) {
-        if (typeof num !== 'bigint')
-            throw new Error('bigint expected');
-        if (!(_0n <= num && num < ORDER_MASK))
-            throw new Error(`bigint expected < 2^${CURVE.nBitLength}`);
+        ut.aInRange(`num < 2^${CURVE.nBitLength}`, num, _0n, ORDER_MASK);
         // works with order, can have different size than numToField!
         return ut.numberToBytesBE(num, CURVE.nByteLength);
     }
@@ -795,6 +869,7 @@ export function weierstrass(curveDef) {
         if (lowS == null)
             lowS = true; // RFC6979 3.2: we skip step A, because we already provide hash
         msgHash = ensureBytes('msgHash', msgHash);
+        validateSigVerOpts(opts);
         if (prehash)
             msgHash = ensureBytes('prehashed msgHash', hash(msgHash));
         // We can't later call bits2octets, since nested bits2int is broken for curves
@@ -881,6 +956,7 @@ export function weierstrass(curveDef) {
         publicKey = ensureBytes('publicKey', publicKey);
         if ('strict' in opts)
             throw new Error('options.strict was renamed to lowS');
+        validateSigVerOpts(opts);
         const { lowS, prehash } = opts;
         let _sig = undefined;
         let P;