@arcium-hq/client 0.9.2 → 0.9.3

package/src/cryptography/hkdf.ts

@@ -0,0 +1,58 @@
+import { HMACRescuePrime } from './hmac.js';
+import { FpField } from './rescueDesc.js';
+
+/**
+ * HKDF (HMAC-based Extract-and-Expand Key Derivation Function) using the Rescue-Prime hash function.
+ * Follows RFC 5869. Only supports L = HashLen.
+ */
+export class HKDFRescuePrime {
+    hmac: HMACRescuePrime;
+
+    /**
+     * Construct a new HKDFRescuePrime instance.
+     */
+    constructor(field: FpField) {
+        this.hmac = new HMACRescuePrime(field);
+    }
+
+    /**
+     * HKDF-Extract step: derive a pseudorandom key (PRK) from the input keying material (IKM) and salt.
+     * @param salt - Salt value as an array of bigints.
+     * @param ikm - Input keying material as an array of bigints.
+     * @returns Pseudorandom key (PRK) as an array of bigints.
+     */
+    extract(salt: bigint[], ikm: bigint[]): bigint[] {
+        // Create effective salt to avoid mutating input parameter
+        const effectiveSalt = salt.length === 0
+            ? Array(this.hmac.hasher.rate).fill(0n)
+            : salt;
+        return this.hmac.digest(effectiveSalt, ikm);
+    }
+
+    /**
+     * HKDF-Expand step: expand the pseudorandom key (PRK) with info to produce output keying material (OKM).
+     * Only supports L = HashLen = 5, i.e. N = 1.
+     * @param prk - Pseudorandom key as an array of bigints.
+     * @param info - Context and application specific information as an array of bigints.
+     * @returns Output keying material (OKM) as an array of bigints.
+     */
+    expand(prk: bigint[], info: bigint[]): bigint[] {
+        // we only support L = HashLen = 5, i.e. N = 1
+        // message = empty string | info | 0x01
+        // Create a copy to avoid mutating the input parameter
+        const infoWithCounter = [...info, 1n];
+        return this.hmac.digest(prk, infoWithCounter);
+    }
+
+    /**
+     * Perform the full HKDF (extract and expand) to derive output keying material (OKM).
+     * @param salt - Salt value as an array of bigints.
+     * @param ikm - Input keying material as an array of bigints.
+     * @param info - Context and application specific information as an array of bigints.
+     * @returns Output keying material (OKM) as an array of bigints.
+     */
+    okm(salt: bigint[], ikm: bigint[], info: bigint[]): bigint[] {
+        const prk = this.extract(salt, ikm);
+        return this.expand(prk, info);
+    }
+}

package/src/cryptography/hmac.ts

@@ -0,0 +1,66 @@
+import { deserializeLE } from './cryptography.js';
+import { FpField } from './rescueDesc.js';
+import { RescuePrimeHash } from './rescuePrimeHash.js';
+
+/**
+ * HMAC inner padding constant (RFC 2104).
+ * Added to each key element for the inner hash computation.
+ * @see https://datatracker.ietf.org/doc/html/rfc2104
+ */
+const HMAC_IPAD_BYTE = 0x36;
+
+/**
+ * HMAC outer padding constant (RFC 2104).
+ * Added to each key element for the outer hash computation.
+ * @see https://datatracker.ietf.org/doc/html/rfc2104
+ */
+const HMAC_OPAD_BYTE = 0x5c;
+
+/**
+ * HMACRescuePrime provides a message authentication code (MAC) using the Rescue-Prime hash function.
+ * We refer to https://datatracker.ietf.org/doc/html/rfc2104 for more details.
+ */
+export class HMACRescuePrime {
+    hasher: RescuePrimeHash;
+
+    /**
+     * Construct a new HMACRescuePrime instance.
+     */
+    constructor(field: FpField) {
+        this.hasher = new RescuePrimeHash(field);
+    }
+
+    /**
+     * Compute the HMAC digest of a message with a given key using Rescue-Prime.
+     * @param key - Key as an array of bigints.
+     * @param message - Message as an array of bigints.
+     * @returns HMAC digest as an array of bigints.
+     * @throws Error if the key is shorter than the hash function's digest length or longer than the hash function's rate.
+     */
+    digest(key: bigint[], message: bigint[]): bigint[] {
+        // We follow https://datatracker.ietf.org/doc/html/rfc2104, though since Rescue-Prime is not based
+        // on the Merkle-Damgard construction we cannot have an exact anology between the
+        // parameters. For our purpose, we set B = hasher.rate and L = hasher.digestLength.
+        if (key.length < this.hasher.digestLength || key.length > this.hasher.rate) {
+            throw Error(`length of key is supposed to be at least the hash function's digest length and at most the hash function's rate (found ${key.length}, ${this.hasher.digestLength} and ${this.hasher.rate})`);
+        }
+        // 32-byte array size is for field element deserialization, not HMAC block size
+        const ipad = deserializeLE(new Uint8Array(32).fill(HMAC_IPAD_BYTE));
+        const opad = deserializeLE(new Uint8Array(32).fill(HMAC_OPAD_BYTE));
+        // the key is first extended to length B
+        // Create a copy to avoid mutating the input parameter
+        const paddedKey = [...key];
+        const offset = this.hasher.rate - paddedKey.length;
+        for (let i = 0; i < offset; ++i) {
+            paddedKey.push(0n);
+        }
+        // inner padding
+        const keyPlusIpad = paddedKey.map((k) => k + ipad);
+        keyPlusIpad.push(...message);
+        const innerDigest = this.hasher.digest(keyPlusIpad);
+        // outer padding
+        const keyPlusOpad = paddedKey.map((k) => k + opad);
+        keyPlusOpad.push(...innerDigest);
+        return this.hasher.digest(keyPlusOpad);
+    }
+}

