@noble/curves 0.1.0 → 0.2.0

package/lib/montgomery.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.montgomery = void 0;
+const mod = require("./modular.js");
+const utils_js_1 = require("./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
+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 (0, utils_js_1.numberToBytesLE)(modP(u), montgomeryBytes);
+    }
+    function decodeUCoordinate(uEnc) {
+        const u = (0, utils_js_1.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 (0, utils_js_1.bytesToNumberLE)(u);
+    }
+    function decodeScalar(n) {
+        const bytes = (0, utils_js_1.ensureBytes)(n);
+        if (bytes.length !== montgomeryBytes && bytes.length !== fieldLen)
+            throw new Error(`Expected ${montgomeryBytes} or ${fieldLen} bytes, got ${bytes.length}`);
+        return (0, utils_js_1.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,
+    };
+}
+exports.montgomery = montgomery;

package/lib/utils.d.ts

@@ -1,8 +1,32 @@
 /*! @noble/curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+export declare type Hex = Uint8Array | string;
+export declare type PrivKey = Hex | bigint | number;
+export declare type BasicCurve = {
+    P: bigint;
+    n: bigint;
+    nBitLength?: number;
+    nByteLength?: number;
+    h: bigint;
+    Gx: bigint;
+    Gy: bigint;
+};
+export declare function validateOpts<T extends BasicCurve>(curve: T): Readonly<{
+    readonly nBitLength: number;
+    readonly nByteLength: number;
+} & T>;
 export declare function bytesToHex(uint8a: Uint8Array): string;
 export declare function numberToHexUnpadded(num: number | bigint): string;
 export declare function hexToNumber(hex: string): bigint;
 export declare function hexToBytes(hex: string): Uint8Array;
-export declare function bytesToNumber(bytes: Uint8Array): bigint;
-export declare function ensureBytes(hex: string | Uint8Array): Uint8Array;
+export declare function bytesToNumberBE(bytes: Uint8Array): bigint;
+export declare function bytesToNumberLE(uint8a: Uint8Array): bigint;
+export declare const numberToBytesBE: (n: bigint, len: number) => Uint8Array;
+export declare const numberToBytesLE: (n: bigint, len: number) => Uint8Array;
+export declare function ensureBytes(hex: Hex, expectedLength?: number): Uint8Array;
 export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
+export declare function nLength(n: bigint, nBitLength?: number): {
+    nBitLength: number;
+    nByteLength: number;
+};
+export declare function hashToPrivateScalar(hash: Hex, CURVE_ORDER: bigint, isLE?: boolean): bigint;
+export declare function equalBytes(b1: Uint8Array, b2: Uint8Array): boolean;

package/lib/utils.js

@@ -1,9 +1,23 @@
 "use strict";
 /*! @noble/curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Convert between types
-// ---------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.concatBytes = exports.ensureBytes = exports.bytesToNumber = exports.hexToBytes = exports.hexToNumber = exports.numberToHexUnpadded = exports.bytesToHex = void 0;
+exports.equalBytes = exports.hashToPrivateScalar = exports.nLength = exports.concatBytes = exports.ensureBytes = exports.numberToBytesLE = exports.numberToBytesBE = exports.bytesToNumberLE = exports.bytesToNumberBE = exports.hexToBytes = exports.hexToNumber = exports.numberToHexUnpadded = exports.bytesToHex = exports.validateOpts = void 0;
+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 });
+}
+exports.validateOpts = validateOpts;
+const mod = require("./modular.js");
 const hexes = Array.from({ length: 256 }, (v, i) => i.toString(16).padStart(2, '0'));
 function bytesToHex(uint8a) {
     if (!(uint8a instanceof Uint8Array))
@@ -49,14 +63,27 @@ function hexToBytes(hex) {
 }
 exports.hexToBytes = hexToBytes;
 // Big Endian
-function bytesToNumber(bytes) {
+function bytesToNumberBE(bytes) {
     return hexToNumber(bytesToHex(bytes));
 }
-exports.bytesToNumber = bytesToNumber;
-function ensureBytes(hex) {
+exports.bytesToNumberBE = bytesToNumberBE;
+function bytesToNumberLE(uint8a) {
+    if (!(uint8a instanceof Uint8Array))
+        throw new Error('Expected Uint8Array');
+    return BigInt('0x' + bytesToHex(Uint8Array.from(uint8a).reverse()));
+}
+exports.bytesToNumberLE = bytesToNumberLE;
+const numberToBytesBE = (n, len) => hexToBytes(n.toString(16).padStart(len * 2, '0'));
+exports.numberToBytesBE = numberToBytesBE;
+const numberToBytesLE = (n, len) => (0, exports.numberToBytesBE)(n, len).reverse();
+exports.numberToBytesLE = numberToBytesLE;
+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;
 }
 exports.ensureBytes = ensureBytes;
 // Copies several Uint8Arrays into one.
@@ -75,3 +102,40 @@ function concatBytes(...arrays) {
     return result;
 }
 exports.concatBytes = concatBytes;
+// CURVE.n lengths
+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 };
+}
+exports.nLength = nLength;
+/**
+ * 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);
+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;
+}
+exports.hashToPrivateScalar = hashToPrivateScalar;
+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;
+}
+exports.equalBytes = equalBytes;

package/lib/{shortw.d.ts → weierstrass.d.ts}

@@ -1,4 +1,6 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import { BasicCurve, Hex, PrivKey } from './utils.js';
+import { Group, GroupConstructor } from './group.js';
 export declare type CHash = {
     (message: Uint8Array | string): Uint8Array;
     blockLen: number;
@@ -15,15 +17,9 @@ declare type EndomorphismOpts = {
         k2: bigint;
     };
 };
-export declare type CurveType = {
+export declare type CurveType = BasicCurve & {
     a: bigint;
     b: bigint;
-    P: bigint;
-    n: bigint;
-    nBitLength?: number;
-    nByteLength?: number;
-    Gx: bigint;
-    Gy: bigint;
     lowS?: boolean;
     hash: CHash;
     hmac: HmacFnSync;
@@ -32,17 +28,16 @@ export declare type CurveType = {
     sqrtMod?: (n: bigint) => bigint;
     endo?: EndomorphismOpts;
 };
-declare type Hex = Uint8Array | string;
-declare type PrivKey = Hex | bigint | number;
 declare function validateOpts(curve: CurveType): Readonly<{
-    readonly a: bigint;
-    readonly b: bigint;
+    readonly nBitLength: number;
+    readonly nByteLength: number;
     readonly P: bigint;
     readonly n: bigint;
-    nBitLength: number;
-    nByteLength: number;
+    readonly h: bigint;
     readonly Gx: bigint;
     readonly Gy: bigint;
+    readonly a: bigint;
+    readonly b: bigint;
     lowS: boolean;
     readonly hash: CHash;
     readonly hmac: HmacFnSync;
@@ -96,28 +91,21 @@ export declare type SignatureConstructor = {
     fromCompact(hex: Hex): SignatureType;
     fromDER(hex: Hex): SignatureType;
 };
-export interface JacobianPointType {
+export interface JacobianPointType extends Group<JacobianPointType> {
     readonly x: bigint;
     readonly y: bigint;
     readonly z: bigint;
-    equals(other: JacobianPointType): boolean;
-    negate(): JacobianPointType;
-    double(): JacobianPointType;
-    add(other: JacobianPointType): JacobianPointType;
-    subtract(other: JacobianPointType): JacobianPointType;
-    multiplyUnsafe(scalar: bigint): JacobianPointType;
     multiply(scalar: number | bigint, affinePoint?: PointType): JacobianPointType;
+    multiplyUnsafe(scalar: bigint): JacobianPointType;
     toAffine(invZ?: bigint): PointType;
 }
-export declare type JacobianPointConstructor = {
+export interface JacobianPointConstructor extends GroupConstructor<JacobianPointType> {
     new (x: bigint, y: bigint, z: bigint): JacobianPointType;
-    BASE: JacobianPointType;
-    ZERO: JacobianPointType;
     fromAffine(p: PointType): JacobianPointType;
     toAffineBatch(points: JacobianPointType[]): PointType[];
     normalizeZ(points: JacobianPointType[]): JacobianPointType[];
-};
-export interface PointType {
+}
+export interface PointType extends Group<PointType> {
     readonly x: bigint;
     readonly y: bigint;
     _setWindowSize(windowSize: number): void;
@@ -125,21 +113,13 @@ export interface PointType {
     toRawBytes(isCompressed?: boolean): Uint8Array;
     toHex(isCompressed?: boolean): string;
     assertValidity(): void;
-    equals(other: PointType): boolean;
-    negate(): PointType;
-    double(): PointType;
-    add(other: PointType): PointType;
-    subtract(other: PointType): PointType;
-    multiply(scalar: number | bigint): PointType;
     multiplyAndAddUnsafe(Q: PointType, a: bigint, b: bigint): PointType | undefined;
 }
-export declare type PointConstructor = {
-    BASE: PointType;
-    ZERO: PointType;
+export interface PointConstructor extends GroupConstructor<PointType> {
     new (x: bigint, y: bigint): PointType;
     fromHex(hex: Hex): PointType;
     fromPrivateKey(privateKey: PrivKey): PointType;
-};
+}
 export declare type PubKey = Hex | PointType;
 export declare type CurveFn = {
     CURVE: ReturnType<typeof validateOpts>;
@@ -155,6 +135,13 @@ export declare type CurveFn = {
     utils: {
         mod: (a: bigint, b?: bigint) => bigint;
         invert: (number: bigint, modulo?: bigint) => bigint;
+        _bigintToBytes: (num: bigint) => Uint8Array;
+        _bigintToString: (num: bigint) => string;
+        _normalizePrivateKey: (key: PrivKey) => bigint;
+        _normalizePublicKey: (publicKey: PubKey) => PointType;
+        _isWithinCurveOrder: (num: bigint) => boolean;
+        _isValidFieldElement: (num: bigint) => boolean;
+        _weierstrassEquation: (x: bigint) => bigint;
         isValidPrivateKey(privateKey: PrivKey): boolean;
         hashToPrivateKey: (hash: Hex) => Uint8Array;
         randomPrivateKey: () => Uint8Array;