@joclaim/tls 0.1.0

package/lib/utils/generics.js

@@ -0,0 +1,146 @@
+import { TLS_PROTOCOL_VERSION_MAP } from "./constants.js";
+/**
+ * Converts a buffer to a hex string with whitespace between each byte
+ * @returns eg. '01 02 03 04'
+ */
+export function toHexStringWithWhitespace(buff, whitespace = ' ') {
+    return [...buff]
+        .map(x => x.toString(16).padStart(2, '0'))
+        .join(whitespace);
+}
+export function xor(a, b) {
+    const result = new Uint8Array(a.length);
+    for (const [i, element] of a.entries()) {
+        result[i] = element ^ b[i];
+    }
+    return result;
+}
+export function concatenateUint8Arrays(arrays) {
+    const totalLength = arrays.reduce((acc, curr) => acc + curr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+export function areUint8ArraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (const [i, element] of a.entries()) {
+        if (element !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+export function uint8ArrayToDataView(arr) {
+    return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+export function asciiToUint8Array(str) {
+    const bytes = new Uint8Array(str.length);
+    for (let i = 0; i < str.length; i++) {
+        const charCode = str.charCodeAt(i);
+        if (charCode < 0 || charCode > 255) {
+            throw new Error(`Invalid ASCII character at index ${i}: ${str[i]}`);
+        }
+        bytes[i] = charCode;
+    }
+    return bytes;
+}
+/**
+ * convert a Uint8Array to a binary encoded str
+ * from: https://github.com/feross/buffer/blob/795bbb5bda1b39f1370ebd784bea6107b087e3a7/index.js#L1063
+ * @param buf
+ * @returns
+ */
+export function uint8ArrayToBinaryStr(buf) {
+    let ret = '';
+    for (const v of buf) {
+        ret += String.fromCharCode(v);
+    }
+    return ret;
+}
+export function generateIV(iv, recordNumber) {
+    // make the recordNumber a buffer, so we can XOR with the main IV
+    // to generate the specific IV to decrypt this packet
+    const recordBuffer = new Uint8Array(iv.length);
+    const recordBufferView = new DataView(recordBuffer.buffer);
+    recordBufferView.setUint32(iv.length - 4, recordNumber);
+    return xor(iv, recordBuffer);
+}
+/**
+ * TLS has this special sort of padding where the last byte
+ * is the number of padding bytes, and all the padding bytes
+ * are the same as the last byte.
+ * Eg. for an 8 byte block [ 0x0a, 0x0b, 0x0c, 0xd ]
+ * -> [ 0x0a, 0x0b, 0x0c, 0x04, 0x04, 0x04, 0x04, 0x04 ]
+ */
+export function padTls(data, blockSize) {
+    const nextMultiple = data.length % blockSize === 0
+        ? data.length + blockSize
+        : Math.ceil(data.length / blockSize) * blockSize;
+    const paddingLength = nextMultiple - data.length;
+    const paddingNum = paddingLength - 1;
+    const padded = new Uint8Array(nextMultiple);
+    padded.set(data);
+    padded.fill(paddingNum, data.length);
+    padded.fill(paddingNum, nextMultiple - 1);
+    return padded;
+}
+/**
+ * Unpad a TLS-spec padded buffer
+ */
+export function unpadTls(data) {
+    const paddingLength = data[data.length - 1];
+    for (let i = 0; i < paddingLength; i++) {
+        if (data[data.length - 1 - i] !== paddingLength) {
+            throw new Error('Invalid padding');
+        }
+    }
+    return data.slice(0, data.length - paddingLength);
+}
+export function isSymmetricCipher(cipher) {
+    return cipher === 'AES-128-CBC';
+}
+export function chunkUint8Array(arr, chunkSize) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += chunkSize) {
+        result.push(arr.slice(i, i + chunkSize));
+    }
+    return result;
+}
+export function getTlsVersionFromBytes(bytes) {
+    const supportedV = Object.entries(TLS_PROTOCOL_VERSION_MAP)
+        .find(([, v]) => areUint8ArraysEqual(v, bytes));
+    if (!supportedV) {
+        throw new Error(`Unsupported TLS version '${bytes}'`);
+    }
+    return supportedV[0];
+}
+export const hkdfExpand = async (alg, hashLength, key, expLength, info, crypto) => {
+    info ||= new Uint8Array(0);
+    const infoLength = info.length;
+    const steps = Math.ceil(expLength / hashLength);
+    if (steps > 0xFF) {
+        throw new Error(`OKM length ${expLength} is too long for ${alg} hash`);
+    }
+    // use single buffer with unnecessary create/copy/move operations
+    const t = new Uint8Array(hashLength * steps + infoLength + 1);
+    for (let c = 1, start = 0, end = 0; c <= steps; ++c) {
+        // add info
+        t.set(info, end);
+        // add counter
+        t.set([c], end + infoLength);
+        // use view: T(C) = T(C-1) | info | C
+        const hmac = await crypto
+            .hmac(alg, key, t.slice(start, end + infoLength + 1));
+        // put back to the same buffer
+        t.set(hmac.slice(0, t.length - end), end);
+        start = end; // used for T(C-1) start
+        end += hashLength; // used for T(C-1) end & overall end
+    }
+    return t.slice(0, expLength);
+};

package/lib/utils/index.d.ts

@@ -0,0 +1,18 @@
+export * from './client-hello.ts';
+export * from './constants.ts';
+export * from './decryption-utils.ts';
+export * from './finish-messages.ts';
+export * from './generics.ts';
+export * from './key-share.ts';
+export * from './key-update.ts';
+export * from './logger.ts';
+export * from './make-queue.ts';
+export * from './packets.ts';
+export * from './parse-alert.ts';
+export * from './parse-certificate.ts';
+export * from './parse-server-hello.ts';
+export * from './mozilla-root-cas.ts';
+export * from './session-ticket.ts';
+export * from './wrapped-record.ts';
+export * from './x509.ts';
+export * from './parse-client-hello.ts';

package/lib/utils/index.js

@@ -0,0 +1,18 @@
+export * from "./client-hello.js";
+export * from "./constants.js";
+export * from "./decryption-utils.js";
+export * from "./finish-messages.js";
+export * from "./generics.js";
+export * from "./key-share.js";
+export * from "./key-update.js";
+export * from "./logger.js";
+export * from "./make-queue.js";
+export * from "./packets.js";
+export * from "./parse-alert.js";
+export * from "./parse-certificate.js";
+export * from "./parse-server-hello.js";
+export * from "./mozilla-root-cas.js";
+export * from "./session-ticket.js";
+export * from "./wrapped-record.js";
+export * from "./x509.js";
+export * from "./parse-client-hello.js";

package/lib/utils/key-share.d.ts

@@ -0,0 +1,13 @@
+import type { Key, TLSProtocolVersion, X509Certificate } from '../types/index.ts';
+export declare function packClientCurveKeyShare(publicKey: Key): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function packClientRsaKeyShare(encPreMaster: Uint8Array): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function processServerKeyShare(data: Uint8Array): Promise<{
+    publicKeyType: "X25519" | "SECP256R1" | "SECP384R1";
+    publicKey: unknown;
+    signatureAlgorithm: "ECDSA_SECP256R1_SHA256" | "ECDSA_SECP384R1_SHA256" | "RSA_PSS_RSAE_SHA256" | "RSA_PKCS1_SHA256" | "RSA_PKCS1_SHA384" | "RSA_PKCS1_SHA512";
+    signatureBytes: Uint8Array<ArrayBuffer>;
+}>;
+export declare function createRsaPreMasterSecret(serverCert: X509Certificate, tlsVersion: TLSProtocolVersion, rand?: Uint8Array): Promise<{
+    preMasterSecret: Uint8Array<ArrayBufferLike>;
+    encrypted: Uint8Array<ArrayBufferLike>;
+}>;

package/lib/utils/key-share.js

@@ -0,0 +1,72 @@
+import { crypto } from "../crypto/index.js";
+import { SUPPORTED_NAMED_CURVE_MAP, SUPPORTED_RECORD_TYPE_MAP, SUPPORTED_SIGNATURE_ALGS_MAP, TLS_PROTOCOL_VERSION_MAP } from "./constants.js";
+import { areUint8ArraysEqual, concatenateUint8Arrays } from "./generics.js";
+import { expectReadWithLength, packWith3ByteLength, packWithLength } from "./packets.js";
+export async function packClientCurveKeyShare(publicKey) {
+    return concatenateUint8Arrays([
+        new Uint8Array([SUPPORTED_RECORD_TYPE_MAP['CLIENT_KEY_SHARE']]),
+        packWith3ByteLength(
+        // pack with 1 byte length
+        packWithLength(await crypto.exportKey(publicKey)).slice(1))
+    ]);
+}
+export async function packClientRsaKeyShare(encPreMaster) {
+    return concatenateUint8Arrays([
+        new Uint8Array([SUPPORTED_RECORD_TYPE_MAP['CLIENT_KEY_SHARE']]),
+        packWith3ByteLength(packWithLength(encPreMaster))
+    ]);
+}
+export async function processServerKeyShare(data) {
+    const type = read(1)[0];
+    if (type !== 0x03) {
+        throw new Error('expected "named_group" key share');
+    }
+    const curveTypeBytes = read(2);
+    const curveTypeEntry = Object.entries(SUPPORTED_NAMED_CURVE_MAP)
+        .find(([, { identifier }]) => areUint8ArraysEqual(identifier, curveTypeBytes));
+    if (!curveTypeEntry) {
+        throw new Error(`unsupported curve type: ${curveTypeBytes}`);
+    }
+    const publicKeyType = curveTypeEntry[0];
+    const publicKeyBytes = readWLength(1);
+    const publicKey = await crypto.importKey(curveTypeEntry[1].algorithm, publicKeyBytes, 'public');
+    const signatureTypeBytes = read(2);
+    const signatureTypeEntry = Object.entries(SUPPORTED_SIGNATURE_ALGS_MAP)
+        .find(([, { identifier }]) => areUint8ArraysEqual(identifier, signatureTypeBytes));
+    if (!signatureTypeEntry) {
+        throw new Error(`unsupported signature type: ${signatureTypeBytes}`);
+    }
+    const signatureAlgorithm = signatureTypeEntry[0];
+    const signatureBytes = readWLength(2);
+    return {
+        publicKeyType,
+        publicKey,
+        signatureAlgorithm,
+        signatureBytes,
+    };
+    function read(bytes) {
+        const result = data.slice(0, bytes);
+        data = data.slice(bytes);
+        return result;
+    }
+    function readWLength(bytesLength = 2) {
+        const content = expectReadWithLength(data, bytesLength);
+        data = data.slice(content.length + bytesLength);
+        return content;
+    }
+}
+export async function createRsaPreMasterSecret(serverCert, tlsVersion, rand = crypto.randomBytes(46)) {
+    const preMasterSecret = concatenateUint8Arrays([
+        TLS_PROTOCOL_VERSION_MAP[tlsVersion],
+        rand
+    ]);
+    const servPubKey = serverCert.getPublicKey();
+    if (servPubKey.algorithm !== 'RSASSA-PKCS1-v1_5') {
+        throw new Error(`expected RSASSA-PKCS1-v1_5 cert, got ${servPubKey.algorithm}`);
+    }
+    const publicKey = await crypto
+        .importKey('RSA-PCKS1_5', servPubKey.buffer, 'public');
+    const rslt = await crypto
+        .asymmetricEncrypt('RSA-PCKS1_5', { data: preMasterSecret, publicKey });
+    return { preMasterSecret, encrypted: rslt };
+}

package/lib/utils/key-update.d.ts

@@ -0,0 +1,2 @@
+import { KEY_UPDATE_TYPE_MAP } from './constants.ts';
+export declare function packKeyUpdateRecord(type: keyof typeof KEY_UPDATE_TYPE_MAP): Uint8Array<ArrayBufferLike>;

package/lib/utils/key-update.js

@@ -0,0 +1,14 @@
+import { KEY_UPDATE_TYPE_MAP, SUPPORTED_RECORD_TYPE_MAP } from "./constants.js";
+import { concatenateUint8Arrays } from "./generics.js";
+import { packWithLength } from "./packets.js";
+export function packKeyUpdateRecord(type) {
+    const encoded = packWithLength(new Uint8Array([KEY_UPDATE_TYPE_MAP[type]]));
+    const packet = concatenateUint8Arrays([
+        new Uint8Array([
+            SUPPORTED_RECORD_TYPE_MAP.KEY_UPDATE,
+            0x00,
+        ]),
+        encoded
+    ]);
+    return packet;
+}

package/lib/utils/logger.d.ts

@@ -0,0 +1,2 @@
+import type { Logger } from '../types/index.ts';
+export declare const logger: Logger;

package/lib/utils/logger.js

@@ -0,0 +1,15 @@
+export const logger = {
+    info(...args) {
+        return console.info(...args);
+    },
+    debug(...args) {
+        return console.debug(...args);
+    },
+    trace: () => { },
+    warn(...args) {
+        return console.warn(...args);
+    },
+    error(...args) {
+        return console.error(...args);
+    }
+};

package/lib/utils/make-queue.d.ts

@@ -0,0 +1,3 @@
+export declare const makeQueue: () => {
+    enqueue<A extends any[], R, T extends (...args: A) => R>(code: T, ...args: A): Promise<R>;
+};

package/lib/utils/make-queue.js

@@ -0,0 +1,22 @@
+export const makeQueue = () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let task = Promise.resolve();
+    return {
+        enqueue(code, ...args) {
+            task = (async () => {
+                // wait for the previous task to complete
+                // if there is an error, we swallow so as to not block the queue
+                try {
+                    await task;
+                }
+                catch { }
+                // execute the current task
+                const result = await code(...args);
+                return result;
+            })();
+            // we replace the existing task, appending the new piece of execution to it
+            // so the next task will have to wait for this one to finish
+            return task;
+        },
+    };
+};

package/lib/utils/mozilla-root-cas.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Mozilla Root CA List
+ * downloaded from: https://wiki.mozilla.org/CA/Included_Certificates
+ */
+export declare const MOZILLA_ROOT_CA_LIST: string[];