@noble/curves 0.1.0 → 0.2.1

package/lib/esm/modular.js

@@ -1,4 +1,5 @@
 /*! @noble/curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+// Utilities for modular arithmetics
 const _0n = BigInt(0);
 const _1n = BigInt(1);
 const _2n = BigInt(2);
@@ -62,6 +63,15 @@ export function invert(number, modulo) {
         throw new Error('invert: does not exist');
     return mod(x, modulo);
 }
+/**
+ * Division over finite field.
+ * `a/b mod p == a * invert(b) mod p`
+ */
+export function div(numerator, denominator, modulo) {
+    const num = mod(numerator, modulo);
+    const iden = invert(denominator, modulo);
+    return mod(num * iden, modulo);
+}
 /**
  * Takes a list of numbers, efficiently inverts all of them.
  * @param nums list of bigints
@@ -97,7 +107,6 @@ export function legendre(num, fieldPrime) {
 }
 /**
  * Calculates square root of a number in a finite field.
- * Used to calculate y - the square root of y².
  */
 export function sqrt(number, modulo) {
     const n = number;
@@ -146,3 +155,12 @@ export function sqrt(number, modulo) {
     }
     return r;
 }
+// Little-endian check for first LE bit (last BE bit);
+export const isNegativeLE = (num, modulo) => (mod(num, modulo) & _1n) === _1n;
+// An idea on modular arithmetic for bls12-381:
+// const FIELD = {add, pow, sqrt, mul};
+// Functions will take field elements, no need for an additional class
+// Could be faster. 1 bigint field will just do operations and mod later:
+// instead of 'r = mod(r * b, P)' we will write r = mul(r, b);
+// Could be insecure without shape check, so it needs to be done.
+// Functions could be inlined by JIT.

package/lib/esm/montgomery.js

