Dilithium-crystals-js NPM

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:

npm install dilithium-crystals-js

Usage

Node.js

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

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"
  );
});

Browser

To use dilithium-crystals-js in a browser:

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

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.

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

`dilithium.generateKeys(kind, seed?)`

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 }

`dilithium.sign(message, privateKey, kind)`

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 }

`dilithium.verify(signature, message, publicKey, kind)`

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.