"use strict"; Object.defineProperty(exports, "__esModule", { value: true }); exports.isNegativeLE = void 0; exports.mod = mod; exports.pow = pow; exports.pow2 = pow2; exports.invert = invert; exports.tonelliShanks = tonelliShanks; exports.FpSqrt = FpSqrt; exports.validateField = validateField; exports.FpPow = FpPow; exports.FpInvertBatch = FpInvertBatch; exports.FpDiv = FpDiv; exports.FpLegendre = FpLegendre; exports.FpIsSquare = FpIsSquare; exports.nLength = nLength; exports.Field = Field; exports.FpSqrtOdd = FpSqrtOdd; exports.FpSqrtEven = FpSqrtEven; exports.hashToPrivateScalar = hashToPrivateScalar; exports.getFieldBytesLength = getFieldBytesLength; exports.getMinHashLength = getMinHashLength; exports.mapHashToField = mapHashToField; /** * Utils for modular division and fields. * Field over 11 is a finite (Galois) field is integer number operations `mod 11`. * There is no division: it is replaced by modular multiplicative inverse. * @module */ /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */ const utils_ts_1 = require("../utils.js"); // prettier-ignore const _0n = BigInt(0), _1n = BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3); // prettier-ignore const _4n = /* @__PURE__ */ BigInt(4), _5n = /* @__PURE__ */ BigInt(5), _7n = /* @__PURE__ */ BigInt(7); // prettier-ignore const _8n = /* @__PURE__ */ BigInt(8), _9n = /* @__PURE__ */ BigInt(9), _16n = /* @__PURE__ */ BigInt(16); // Calculates a modulo b function mod(a, b) { const result = a % b; return result >= _0n ? result : b + result; } /** * Efficiently raise num to power and do modular division. * Unsafe in some contexts: uses ladder, so can expose bigint bits. * @example * pow(2n, 6n, 11n) // 64n % 11n == 9n */ function pow(num, power, modulo) { return FpPow(Field(modulo), num, power); } /** Does `x^(2^power)` mod p. `pow2(30, 4)` == `30^(2^4)` */ function pow2(x, power, modulo) { let res = x; while (power-- > _0n) { res *= res; res %= modulo; } return res; } /** * Inverses number over modulo. * Implemented using [Euclidean GCD](https://brilliant.org/wiki/extended-euclidean-algorithm/). */ function invert(number, modulo) { if (number === _0n) throw new Error('invert: expected non-zero number'); if (modulo <= _0n) throw new Error('invert: expected positive modulus, got ' + modulo); // Fermat's little theorem "CT-like" version inv(n) = n^(m-2) mod m is 30x slower. let a = mod(number, modulo); let b = modulo; // prettier-ignore let x = _0n, y = _1n, u = _1n, v = _0n; while (a !== _0n) { // JIT applies optimization if those two lines follow each other const q = b / a; const r = b % a; const m = x - u * q; const n = y - v * q; // prettier-ignore b = a, a = r, x = u, y = v, u = m, v = n; } const gcd = b; if (gcd !== _1n) throw new Error('invert: does not exist'); return mod(x, modulo); } function assertIsSquare(Fp, root, n) { if (!Fp.eql(Fp.sqr(root), n)) throw new Error('Cannot find square root'); } // Not all roots are possible! Example which will throw: // const NUM = // n = 72057594037927816n; // Fp = Field(BigInt('0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab')); function sqrt3mod4(Fp, n) { const p1div4 = (Fp.ORDER + _1n) / _4n; const root = Fp.pow(n, p1div4); assertIsSquare(Fp, root, n); return root; } function sqrt5mod8(Fp, n) { const p5div8 = (Fp.ORDER - _5n) / _8n; const n2 = Fp.mul(n, _2n); const v = Fp.pow(n2, p5div8); const nv = Fp.mul(n, v); const i = Fp.mul(Fp.mul(nv, _2n), v); const root = Fp.mul(nv, Fp.sub(i, Fp.ONE)); assertIsSquare(Fp, root, n); return root; } // Based on RFC9380, Kong algorithm // prettier-ignore function sqrt9mod16(P) { const Fp_ = Field(P); const tn = tonelliShanks(P); const c1 = tn(Fp_, Fp_.neg(Fp_.ONE)); // 1. c1 = sqrt(-1) in F, i.e., (c1^2) == -1 in F const c2 = tn(Fp_, c1); // 2. c2 = sqrt(c1) in F, i.e., (c2^2) == c1 in F const c3 = tn(Fp_, Fp_.neg(c1)); // 3. c3 = sqrt(-c1) in F, i.e., (c3^2) == -c1 in F const c4 = (P + _7n) / _16n; // 4. c4 = (q + 7) / 16 # Integer arithmetic return (Fp, n) => { let tv1 = Fp.pow(n, c4); // 1. tv1 = x^c4 let tv2 = Fp.mul(tv1, c1); // 2. tv2 = c1 * tv1 const tv3 = Fp.mul(tv1, c2); // 3. tv3 = c2 * tv1 const tv4 = Fp.mul(tv1, c3); // 4. tv4 = c3 * tv1 const e1 = Fp.eql(Fp.sqr(tv2), n); // 5. e1 = (tv2^2) == x const e2 = Fp.eql(Fp.sqr(tv3), n); // 6. e2 = (tv3^2) == x tv1 = Fp.cmov(tv1, tv2, e1); // 7. tv1 = CMOV(tv1, tv2, e1) # Select tv2 if (tv2^2) == x tv2 = Fp.cmov(tv4, tv3, e2); // 8. tv2 = CMOV(tv4, tv3, e2) # Select tv3 if (tv3^2) == x const e3 = Fp.eql(Fp.sqr(tv2), n); // 9. e3 = (tv2^2) == x const root = Fp.cmov(tv1, tv2, e3); // 10. z = CMOV(tv1, tv2, e3) # Select sqrt from tv1 & tv2 assertIsSquare(Fp, root, n); return root; }; } /** * Tonelli-Shanks square root search algorithm. * 1. https://eprint.iacr.org/2012/685.pdf (page 12) * 2. Square Roots from 1; 24, 51, 10 to Dan Shanks * @param P field order * @returns function that takes field Fp (created from P) and number n */ function tonelliShanks(P) { // Initialization (precomputation). // Caching initialization could boost perf by 7%. if (P < _3n) throw new Error('sqrt is not defined for small field'); // Factor P - 1 = Q * 2^S, where Q is odd let Q = P - _1n; let S = 0; while (Q % _2n === _0n) { Q /= _2n; S++; } // Find the first quadratic non-residue Z >= 2 let Z = _2n; const _Fp = Field(P); while (FpLegendre(_Fp, Z) === 1) { // Basic primality test for P. After x iterations, chance of // not finding quadratic non-residue is 2^x, so 2^1000. if (Z++ > 1000) throw new Error('Cannot find square root: probably non-prime P'); } // Fast-path; usually done before Z, but we do "primality test". if (S === 1) return sqrt3mod4; // Slow-path // TODO: test on Fp2 and others let cc = _Fp.pow(Z, Q); // c = z^Q const Q1div2 = (Q + _1n) / _2n; return function tonelliSlow(Fp, n) { if (Fp.is0(n)) return n; // Check if n is a quadratic residue using Legendre symbol if (FpLegendre(Fp, n) !== 1) throw new Error('Cannot find square root'); // Initialize variables for the main loop let M = S; let c = Fp.mul(Fp.ONE, cc); // c = z^Q, move cc from field _Fp into field Fp let t = Fp.pow(n, Q); // t = n^Q, first guess at the fudge factor let R = Fp.pow(n, Q1div2); // R = n^((Q+1)/2), first guess at the square root // Main loop // while t != 1 while (!Fp.eql(t, Fp.ONE)) { if (Fp.is0(t)) return Fp.ZERO; // if t=0 return R=0 let i = 1; // Find the smallest i >= 1 such that t^(2^i) ≡ 1 (mod P) let t_tmp = Fp.sqr(t); // t^(2^1) while (!Fp.eql(t_tmp, Fp.ONE)) { i++; t_tmp = Fp.sqr(t_tmp); // t^(2^2)... if (i === M) throw new Error('Cannot find square root'); } // Calculate the exponent for b: 2^(M - i - 1) const exponent = _1n << BigInt(M - i - 1); // bigint is important const b = Fp.pow(c, exponent); // b = 2^(M - i - 1) // Update variables M = i; c = Fp.sqr(b); // c = b^2 t = Fp.mul(t, c); // t = (t * b^2) R = Fp.mul(R, b); // R = R*b } return R; }; } /** * Square root for a finite field. Will try optimized versions first: * * 1. P ≡ 3 (mod 4) * 2. P ≡ 5 (mod 8) * 3. P ≡ 9 (mod 16) * 4. Tonelli-Shanks algorithm * * Different algorithms can give different roots, it is up to user to decide which one they want. * For example there is FpSqrtOdd/FpSqrtEven to choice root based on oddness (used for hash-to-curve). */ function FpSqrt(P) { // P ≡ 3 (mod 4) => √n = n^((P+1)/4) if (P % _4n === _3n) return sqrt3mod4; // P ≡ 5 (mod 8) => Atkin algorithm, page 10 of https://eprint.iacr.org/2012/685.pdf if (P % _8n === _5n) return sqrt5mod8; // P ≡ 9 (mod 16) => Kong algorithm, page 11 of https://eprint.iacr.org/2012/685.pdf (algorithm 4) if (P % _16n === _9n) return sqrt9mod16(P); // Tonelli-Shanks algorithm return tonelliShanks(P); } // Little-endian check for first LE bit (last BE bit); const isNegativeLE = (num, modulo) => (mod(num, modulo) & _1n) === _1n; exports.isNegativeLE = isNegativeLE; // prettier-ignore const FIELD_FIELDS = [ 'create', 'isValid', 'is0', 'neg', 'inv', 'sqrt', 'sqr', 'eql', 'add', 'sub', 'mul', 'pow', 'div', 'addN', 'subN', 'mulN', 'sqrN' ]; function validateField(field) { const initial = { ORDER: 'bigint', MASK: 'bigint', BYTES: 'number', BITS: 'number', }; const opts = FIELD_FIELDS.reduce((map, val) => { map[val] = 'function'; return map; }, initial); (0, utils_ts_1._validateObject)(field, opts); // const max = 16384; // if (field.BYTES < 1 || field.BYTES > max) throw new Error('invalid field'); // if (field.BITS < 1 || field.BITS > 8 * max) throw new Error('invalid field'); return field; } // Generic field functions /** * Same as `pow` but for Fp: non-constant-time. * Unsafe in some contexts: uses ladder, so can expose bigint bits. */ function FpPow(Fp, num, power) { if (power < _0n) throw new Error('invalid exponent, negatives unsupported'); if (power === _0n) return Fp.ONE; if (power === _1n) return num; let p = Fp.ONE; let d = num; while (power > _0n) { if (power & _1n) p = Fp.mul(p, d); d = Fp.sqr(d); power >>= _1n; } return p; } /** * Efficiently invert an array of Field elements. * Exception-free. Will return `undefined` for 0 elements. * @param passZero map 0 to 0 (instead of undefined) */ function FpInvertBatch(Fp, nums, passZero = false) { const inverted = new Array(nums.length).fill(passZero ? Fp.ZERO : undefined); // Walk from first to last, multiply them by each other MOD p const multipliedAcc = nums.reduce((acc, num, i) => { if (Fp.is0(num)) return acc; inverted[i] = acc; return Fp.mul(acc, num); }, Fp.ONE); // Invert last element const invertedAcc = Fp.inv(multipliedAcc); // Walk from last to first, multiply them by inverted each other MOD p nums.reduceRight((acc, num, i) => { if (Fp.is0(num)) return acc; inverted[i] = Fp.mul(acc, inverted[i]); return Fp.mul(acc, num); }, invertedAcc); return inverted; } // TODO: remove function FpDiv(Fp, lhs, rhs) { return Fp.mul(lhs, typeof rhs === 'bigint' ? invert(rhs, Fp.ORDER) : Fp.inv(rhs)); } /** * Legendre symbol. * Legendre constant is used to calculate Legendre symbol (a | p) * which denotes the value of a^((p-1)/2) (mod p). * * * (a | p) ≡ 1 if a is a square (mod p), quadratic residue * * (a | p) ≡ -1 if a is not a square (mod p), quadratic non residue * * (a | p) ≡ 0 if a ≡ 0 (mod p) */ function FpLegendre(Fp, n) { // We can use 3rd argument as optional cache of this value // but seems unneeded for now. The operation is very fast. const p1mod2 = (Fp.ORDER - _1n) / _2n; const powered = Fp.pow(n, p1mod2); const yes = Fp.eql(powered, Fp.ONE); const zero = Fp.eql(powered, Fp.ZERO); const no = Fp.eql(powered, Fp.neg(Fp.ONE)); if (!yes && !zero && !no) throw new Error('invalid Legendre symbol result'); return yes ? 1 : zero ? 0 : -1; } // This function returns True whenever the value x is a square in the field F. function FpIsSquare(Fp, n) { const l = FpLegendre(Fp, n); return l === 1; } // CURVE.n lengths function nLength(n, nBitLength) { // Bit size, byte size of CURVE.n if (nBitLength !== undefined) (0, utils_ts_1.anumber)(nBitLength); const _nBitLength = nBitLength !== undefined ? nBitLength : n.toString(2).length; const nByteLength = Math.ceil(_nBitLength / 8); return { nBitLength: _nBitLength, nByteLength }; } /** * Creates a finite field. Major performance optimizations: * * 1. Denormalized operations like mulN instead of mul. * * 2. Identical object shape: never add or remove keys. * * 3. `Object.freeze`. * Fragile: always run a benchmark on a change. * Security note: operations don't check 'isValid' for all elements for performance reasons, * it is caller responsibility to check this. * This is low-level code, please make sure you know what you're doing. * * Note about field properties: * * CHARACTERISTIC p = prime number, number of elements in main subgroup. * * ORDER q = similar to cofactor in curves, may be composite `q = p^m`. * * @param ORDER field order, probably prime, or could be composite * @param bitLen how many bits the field consumes * @param isLE (default: false) if encoding / decoding should be in little-endian * @param redef optional faster redefinitions of sqrt and other methods */ function Field(ORDER, bitLenOrOpts, // TODO: use opts only in v2? isLE = false, opts = {}) { if (ORDER <= _0n) throw new Error('invalid field: expected ORDER > 0, got ' + ORDER); let _nbitLength = undefined; let _sqrt = undefined; let modFromBytes = false; let allowedLengths = undefined; if (typeof bitLenOrOpts === 'object' && bitLenOrOpts != null) { if (opts.sqrt || isLE) throw new Error('cannot specify opts in two arguments'); const _opts = bitLenOrOpts; if (_opts.BITS) _nbitLength = _opts.BITS; if (_opts.sqrt) _sqrt = _opts.sqrt; if (typeof _opts.isLE === 'boolean') isLE = _opts.isLE; if (typeof _opts.modFromBytes === 'boolean') modFromBytes = _opts.modFromBytes; allowedLengths = _opts.allowedLengths; } else { if (typeof bitLenOrOpts === 'number') _nbitLength = bitLenOrOpts; if (opts.sqrt) _sqrt = opts.sqrt; } const { nBitLength: BITS, nByteLength: BYTES } = nLength(ORDER, _nbitLength); if (BYTES > 2048) throw new Error('invalid field: expected ORDER of <= 2048 bytes'); let sqrtP; // cached sqrtP const f = Object.freeze({ ORDER, isLE, BITS, BYTES, MASK: (0, utils_ts_1.bitMask)(BITS), ZERO: _0n, ONE: _1n, allowedLengths: allowedLengths, create: (num) => mod(num, ORDER), isValid: (num) => { if (typeof num !== 'bigint') throw new Error('invalid field element: expected bigint, got ' + typeof num); return _0n <= num && num < ORDER; // 0 is valid element, but it's not invertible }, is0: (num) => num === _0n, // is valid and invertible isValidNot0: (num) => !f.is0(num) && f.isValid(num), isOdd: (num) => (num & _1n) === _1n, neg: (num) => mod(-num, ORDER), eql: (lhs, rhs) => lhs === rhs, sqr: (num) => mod(num * num, ORDER), add: (lhs, rhs) => mod(lhs + rhs, ORDER), sub: (lhs, rhs) => mod(lhs - rhs, ORDER), mul: (lhs, rhs) => mod(lhs * rhs, ORDER), pow: (num, power) => FpPow(f, num, power), div: (lhs, rhs) => mod(lhs * invert(rhs, ORDER), ORDER), // Same as above, but doesn't normalize sqrN: (num) => num * num, addN: (lhs, rhs) => lhs + rhs, subN: (lhs, rhs) => lhs - rhs, mulN: (lhs, rhs) => lhs * rhs, inv: (num) => invert(num, ORDER), sqrt: _sqrt || ((n) => { if (!sqrtP) sqrtP = FpSqrt(ORDER); return sqrtP(f, n); }), toBytes: (num) => (isLE ? (0, utils_ts_1.numberToBytesLE)(num, BYTES) : (0, utils_ts_1.numberToBytesBE)(num, BYTES)), fromBytes: (bytes, skipValidation = true) => { if (allowedLengths) { if (!allowedLengths.includes(bytes.length) || bytes.length > BYTES) { throw new Error('Field.fromBytes: expected ' + allowedLengths + ' bytes, got ' + bytes.length); } const padded = new Uint8Array(BYTES); // isLE add 0 to right, !isLE to the left. padded.set(bytes, isLE ? 0 : padded.length - bytes.length); bytes = padded; } if (bytes.length !== BYTES) throw new Error('Field.fromBytes: expected ' + BYTES + ' bytes, got ' + bytes.length); let scalar = isLE ? (0, utils_ts_1.bytesToNumberLE)(bytes) : (0, utils_ts_1.bytesToNumberBE)(bytes); if (modFromBytes) scalar = mod(scalar, ORDER); if (!skipValidation) if (!f.isValid(scalar)) throw new Error('invalid field element: outside of range 0..ORDER'); // NOTE: we don't validate scalar here, please use isValid. This done such way because some // protocol may allow non-reduced scalar that reduced later or changed some other way. return scalar; }, // TODO: we don't need it here, move out to separate fn invertBatch: (lst) => FpInvertBatch(f, lst), // We can't move this out because Fp6, Fp12 implement it // and it's unclear what to return in there. cmov: (a, b, c) => (c ? b : a), }); return Object.freeze(f); } // Generic random scalar, we can do same for other fields if via Fp2.mul(Fp2.ONE, Fp2.random)? // This allows unsafe methods like ignore bias or zero. These unsafe, but often used in different protocols (if deterministic RNG). // which mean we cannot force this via opts. // Not sure what to do with randomBytes, we can accept it inside opts if wanted. // Probably need to export getMinHashLength somewhere? // random(bytes?: Uint8Array, unsafeAllowZero = false, unsafeAllowBias = false) { // const LEN = !unsafeAllowBias ? getMinHashLength(ORDER) : BYTES; // if (bytes === undefined) bytes = randomBytes(LEN); // _opts.randomBytes? // const num = isLE ? bytesToNumberLE(bytes) : bytesToNumberBE(bytes); // // `mod(x, 11)` can sometimes produce 0. `mod(x, 10) + 1` is the same, but no 0 // const reduced = unsafeAllowZero ? mod(num, ORDER) : mod(num, ORDER - _1n) + _1n; // return reduced; // }, function FpSqrtOdd(Fp, elm) { if (!Fp.isOdd) throw new Error("Field doesn't have isOdd"); const root = Fp.sqrt(elm); return Fp.isOdd(root) ? root : Fp.neg(root); } function FpSqrtEven(Fp, elm) { if (!Fp.isOdd) throw new Error("Field doesn't have isOdd"); const root = Fp.sqrt(elm); return Fp.isOdd(root) ? Fp.neg(root) : root; } /** * "Constant-time" private key generation utility. * Same as mapKeyToField, but accepts less bytes (40 instead of 48 for 32-byte field). * Which makes it slightly more biased, less secure. * @deprecated use `mapKeyToField` instead */ function hashToPrivateScalar(hash, groupOrder, isLE = false) { hash = (0, utils_ts_1.ensureBytes)('privateHash', hash); const hashLen = hash.length; const minLen = nLength(groupOrder).nByteLength + 8; if (minLen < 24 || hashLen < minLen || hashLen > 1024) throw new Error('hashToPrivateScalar: expected ' + minLen + '-1024 bytes of input, got ' + hashLen); const num = isLE ? (0, utils_ts_1.bytesToNumberLE)(hash) : (0, utils_ts_1.bytesToNumberBE)(hash); return mod(num, groupOrder - _1n) + _1n; } /** * Returns total number of bytes consumed by the field element. * For example, 32 bytes for usual 256-bit weierstrass curve. * @param fieldOrder number of field elements, usually CURVE.n * @returns byte length of field */ function getFieldBytesLength(fieldOrder) { if (typeof fieldOrder !== 'bigint') throw new Error('field order must be bigint'); const bitLength = fieldOrder.toString(2).length; return Math.ceil(bitLength / 8); } /** * Returns minimal amount of bytes that can be safely reduced * by field order. * Should be 2^-128 for 128-bit curve such as P256. * @param fieldOrder number of field elements, usually CURVE.n * @returns byte length of target hash */ function getMinHashLength(fieldOrder) { const length = getFieldBytesLength(fieldOrder); return length + Math.ceil(length / 2); } /** * "Constant-time" private key generation utility. * Can take (n + n/2) or more bytes of uniform input e.g. from CSPRNG or KDF * and convert them into private scalar, with the modulo bias being negligible. * Needs at least 48 bytes of input for 32-byte private key. * https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/ * FIPS 186-5, A.2 https://csrc.nist.gov/publications/detail/fips/186/5/final * RFC 9380, https://www.rfc-editor.org/rfc/rfc9380#section-5 * @param hash hash output from SHA3 or a similar function * @param groupOrder size of subgroup - (e.g. secp256k1.CURVE.n) * @param isLE interpret hash bytes as LE num * @returns valid private scalar */ function mapHashToField(key, fieldOrder, isLE = false) { const len = key.length; const fieldLen = getFieldBytesLength(fieldOrder); const minLen = getMinHashLength(fieldOrder); // No small numbers: need to understand bias story. No huge numbers: easier to detect JS timings. if (len < 16 || len < minLen || len > 1024) throw new Error('expected ' + minLen + '-1024 bytes of input, got ' + len); const num = isLE ? (0, utils_ts_1.bytesToNumberLE)(key) : (0, utils_ts_1.bytesToNumberBE)(key); // `mod(x, 11)` can sometimes produce 0. `mod(x, 10) + 1` is the same, but no 0 const reduced = mod(num, fieldOrder - _1n) + _1n; return isLE ? (0, utils_ts_1.numberToBytesLE)(reduced, fieldLen) : (0, utils_ts_1.numberToBytesBE)(reduced, fieldLen); } //# sourceMappingURL=modular.js.map