@@ -0,0 +1,189 @@
+import * as mod from './modular.js';
+import { ensureBytes, numberToBytesLE, bytesToNumberLE,
+// nLength,
+ } from './utils.js';
+const _0n = BigInt(0);
+const _1n = BigInt(1);
+function validateOpts(curve) {
+    for (const i of ['a24']) {
+        if (typeof curve[i] !== 'bigint')
+            throw new Error(`Invalid curve param ${i}=${curve[i]} (${typeof curve[i]})`);
+    }
+    for (const i of ['montgomeryBits', 'nByteLength']) {
+        if (curve[i] === undefined)
+            continue; // Optional
+        if (!Number.isSafeInteger(curve[i]))
+            throw new Error(`Invalid curve param ${i}=${curve[i]} (${typeof curve[i]})`);
+    }
+    for (const fn of ['adjustScalarBytes', 'domain', 'powPminus2']) {
+        if (curve[fn] === undefined)
+            continue; // Optional
+        if (typeof curve[fn] !== 'function')
+            throw new Error(`Invalid ${fn} function`);
+    }
+    for (const i of ['Gu']) {
+        if (curve[i] === undefined)
+            continue; // Optional
+        if (typeof curve[i] !== 'string')
+            throw new Error(`Invalid curve param ${i}=${curve[i]} (${typeof curve[i]})`);
+    }
+    // Set defaults
+    // ...nLength(curve.n, curve.nBitLength),
+    return Object.freeze({ ...curve });
+}
+// NOTE: not really montgomery curve, just bunch of very specific methods for X25519/X448 (RFC 7748, https://www.rfc-editor.org/rfc/rfc7748)
+// Uses only one coordinate instead of two
+export function montgomery(curveDef) {
+    const CURVE = validateOpts(curveDef);
+    const { P } = CURVE;
+    const modP = (a) => mod.mod(a, P);
+    const montgomeryBits = CURVE.montgomeryBits;
+    const montgomeryBytes = Math.ceil(montgomeryBits / 8);
+    const fieldLen = CURVE.nByteLength;
+    const adjustScalarBytes = CURVE.adjustScalarBytes || ((bytes) => bytes);
+    const powPminus2 = CURVE.powPminus2 || ((x) => mod.pow(x, P - BigInt(2), P));
+    /**
+     * Checks for num to be in range:
+     * For strict == true:  `0 <  num < max`.
+     * For strict == false: `0 <= num < max`.
+     * Converts non-float safe numbers to bigints.
+     */
+    function normalizeScalar(num, max, strict = true) {
+        if (!max)
+            throw new TypeError('Specify max value');
+        if (typeof num === 'number' && Number.isSafeInteger(num))
+            num = BigInt(num);
+        if (typeof num === 'bigint' && num < max) {
+            if (strict) {
+                if (_0n < num)
+                    return num;
+            }
+            else {
+                if (_0n <= num)
+                    return num;
+            }
+        }
+        throw new TypeError('Expected valid scalar: 0 < scalar < max');
+    }
+    // cswap from RFC7748
+    // NOTE: cswap is not from RFC7748!
+    /*
+      cswap(swap, x_2, x_3):
+           dummy = mask(swap) AND (x_2 XOR x_3)
+           x_2 = x_2 XOR dummy
+           x_3 = x_3 XOR dummy
+           Return (x_2, x_3)
+    Where mask(swap) is the all-1 or all-0 word of the same length as x_2
+     and x_3, computed, e.g., as mask(swap) = 0 - swap.
+    */
+    function cswap(swap, x_2, x_3) {
+        const dummy = modP(swap * (x_2 - x_3));
+        x_2 = modP(x_2 - dummy);
+        x_3 = modP(x_3 + dummy);
+        return [x_2, x_3];
+    }
+    // x25519 from 4
+    /**
+     *
+     * @param pointU u coordinate (x) on Montgomery Curve 25519
+     * @param scalar by which the point would be multiplied
+     * @returns new Point on Montgomery curve
+     */
+    function montgomeryLadder(pointU, scalar) {
+        const { P } = CURVE;
+        const u = normalizeScalar(pointU, P);
+        // Section 5: Implementations MUST accept non-canonical values and process them as
+        // if they had been reduced modulo the field prime.
+        const k = normalizeScalar(scalar, P);
+        // The constant a24 is (486662 - 2) / 4 = 121665 for curve25519/X25519
+        const a24 = CURVE.a24;
+        const x_1 = u;
+        let x_2 = _1n;
+        let z_2 = _0n;
+        let x_3 = u;
+        let z_3 = _1n;
+        let swap = _0n;
+        let sw;
+        for (let t = BigInt(montgomeryBits - 1); t >= _0n; t--) {
+            const k_t = (k >> t) & _1n;
+            swap ^= k_t;
+            sw = cswap(swap, x_2, x_3);
+            x_2 = sw[0];
+            x_3 = sw[1];
+            sw = cswap(swap, z_2, z_3);
+            z_2 = sw[0];
+            z_3 = sw[1];
+            swap = k_t;
+            const A = x_2 + z_2;
+            const AA = modP(A * A);
+            const B = x_2 - z_2;
+            const BB = modP(B * B);
+            const E = AA - BB;
+            const C = x_3 + z_3;
+            const D = x_3 - z_3;
+            const DA = modP(D * A);
+            const CB = modP(C * B);
+            const dacb = DA + CB;
+            const da_cb = DA - CB;
+            x_3 = modP(dacb * dacb);
+            z_3 = modP(x_1 * modP(da_cb * da_cb));
+            x_2 = modP(AA * BB);
+            z_2 = modP(E * (AA + modP(a24 * E)));
+        }
+        // (x_2, x_3) = cswap(swap, x_2, x_3)
+        sw = cswap(swap, x_2, x_3);
+        x_2 = sw[0];
+        x_3 = sw[1];
+        // (z_2, z_3) = cswap(swap, z_2, z_3)
+        sw = cswap(swap, z_2, z_3);
+        z_2 = sw[0];
+        z_3 = sw[1];
+        // z_2^(p - 2)
+        const z2 = powPminus2(z_2);
+        // Return x_2 * (z_2^(p - 2))
+        return modP(x_2 * z2);
+    }
+    function encodeUCoordinate(u) {
+        return numberToBytesLE(modP(u), montgomeryBytes);
+    }
+    function decodeUCoordinate(uEnc) {
+        const u = ensureBytes(uEnc, montgomeryBytes);
+        // Section 5: When receiving such an array, implementations of X25519
+        // MUST mask the most significant bit in the final byte.
+        // This is very ugly way, but it works because fieldLen-1 is outside of bounds for X448, so this becomes NOOP
+        // fieldLen - scalaryBytes = 1 for X448 and = 0 for X25519
+        u[fieldLen - 1] &= 127; // 0b0111_1111
+        return bytesToNumberLE(u);
+    }
+    function decodeScalar(n) {
+        const bytes = ensureBytes(n);
+        if (bytes.length !== montgomeryBytes && bytes.length !== fieldLen)
+            throw new Error(`Expected ${montgomeryBytes} or ${fieldLen} bytes, got ${bytes.length}`);
+        return bytesToNumberLE(adjustScalarBytes(bytes));
+    }
+    // Multiply point u by scalar
+    function scalarMult(u, scalar) {
+        const pointU = decodeUCoordinate(u);
+        const _scalar = decodeScalar(scalar);
+        const pu = montgomeryLadder(pointU, _scalar);
+        // The result was not contributory
+        // https://cr.yp.to/ecdh.html#validate
+        if (pu === _0n)
+            throw new Error('Invalid private or public key received');
+        return encodeUCoordinate(pu);
+    }
+    // Multiply base point by scalar
+    function scalarMultBase(scalar) {
+        return scalarMult(CURVE.Gu, scalar);
+    }
+    return {
+        // NOTE: we can get 'y' coordinate from 'u', but Point.fromHex also wants 'x' coordinate oddity flag, and we cannot get 'x' without knowing 'v'
+        // Need to add generic conversion between twisted edwards and complimentary curve for JubJub
+        scalarMult,
+        scalarMultBase,
+        // NOTE: these function work on complimentary montgomery curve
+        // getSharedSecret: (privateKey: Hex, publicKey: Hex) => scalarMult(publicKey, privateKey),
+        getPublicKey: (privateKey) => scalarMultBase(privateKey),
+        Gu: CURVE.Gu,
+    };
+}

