TypeScript Implementation of CRYSTALS-Kyber

Warning

Do NOT use this for anything serious. I am NOT a cryptography or infosec expert. This program is purely a hobby project I started to explore low-level TS/JS coding and learn more about post-quantum cryptography.

This program is a TypeScript implementation of the post-quantum cryptographic key encapsulation mechanism known as CRYSTALS-Kyber (NIST FIPS 203). It is highly likely that this implementation is NOT secure.

I referenced the original C and TypeScript implementations, while also following the CRYSTALS-Kyber paper as closely as I could. In hindsight, I probably should have followed the NIST FIPS 203 paper instead, as it breaks down the operations in more detail and might have helped me understand the logic better.

The main difference between this version and the original TypeScript implementation is that this version uses TypedArray construct (Uint8Array and Uint16Array) instead of an Array of numbers. This is simply an implementation detail I chose to experiment with low-level bit shifting -- I haven't investigated whether it offers any tangible performance benefits.

Usage

To run this program, you can compile it to JavaScript with tsc and then run it with Node, or simply execute it using ts-node. The program is a CLI tool that allows you to generate a key pair, produce a shared secret and ciphertext, and decrypt the ciphertext. You can obtain the usage instructions by running the program without any additional arguments.

Below is an example of how this program could be used to share a secret (note that this particular implementation is NOT secure):

1. Alice generates a public key in the file publicKey and a secret key in the file secretKey:

   • npx ts-node ./crystals-kyber.ts keygen --publicKeyFile=publicKey --secretKeyFile=secretKey

2. Alice sends her public key file to Bob.

3. Bob uses Alice's public key to generate ciphertext in the file cipherText and a shared secret in the file sharedSecret:

   • npx ts-node ./crystals-kyber.ts encrypt --publicKeyFile=alicesPublicKey --cipherFile=cipherText --sharedSecretFile=sharedSecret

4. Bob sends Alice the ciphertext he generated using Alice's public key.

5. Alice uses her secret key to decrypt the ciphertext generated by Bob and obtain the shared secret:

   • npx ts-node ./crystals-kyber.ts decrypt --secretKeyFile=secretKey --cipherFile=bobsCipherText --sharedSecretFile=sharedSecret

Now Alice and Bob have the same shared secret, which they can use as a password for, e.g., AES-encrypted communication.