@joclaim/tls 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+<div>
+    <div>
+        <img src="https://raw.githubusercontent.com/reclaimprotocol/.github/main/assets/banners/TLS.png"  />
+    </div>
+</div>
+
+A TLS client implementation in typescript. This library is fully compatible with the browser (without any polyfills), and on any other JavaScript environment.
+
+As all the cryptography is handled by either "webcrypto" or a "pure-js" implementation if webcrypto is not available.
+
+## Dependencies
+
+1. The ChaCha20-Poly1305 cipher is not supported via WebCrypto -- so we utilise `@stablelib/chacha20-poly1305` to provide this functionality.
+2. To handle X509 certificate validation we utilise `@peculiar/x509`
+3. Optionally a few other crypto dependencies are used when using the `pure-js` implementation. These can be excluded when using WebCrypto.
+
+## Supported Crypto Suites & Versions
+
+### TLS
+- TLS 1.2
+- TLS 1.3
+
+### Curves
+- X25519 (only on NodeJs -- not supported in the browser)
+- P-256 (SECP256R1)
+- P-384 (SECP384R1)
+
+### Signature Algorithms
+- RSA-PSS-RSAE-SHA256
+- ECDSA-SECP256R1-SHA256
+- ECDSA-SECP256R1-SHA384
+- ECDSA-SECP384R1-SHA256
+- ECDSA-SECP384R1-SHA384
+- RSA-PKCS1-SHA256
+- RSA-PKCS1-SHA384
+- RSA-PKCS1-SHA512
+- RSA-PKCS1-SHA1
+
+### Cipher Suites (TLS 1.3)
+- AES-128-GCM-SHA256
+- AES-256-GCM-SHA384
+- CHACHA20-POLY1305-SHA256
+
+### Cipher Suites (TLS 1.2)
+- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
+- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
+- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
+- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
+- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
+- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
+- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
+- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
+
+### Certificates
+- The entire Mozilla CA store is supported
+- A few additional certificates have also been added. See `src/utils/root-ca.ts`
+- We also implement fetching intermediate certificates via AIA fetching. Any fetched certificates are also then verified against the root CA store.
+
+## Install
+
+Edge version:
+``` sh
+npm i git+https://github.com/reclaimprotocol/tls
+```
+
+## Set Crypto Implementation
+
+When on the browser, NodeJS or another NodeJS like runtime (such as Bun), you can set the crypto implementation to use the native `webcrypto` API. This is the most performant way to use this library.
+``` ts
+import { setCryptoImplementation } from '@reclaimprotocol/tls'
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto'
+
+setCryptoImplementation(webcryptoCrypto)
+```
+
+If webcrypto is not available, you can use the `pure-js` implementation. This is slower, but works in all JavaScript environments -- even JavascriptCore.
+``` ts
+import { setCryptoImplementation } from '@reclaimprotocol/tls'
+import { pureJsCrypto } from '@reclaimprotocol/tls/pure-js'
+
+setCryptoImplementation(pureJsCrypto)
+```
+
+## Example Usage
+
+After you've set the crypto implementation, you can use the TLS client like this:
+
+``` ts
+import { Socket } from 'net'
+import { makeTLSClient, uint8ArrayToBinaryStr } from '@reclaimprotocol/tls'
+
+const socket = new Socket()
+const host = 'www.google.com'
+const port = 443
+
+const tls = makeTLSClient({
+	host,
+	// verify the server's certificate
+	// disable when using self-signed certificates
+	// or if you don't care about the authenticity
+	// of the server
+	verifyServerCertificate: true,
+	// only use the following cipher suites
+	// leave undefined to use all supported cipher suites
+	cipherSuites: [
+		'TLS_CHACHA20_POLY1305_SHA256'
+		// ... other suites
+	],
+	// write raw bytes to the socket
+	async write({ header, content }) {
+		socket.write(header)
+		socket.write(content)
+	},
+	onHandshake() {
+		console.log('handshake completed successfully')
+		// write encrypted data to the socket
+		const getReq = `GET / HTTP/1.1\r\nHost: ${host}\r\n\r\n`
+		tls.write(Buffer.from(getReq))
+	},
+	onApplicationData(plaintext) {
+		const str = uint8ArrayToBinaryStr(plaintext)
+		console.log('received application data: ', str)
+	},
+	onTlsEnd(error) {
+		console.error('TLS connect ended: ', error)
+	}
+})
+
+socket.on('data', tls.handleReceivedBytes)
+
+// start handshake as soon as the socket connects
+socket.on('connect', () => tls.startHandshake())
+
+// use the TCP socket to connect to the server
+socket.connect({ host, port })
+```
+
+### Misc API Usage
+
+Handle a Session Ticket & Resume Session with a PSK
+``` ts
+const tlsClient = makeTlsClient({
+	// ... other options
+	onSessionTicket(ticket) {
+		// get a PSK (pre-shared key) from the session ticket
+		const psk = tls.getPskFromTicket(ticket)
+		// this can be used to resume a session
+		// if disconnected, using
+		// tls.startHandshake({ psk })
+	}
+})
+```
+
+Handle received certificates
+``` ts
+const tlsClient = makeTlsClient({
+	// ... other options
+
+	// handle received certificates
+	// (if you want to for some reason)
+	onRecvCertificates({ certificates }) {
+		// do something I guess?
+	}
+})
+```
+
+Use the TLS KeyUpdate method to update the traffic keys. This sends a KeyUpdate message to the server & generates a fresh set of keys to encrypt/decrypt data. The server will then respond with a KeyUpdate message of its own. This is useful for forward secrecy.
+```ts
+await tls.updateTrafficKeys()
+```
+
+## Testing
+
+Once you clone the repository, install dependencies via `npm i`, you can run the tests using:
+```bash
+npm run test:webcrypto
+```
+to test the WebCrypto implementation, or
+```bash
+npm run test:pure-js
+```
+to test the PureJS implementation.
+
+If you want to test a connection to a host, you can use the `handshake.ts` script. This script will connect to the specified host and port, perform a TLS handshake, and log the result.
+```bash
+npm run handshake -- --host www.google.com
+```
+
+if you want to test `javascriptcore` compatibility, you can run the [jsc](/src/tests/jsc.test_mac.ts) test. This will run the tests in a JavaScriptCore environment, which is useful for testing compatibility with an ECMAScript environment that does not support WebCrypto.
+Before you run the `jsc` test, make sure you have the `jsc` binary installed on your system & have built the `jsc` file using the `npm run build:jsc` command.
+
+## Updating CA certificates
+```bash
+npm run update:root-ca
+```
+
+## Contributing to Our Project
+
+We're excited that you're interested in contributing to our project! Before you get started, please take a moment to review the following guidelines.
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](https://github.com/reclaimprotocol/.github/blob/main/Code-of-Conduct.md) to ensure a positive and inclusive environment for all contributors.
+
+## Security
+
+If you discover any security-related issues, please refer to our [Security Policy](https://github.com/reclaimprotocol/.github/blob/main/SECURITY.md) for information on how to responsibly disclose vulnerabilities.
+
+## Contributor License Agreement
+
+Before contributing to this project, please read and sign our [Contributor License Agreement (CLA)](https://github.com/reclaimprotocol/.github/blob/main/CLA.md).
+
+## Indie Hackers
+
+For Indie Hackers: [Check out our guidelines and potential grant opportunities](https://github.com/reclaimprotocol/.github/blob/main/Indie-Hackers.md)
+
+## License
+
+This project is licensed under a [custom license](https://github.com/reclaimprotocol/.github/blob/main/LICENSE). By contributing to this project, you agree that your contributions will be licensed under its terms.
+
+Thank you for your contributions!

package/lib/crypto/common.d.ts

@@ -0,0 +1,3 @@
+import type { PublicKey as RSAPubKey } from 'micro-rsa-dsa-dh/rsa.js';
+export declare function parseRsaPublicKeyFromAsn1(asn1: Uint8Array): RSAPubKey;
+export declare function bufToUint8Array(buf: ArrayBuffer | Uint8Array): Uint8Array;

package/lib/crypto/common.js

@@ -0,0 +1,26 @@
+import { OriginatorPublicKey } from '@peculiar/asn1-cms';
+import { RSAPublicKey } from '@peculiar/asn1-rsa';
+import { AsnParser } from '@peculiar/asn1-schema';
+export function parseRsaPublicKeyFromAsn1(asn1) {
+    const parsed = AsnParser.parse(asn1, OriginatorPublicKey);
+    const rsaPubKey = AsnParser.parse(parsed.publicKey, RSAPublicKey);
+    return {
+        e: bufToBigint(bufToUint8Array(rsaPubKey.publicExponent)),
+        n: bufToBigint(bufToUint8Array(rsaPubKey.modulus)),
+    };
+}
+export function bufToUint8Array(buf) {
+    if (buf instanceof Uint8Array) {
+        return buf;
+    }
+    return new Uint8Array(buf);
+}
+const BITS = 8n;
+function bufToBigint(buf) {
+    let ret = 0n;
+    for (const i of buf.values()) {
+        const bi = BigInt(i);
+        ret = (ret << BITS) + bi;
+    }
+    return ret;
+}

package/lib/crypto/index.d.ts

@@ -0,0 +1,3 @@
+import type { Crypto } from '../types/index.ts';
+export declare const crypto: Crypto<unknown>;
+export declare function setCryptoImplementation(impl: Crypto<unknown>): void;

package/lib/crypto/index.js

@@ -0,0 +1,4 @@
+export const crypto = {};
+export function setCryptoImplementation(impl) {
+    Object.assign(crypto, impl);
+}

package/lib/crypto/insecure-rand.d.ts

@@ -0,0 +1 @@
+export declare function randomBytes(length: number): Uint8Array<ArrayBuffer>;

package/lib/crypto/insecure-rand.js

@@ -0,0 +1,9 @@
+export function randomBytes(length) {
+    // not the most secure but has to do for an env
+    // without crypto.getRandomValues
+    const bytes = new Uint8Array(length);
+    for (let i = 0; i < length; i++) {
+        bytes[i] = Math.floor(Math.random() * 256) % 256;
+    }
+    return bytes;
+}

package/lib/crypto/pure-js.d.ts

@@ -0,0 +1,2 @@
+import type { Crypto } from '../types/index.ts';
+export declare const pureJsCrypto: Crypto<Uint8Array>;

package/lib/crypto/pure-js.js

@@ -0,0 +1,144 @@
+import { cbc as aesCbc, gcm as aesGcm } from '@noble/ciphers/aes';
+import { chacha20poly1305 } from '@noble/ciphers/chacha';
+import { x25519 } from '@noble/curves/ed25519';
+import { p256, p384 } from '@noble/curves/nist';
+import { extract } from '@noble/hashes/hkdf';
+import { hmac } from '@noble/hashes/hmac';
+import { sha1 } from '@noble/hashes/legacy';
+import { sha256, sha384 } from '@noble/hashes/sha2';
+import { OriginatorPublicKey } from '@peculiar/asn1-cms';
+import { AsnParser } from '@peculiar/asn1-schema';
+import { mgf1, PKCS1_KEM, PKCS1_SHA256, PKCS1_SHA384, PKCS1_SHA512, PSS } from 'micro-rsa-dsa-dh/rsa.js';
+import { asciiToUint8Array, concatenateUint8Arrays } from "../utils/generics.js";
+import { bufToUint8Array, parseRsaPublicKeyFromAsn1 } from "./common.js";
+import { randomBytes } from "./insecure-rand.js";
+const CURVE_MAP = {
+    'P-256': p256,
+    'P-384': p384,
+    'X25519': x25519
+};
+const AUTH_CIPHER_MAP = {
+    'AES-128-GCM': aesGcm,
+    'AES-256-GCM': aesGcm,
+    'CHACHA20-POLY1305': chacha20poly1305,
+};
+const HASH_MAP = {
+    'SHA-1': sha1,
+    'SHA-256': sha256,
+    'SHA-384': sha384
+};
+const AUTH_TAG_BYTE_LENGTH = 16;
+export const pureJsCrypto = {
+    importKey(_, raw) {
+        return raw;
+    },
+    exportKey(key) {
+        return key;
+    },
+    async generateKeyPair(alg) {
+        const curve = CURVE_MAP[alg];
+        const secretKey = curve.utils.randomSecretKey();
+        if (alg === 'P-256' || alg === 'P-384') {
+            // @ts-expect-error: need uncompressed public key for TLS
+            const pubKey = curve.getPublicKey(secretKey, false);
+            return { privKey: secretKey, pubKey };
+        }
+        return { privKey: secretKey, pubKey: curve.getPublicKey(secretKey) };
+    },
+    calculateSharedSecret(alg, privateKey, publicKey) {
+        const curve = CURVE_MAP[alg];
+        if (!curve) {
+            throw new Error(`Unsupported algorithm: ${alg}`);
+        }
+        const secret = curve.getSharedSecret(privateKey, publicKey);
+        if (alg === 'P-256' || alg === 'P-384') {
+            // from noble curves, the secret is packed with 1 y-coordinate byte
+            // so we need to remove the first byte
+            return secret.slice(1); // remove the first byte
+        }
+        return secret;
+    },
+    randomBytes: randomBytes,
+    asymmetricEncrypt(cipherSuite, { publicKey, data }) {
+        if (cipherSuite !== 'RSA-PCKS1_5') {
+            throw new Error(`Unsupported cipher suite ${cipherSuite}`);
+        }
+        return PKCS1_KEM.encrypt(parseRsaPublicKeyFromAsn1(publicKey), data);
+    },
+    encrypt(cipherSuite, { key, iv, data }) {
+        if (cipherSuite !== 'AES-128-CBC') {
+            throw new Error(`Unsupported cipher suite: ${cipherSuite}`);
+        }
+        const cipher = aesCbc(key, iv, { disablePadding: true });
+        return cipher.encrypt(data);
+    },
+    decrypt(cipherSuite, { key, iv, data }) {
+        if (cipherSuite !== 'AES-128-CBC') {
+            throw new Error(`Unsupported cipher suite: ${cipherSuite}`);
+        }
+        const cipher = aesCbc(key, iv, { disablePadding: true });
+        const decrypted = cipher.decrypt(data);
+        return decrypted;
+    },
+    authenticatedEncrypt(cipherSuite, { key, iv, data, aead }) {
+        const cipher = AUTH_CIPHER_MAP[cipherSuite](key, iv, aead);
+        const ciphertext = cipher.encrypt(data);
+        return {
+            ciphertext: ciphertext.slice(0, -AUTH_TAG_BYTE_LENGTH),
+            authTag: ciphertext.slice(-AUTH_TAG_BYTE_LENGTH),
+        };
+    },
+    authenticatedDecrypt(cipherSuite, { key, iv, data, aead, authTag }) {
+        const cipher = AUTH_CIPHER_MAP[cipherSuite](key, iv, aead);
+        const decrypted = cipher.decrypt(concatenateUint8Arrays([data, authTag]));
+        return { plaintext: decrypted };
+    },
+    verify(alg, { data, signature, publicKey }) {
+        if (alg === 'ECDSA-SECP384R1-SHA384'
+            || alg === 'ECDSA-SECP384R1-SHA256'
+            || alg === 'ECDSA-SECP256R1-SHA384'
+            || alg === 'ECDSA-SECP256R1-SHA256') {
+            const parsedPubKey = parseAsn1PublicKey(publicKey);
+            const curv = alg.includes('P-384') ? p384 : p256;
+            return curv
+                .verify(signature, data, parsedPubKey, { prehash: true, format: 'der' });
+        }
+        if (alg === 'RSA-PSS-SHA256') {
+            const rsaPubKey = parseRsaPublicKeyFromAsn1(publicKey);
+            const pss = PSS(sha256, mgf1(sha256), 32);
+            return pss.verify(rsaPubKey, data, signature);
+        }
+        if (alg === 'RSA-PKCS1-SHA256') {
+            const rsaPubKey = parseRsaPublicKeyFromAsn1(publicKey);
+            return PKCS1_SHA256.verify(rsaPubKey, data, signature);
+        }
+        if (alg === 'RSA-PKCS1-SHA384') {
+            const rsaPubKey = parseRsaPublicKeyFromAsn1(publicKey);
+            return PKCS1_SHA384.verify(rsaPubKey, data, signature);
+        }
+        if (alg === 'RSA-PKCS1-SHA512') {
+            const rsaPubKey = parseRsaPublicKeyFromAsn1(publicKey);
+            return PKCS1_SHA512.verify(rsaPubKey, data, signature);
+        }
+        throw new Error(`Unsupported signature algorithm: ${alg}`);
+    },
+    hash(alg, data) {
+        const hasher = HASH_MAP[alg].create();
+        hasher.update(data);
+        return hasher.digest();
+    },
+    hmac(alg, key, data) {
+        return hmac(HASH_MAP[alg], key, data);
+    },
+    extract(alg, hashLength, ikm, salt) {
+        salt = typeof salt === 'string' ? asciiToUint8Array(salt) : salt;
+        if (!salt.length) {
+            salt = new Uint8Array(hashLength).fill(0);
+        }
+        return extract(HASH_MAP[alg], ikm, salt);
+    }
+};
+function parseAsn1PublicKey(pubKey) {
+    const parsed = AsnParser.parse(pubKey, OriginatorPublicKey);
+    return bufToUint8Array(parsed.publicKey);
+}

package/lib/crypto/webcrypto.d.ts

@@ -0,0 +1,3 @@
+import type { webcrypto as WebCrypto } from 'crypto';
+import type { Crypto } from '../types/crypto.ts';
+export declare const webcryptoCrypto: Crypto<WebCrypto.CryptoKey>;