common: add utilities for curves. (#602)

Author: dajiaji

packages/common/mod.ts

@@ -51,3 +51,7 @@ export {
 
 export { hmac } from "./src/hash/hmac.ts";
 export { sha256, sha384, sha512 } from "./src/hash/sha2.ts";
+
+export { type DST_SCALAR } from "./src/curve/hash-to-curve.ts";
+export { mod, pow2 } from "./src/curve/modular.ts";
+export { montgomery, type MontgomeryECDH } from "./src/curve/montgomery.ts";

packages/common/src/curve/curve.ts

@@ -0,0 +1,42 @@
+/**
+ * This file is based on noble-curves (https://github.com/paulmillr/noble-curves).
+ *
+ * noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com)
+ *
+ * The original file is located at:
+ * https://github.com/paulmillr/noble-curves/blob/b9d49d2b41d550571a0c5be443ecb62109fa3373/src/abstract/curve.ts
+ */
+
+/**
+ * Methods for elliptic curve multiplication by scalars.
+ * Contains wNAF, pippenger.
+ * @module
+ */
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import type { Signer } from "../utils/noble.ts";
+
+// import { Field, FpInvertBatch, type IField, validateField } from "./modular.ts";
+
+export interface CurveLengths {
+  secretKey?: number;
+  publicKey?: number;
+  publicKeyUncompressed?: number;
+  publicKeyHasPrefix?: boolean;
+  signature?: number;
+  seed?: number;
+}
+
+type KeygenFn = (
+  seed?: Uint8Array,
+  isCompressed?: boolean,
+) => { secretKey: Uint8Array; publicKey: Uint8Array };
+export function createKeygen(
+  // deno-lint-ignore ban-types
+  randomSecretKey: Function,
+  getPublicKey: Signer["getPublicKey"],
+): KeygenFn {
+  return function keygen(seed?: Uint8Array) {
+    const secretKey = randomSecretKey(seed);
+    return { secretKey, publicKey: getPublicKey(secretKey) };
+  };
+}

packages/common/src/curve/hash-to-curve.ts

@@ -0,0 +1,19 @@
+/**
+ * This file is based on noble-curves (https://github.com/paulmillr/noble-curves).
+ *
+ * noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com)
+ *
+ * The original file is located at:
+ * https://github.com/paulmillr/noble-curves/blob/b9d49d2b41d550571a0c5be443ecb62109fa3373/src/abstract/hash-to-curve.ts
+ */
+
+/**
+ * hash-to-curve from RFC 9380.
+ * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F.
+ * https://www.rfc-editor.org/rfc/rfc9380
+ * @module
+ */
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import { asciiToBytes } from "../utils/noble.ts";
+
+export const DST_SCALAR: Uint8Array = asciiToBytes("HashToScalar-");

packages/common/src/curve/modular.ts

@@ -0,0 +1,36 @@
+/**
+ * This file is based on noble-curves (https://github.com/paulmillr/noble-curves).
+ *
+ * noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com)
+ *
+ * The original file is located at:
+ * https://github.com/paulmillr/noble-curves/blob/b9d49d2b41d550571a0c5be443ecb62109fa3373/src/abstract/modular.ts
+ */
+
+/**
+ * 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) */
+
+// Numbers aren't used in x25519 / x448 builds
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0);
+
+// Calculates a modulo b
+export function mod(a: bigint, b: bigint): bigint {
+  const result = a % b;
+  return result >= _0n ? result : b + result;
+}
+
+/** Does `x^(2^power)` mod p. `pow2(30, 4)` == `30^(2^4)` */
+export function pow2(x: bigint, power: bigint, modulo: bigint): bigint {
+  let res = x;
+  while (power-- > _0n) {
+    res *= res;
+    res %= modulo;
+  }
+  return res;
+}

packages/common/src/curve/montgomery.ts

@@ -0,0 +1,210 @@
+/**
+ * This file is based on noble-curves (https://github.com/paulmillr/noble-curves).
+ *
+ * noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com)
+ *
+ * The original file is located at:
+ * https://github.com/paulmillr/noble-curves/blob/b9d49d2b41d550571a0c5be443ecb62109fa3373/src/abstract/montgomery.ts
+ */
+
+/**
+ * Montgomery curve methods. It's not really whole montgomery curve,
+ * just bunch of very specific methods for X25519 / X448 from
+ * [RFC 7748](https://www.rfc-editor.org/rfc/rfc7748)
+ * @module
+ */
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import {
+  abytes,
+  aInRange,
+  bytesToNumberLE,
+  copyBytes,
+  type CryptoKeys,
+  numberToBytesLE,
+  randomBytesAsync,
+  validateObject,
+} from "../utils/noble.ts";
+import { createKeygen, type CurveLengths } from "./curve.ts";
+import { mod } from "./modular.ts";
+
+const _0n = BigInt(0);
+const _1n = BigInt(1);
+const _2n = BigInt(2);
+
+export type CurveType = {
+  P: bigint; // finite field prime
+  type: "x25519" | "x448";
+  adjustScalarBytes: (bytes: Uint8Array) => Uint8Array;
+  powPminus2: (x: bigint) => bigint;
+  randomBytes?: (bytesLength?: number) => Promise<Uint8Array>;
+};
+
+export type MontgomeryECDH = {
+  scalarMult: (scalar: Uint8Array, u: Uint8Array) => Uint8Array;
+  scalarMultBase: (scalar: Uint8Array) => Uint8Array;
+  getSharedSecret: (
+    secretKeyA: Uint8Array,
+    publicKeyB: Uint8Array,
+  ) => Uint8Array;
+  getPublicKey: (secretKey: Uint8Array) => Uint8Array;
+  utils: {
+    randomSecretKey: (seed?: Uint8Array) => Promise<Uint8Array>;
+  };
+  GuBytes: Uint8Array;
+  lengths: CurveLengths;
+  keygen: (
+    seed?: Uint8Array,
+  ) => { secretKey: Uint8Array; publicKey: Uint8Array };
+};
+
+function validateOpts(curve: CurveType) {
+  validateObject(curve, {
+    adjustScalarBytes: "function",
+    powPminus2: "function",
+  });
+  return Object.freeze({ ...curve } as const);
+}
+
+export function montgomery(curveDef: CurveType): MontgomeryECDH {
+  const CURVE = validateOpts(curveDef);
+  const { P, type, adjustScalarBytes, powPminus2, randomBytes: rand } = CURVE;
+  const is25519 = type === "x25519";
+  if (!is25519 && type !== "x448") throw new Error("invalid type");
+  const randomBytes_ = rand || randomBytesAsync;
+
+  const montgomeryBits = is25519 ? 255 : 448;
+  const fieldLen = is25519 ? 32 : 56;
+  const Gu = is25519 ? BigInt(9) : BigInt(5);
+  // RFC 7748 #5:
+  // The constant a24 is (486662 - 2) / 4 = 121665 for curve25519/X25519 and
+  // (156326 - 2) / 4 = 39081 for curve448/X448
+  // const a = is25519 ? 156326n : 486662n;
+  const a24 = is25519 ? BigInt(121665) : BigInt(39081);
+  // RFC: x25519 "the resulting integer is of the form 2^254 plus
+  // eight times a value between 0 and 2^251 - 1 (inclusive)"
+  // x448: "2^447 plus four times a value between 0 and 2^445 - 1 (inclusive)"
+  const minScalar = is25519 ? _2n ** BigInt(254) : _2n ** BigInt(447);
+  const maxAdded = is25519
+    ? BigInt(8) * _2n ** BigInt(251) - _1n
+    : BigInt(4) * _2n ** BigInt(445) - _1n;
+  const maxScalar = minScalar + maxAdded + _1n; // (inclusive)
+  const modP = (n: bigint) => mod(n, P);
+  const GuBytes = encodeU(Gu);
+  function encodeU(u: bigint): Uint8Array {
+    return numberToBytesLE(modP(u), fieldLen);
+  }
+  function decodeU(u: Uint8Array): bigint {
+    const _u = copyBytes(abytes(u, fieldLen, "uCoordinate"));
+    // RFC: When receiving such an array, implementations of X25519
+    // (but not X448) MUST mask the most significant bit in the final byte.
+    if (is25519) _u[31] &= 127; // 0b0111_1111
+    // RFC: Implementations MUST accept non-canonical values and process them as
+    // if they had been reduced modulo the field prime.  The non-canonical
+    // values are 2^255 - 19 through 2^255 - 1 for X25519 and 2^448 - 2^224
+    // - 1 through 2^448 - 1 for X448.
+    return modP(bytesToNumberLE(_u));
+  }
+  function decodeScalar(scalar: Uint8Array): bigint {
+    return bytesToNumberLE(
+      adjustScalarBytes(copyBytes(abytes(scalar, fieldLen, "scalar"))),
+    );
+  }
+  function scalarMult(scalar: Uint8Array, u: Uint8Array): Uint8Array {
+    const pu = montgomeryLadder(decodeU(u), decodeScalar(scalar));
+    // Some public keys are useless, of low-order. Curve author doesn't think
+    // it needs to be validated, but we do it nonetheless.
+    // https://cr.yp.to/ecdh.html#validate
+    if (pu === _0n) throw new Error("invalid private or public key received");
+    return encodeU(pu);
+  }
+  // Computes public key from private. By doing scalar multiplication of base point.
+  function scalarMultBase(scalar: Uint8Array): Uint8Array {
+    return scalarMult(scalar, GuBytes);
+  }
+  const getPublicKey = scalarMultBase;
+  const getSharedSecret = scalarMult;
+
+  // cswap from RFC7748 "example code"
+  function cswap(
+    swap: bigint,
+    x_2: bigint,
+    x_3: bigint,
+  ): { x_2: bigint; x_3: bigint } {
+    // dummy = mask(swap) AND (x_2 XOR 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.
+    const dummy = modP(swap * (x_2 - x_3));
+    x_2 = modP(x_2 - dummy); // x_2 = x_2 XOR dummy
+    x_3 = modP(x_3 + dummy); // x_3 = x_3 XOR dummy
+    return { x_2, x_3 };
+  }
+
+  /**
+   * Montgomery x-only multiplication ladder.
+   * @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(u: bigint, scalar: bigint): bigint {
+    aInRange("u", u, _0n, P);
+    aInRange("scalar", scalar, minScalar, maxScalar);
+    const k = scalar;
+    const x_1 = u;
+    let x_2 = _1n;
+    let z_2 = _0n;
+    let x_3 = u;
+    let z_3 = _1n;
+    let swap = _0n;
+    for (let t = BigInt(montgomeryBits - 1); t >= _0n; t--) {
+      const k_t = (k >> t) & _1n;
+      swap ^= k_t;
+      ({ x_2, x_3 } = cswap(swap, x_2, x_3));
+      ({ x_2: z_2, x_3: z_3 } = cswap(swap, z_2, z_3));
+      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));
+    ({ x_2: z_2, x_3: z_3 } = cswap(swap, z_2, z_3));
+    const z2 = powPminus2(z_2); // `Fp.pow(x, P - _2n)` is much slower equivalent
+    return modP(x_2 * z2); // Return x_2 * (z_2^(p - 2))
+  }
+  const lengths = {
+    secretKey: fieldLen,
+    publicKey: fieldLen,
+    seed: fieldLen,
+  };
+  const randomSecretKey = async (seed?: Uint8Array) => {
+    if (seed === undefined) {
+      seed = await randomBytes_(fieldLen);
+    }
+    abytes(seed, lengths.seed, "seed");
+    return seed;
+  };
+  const utils = { randomSecretKey };
+
+  return Object.freeze({
+    keygen: createKeygen(randomSecretKey, getPublicKey),
+    getSharedSecret,
+    getPublicKey,
+    scalarMult,
+    scalarMultBase,
+    utils,
+    GuBytes: GuBytes.slice(),
+    lengths,
+  }) satisfies CryptoKeys;
+}