@noble/curves 1.2.0 → 1.3.0

package/esm/bls12-381.js

@@ -1,14 +1,8 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// bls12-381 pairing-friendly Barreto-Lynn-Scott elliptic curve construction allows to:
-// - Construct zk-SNARKs at the 128-bit security
-// - Use threshold signatures, which allows a user to sign lots of messages with one signature and
-//   verify them swiftly in a batch, using Boneh-Lynn-Shacham signature scheme.
-//
-// The library uses G1 for public keys and G2 for signatures. Support for G1 signatures is planned.
-// Compatible with Algorand, Chia, Dfinity, Ethereum, FIL, Zcash. Matches specs
-// [pairing-curves-11](https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-11),
-// [bls-sigs-04](https:/cfrg-hash-to/tools.ietf.org/html/draft-irtf-cfrg-bls-signature-04),
-// [hash-to-curve-12](https://tools.ietf.org/html/draft-irtf--curve-12).
+// bls12-381 is pairing-friendly Barreto-Lynn-Scott elliptic curve construction allowing to:
+// - Construct zk-SNARKs at the 120-bit security
+// - Efficiently verify N aggregate signatures with 1 pairing and N ec additions:
+//   the Boneh-Lynn-Shacham signature scheme is orders of magnitude more efficient than Schnorr
 //
 // ### Summary
 // 1. BLS Relies on Bilinear Pairing (expensive)
@@ -24,13 +18,22 @@
 // - `S = pk x H(m)` - signing
 // - `e(P, H(m)) == e(G, S)` - verification using pairings
 // - `e(G, S) = e(G, SUM(n)(Si)) = MUL(n)(e(G, Si))` - signature aggregation
-// Filecoin uses little endian byte arrays for private keys -
-// so ensure to reverse byte order if you'll use it with FIL.
+//
+// ### Compatibility and notes
+// 1. It is compatible with Algorand, Chia, Dfinity, Ethereum, Filecoin, ZEC
+//    Filecoin uses little endian byte arrays for private keys - make sure to reverse byte order.
+// 2. Some projects use G2 for public keys and G1 for signatures. It's called "short signature"
+// 3. Curve security level is about 120 bits as per Barbulescu-Duquesne 2017
+//    https://hal.science/hal-01534101/file/main.pdf
+// 4. Compatible with specs:
+// [cfrg-pairing-friendly-curves-11](https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-11),
+// [cfrg-bls-signature-05](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05),
+// [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
 import { sha256 } from '@noble/hashes/sha256';
 import { randomBytes } from '@noble/hashes/utils';
 import { bls } from './abstract/bls.js';
 import * as mod from './abstract/modular.js';
-import { concatBytes as concatB, ensureBytes, numberToBytesBE, bytesToNumberBE, bitLen, bitSet, bitGet, bitMask, bytesToHex, } from './abstract/utils.js';
+import { concatBytes as concatB, ensureBytes, numberToBytesBE, bytesToNumberBE, bitLen, bitGet, bitMask, bytesToHex, } from './abstract/utils.js';
 // Types
 import { mapToCurveSimpleSWU, } from './abstract/weierstrass.js';
 import { isogenyMap } from './abstract/hash-to-curve.js';
