functionalscript 0.43.1 → 0.45.0

package/fjs/crypto/sha2/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Types for the SHA-2 family of hash functions.
+ *
+ * @module
+ */
+import type { Tuple } from '../../types/array/types.ts';
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Fold } from '../../types/function/operator/types.ts';
+/**
+ * 8-word SHA-2 state vector.
+ */
+export type V8 = Tuple<8, bigint>;
+/**
+ * 16-word SHA-2 message schedule chunk.
+ */
+export type V16 = Tuple<16, bigint>;
+/**
+ * State of the SHA-2 algorithm: `hash` is the current hash value, `len` the
+ * length of the data processed so far, and `remainder` the data that has not
+ * yet been processed.
+ */
+export type State = {
+    readonly hash: V8;
+    readonly len: bigint;
+    readonly remainder: Vec;
+};
+export type Base = {
+    readonly bitLength: bigint;
+    readonly chunkLength: bigint;
+    readonly compress: (i: V8) => (u: bigint) => V8;
+    readonly fromV8: (a: V8) => bigint;
+    readonly append: Fold<Vec, State>;
+    readonly end: (hashLength: bigint) => (state: State) => Vec;
+};
+/**
+ * SHA2. See https://en.wikipedia.org/wiki/SHA-2
+ *
+ * `hashLength` is a hash length, `blockLength` an internal block length,
+ * `init` the initial state of the SHA-2 algorithm, `append` adds data to a
+ * state and returns the new state, and `end` finalizes the hash of a state.
+ *
+ * @example
+ *
+ * ```js
+ * const s = msbUtf8("The quick brown fox jumps over the lazy dog.")
+ * let state = sha224.init
+ * state = sha224.append(state)(s)
+ * const h = sha224.end(state) // 0x1_619cba8e8e05826e9b8c519c0a5c68f4fb653e8a3d8aa04bb2c8cd4cn
+ * ```
+ */
+export type Sha2 = {
+    readonly hashLength: bigint;
+    readonly blockLength: bigint;
+    readonly init: State;
+    readonly append: Fold<Vec, State>;
+    readonly end: (state: State) => Vec;
+};

package/fjs/crypto/sign/module.f.d.mts

@@ -0,0 +1,46 @@
+/**
+ * Signing helpers built on secp256k1 and SHA-256 primitives. See `./types.ts`
+ * for the `All` type.
+ *
+ * @module
+ *
+ * @import { Tuple } from '../../types/array/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Curve } from '../secp/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ * @import { All } from './types.ts'
+ */
+import type { Tuple } from '../../types/array/types.ts';
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Curve } from '../secp/types.ts';
+import type { Sha2 } from '../sha2/types.ts';
+import type { All } from './types.ts';
+/**
+ * Builds RFC6979 helper conversions for a subgroup order.
+ *
+ * @param {bigint} q - Subgroup order.
+ * @returns {All} Conversion helpers used by deterministic nonce generation.
+ */
+export declare const all: (q: bigint) => All;
+/**
+ * Builds RFC6979 helper conversions from curve parameters.
+ *
+ * @type {(c: Curve) => All}
+ */
+export declare const fromCurve: (c: Curve) => All;
+/** @type {(...x: readonly Vec[]) => Vec} */
+export declare const concat: (...x: readonly Vec[]) => Vec;
+/**
+ * Computes deterministic ECDSA nonce `k` as described by RFC6979.
+ *
+ * @type {(_: All) => (_: Sha2) => (x: bigint) => (m: Vec) => bigint}
+ */
+export declare const computeK: (_: All) => (_: Sha2) => (x: bigint) => (m: Vec) => bigint;
+export type _Signature = Tuple<2, bigint>;
+/** @typedef {Tuple<2, bigint>} _Signature */
+/**
+ * Signs a message bit vector and returns an ECDSA `(r, s)` signature pair.
+ *
+ * @type {(c: Curve) => (hf: Sha2) => (x: bigint) => (m: Vec) => _Signature}
+ */
+export declare const sign: (c: Curve) => (hf: Sha2) => (x: bigint) => (m: Vec) => _Signature;

package/fjs/crypto/sign/module.f.mjs

