The only purpose of this project is to provide an easy-to-use Typescript module that allows the Falcon implementation of the above repository to be used in TS projects with types included and with some utilities.

Overview

This project provides a TypeScript implementation of the Falcon signature scheme, along with a custom mnemonic implementation for generating, storing, and recovering Falcon keys using human-readable phrases.

Features

Falcon signature scheme implementation
Custom mnemonic implementation for Falcon keys
Key generation, signing, and verification
Mnemonic phrase generation and validation
Key recovery from mnemonic phrases
Hex and Base64 encoding/decoding utilities

Installation

This will install https://github.com/pqcsf/falcon-sign-js.

npm install

Usage

Basic Falcon Usage

import { Falcon } from './src';

// Create a Falcon instance
const falcon = new Falcon();
await falcon.init();

// Generate a key pair
await falcon.genkey();

// Get the key pair
const keypair = await falcon.getKeypair();
const publicKey = keypair.pk;
const privateKey = keypair.sk;

// Sign a message
const message = 'Hello, Falcon!';
const signature = await falcon.sign(message);

// Verify the signature
const isValid = await falcon.verify(message, signature);
console.log('Signature verification:', isValid ? 'Valid' : 'Invalid');

Mnemonic Implementation

import { generateMnemonic, mnemonicToUint8Array, uint8ArrayToMnemonic, validateMnemonic } from './src/mnemonic';
import { Falcon } from './src/falcon';

// Generate a random mnemonic
const mnemonic = generateMnemonic();
console.log('Generated mnemonic:', mnemonic);

// Convert mnemonic to seed
const seed = mnemonicToUint8Array(mnemonic);

// Create a Falcon instance
const falcon = new Falcon();
await falcon.init();

// Generate a key pair using the seed
await falcon.genkey(seed);

// Get the key pair
const keypair = await falcon.getKeypair();
const publicKey = keypair.pk;
const privateKey = keypair.sk;

// Later, recover the keys from the mnemonic
const recoveredSeed = mnemonicToUint8Array(mnemonic);
const recoveredFalcon = new Falcon();
await recoveredFalcon.init();
await recoveredFalcon.genkey(recoveredSeed);
const recoveredKeypair = await recoveredFalcon.getKeypair();

Hex and Base64 Encoding

The Falcon class provides utilities for working with hex and base64 encoded keys and signatures:

import { Falcon } from './src/falcon';

// Create a Falcon instance
const falcon = new Falcon();
await falcon.init();

// Generate a key pair
await falcon.genkey();

// Get keys in hex format
const publicKeyHex = await falcon.getPublicKeyHex();
const privateKeyHex = await falcon.getPrivateKeyHex();

// Get keys in base64 format
const publicKeyBase64 = await falcon.getPublicKeyBase64();
const privateKeyBase64 = await falcon.getPrivateKeyBase64();

// Sign a message and get the signature in hex
const message = 'Hello, Falcon!';
const signatureHex = await falcon.signHex(message);

// Verify a hex signature
const isValid = await falcon.verifyHex(message, signatureHex);

// Sign a message and get the signature in base64
const signatureBase64 = await falcon.signBase64(message);

// Verify a base64 signature
const isValidBase64 = await falcon.verifyBase64(message, signatureBase64);

// Create a public key from a private key in hex format
const derivedPublicKeyHex = await falcon.publicKeyCreateHex(privateKeyHex);

// Set a private key from hex format
const newPublicKeyHex = await falcon.setPrivateKeyHex(privateKeyHex);

// Create a public key from a private key in base64 format
const derivedPublicKeyBase64 = await falcon.publicKeyCreateBase64(privateKeyBase64);

// Set a private key from base64 format
const newPublicKeyBase64 = await falcon.setPrivateKeyBase64(privateKeyBase64);

Examples

Run the examples to see the mnemonic implementation in action:

# Run the basic example
npx ts-node example.ts

# Run the mnemonic example
npx ts-node mnemonic_example.ts

How It Works

Falcon Signature Scheme

Falcon is a lattice-based signature scheme that offers strong security with relatively small key and signature sizes. This implementation provides a TypeScript interface to the Falcon signature scheme.

Custom Mnemonic Implementation

The mnemonic implementation converts between binary data (Uint8Array) and human-readable mnemonic phrases. It uses a list of 2048 common English words, with each word representing 11 bits of entropy. A mnemonic phrase consists of 12 words, providing 132 bits of entropy, which is sufficient for Falcon keys.

The implementation includes the following functions:

uint8ArrayToMnemonic(data: Uint8Array): string - Converts a Uint8Array to a mnemonic phrase
mnemonicToUint8Array(mnemonic: string): Uint8Array - Converts a mnemonic phrase to a Uint8Array
validateMnemonic(mnemonic: string): boolean - Validates a mnemonic phrase
generateMnemonic(): string - Generates a random mnemonic phrase

Tests

Run the test suite using:

npm test

Credits

This project is a TypeScript wrapper around the falcon-sign-js library, which provides the core Falcon signature implementation. We've added TypeScript types, a custom mnemonic implementation, and additional utilities to make it easier to use in TypeScript projects.

License

MIT