@@ -257,14 +260,14 @@ const Fp6Square = ({ c0, c1, c2 }) => {
     let t3 = Fp2.mul(Fp2.mul(c1, c2), _2n); // 2 * c1 * c2
     let t4 = Fp2.sqr(c2); // c2²
     return {
-        c0: Fp2.add(Fp2.mulByNonresidue(t3), t0),
-        c1: Fp2.add(Fp2.mulByNonresidue(t4), t1),
+        c0: Fp2.add(Fp2.mulByNonresidue(t3), t0), // T3 * (u + 1) + T0
+        c1: Fp2.add(Fp2.mulByNonresidue(t4), t1), // T4 * (u + 1) + T1
         // T1 + (c0 - c1 + c2)² + T3 - T0 - T4
         c2: Fp2.sub(Fp2.sub(Fp2.add(Fp2.add(t1, Fp2.sqr(Fp2.add(Fp2.sub(c0, c1), c2))), t3), t0), t4),
     };
 };
 const Fp6 = {
-    ORDER: Fp2.ORDER,
+    ORDER: Fp2.ORDER, // TODO: unused, but need to verify
     BITS: 3 * Fp2.BITS,
     BYTES: 3 * Fp2.BYTES,
     MASK: bitMask(3 * Fp2.BITS),
@@ -424,7 +427,7 @@ const Fp12Multiply = ({ c0, c1 }, rhs) => {
     let t1 = Fp6.mul(c0, r0); // c0 * r0
     let t2 = Fp6.mul(c1, r1); // c1 * r1
     return {
-        c0: Fp6.add(t1, Fp6.mulByNonresidue(t2)),
+        c0: Fp6.add(t1, Fp6.mulByNonresidue(t2)), // T1 + T2 * v
         // (c0 + c1) * (r0 + r1) - (T1 + T2)
         c1: Fp6.sub(Fp6.mul(Fp6.add(c0, c1), Fp6.add(r0, r1)), Fp6.add(t1, t2)),
     };
@@ -441,12 +444,12 @@ function Fp4Square(a, b) {
     const a2 = Fp2.sqr(a);
     const b2 = Fp2.sqr(b);
     return {
-        first: Fp2.add(Fp2.mulByNonresidue(b2), a2),
+        first: Fp2.add(Fp2.mulByNonresidue(b2), a2), // b² * Nonresidue + a²
         second: Fp2.sub(Fp2.sub(Fp2.sqr(Fp2.add(a, b)), a2), b2), // (a + b)² - a² - b²
     };
 }
 const Fp12 = {
-    ORDER: Fp2.ORDER,
+    ORDER: Fp2.ORDER, // TODO: unused, but need to verify
     BITS: 2 * Fp2.BITS,
     BYTES: 2 * Fp2.BYTES,
     MASK: bitMask(2 * Fp2.BITS),
@@ -521,7 +524,7 @@ const Fp12 = {
         let t0 = Fp6.multiplyBy01(c0, o0, o1);
         let t1 = Fp6.multiplyBy1(c1, o4);
         return {
-            c0: Fp6.add(Fp6.mulByNonresidue(t1), t0),
+            c0: Fp6.add(Fp6.mulByNonresidue(t1), t0), // T1 * v + T0
             // (c1 + c0) * [o0, o1+o4] - T0 - T1
             c1: Fp6.sub(Fp6.sub(Fp6.multiplyBy01(Fp6.add(c1, c0), o0, Fp2.add(o1, o4)), t0), t1),
         };
@@ -544,13 +547,13 @@ const Fp12 = {
         let t9 = Fp2.mulByNonresidue(t8); // T8 * (u + 1)
         return {
             c0: Fp6.create({
-                c0: Fp2.add(Fp2.mul(Fp2.sub(t3, c0c0), _2n), t3),
-                c1: Fp2.add(Fp2.mul(Fp2.sub(t5, c0c1), _2n), t5),
+                c0: Fp2.add(Fp2.mul(Fp2.sub(t3, c0c0), _2n), t3), // 2 * (T3 - c0c0)  + T3
+                c1: Fp2.add(Fp2.mul(Fp2.sub(t5, c0c1), _2n), t5), // 2 * (T5 - c0c1)  + T5
                 c2: Fp2.add(Fp2.mul(Fp2.sub(t7, c0c2), _2n), t7),
-            }),
+            }), // 2 * (T7 - c0c2)  + T7
             c1: Fp6.create({
-                c0: Fp2.add(Fp2.mul(Fp2.add(t9, c1c0), _2n), t9),
-                c1: Fp2.add(Fp2.mul(Fp2.add(t4, c1c1), _2n), t4),
+                c0: Fp2.add(Fp2.mul(Fp2.add(t9, c1c0), _2n), t9), // 2 * (T9 + c1c0) + T9
+                c1: Fp2.add(Fp2.mul(Fp2.add(t4, c1c1), _2n), t4), // 2 * (T4 + c1c1) + T4
                 c2: Fp2.add(Fp2.mul(Fp2.add(t6, c1c2), _2n), t6),
             }),
         }; // 2 * (T6 + c1c2) + T6
@@ -776,8 +779,8 @@ const isogenyMapG1 = isogenyMap(Fp, [
 ].map((i) => i.map((j) => BigInt(j))));
 // SWU Map - Fp2 to G2': y² = x³ + 240i * x + 1012 + 1012i
 const G2_SWU = mapToCurveSimpleSWU(Fp2, {
-    A: Fp2.create({ c0: Fp.create(_0n), c1: Fp.create(BigInt(240)) }),
-    B: Fp2.create({ c0: Fp.create(BigInt(1012)), c1: Fp.create(BigInt(1012)) }),
+    A: Fp2.create({ c0: Fp.create(_0n), c1: Fp.create(BigInt(240)) }), // A' = 240 * I
+    B: Fp2.create({ c0: Fp.create(BigInt(1012)), c1: Fp.create(BigInt(1012)) }), // B' = 1012 * (1 + I)
     Z: Fp2.create({ c0: Fp.create(BigInt(-2)), c1: Fp.create(BigInt(-1)) }), // Z: -(2 + I)
 });
 // Optimized SWU Map - Fp to G1
@@ -850,11 +853,39 @@ const htfDefaults = Object.freeze({
 });
 // Encoding utils
 // Point on G1 curve: (x, y)
-const C_BIT_POS = Fp.BITS; // C_bit, compression bit for serialization flag
-const I_BIT_POS = Fp.BITS + 1; // I_bit, point-at-infinity bit for serialization flag
-const S_BIT_POS = Fp.BITS + 2; // S_bit, sign bit for serialization flag
 // Compressed point of infinity
-const COMPRESSED_ZERO = Fp.toBytes(bitSet(bitSet(_0n, I_BIT_POS, true), S_BIT_POS, true)); // set compressed & point-at-infinity bits
+const COMPRESSED_ZERO = setMask(Fp.toBytes(_0n), { infinity: true, compressed: true }); // set compressed & point-at-infinity bits
+function parseMask(bytes) {
+    // Copy, so we can remove mask data. It will be removed also later, when Fp.create will call modulo.
+    bytes = bytes.slice();
+    const mask = bytes[0] & 224;
+    const compressed = !!((mask >> 7) & 1); // compression bit (0b1000_0000)
+    const infinity = !!((mask >> 6) & 1); // point at infinity bit (0b0100_0000)
+    const sort = !!((mask >> 5) & 1); // sort bit (0b0010_0000)
+    bytes[0] &= 31; // clear mask (zero first 3 bits)
+    return { compressed, infinity, sort, value: bytes };
+}
+function setMask(bytes, mask) {
+    if (bytes[0] & 224)
+        throw new Error('setMask: non-empty mask');
+    if (mask.compressed)
+        bytes[0] |= 128;
+    if (mask.infinity)
+        bytes[0] |= 64;
+    if (mask.sort)
+        bytes[0] |= 32;
+    return bytes;
+}
+function signatureG1ToRawBytes(point) {
+    point.assertValidity();
+    const isZero = point.equals(bls12_381.G1.ProjectivePoint.ZERO);
+    const { x, y } = point.toAffine();
+    if (isZero)
+        return COMPRESSED_ZERO.slice();
+    const P = Fp.ORDER;
+    const sort = Boolean((y * _2n) / P);
+    return setMask(numberToBytesBE(x, Fp.BYTES), { compressed: true, sort });
+}
 function signatureG2ToRawBytes(point) {
     // NOTE: by some reasons it was missed in bls12-381, looks like bug
     point.assertValidity();
@@ -865,10 +896,9 @@ function signatureG2ToRawBytes(point) {
     const { re: x0, im: x1 } = Fp2.reim(x);
     const { re: y0, im: y1 } = Fp2.reim(y);
     const tmp = y1 > _0n ? y1 * _2n : y0 * _2n;
-    const aflag1 = Boolean((tmp / Fp.ORDER) & _1n);
-    const z1 = bitSet(bitSet(x1, 381, aflag1), S_BIT_POS, true);
+    const sort = Boolean((tmp / Fp.ORDER) & _1n);
     const z2 = x0;
-    return concatB(numberToBytesBE(z1, len), numberToBytesBE(z2, len));
+    return concatB(setMask(numberToBytesBE(x1, len), { sort, compressed: true }), numberToBytesBE(z2, len));
 }
 // To verify curve parameters, see pairing-friendly-curves spec:
 // https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-pairing-friendly-curves-11
@@ -902,7 +932,7 @@ export const bls12_381 = bls({
         Gy: BigInt('0x08b3f481e3aaa0f1a09e30ed741d8ae4fcf5e095d5d00af600db18cb2c04b3edd03cc744a2888ae40caa232946c5e7e1'),
         a: Fp.ZERO,
         b: _4n,
-        htfDefaults: { ...htfDefaults, m: 1 },
+        htfDefaults: { ...htfDefaults, m: 1, DST: 'BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_' },
         wrapPrivateKey: true,
         allowInfinityPoint: true,
         // Checks is the point resides in prime-order subgroup.
@@ -940,31 +970,35 @@ export const bls12_381 = bls({
             return isogenyMapG1(x, y);
         },
         fromBytes: (bytes) => {
-            bytes = bytes.slice();
-            if (bytes.length === 48) {
+            const { compressed, infinity, sort, value } = parseMask(bytes);
+            if (value.length === 48 && compressed) {
                 // TODO: Fp.bytes
                 const P = Fp.ORDER;
-                const compressedValue = bytesToNumberBE(bytes);
-                const bflag = bitGet(compressedValue, I_BIT_POS);
+                const compressedValue = bytesToNumberBE(value);
                 // Zero
-                if (bflag === _1n)
-                    return { x: _0n, y: _0n };
                 const x = Fp.create(compressedValue & Fp.MASK);
+                if (infinity) {
+                    if (x !== _0n)
+                        throw new Error('G1: non-empty compressed point at infinity');
+                    return { x: _0n, y: _0n };
+                }
                 const right = Fp.add(Fp.pow(x, _3n), Fp.create(bls12_381.params.G1b)); // y² = x³ + b
                 let y = Fp.sqrt(right);
                 if (!y)
                     throw new Error('Invalid compressed G1 point');
-                const aflag = bitGet(compressedValue, C_BIT_POS);
-                if ((y * _2n) / P !== aflag)
+                if ((y * _2n) / P !== BigInt(sort))
                     y = Fp.neg(y);
                 return { x: Fp.create(x), y: Fp.create(y) };
             }
-            else if (bytes.length === 96) {
+            else if (value.length === 96 && !compressed) {
                 // Check if the infinity flag is set
-                if ((bytes[0] & (1 << 6)) !== 0)
+                const x = bytesToNumberBE(value.subarray(0, Fp.BYTES));
+                const y = bytesToNumberBE(value.subarray(Fp.BYTES));
+                if (infinity) {
+                    if (x !== _0n || y !== _0n)
+                        throw new Error('G1: non-empty point at infinity');
                     return bls12_381.G1.ProjectivePoint.ZERO.toAffine();
-                const x = bytesToNumberBE(bytes.subarray(0, Fp.BYTES));
-                const y = bytesToNumberBE(bytes.subarray(Fp.BYTES));
+                }
                 return { x: Fp.create(x), y: Fp.create(y) };
             }
             else {
@@ -978,10 +1012,8 @@ export const bls12_381 = bls({
                 if (isZero)
                     return COMPRESSED_ZERO.slice();
                 const P = Fp.ORDER;
-                let num;
-                num = bitSet(x, C_BIT_POS, Boolean((y * _2n) / P)); // set aflag
-                num = bitSet(num, S_BIT_POS, true);
-                return numberToBytesBE(num, Fp.BYTES);
+                const sort = Boolean((y * _2n) / P);
+                return setMask(numberToBytesBE(x, Fp.BYTES), { compressed: true, sort });
             }
             else {
                 if (isZero) {
@@ -994,6 +1026,33 @@ export const bls12_381 = bls({
                 }
             }
         },
+        ShortSignature: {
+            fromHex(hex) {
+                const { infinity, sort, value } = parseMask(ensureBytes('signatureHex', hex, 48));
+                const P = Fp.ORDER;
+                const compressedValue = bytesToNumberBE(value);
+                // Zero
+                if (infinity)
+                    return bls12_381.G1.ProjectivePoint.ZERO;
+                const x = Fp.create(compressedValue & Fp.MASK);
+                const right = Fp.add(Fp.pow(x, _3n), Fp.create(bls12_381.params.G1b)); // y² = x³ + b
+                let y = Fp.sqrt(right);
+                if (!y)
+                    throw new Error('Invalid compressed G1 point');
+                const aflag = BigInt(sort);
+                if ((y * _2n) / P !== aflag)
+                    y = Fp.neg(y);
+                const point = bls12_381.G1.ProjectivePoint.fromAffine({ x, y });
+                point.assertValidity();
+                return point;
+            },
+            toRawBytes(point) {
+                return signatureG1ToRawBytes(point);
+            },
+            toHex(point) {
+                return bytesToHex(signatureG1ToRawBytes(point));
+            },
+        },
     },
     // G2 is the order-q subgroup of E2(Fp²) : y² = x³+4(1+√−1),
     // where Fp2 is Fp[√−1]/(x2+1). #E2(Fp2 ) = h2q, where
@@ -1053,45 +1112,45 @@ export const bls12_381 = bls({
             return Q; // [x²-x-1]P + [x-1]Ψ(P) + Ψ²(2P)
         },
         fromBytes: (bytes) => {
-            bytes = bytes.slice();
-            const m_byte = bytes[0] & 0xe0;
-            if (m_byte === 0x20 || m_byte === 0x60 || m_byte === 0xe0) {
-                throw new Error('Invalid encoding flag: ' + m_byte);
+            const { compressed, infinity, sort, value } = parseMask(bytes);
+            if ((!compressed && !infinity && sort) || // 00100000
+                (!compressed && infinity && sort) || // 01100000
+                (sort && infinity && compressed) // 11100000
+            ) {
+                throw new Error('Invalid encoding flag: ' + (bytes[0] & 224));
             }
-            const bitC = m_byte & 0x80; // compression bit
-            const bitI = m_byte & 0x40; // point at infinity bit
-            const bitS = m_byte & 0x20; // sign bit
             const L = Fp.BYTES;
             const slc = (b, from, to) => bytesToNumberBE(b.slice(from, to));
-            if (bytes.length === 96 && bitC) {
+            if (value.length === 96 && compressed) {
                 const b = bls12_381.params.G2b;
                 const P = Fp.ORDER;
-                bytes[0] = bytes[0] & 0x1f; // clear flags
-                if (bitI) {
+                if (infinity) {
                     // check that all bytes are 0
-                    if (bytes.reduce((p, c) => (p !== 0 ? c + 1 : c), 0) > 0) {
+                    if (value.reduce((p, c) => (p !== 0 ? c + 1 : c), 0) > 0) {
                         throw new Error('Invalid compressed G2 point');
                     }
                     return { x: Fp2.ZERO, y: Fp2.ZERO };
                 }
-                const x_1 = slc(bytes, 0, L);
-                const x_0 = slc(bytes, L, 2 * L);
+                const x_1 = slc(value, 0, L);
+                const x_0 = slc(value, L, 2 * L);
                 const x = Fp2.create({ c0: Fp.create(x_0), c1: Fp.create(x_1) });
                 const right = Fp2.add(Fp2.pow(x, _3n), b); // y² = x³ + 4 * (u+1) = x³ + b
                 let y = Fp2.sqrt(right);
                 const Y_bit = y.c1 === _0n ? (y.c0 * _2n) / P : (y.c1 * _2n) / P ? _1n : _0n;
-                y = bitS > 0 && Y_bit > 0 ? y : Fp2.neg(y);
+                y = sort && Y_bit > 0 ? y : Fp2.neg(y);
                 return { x, y };
             }
-            else if (bytes.length === 192 && !bitC) {
-                // Check if the infinity flag is set
-                if ((bytes[0] & (1 << 6)) !== 0) {
+            else if (value.length === 192 && !compressed) {
+                if (infinity) {
+                    if (value.reduce((p, c) => (p !== 0 ? c + 1 : c), 0) > 0) {
+                        throw new Error('Invalid uncompressed G2 point');
+                    }
                     return { x: Fp2.ZERO, y: Fp2.ZERO };
                 }
-                const x1 = slc(bytes, 0, L);
-                const x0 = slc(bytes, L, 2 * L);
-                const y1 = slc(bytes, 2 * L, 3 * L);
-                const y0 = slc(bytes, 3 * L, 4 * L);
+                const x1 = slc(value, 0, L);
+                const x0 = slc(value, L, 2 * L);
+                const y1 = slc(value, 2 * L, 3 * L);
+                const y0 = slc(value, 3 * L, 4 * L);
                 return { x: Fp2.fromBigTuple([x0, x1]), y: Fp2.fromBigTuple([y0, y1]) };
             }
             else {
@@ -1106,10 +1165,7 @@ export const bls12_381 = bls({
                 if (isZero)
                     return concatB(COMPRESSED_ZERO, numberToBytesBE(_0n, len));
                 const flag = Boolean(y.c1 === _0n ? (y.c0 * _2n) / P : (y.c1 * _2n) / P);
-                // set compressed & sign bits (looks like different offsets than for G1/Fp?)
-                let x_1 = bitSet(x.c1, C_BIT_POS, flag);
-                x_1 = bitSet(x_1, S_BIT_POS, true);
-                return concatB(numberToBytesBE(x_1, len), numberToBytesBE(x.c0, len));
+                return concatB(setMask(numberToBytesBE(x.c1, len), { compressed: true, sort: flag }), numberToBytesBE(x.c0, len));
             }
             else {
                 if (isZero)
@@ -1122,16 +1178,15 @@ export const bls12_381 = bls({
         Signature: {
             // TODO: Optimize, it's very slow because of sqrt.
             fromHex(hex) {
-                hex = ensureBytes('signatureHex', hex);
+                const { infinity, sort, value } = parseMask(ensureBytes('signatureHex', hex));
                 const P = Fp.ORDER;
                 const half = hex.length / 2;
                 if (half !== 48 && half !== 96)
                     throw new Error('Invalid compressed signature length, must be 96 or 192');
-                const z1 = bytesToNumberBE(hex.slice(0, half));
-                const z2 = bytesToNumberBE(hex.slice(half));
+                const z1 = bytesToNumberBE(value.slice(0, half));
+                const z2 = bytesToNumberBE(value.slice(half));
                 // Indicates the infinity point
-                const bflag1 = bitGet(z1, I_BIT_POS);
-                if (bflag1 === _1n)
+                if (infinity)
                     return bls12_381.G2.ProjectivePoint.ZERO;
                 const x1 = Fp.create(z1 & Fp.MASK);
                 const x2 = Fp.create(z2);
@@ -1144,7 +1199,7 @@ export const bls12_381 = bls({
                 // Choose the y whose leftmost bit of the imaginary part is equal to the a_flag1
                 // If y1 happens to be zero, then use the bit of y0
                 const { re: y0, im: y1 } = Fp2.reim(y);
-                const aflag1 = bitGet(z1, 381);
+                const aflag1 = BigInt(sort);
                 const isGreater = y1 > _0n && (y1 * _2n) / P !== aflag1;
                 const isZero = y1 === _0n && (y0 * _2n) / P !== aflag1;
                 if (isGreater || isZero)
@@ -1162,7 +1217,7 @@ export const bls12_381 = bls({
         },
     },
     params: {
-        x: BLS_X,
+        x: BLS_X, // The BLS parameter x for BLS12-381
         r: Fr.ORDER, // order; z⁴ − z² + 1; CURVE.n from other curves
     },
     htfDefaults,