@@ -0,0 +1,189 @@
+/**
+ * Signing helpers built on secp256k1 and SHA-256 primitives. See `./types.ts`
+ * for the `All` type.
+ *
+ * @module
+ *
+ * @import { Tuple } from '../../types/array/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Curve } from '../secp/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ * @import { All } from './types.ts'
+ */
+
+import { assertNotNullish } from '../../asserts/module.f.mjs'
+import { bitLength, divUp8, roundUp8 } from '../../types/bigint/module.f.mjs'
+import { empty, length, msb, repeat, unpack, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
+import { hmac } from '../hmac/module.f.mjs'
+import { computeSync } from '../sha2/module.f.mjs'
+
+/**
+ * Builds RFC6979 helper conversions for a subgroup order.
+ *
+ * @param {bigint} q - Subgroup order.
+ * @returns {All} Conversion helpers used by deterministic nonce generation.
+ */
+export const all = q => {
+    const qlen = bitLength(q)
+    /** @type {(b: Vec) => bigint} */
+    const bits2int = b => {
+        const { length, uint } = unpack(b)
+        const diff = length - qlen
+        return diff > 0n ? uint >> diff : uint
+    }
+    const int2octets = vec(roundUp8(qlen))
+    return {
+        q,
+        qlen,
+        bits2int,
+        int2octets,
+        // since z2 < 2*q, we can use simple mod with `z1 < q ? z1 : z1 - q`
+        bits2octets: b => int2octets(bits2int(b) % q),
+    }
+}
+
+/**
+ * Builds RFC6979 helper conversions from curve parameters.
+ *
+ * @type {(c: Curve) => All}
+ */
+export const fromCurve = c => all(c.nf.p)
+
+const x01 = vec8(0x01n)
+const x00 = vec8(0x00n)
+
+const { listToVec } = msb
+
+/** @type {(...x: readonly Vec[]) => Vec} */
+export const concat = (...x) => listToVec(x)
+
+/**
+ * Computes deterministic ECDSA nonce `k` as described by RFC6979.
+ *
+ * @type {(_: All) => (_: Sha2) => (x: bigint) => (m: Vec) => bigint}
+ */
+export const computeK =
+    ({ q, bits2int, qlen, int2octets, bits2octets }) => hf => {
+        // TODO: Look at https://www.rfc-editor.org/rfc/rfc6979#section-3.3 to reformulate
+        //       it using `HMAC_DRBG`.
+        const hmacf = hmac(hf)
+        // b. Set:
+        //      V = 0x01 0x01 0x01 ... 0x01
+        //    such that the length of V, in bits, is equal to 8*ceil(hlen/8).
+        //    For instance, on an octet-based system, if H is SHA-256, then V
+        //    is set to a sequence of 32 octets of value 1.  Note that in this
+        //    step and all subsequent steps, we use the same H function as the
+        //    one used in step 'a' to process the input message; this choice
+        //    will be discussed in more detail in Section 3.6.
+        const rep = repeat(divUp8(hf.hashLength))
+        const v0 = rep(x01)
+        // c. Set:
+        //      K = 0x00 0x00 0x00 ... 0x00
+        //    such that the length of K, in bits, is equal to 8*ceil(hlen/8).
+        const k0 = rep(x00)
+        //
+        return x => m => {
+            let v = v0
+            let k = k0
+            // a. Process m through the hash function H, yielding:
+            //      h1 = H(m)
+            //   (h1 is a sequence of hlen bits).
+            const h1 = computeSync(hf)([m])
+            // d. Set:
+            //      K = HMAC_K(V || 0x00 || int2octets(x) || bits2octets(h1))
+            //    where '||' denotes concatenation.
+            const xh1 = concat(int2octets(x), bits2octets(h1))
+            k = hmacf(k)(concat(v, x00, xh1))
+            // e. Set:
+            //      V = HMAC_K(V)
+            v = hmacf(k)(v)
+            // f. Set:
+            //      K = HMAC_K(V || 0x01 || int2octets(x) || bits2octets(h1))
+            k = hmacf(k)(concat(v, x01, xh1))
+            // g. Set:
+            //      V = HMAC_K(V)
+            v = hmacf(k)(v)
+            // h. Apply the following algorithm until a proper value is for `k`:
+            while (true) {
+                // h. Apply the following algorithm until a proper value is for `k`:
+                //    1. Set `T` to the empty sequence, so `tlen = 0`.
+                let t = empty
+                //    2. while `tlen < qlen` do:
+                //       - `V = HMAC_K(V)`
+                //       - `T = T || V`
+                // Possible optimizations:
+                // - precompute number of iterations
+                // - `qlen` can't be 0, so we can avoid the first check and
+                //   first concatenation.
+                while (length(t) < qlen) {
+                    v = hmacf(k)(v)
+                    t = concat(t, v)
+                }
+                //    3. Compute `k = bits2int(T)`. If `k` is not in `[1, q-1]` or `kG = 0` then
+                //       - `K = HMAC_K(V || 0x00)`
+                //       - `V = HMAC_K(V)`
+                //       and loop (try to generate a new `T`, and so on). Return to step `1`.
+                const result = bits2int(t)
+                if (0n < result && result < q) {
+                    return result
+                }
+                k = hmacf(k)(concat(v, x00))
+                v = hmacf(k)(v)
+            }
+        }
+    }
+
+/** @typedef {Tuple<2, bigint>} _Signature */
+
+/**
+ * Signs a message bit vector and returns an ECDSA `(r, s)` signature pair.
+ *
+ * @type {(c: Curve) => (hf: Sha2) => (x: bigint) => (m: Vec) => _Signature}
+ */
+export const sign = c => hf => x => m => {
+    // 2.4 Signature Generation
+    const { nf: { p: q, div }, g } = c
+    const a = all(q)
+    const { bits2int } = a
+    // The following steps are then applied:
+    //
+    // 1. H(m) is transformed into an integer modulo q using the bits2int
+    //    transform and an extra modular reduction:
+    //
+    //       h = bits2int(H(m)) mod q
+    //
+    //     As was noted in the description of bits2octets, the extra modular
+    //     reduction is no more than a conditional subtraction.
+    const hm = computeSync(hf)([m])
+    const h = bits2int(hm) % q
+    // 2. A random value modulo q, dubbed k, is generated.  That value
+    //    shall not be 0; hence, it lies in the [1, q-1] range.  Most of
+    //    the remainder of this document will revolve around the process
+    //    used to generate k.  In plain DSA or ECDSA, k should be selected
+    //    through a random selection that chooses a value among the q-1
+    //    possible values with uniform probability.
+    const k = computeK(a)(hf)(x)(m)
+    // 3.  A value r (modulo q) is computed from k and the key parameters:
+    //
+    //     *  For ECDSA: the point kG is computed; its X coordinate (a
+    //        member of the field over which E is defined) is converted to
+    //        an integer, which is reduced modulo q, yielding r.
+    //
+    //     If r turns out to be zero, a new k should be selected and r
+    //     computed again (this is an utterly improbable occurrence).
+    // TODO: implement the loop. `computeK` should either
+    // - accept a state (current `k`).
+    // - accept a `is_valid` function.
+    const rxy = assertNotNullish(c.mul(k)(g), 'rxy === null')
+    const [r] = rxy
+    // 4.  The value s (modulo q) is computed:
+    //
+    //        s = (h+x*r)/k mod q
+    //
+    //     The pair (r, s) is the signature.  How a signature is to be
+    //     encoded is not covered by the DSA and ECDSA standards themselves;
+    //     a common way is to use a DER-encoded ASN.1 structure (a SEQUENCE
+    //     of two INTEGERs, for r and s, in that order).
+    const s = div(h + x*r)(k)
+    return [r, s]
+}

package/fjs/crypto/sign/proof.f.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @import { Tuple } from '../../types/array/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Curve } from '../secp/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ */
+export declare const proof: {
+    bits2int: () => void;
+    int2octets: () => void;
+    bit2octets: () => void;
+    k: () => void;
+    computeK: () => void;
+    investigate: () => void;
+    kk: () => void;
+    a2: () => void;
+    a2s: () => void;
+};