package/lib/esm/utils.js

@@ -1,6 +1,19 @@
 /*! @noble/curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Convert between types
-// ---------------------
+export function validateOpts(curve) {
+    for (const i of ['P', 'n', 'h', 'Gx', 'Gy']) {
+        if (typeof curve[i] !== 'bigint')
+            throw new Error(`Invalid curve param ${i}=${curve[i]} (${typeof curve[i]})`);
+    }
+    for (const i of ['nBitLength', 'nByteLength']) {
+        if (curve[i] === undefined)
+            continue; // Optional
+        if (!Number.isSafeInteger(curve[i]))
+            throw new Error(`Invalid curve param ${i}=${curve[i]} (${typeof curve[i]})`);
+    }
+    // Set defaults
+    return Object.freeze({ ...nLength(curve.n, curve.nBitLength), ...curve });
+}
+import * as mod from './modular.js';
 const hexes = Array.from({ length: 256 }, (v, i) => i.toString(16).padStart(2, '0'));
 export function bytesToHex(uint8a) {
     if (!(uint8a instanceof Uint8Array))
@@ -42,13 +55,23 @@ export function hexToBytes(hex) {
     return array;
 }
 // Big Endian
-export function bytesToNumber(bytes) {
+export function bytesToNumberBE(bytes) {
     return hexToNumber(bytesToHex(bytes));
 }
-export function ensureBytes(hex) {
+export function bytesToNumberLE(uint8a) {
+    if (!(uint8a instanceof Uint8Array))
+        throw new Error('Expected Uint8Array');
+    return BigInt('0x' + bytesToHex(Uint8Array.from(uint8a).reverse()));
+}
+export const numberToBytesBE = (n, len) => hexToBytes(n.toString(16).padStart(len * 2, '0'));
+export const numberToBytesLE = (n, len) => numberToBytesBE(n, len).reverse();
+export function ensureBytes(hex, expectedLength) {
     // Uint8Array.from() instead of hash.slice() because node.js Buffer
     // is instance of Uint8Array, and its slice() creates **mutable** copy
-    return hex instanceof Uint8Array ? Uint8Array.from(hex) : hexToBytes(hex);
+    const bytes = hex instanceof Uint8Array ? Uint8Array.from(hex) : hexToBytes(hex);
+    if (typeof expectedLength === 'number' && bytes.length !== expectedLength)
+        throw new Error(`Expected ${expectedLength} bytes`);
+    return bytes;
 }
 // Copies several Uint8Arrays into one.
 export function concatBytes(...arrays) {
@@ -65,3 +88,37 @@ export function concatBytes(...arrays) {
     }
     return result;
 }
+// CURVE.n lengths
+export function nLength(n, nBitLength) {
+    // Bit size, byte size of CURVE.n
+    const _nBitLength = nBitLength !== undefined ? nBitLength : n.toString(2).length;
+    const nByteLength = Math.ceil(_nBitLength / 8);
+    return { nBitLength: _nBitLength, nByteLength };
+}
+/**
+ * Can take (n+8) or more bytes of uniform input e.g. from CSPRNG or KDF
+ * and convert them into private scalar, with the modulo bias being neglible.
+ * As per FIPS 186 B.4.1.
+ * https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/
+ * @param hash hash output from sha512, or a similar function
+ * @returns valid private scalar
+ */
+const _1n = BigInt(1);
+export function hashToPrivateScalar(hash, CURVE_ORDER, isLE = false) {
+    hash = ensureBytes(hash);
+    const orderLen = nLength(CURVE_ORDER).nByteLength;
+    const minLen = orderLen + 8;
+    if (orderLen < 16 || hash.length < minLen || hash.length > 1024)
+        throw new Error('Expected valid bytes of private key as per FIPS 186');
+    const num = isLE ? bytesToNumberLE(hash) : bytesToNumberBE(hash);
+    return mod.mod(num, CURVE_ORDER - _1n) + _1n;
+}
+export function equalBytes(b1, b2) {
+    // We don't care about timing attacks here
+    if (b1.length !== b2.length)
+        return false;
+    for (let i = 0; i < b1.length; i++)
+        if (b1[i] !== b2[i])
+            return false;
+    return true;
+}