ML-KEM.NetCore.Browser

ML-KEM.NetCore.Browser is a pure JavaScript companion package to ML-KEM.NetCore, focused on ML-KEM-768 compatibility in browser and Node.js runtimes.

The package includes high-level KEM APIs (generateKeyPair, encapsulate, decapsulate) and lower-level modules for polynomial math, packing, NTT, and CPA-PKE internals.

Table of contents

• Requirements
• Installation
  • npm
  • NuGet
  • Browser script bundle
• Quick start
  • ESM usage
  • Browser global usage
• API reference
  • generateKeyPair(seed64?)
  • encapsulate(publicKey, seed32?)
  • decapsulate(secretKey, ciphertext)
  • setRandomBytesProvider(provider)
  • MLKEM_768 parameter sizes
• Deterministic/vector workflows
• Validation and testing
• Development
• Interoperability notes
• Security notes
• License

Requirements

• Runtime: modern browser or Node.js with ES modules.
• No native addons required.
• Project package type: "module".

Installation

npm

npm install ml-kem.netcore.browser

NuGet

dotnet add package ML-KEM.NetCore.Browser

Browser script bundle

Build the one-file bundle:

npm run build:bundle

Then include it in your page:

<script src="./dist/ML-KEM.NetCore.Browser.js"></script>
<script>
  const { generateKeyPair, encapsulate, decapsulate } = window.MLKEMNetCoreBrowser;
</script>

Quick start

ESM usage

import { generateKeyPair, encapsulate, decapsulate } from 'ml-kem.netcore.browser';

const { publicKey, secretKey } = await generateKeyPair();
const { ciphertext, sharedSecret: senderSecret } = await encapsulate(publicKey);
const { sharedSecret: receiverSecret } = await decapsulate(secretKey, ciphertext);

console.log(senderSecret.length, receiverSecret.length); // 32, 32

Browser global usage

<script src="./dist/ML-KEM.NetCore.Browser.js"></script>
<script>
  (async () => {
    const { generateKeyPair, encapsulate, decapsulate } = window.MLKEMNetCoreBrowser;

    const { publicKey, secretKey } = await generateKeyPair();
    const { ciphertext, sharedSecret: senderSecret } = await encapsulate(publicKey);
    const { sharedSecret: receiverSecret } = await decapsulate(secretKey, ciphertext);

    console.log(senderSecret, receiverSecret);
  })();
</script>

API reference

All binary values are Uint8Array.

generateKeyPair(seed64?)

async function generateKeyPair(seed64?: Uint8Array): Promise<{
  publicKey: Uint8Array;
  secretKey: Uint8Array;
}>;

• Without seed64, key generation uses the configured random source.
• With seed64, deterministic derivation is used (intended for vectors/tests).

encapsulate(publicKey, seed32?)

async function encapsulate(publicKey: Uint8Array, seed32?: Uint8Array): Promise<{
  ciphertext: Uint8Array;
  sharedSecret: Uint8Array;
}>;

• publicKey must be a Uint8Array with ML-KEM-768 public key length.
• Optional seed32 enables deterministic encapsulation for vector scenarios.

decapsulate(secretKey, ciphertext)

async function decapsulate(secretKey: Uint8Array, ciphertext: Uint8Array): Promise<{
  sharedSecret: Uint8Array;
}>;

• Both arguments must be Uint8Array values.
• Returns the receiver shared secret.

setRandomBytesProvider(provider)

function setRandomBytesProvider(provider: (length: number) => Uint8Array): void;

• Overrides random byte generation used internally.
• Useful for deterministic testing harnesses and controlled environments.

MLKEM_768 parameter sizes

const MLKEM_768 = {
  publicKeyBytes: 1184,
  secretKeyBytes: 2400,
  ciphertextBytes: 1088,
  sharedSecretBytes: 32,
  // ...other structural parameters
};

Import from:

import { MLKEM_768 } from 'ml-kem.netcore.browser';
// or: import { MLKEM_768 } from 'ml-kem.netcore.browser/params';

Deterministic/vector workflows

This package supports deterministic pathways used for fixture generation and cross-language verification:

• generateKeyPair(seed64) for deterministic key derivation.
• encapsulate(publicKey, seed32) for deterministic encapsulation.

Reference fixture:

• test/vectors/mlkem768-fixture.json

Validation and testing

Run the test suite:

npm test

Dry-run publish contents:

npm run pack:check

Tests include:

• ML-KEM round-trip behavior
• CPA-PKE layer checks
• Cross-language deterministic vector validation

Development

Build browser bundle

npm run build:bundle

Main implementation modules

• High-level API:
  • src/index.js
  • src/mlkem.js
• Core primitives:
  • src/params.js
  • src/random.js
  • src/sha3.js
  • src/shake.js
  • src/keccak-f1600.js
  • src/sponge.js
  • src/utils.js
  • src/modq.js
  • src/poly.js
  • src/polyvec.js
  • src/ntt.js
  • src/packing.js
  • src/cpapke.js
• Vendored core:
  • src/vendor/mlkem/*

Interoperability notes

• This package is intended to maintain byte-level interoperability with ML-KEM.NetCore for ML-KEM-768 workflows.
• Keep parameter set and serialized sizes aligned between communicating peers.
• Prefer deterministic methods only for test vectors and reproducibility.

Security notes

• Treat secret material (secretKey, sharedSecret) as sensitive and keep lifetimes short.
• Clear transient buffers in application code when possible.
• Validate all external key/ciphertext lengths before calling KEM operations.
• For high-assurance use, perform an independent cryptographic and implementation review.

License

MIT. See LICENSE.