dilithium-crystals-js

dilithium-crystals-js is a JavaScript implementation of the Dilithium post-quantum cryptographic signature scheme. This package provides a unified API for both Node.js and browser environments, offering robust quantum-resistant digital signatures. It includes TypeScript declarations (.d.ts files) for improved IDE support, type checking, and autocompletion.

Features

- Implements Dilithium, a lattice-based digital signature scheme
- Supports all four parameter sets of Dilithium
- Works in both Node.js and browser environments
- Easy-to-use API for key generation, signing, and verification

Installation

You can install the package using npm:

``bash
npm install dilithium-crystals-js
`

Usage

$3

In a Node.js environment, you can use the package as follows:

`javascript
const Dilithium = require("dilithium-crystals-js");

Dilithium.then((dilithium) => {
// Generate keys
const kind = 2; // Dilithium2
const { publicKey, privateKey } = dilithium.generateKeys(kind);

// Sign a message
const message = Buffer.from("Hello, Dilithium!");
const { signature } = dilithium.sign(message, privateKey, kind);

// Verify the signature
const verificationResult = dilithium.verify(
signature,
message,
publicKey,
kind
);

console.log(
"Verification result:",
verificationResult.result === 0 ? "Valid" : "Invalid"
);
});
`

$3

To use dilithium-crystals-js in a browser:

1. Ensure dilithium.wasm is in your public directory.
2. Adjust the WASM fetch path in ./browser/index.js, by default it's set to node_modules/dilithium-crystals-js/kyber.wasm:

`javascript
async function fetchWasm() {
return await (await fetch("/path/to/your/dilithium.wasm")).arrayBuffer();
}
`

Replace /path/to/your/dilithium.wasm with the actual path where you serve the WASM file.
Note: Configure your server to serve WASM files with application/wasm MIME type.

`javascript
import { createDilithium } from "./node_modules/dilithium-crystals-js/dist/dilithium.min.js";

async function main() {
let dilithium = await createDilithium();

console.log("Dilithium initialized:", dilithium);

// Generate keys

const kind = 2; // Dilithium2
const { publicKey, privateKey } = dilithium.generateKeys(kind);

// Sign a message
const message = new TextEncoder().encode("Hello, Dilithium!");
const { signature } = dilithium.sign(message, privateKey, kind);

// Verify the signature
const verificationResult = dilithium.verify(
signature,
message,
publicKey,
kind
);

console.log(
"Verification result:",
verificationResult.result === 0 ? "Valid" : "Invalid"
);
}

main();
`

Note: Make sure to properly configure your build process to handle ES6 modules and to include the WASM file in your public directory.

API Reference

$3

Generates a new key pair.

- kind: Number (0-3) specifying the Dilithium parameter set.
- seed (optional): A seed for deterministic key generation.

Returns: { publicKey, privateKey }

$3

Signs a message.

- message: Uint8Array or Buffer containing the message to sign.
- privateKey: The private key generated by generateKeys.
- kind: Number (0-3) specifying the Dilithium parameter set.

Returns: { signature, signatureLength }`

$3

Verifies a signature.

- signature: The signature to verify.
- message: The original message that was signed.
- publicKey: The public key corresponding to the private key used for signing.
- kind: Number (0-3) specifying the Dilithium parameter set.

Returns: An object containing the verification result and other metadata.

Dilithium Parameter Sets

dilithium-crystals-js supports all four parameter sets of the Dilithium signature scheme:

- 0: Dilithium2 (NIST security level 2)
- 1: Dilithium3 (NIST security level 3)
- 2: Dilithium5 (NIST security level 5)
- 3: Dilithium2-AES (NIST security level 2, AES variant)

Choose the appropriate parameter set based on your security requirements.