package/src/cryptography/rescueCipher.ts

@@ -0,0 +1,41 @@
+import {
+    CURVE25519_BASE_FIELD,
+} from './rescueDesc.js';
+import { RescueCipherCommon } from './rescueCipherCommon.js';
+
+/**
+ * The Rescue cipher over Curve25519's base field in Counter (CTR) mode, with a fixed block size m = 5.
+ * See: https://tosc.iacr.org/index.php/ToSC/article/view/8695/8287
+ */
+export class RescueCipher {
+    cipher: RescueCipherCommon;
+
+    /**
+     * Construct a RescueCipher instance using a shared secret.
+     * The key is derived using RescuePrimeHash and used to initialize the RescueDesc.
+     * @param sharedSecret - Shared secret to derive the cipher key from.
+     */
+    constructor(sharedSecret: Uint8Array) {
+        this.cipher = new RescueCipherCommon(sharedSecret, CURVE25519_BASE_FIELD);
+    }
+
+    /**
+     * Encrypt the plaintext vector in Counter (CTR) mode and serialize each block.
+     * @param plaintext - Array of plaintext bigints to encrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Ciphertext as an array of arrays of numbers (each 32 bytes).
+     */
+    encrypt(plaintext: bigint[], nonce: Uint8Array): number[][] {
+        return this.cipher.encrypt(plaintext, nonce);
+    }
+
+    /**
+     * Deserialize and decrypt the ciphertext vector in Counter (CTR) mode.
+     * @param ciphertext - Array of arrays of numbers (each 32 bytes) to decrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Decrypted plaintext as an array of bigints.
+     */
+    decrypt(ciphertext: number[][], nonce: Uint8Array): bigint[] {
+        return this.cipher.decrypt(ciphertext, nonce);
+    }
+}

package/src/cryptography/rescueCipherCommon.ts

