mirror of
https://github.com/tcsenpai/falconTS.git
synced 2025-06-04 18:45:39 +00:00
115 lines
3.3 KiB
Markdown
115 lines
3.3 KiB
Markdown
# FalconTS
|
|
|
|
A TypeScript implementation of the Falcon signature scheme with a custom mnemonic implementation for key management.
|
|
|
|
## 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
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Falcon Usage
|
|
|
|
```typescript
|
|
import { Falcon } from './src/falcon';
|
|
|
|
// 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
|
|
|
|
```typescript
|
|
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();
|
|
```
|
|
|
|
## Examples
|
|
|
|
Run the examples to see the mnemonic implementation in action:
|
|
|
|
```bash
|
|
# Run the basic example
|
|
npx ts-node src/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
|
|
|
|
## License
|
|
|
|
MIT |