@noble/curves 0.5.0 → 0.5.2

package/README.md

@@ -7,8 +7,8 @@ Minimal, auditable JS implementation of elliptic curve cryptography.
 - [hash to curve](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hash-to-curve/)
   for encoding or hashing an arbitrary string to a point on an elliptic curve
 - Auditable, [fast](#speed)
-- 🔻 Tree-shaking-friendly: there is no entry point, which ensures small size of your app
 - 🔍 Unique tests ensure correctness. Wycheproof vectors included
+- 🔻 Tree-shaking-friendly: there is no entry point, which ensures small size of your app
 
 There are two parts of the package:
 
@@ -84,11 +84,12 @@ To define a custom curve, check out API below.
 ## API
 
 - [Overview](#overview)
-- [abstract/edwards: Twisted Edwards curve](#abstract/edwards-twisted-edwards-curve)
-- [abstract/montgomery: Montgomery curve](#abstract/montgomery-montgomery-curve)
-- [abstract/weierstrass: Short Weierstrass curve](#abstract/weierstrass-short-weierstrass-curve)
-- [abstract/modular](#abstract/modular)
-- [abstract/utils](#abstract/utils)
+- [abstract/edwards: Twisted Edwards curve](#abstractedwards-twisted-edwards-curve)
+- [abstract/montgomery: Montgomery curve](#abstractmontgomery-montgomery-curve)
+- [abstract/weierstrass: Short Weierstrass curve](#abstractweierstrass-short-weierstrass-curve)
+- [abstract/hash-to-curve: Hashing strings to curve points](#abstracthash-to-curve-hashing-strings-to-curve-points)
+- [abstract/modular](#abstractmodular)
+- [abstract/utils](#abstractutils)
 
 ### Overview
 
@@ -200,8 +201,6 @@ export type CurveFn = {
   ExtendedPoint: ExtendedPointConstructor;
   Signature: SignatureConstructor;
   utils: {
-    mod: (a: bigint, b?: bigint) => bigint;
-    invert: (number: bigint, modulo?: bigint) => bigint;
     randomPrivateKey: () => Uint8Array;
     getExtendedPublicKey: (key: PrivKey) => {
       head: Uint8Array;
@@ -305,6 +304,7 @@ export type CurveFn = {
   getPublicKey: (privateKey: PrivKey, isCompressed?: boolean) => Uint8Array;
   getSharedSecret: (privateA: PrivKey, publicB: PubKey, isCompressed?: boolean) => Uint8Array;
   sign: (msgHash: Hex, privKey: PrivKey, opts?: SignOpts) => SignatureType;
+  signUnhashed: (msg: Uint8Array, privKey: PrivKey, opts?: SignOpts) => SignatureType;
   verify: (
     signature: Hex | SignatureType,
     msgHash: Hex,
@@ -315,8 +315,6 @@ export type CurveFn = {
   ProjectivePoint: ProjectivePointConstructor;
   Signature: SignatureConstructor;
   utils: {
-    mod: (a: bigint) => bigint;
-    invert: (number: bigint) => bigint;
     isValidPrivateKey(privateKey: PrivKey): boolean;
     hashToPrivateKey: (hash: Hex) => Uint8Array;
     randomPrivateKey: () => Uint8Array;
@@ -324,20 +322,70 @@ export type CurveFn = {
 };
 ```
 
+### abstract/hash-to-curve: Hashing strings to curve points
+
+The module allows to hash arbitrary strings to elliptic curve points.
+
+- `expand_message_xmd` [(spec)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.4.1) produces a uniformly random byte string using a cryptographic hash function H that outputs b bits..
+
+    ```ts
+    function expand_message_xmd(
+      msg: Uint8Array, DST: Uint8Array, lenInBytes: number, H: CHash
+    ): Uint8Array;
+    function expand_message_xof(
+      msg: Uint8Array, DST: Uint8Array, lenInBytes: number, k: number, H: CHash
+    ): Uint8Array;
+    ```
+
+- `hash_to_field(msg, count, options)` [(spec)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3)
+hashes arbitrary-length byte strings to a list of one or more elements of a finite field F.
+    * `msg` a byte string containing the message to hash
+    * `count` the number of elements of F to output
+    * `options` `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`
+    * Returns `[u_0, ..., u_(count - 1)]`, a list of field elements.
+
+    ```ts
+    function hash_to_field(msg: Uint8Array, count: number, options: htfOpts): bigint[][];
+    type htfOpts = {
+      // DST: a domain separation tag
+      // defined in section 2.2.5
+      DST: string;
+      // p: the characteristic of F
+      //    where F is a finite field of characteristic p and order q = p^m
+      p: bigint;
+      // m: the extension degree of F, m >= 1
+      //     where F is a finite field of characteristic p and order q = p^m
+      m: number;
+      // k: the target security level for the suite in bits
+      // defined in section 5.1
+      k: number;
+      // option to use a message that has already been processed by
+      // expand_message_xmd
+      expand?: 'xmd' | 'xof';
+      // Hash functions for: expand_message_xmd is appropriate for use with a
+      // wide range of hash functions, including SHA-2, SHA-3, BLAKE2, and others.
+      // BBS+ uses blake2: https://github.com/hyperledger/aries-framework-go/issues/2247
+      // TODO: verify that hash is shake if expand==='xof' via types
+      hash: CHash;
+    };
+    ```
+
 ### abstract/modular
 
 Modular arithmetics utilities.
 
 ```typescript
-import { mod, invert, div, invertBatch, sqrt, Fp } from '@noble/curves/abstract/modular';
+import { Fp, mod, invert, div, invertBatch, sqrt } from '@noble/curves/abstract/modular';
+const fp = Fp(2n ** 255n - 19n); // Finite field over 2^255-19
+fp.mul(591n, 932n);
+fp.pow(481n, 11024858120n);
+
+// Generic non-FP utils are also available
 mod(21n, 10n); // 21 mod 10 == 1n; fixed version of 21 % 10
 invert(17n, 10n); // invert(17) mod 10; modular multiplicative inverse
 div(5n, 17n, 10n); // 5/17 mod 10 == 5 * invert(17) mod 10; division
 invertBatch([1n, 2n, 4n], 21n); // => [1n, 11n, 16n] in one inversion
 sqrt(21n, 73n); // √21 mod 73; square root
-const fp = Fp(2n ** 255n - 19n); // Finite field over 2^255-19
-fp.mul(591n, 932n);
-fp.pow(481n, 11024858120n);
 ```
 
 ### abstract/utils

package/lib/_shortw_utils.d.ts

@@ -47,10 +47,8 @@ export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonl
     }>;
     getPublicKey: (privateKey: import("./abstract/utils.js").PrivKey, isCompressed?: boolean | undefined) => Uint8Array;
     getSharedSecret: (privateA: import("./abstract/utils.js").PrivKey, publicB: import("./abstract/weierstrass.js").PubKey, isCompressed?: boolean | undefined) => Uint8Array;
-    sign: (msgHash: import("./abstract/utils.js").Hex, privKey: import("./abstract/utils.js").PrivKey, opts?: {
-        lowS?: boolean | undefined;
-        extraEntropy?: (true | import("./abstract/utils.js").Hex) | undefined;
-    } | undefined) => import("./abstract/weierstrass.js").SignatureType;
+    sign: (msgHash: import("./abstract/utils.js").Hex, privKey: import("./abstract/utils.js").PrivKey, opts?: import("./abstract/weierstrass.js").SignOpts | undefined) => import("./abstract/weierstrass.js").SignatureType;
+    signUnhashed: (msg: Uint8Array, privKey: import("./abstract/utils.js").PrivKey, opts?: import("./abstract/weierstrass.js").SignOpts | undefined) => import("./abstract/weierstrass.js").SignatureType;
     verify: (signature: import("./abstract/utils.js").Hex | import("./abstract/weierstrass.js").SignatureType, msgHash: import("./abstract/utils.js").Hex, publicKey: import("./abstract/weierstrass.js").PubKey, opts?: {
         lowS?: boolean | undefined;
     } | undefined) => boolean;
@@ -58,8 +56,6 @@ export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonl
     ProjectivePoint: import("./abstract/weierstrass.js").ProjectiveConstructor<bigint>;
     Signature: import("./abstract/weierstrass.js").SignatureConstructor;
     utils: {
-        mod: (a: bigint, b?: bigint | undefined) => bigint;
-        invert: (number: bigint, modulo?: bigint | undefined) => bigint;
         _bigintToBytes: (num: bigint) => Uint8Array;
         _bigintToString: (num: bigint) => string;
         _normalizePrivateKey: (key: import("./abstract/utils.js").PrivKey) => bigint;

package/lib/abstract/bls.d.ts

@@ -1,8 +1,20 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+/**
+ * BLS (Barreto-Lynn-Scott) family of pairing-friendly curves.
+ * Implements BLS (Boneh-Lynn-Shacham) signatures.
+ * Consists of two curves: G1 and G2:
+ * - G1 is a subgroup of (x, y) E(Fq) over y² = x³ + 4.
+ * - G2 is a subgroup of ((x₁, x₂+i), (y₁, y₂+i)) E(Fq²) over y² = x³ + 4(1 + i) where i is √-1
+ * - Gt, created by bilinear (ate) pairing e(G1, G2), consists of p-th roots of unity in
+ *   Fq^k where k is embedding degree. Only degree 12 is currently supported, 24 is not.
+ * Pairing is used to aggregate and verify signatures.
+ * We are using Fp for private keys (shorter) and Fp₂ for signatures (longer).
+ * Some projects may prefer to swap this relation, it is not supported for now.
+ */
 import * as mod from './modular.js';
-import * as utils from './utils.js';
+import * as ut from './utils.js';
 import { Hex, PrivKey } from './utils.js';
-import { htfOpts, stringToBytes, hash_to_field, expand_message_xmd } from './hash-to-curve.js';
+import { htfOpts, stringToBytes, hash_to_field as hashToField, expand_message_xmd as expandMessageXMD } from './hash-to-curve.js';
 import { CurvePointsType, PointType, CurvePointsRes } from './weierstrass.js';
 declare type Fp = bigint;
 export declare type SignatureCoder<Fp2> = {
@@ -34,7 +46,7 @@ export declare type CurveType<Fp, Fp2, Fp6, Fp12> = {
         finalExponentiate(num: Fp12): Fp12;
     };
     htfDefaults: htfOpts;
-    hash: utils.CHash;
+    hash: ut.CHash;
     randomBytes: (bytesLength?: number) => Uint8Array;
 };
 export declare type CurveFn<Fp, Fp2, Fp6, Fp12> = {
@@ -66,12 +78,9 @@ export declare type CurveFn<Fp, Fp2, Fp6, Fp12> = {
     };
     verifyBatch: (signature: Hex | PointType<Fp2>, messages: (Hex | PointType<Fp2>)[], publicKeys: (Hex | PointType<Fp>)[]) => boolean;
     utils: {
-        bytesToHex: typeof utils.bytesToHex;
-        hexToBytes: typeof utils.hexToBytes;
         stringToBytes: typeof stringToBytes;
-        hashToField: typeof hash_to_field;
-        expandMessageXMD: typeof expand_message_xmd;
-        mod: typeof mod.mod;
+        hashToField: typeof hashToField;
+        expandMessageXMD: typeof expandMessageXMD;
         getDSTLabel: () => string;
         setDSTLabel(newLabel: string): void;
     };

package/lib/abstract/bls.js

@@ -1,24 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bls = void 0;
-/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Barreto-Lynn-Scott Curves. A family of pairing friendly curves, with embedding degree = 12 or 24
-// NOTE: only 12 supported for now
-// Constructed from pair of weierstrass curves, based pairing logic
-const mod = require("./modular.js");
-const utils_js_1 = require("./utils.js");
-// Types
-const utils_js_2 = require("./utils.js");
+const ut = require("./utils.js");
 const hash_to_curve_js_1 = require("./hash-to-curve.js");
 const weierstrass_js_1 = require("./weierstrass.js");
 function bls(CURVE) {
     // Fields looks pretty specific for curve, so for now we need to pass them with options
-    const Fp = CURVE.Fp;
-    const Fr = CURVE.Fr;
-    const Fp2 = CURVE.Fp2;
-    const Fp6 = CURVE.Fp6;
-    const Fp12 = CURVE.Fp12;
-    const BLS_X_LEN = (0, utils_js_1.bitLen)(CURVE.x);
+    const { Fp, Fr, Fp2, Fp6, Fp12 } = CURVE;
+    const BLS_X_LEN = ut.bitLen(CURVE.x);
+    const groupLen = 32; // TODO: calculate; hardcoded for now
     // Pre-compute coefficients for sparse multiplication
     // Point addition and point double calculations is reused for coefficients
     function calcPairingPrecomputes(x, y) {
@@ -42,7 +32,7 @@ function bls(CURVE) {
             Rx = Fp2.div(Fp2.mul(Fp2.mul(Fp2.sub(t0, t3), Rx), Ry), 2n); // ((T0 - T3) * Rx * Ry) / 2
             Ry = Fp2.sub(Fp2.square(Fp2.div(Fp2.add(t0, t3), 2n)), Fp2.mul(Fp2.square(t2), 3n)); // ((T0 + T3) / 2)² - 3 * T2²
             Rz = Fp2.mul(t0, t4); // T0 * T4
-            if ((0, utils_js_1.bitGet)(CURVE.x, i)) {
+            if (ut.bitGet(CURVE.x, i)) {
                 // Addition
                 let t0 = Fp2.sub(Ry, Fp2.mul(Qy, Rz)); // Ry - Qy * Rz
                 let t1 = Fp2.sub(Rx, Fp2.mul(Qx, Rz)); // Rx - Qx * Rz
@@ -63,13 +53,14 @@ function bls(CURVE) {
         return ell_coeff;
     }
     function millerLoop(ell, g1) {
+        const { x } = CURVE;
         const Px = g1[0];
         const Py = g1[1];
         let f12 = Fp12.ONE;
         for (let j = 0, i = BLS_X_LEN - 2; i >= 0; i--, j++) {
             const E = ell[j];
             f12 = Fp12.multiplyBy014(f12, E[0], Fp2.mul(E[1], Px), Fp2.mul(E[2], Py));
-            if ((0, utils_js_1.bitGet)(CURVE.x, i)) {
+            if (ut.bitGet(x, i)) {
                 j += 1;
                 const F = ell[j];
                 f12 = Fp12.multiplyBy014(f12, F[0], Fp2.mul(F[1], Px), Fp2.mul(F[2], Py));
@@ -79,79 +70,25 @@ function bls(CURVE) {
         }
         return Fp12.conjugate(f12);
     }
-    // bls12-381 is a construction of two curves:
-    // 1. Fp: (x, y)
-    // 2. Fp₂: ((x₁, x₂+i), (y₁, y₂+i)) - (complex numbers)
-    //
-    // Bilinear Pairing (ate pairing) is used to combine both elements into a paired one:
-    //   Fp₁₂ = e(Fp, Fp2)
-    //   where Fp₁₂ = 12-degree polynomial
-    // Pairing is used to verify signatures.
-    //
-    // We are using Fp for private keys (shorter) and Fp2 for signatures (longer).
-    // Some projects may prefer to swap this relation, it is not supported for now.
-    const htfDefaults = { ...CURVE.htfDefaults };
-    function isWithinCurveOrder(num) {
-        return 0 < num && num < CURVE.r;
-    }
     const utils = {
-        hexToBytes: utils_js_2.hexToBytes,
-        bytesToHex: utils_js_2.bytesToHex,
-        mod: mod.mod,
+        hexToBytes: ut.hexToBytes,
+        bytesToHex: ut.bytesToHex,
         stringToBytes: hash_to_curve_js_1.stringToBytes,
         // TODO: do we need to export it here?
         hashToField: (msg, count, options = {}) => (0, hash_to_curve_js_1.hash_to_field)(msg, count, { ...CURVE.htfDefaults, ...options }),
         expandMessageXMD: (msg, DST, lenInBytes, H = CURVE.hash) => (0, hash_to_curve_js_1.expand_message_xmd)(msg, DST, lenInBytes, H),
-        /**
-         * Can take 40 or more bytes of uniform input e.g. from CSPRNG or KDF
-         * and convert them into private key, with the modulo bias being negligible.
-         * As per FIPS 186 B.1.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 key
-         */
-        hashToPrivateKey: (hash) => {
-            hash = (0, utils_js_1.ensureBytes)(hash);
-            if (hash.length < 40 || hash.length > 1024)
-                throw new Error('Expected 40-1024 bytes of private key as per FIPS 186');
-            //     hashToPrivateScalar(hash, CURVE.r)
-            // NOTE: doesn't add +/-1
-            const num = mod.mod((0, utils_js_1.bytesToNumberBE)(hash), CURVE.r);
-            // This should never happen
-            if (num === 0n || num === 1n)
-                throw new Error('Invalid private key');
-            return (0, utils_js_1.numberToBytesBE)(num, 32);
-        },
-        randomBytes: (bytesLength = 32) => CURVE.randomBytes(bytesLength),
-        // NIST SP 800-56A rev 3, section 5.6.1.2.2
-        // https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/
-        randomPrivateKey: () => utils.hashToPrivateKey(utils.randomBytes(40)),
-        getDSTLabel: () => htfDefaults.DST,
+        hashToPrivateKey: (hash) => Fr.toBytes(ut.hashToPrivateScalar(hash, CURVE.r)),
+        randomBytes: (bytesLength = groupLen) => CURVE.randomBytes(bytesLength),
+        randomPrivateKey: () => utils.hashToPrivateKey(utils.randomBytes(groupLen + 8)),
+        getDSTLabel: () => CURVE.htfDefaults.DST,
         setDSTLabel(newLabel) {
             // https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-3.1
             if (typeof newLabel !== 'string' || newLabel.length > 2048 || newLabel.length === 0) {
                 throw new TypeError('Invalid DST');
             }
-            htfDefaults.DST = newLabel;
+            CURVE.htfDefaults.DST = newLabel;
         },
     };
-    function normalizePrivKey(key) {
-        let int;
-        if (key instanceof Uint8Array && key.length === 32)
-            int = (0, utils_js_1.bytesToNumberBE)(key);
-        else if (typeof key === 'string' && key.length === 64)
-            int = BigInt(`0x${key}`);
-        else if (typeof key === 'number' && key > 0 && Number.isSafeInteger(key))
-            int = BigInt(key);
-        else if (typeof key === 'bigint' && key > 0n)
-            int = key;
-        else
-            throw new TypeError('Expected valid private key');
-        int = mod.mod(int, CURVE.r);
-        if (!isWithinCurveOrder(int))
-            throw new Error('Private key must be 0 < key < CURVE.r');
-        return int;
-    }
     // Point on G1 curve: (x, y)
     const G1 = (0, weierstrass_js_1.weierstrassPoints)({
         n: Fr.ORDER,
@@ -205,7 +142,7 @@ function bls(CURVE) {
     function sign(message, privateKey) {
         const msgPoint = normP2Hash(message);
         msgPoint.assertValidity();
-        const sigPoint = msgPoint.multiply(normalizePrivKey(privateKey));
+        const sigPoint = msgPoint.multiply(G1.normalizePrivateKey(privateKey));
         if (message instanceof G2.Point)
             return sigPoint;
         return Signature.encode(sigPoint);

package/lib/abstract/edwards.d.ts

@@ -1,18 +1,13 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import * as mod from './modular.js';
-import { BasicCurve, Hex, PrivKey } from './utils.js';
+import * as ut from './utils.js';
+import { Hex, PrivKey } from './utils.js';
 import { Group, GroupConstructor } from './group.js';
 import { htfOpts } from './hash-to-curve.js';
-export declare type CHash = {
-    (message: Uint8Array | string): Uint8Array;
-    blockLen: number;
-    outputLen: number;
-    create(): any;
-};
-export declare type CurveType = BasicCurve<bigint> & {
+export declare type CurveType = ut.BasicCurve<bigint> & {
     a: bigint;
     d: bigint;
-    hash: CHash;
+    hash: ut.CHash;
     randomBytes: (bytesLength?: number) => Uint8Array;
     adjustScalarBytes?: (bytes: Uint8Array) => Uint8Array;
     domain?: (data: Uint8Array, ctx: Uint8Array, phflag: boolean) => Uint8Array;
@@ -20,8 +15,7 @@ export declare type CurveType = BasicCurve<bigint> & {
         isValid: boolean;
         value: bigint;
     };
-    preHash?: CHash;
-    clearCofactor?: (c: ExtendedPointConstructor, point: ExtendedPointType) => ExtendedPointType;
+    preHash?: ut.CHash;
     htfDefaults?: htfOpts;
     mapToCurve?: (scalar: bigint[]) => {
         x: bigint;
@@ -41,7 +35,7 @@ declare function validateOpts(curve: CurveType): Readonly<{
     readonly allowInfinityPoint?: boolean | undefined;
     readonly a: bigint;
     readonly d: bigint;
-    readonly hash: CHash;
+    readonly hash: ut.CHash;
     readonly randomBytes: (bytesLength?: number | undefined) => Uint8Array;
     readonly adjustScalarBytes?: ((bytes: Uint8Array) => Uint8Array) | undefined;
     readonly domain?: ((data: Uint8Array, ctx: Uint8Array, phflag: boolean) => Uint8Array) | undefined;
@@ -49,8 +43,7 @@ declare function validateOpts(curve: CurveType): Readonly<{
         isValid: boolean;
         value: bigint;
     }) | undefined;
-    readonly preHash?: CHash | undefined;
-    readonly clearCofactor?: ((c: ExtendedPointConstructor, point: ExtendedPointType) => ExtendedPointType) | undefined;
+    readonly preHash?: ut.CHash | undefined;
     readonly htfDefaults?: htfOpts | undefined;
     readonly mapToCurve?: ((scalar: bigint[]) => {
         x: bigint;
@@ -113,8 +106,6 @@ export declare type CurveFn = {
     ExtendedPoint: ExtendedPointConstructor;
     Signature: SignatureConstructor;
     utils: {
-        mod: (a: bigint) => bigint;
-        invert: (number: bigint) => bigint;
         randomPrivateKey: () => Uint8Array;
         getExtendedPublicKey: (key: PrivKey) => {
             head: Uint8Array;