@@ -0,0 +1,211 @@
+import {
+    RescueDesc,
+    toVec,
+    FpField,
+    CURVE25519_BASE_FIELD,
+} from './rescueDesc.js';
+import { deserializeLE, serializeLE } from './cryptography.js';
+import { Matrix } from '../matrix.js';
+import { getBinSize } from '../utils.js';
+import {
+    ctLt,
+    ctAdd,
+    ctSelect,
+    ctSub,
+    ctSignBit,
+    verifyBinSize,
+} from '../ctUtils.js';
+import { RescuePrimeHash } from './rescuePrimeHash.js';
+
+/**
+ * Block size m for Rescue cipher operations.
+ * Rescue operates on 5-element blocks of field elements.
+ */
+const RESCUE_CIPHER_BLOCK_SIZE = 5;
+
+/**
+ * The Rescue cipher in Counter (CTR) mode, with a fixed block size m = 5.
+ * See: https://tosc.iacr.org/index.php/ToSC/article/view/8695/8287
+ */
+export class RescueCipherCommon {
+    desc: RescueDesc;
+
+    /**
+     * Construct a RescueCipherCommon instance using a shared secret.
+     * The key is derived using RescuePrimeHash and used to initialize the RescueDesc.
+     * @param sharedSecret - Shared secret to derive the cipher key from.
+     */
+    constructor(sharedSecret: Uint8Array, field: FpField) {
+        if (sharedSecret.length != 32) {
+            throw Error(`sharedSecret must be of length 32 (found ${sharedSecret.length})`);
+        }
+
+        const hasher = new RescuePrimeHash(field);
+
+        // In case `field` is different from CURVE25519_BASE_FIELD we need to injectively map sharedSecret
+        // to a vector of elements over `field`.
+        const converted = [];
+        if (field === CURVE25519_BASE_FIELD) {
+            converted.push(deserializeLE(sharedSecret));
+        }
+        else {
+            // We chunk sharedSecret by field.BYTES - 1 and convert.
+            const chunkSize = field.BYTES - 1;
+            const nChunks = Math.ceil(sharedSecret.length / chunkSize);
+            for (let i = 0; i < nChunks; ++i) {
+                converted.push(deserializeLE(sharedSecret.slice(i * chunkSize, (i + 1) * chunkSize)));
+            }
+        }
+
+        // We follow [Section 4, Option 1.](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Cr2.pdf).
+        // For our choice of hash function, we have:
+        // - H_outputBits = hasher.digestLength = RESCUE_CIPHER_BLOCK_SIZE
+        // - max_H_inputBits = arbitrarily long, as the Rescue-Prime hash function is built upon the
+        //   sponge construction
+        // - L = RESCUE_CIPHER_BLOCK_SIZE.
+
+        // Build the vector `counter || Z || FixedInfo` (we only have i = 1, since reps = 1).
+        // For the FixedInfo we simply take L.
+        const counter = [1n, ...converted, BigInt(RESCUE_CIPHER_BLOCK_SIZE)];
+        const rescueKey = hasher.digest(counter);
+        this.desc = new RescueDesc(
+            field,
+            { kind: 'cipher', key: rescueKey },
+        );
+    }
+
+    /**
+     * Encrypt the plaintext vector in Counter (CTR) mode (raw, returns bigints).
+     * @param plaintext - Array of plaintext bigints to encrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Ciphertext as an array of bigints.
+     * @throws Error if the nonce is not 16 bytes long.
+     */
+    encrypt_raw(plaintext: bigint[], nonce: Uint8Array): bigint[] {
+        if (nonce.length !== 16) {
+            throw Error(`nonce must be of length 16 (found ${nonce.length})`);
+        }
+        const binSize = getBinSize(this.desc.field.ORDER - 1n);
+
+        function encryptBatch(desc: RescueDesc, ptxt: bigint[], cntr: bigint[]): bigint[] {
+            if (cntr.length !== RESCUE_CIPHER_BLOCK_SIZE) {
+                throw Error(`counter must be of length ${RESCUE_CIPHER_BLOCK_SIZE} (found ${cntr.length})`);
+            }
+            const encryptedCounter = desc.permute(new Matrix(desc.field, toVec(cntr)));
+            const ciphertext = [];
+            for (let i = 0; i < ptxt.length; ++i) {
+                if (!verifyBinSize(ptxt[i], binSize - 1n) || ctSignBit(ptxt[i], binSize) || !ctLt(ptxt[i], desc.field.ORDER, binSize)) {
+                    throw Error(`plaintext must be non-negative and less than ${desc.field.ORDER}`);
+                }
+                const sum = ctAdd(ptxt[i], encryptedCounter.data[i][0], binSize);
+                ciphertext.push(ctSelect(ctLt(sum, desc.field.ORDER, binSize), sum, ctSub(sum, desc.field.ORDER, binSize), binSize));
+            }
+            return ciphertext;
+        }
+
+        const nBlocks = Math.ceil(plaintext.length / RESCUE_CIPHER_BLOCK_SIZE);
+        const counter = getCounter(deserializeLE(nonce), nBlocks);
+
+        const ciphertext = [];
+        for (let i = 0; i < nBlocks; ++i) {
+            const cnt = RESCUE_CIPHER_BLOCK_SIZE * i;
+            const newCiphertext = encryptBatch(
+                this.desc,
+                plaintext.slice(cnt, Math.min(cnt + RESCUE_CIPHER_BLOCK_SIZE, plaintext.length)),
+                counter.slice(cnt, cnt + RESCUE_CIPHER_BLOCK_SIZE),
+            );
+            for (let j = 0; j < newCiphertext.length; ++j) {
+                ciphertext.push(newCiphertext[j]);
+            }
+        }
+        return ciphertext;
+    }
+
+    /**
+     * Encrypt the plaintext vector in Counter (CTR) mode and serialize each block.
+     * @param plaintext - Array of plaintext bigints to encrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Ciphertext as an array of arrays of numbers (each 32 bytes).
+     */
+    encrypt(plaintext: bigint[], nonce: Uint8Array): number[][] {
+        return this.encrypt_raw(plaintext, nonce).map((c) => Array.from(serializeLE(c, 32)));
+    }
+
+    /**
+     * Decrypt the ciphertext vector in Counter (CTR) mode (raw, expects bigints).
+     * @param ciphertext - Array of ciphertext bigints to decrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Decrypted plaintext as an array of bigints.
+     * @throws Error if the nonce is not 16 bytes long.
+     */
+    decrypt_raw(ciphertext: bigint[], nonce: Uint8Array): bigint[] {
+        if (nonce.length !== 16) {
+            throw Error(`nonce must be of length 16 (found ${nonce.length})`);
+        }
+        const binSize = getBinSize(this.desc.field.ORDER - 1n);
+
+        function decryptBatch(desc: RescueDesc, ctxt: bigint[], cntr: bigint[]): bigint[] {
+            if (cntr.length !== RESCUE_CIPHER_BLOCK_SIZE) {
+                throw Error(`counter must be of length ${RESCUE_CIPHER_BLOCK_SIZE} (found ${cntr.length})`);
+            }
+            const encryptedCounter = desc.permute(new Matrix(desc.field, toVec(cntr)));
+            const decrypted = [];
+            for (let i = 0; i < ctxt.length; ++i) {
+                const diff = ctSub(ctxt[i], encryptedCounter.data[i][0], binSize);
+                decrypted.push(ctSelect(ctSignBit(diff, binSize), ctAdd(diff, desc.field.ORDER, binSize), diff, binSize));
+            }
+            return decrypted;
+        }
+
+        const nBlocks = Math.ceil(ciphertext.length / RESCUE_CIPHER_BLOCK_SIZE);
+        const counter = getCounter(deserializeLE(nonce), nBlocks);
+
+        const decrypted = [];
+        for (let i = 0; i < nBlocks; ++i) {
+            const cnt = RESCUE_CIPHER_BLOCK_SIZE * i;
+            const newDecrypted = decryptBatch(
+                this.desc,
+                ciphertext.slice(cnt, Math.min(cnt + RESCUE_CIPHER_BLOCK_SIZE, ciphertext.length)),
+                counter.slice(cnt, cnt + RESCUE_CIPHER_BLOCK_SIZE),
+            );
+            for (let j = 0; j < newDecrypted.length; ++j) {
+                decrypted.push(newDecrypted[j]);
+            }
+        }
+        return decrypted;
+    }
+
+    /**
+     * Deserialize and decrypt the ciphertext vector in Counter (CTR) mode.
+     * @param ciphertext - Array of arrays of numbers (each 32 bytes) to decrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Decrypted plaintext as an array of bigints.
+     */
+    decrypt(ciphertext: number[][], nonce: Uint8Array): bigint[] {
+        return this.decrypt_raw(ciphertext.map((c) => {
+            if (c.length !== 32) {
+                throw Error(`ciphertext must be of length 32 (found ${c.length})`);
+            }
+            return deserializeLE(Uint8Array.from(c));
+        }), nonce);
+    }
+}
+
+/**
+ * Generate the counter values for Rescue cipher CTR mode.
+ * @param nonce - Initial nonce as a bigint.
+ * @param nBlocks - Number of blocks to generate counters for.
+ * @returns Array of counter values as bigints.
+ */
+function getCounter(nonce: bigint, nBlocks: number): bigint[] {
+    const counter = [];
+    for (let i = 0n; i < nBlocks; ++i) {
+        counter.push(nonce);
+        counter.push(i);
+        // Pad to RESCUE_CIPHER_BLOCK_SIZE elements per counter block
+        for (let j = 2; j < RESCUE_CIPHER_BLOCK_SIZE; ++j) {
+            counter.push(0n);
+        }
+    }
+    return counter;
+}