falcon/
lib.rs

1//! # falcon — Post-Quantum Digital Signatures
2//!
3//! Native Rust implementation of the **Falcon** lattice-based signature
4//! scheme, ported from the [C reference](https://falcon-sign.info/) by
5//! Thomas Pornin. Falcon is selected by NIST for post-quantum
6//! standardization.
7//!
8//! ## Quick Start
9//!
10//! ```rust
11//! use falcon::safe_api::{FalconKeyPair, FalconSignature};
12//!
13//! // Generate a Falcon-512 key pair (logn=9)
14//! let kp = FalconKeyPair::generate(9).unwrap();
15//!
16//! // Sign a message
17//! let sig = kp.sign(b"Hello, post-quantum world!").unwrap();
18//!
19//! // Verify the signature
20//! FalconSignature::verify(sig.to_bytes(), kp.public_key(), b"Hello, post-quantum world!").unwrap();
21//! ```
22//!
23//! ## Key Serialization
24//!
25//! Keys can be exported to bytes for storage and reconstructed:
26//!
27//! ```rust
28//! # use falcon::safe_api::FalconKeyPair;
29//! let kp = FalconKeyPair::generate(9).unwrap();
30//!
31//! // Export
32//! let private_key = kp.private_key().to_vec();  // 1281 bytes
33//! let public_key = kp.public_key().to_vec();     // 897 bytes
34//!
35//! // Import from both keys
36//! let restored = FalconKeyPair::from_keys(&private_key, &public_key).unwrap();
37//!
38//! // Or import from private key only (recomputes public key)
39//! let restored2 = FalconKeyPair::from_private_key(&private_key).unwrap();
40//! assert_eq!(public_key, restored2.public_key());
41//! ```
42//!
43//! ## Signature Serialization
44//!
45//! ```rust
46//! # use falcon::safe_api::{FalconKeyPair, FalconSignature};
47//! let kp = FalconKeyPair::generate(9).unwrap();
48//! let sig = kp.sign(b"msg").unwrap();
49//!
50//! // Export signature bytes (for storage, transmission, etc.)
51//! let sig_bytes: Vec<u8> = sig.into_bytes();
52//!
53//! // Import signature bytes
54//! let sig2 = FalconSignature::from_bytes(sig_bytes);
55//! ```
56//!
57//! ## Security Levels
58//!
59//! | `logn` | Variant | NIST Level | Private Key | Public Key | Signature |
60//! |--------|---------|------------|-------------|------------|-----------|
61//! | 9 | Falcon-512 | I | 1281 B | 897 B | ~666 B |
62//! | 10 | Falcon-1024 | V | 2305 B | 1793 B | ~1280 B |
63//!
64//! ## Architecture
65//!
66//! - **[`safe_api`]** — High-level SDK: key generation, signing, verification,
67//!   serialization. **Start here.**
68//! - **[`falcon`]** — Low-level C-equivalent API for advanced use cases
69//!   (streamed signing, expanded keys, custom signature formats).
70//! - **Internal modules**: `shake`, `fpr`, `fft`, `codec`, `rng`, `keygen`,
71//!   `sign`, `vrfy`, `common` — faithful ports of the C reference.
72//!
73//! ## Features
74//!
75//! - `std` *(default)* — Enables OS-level entropy via `/dev/urandom`.
76//! - Without `std` — Compiles for `no_std` environments (embedded, WASM).
77//!   Use [`FalconKeyPair::generate_deterministic`](safe_api::FalconKeyPair::generate_deterministic)
78//!   with your own entropy source.
79
80#![no_std]
81#![allow(
82    clippy::needless_range_loop,
83    clippy::manual_range_contains,
84    clippy::identity_op,
85    clippy::excessive_precision,
86    clippy::too_many_arguments,
87    clippy::unnecessary_cast,
88    non_snake_case,
89    non_upper_case_globals,
90    dead_code
91)]
92
93#[cfg(feature = "std")]
94extern crate std;
95
96extern crate alloc;
97
98pub mod codec;
99pub mod common;
100pub mod falcon;
101pub mod fft;
102pub mod fpr;
103pub mod keygen;
104pub mod rng;
105pub mod safe_api;
106pub mod shake;
107pub mod sign;
108pub mod vrfy;
falcon/lib.rs

falcon/
lib.rs
