ntrust_native/lib.rs
1//!
2//! A safe pure-rust implementation of the NTRU post-quantum scheme.
3//!
4//! * NTRU is a lattice-based key encapsulation mechanism (KEM)
5//! * The implementation is based on the NTRU reference implementation of NIST round 3
6//! * The implementation does not utilize any concurrency techniques (SIMD/threading/…, except maybe auto-vectorization on your CPU)
7//! * It passes the 100 testcases of the C reference implementation
8//! * It implements the NTRU-HPS (Hoffstein-Pipher-Silverman) scheme in three variants
9//! * It implements the NTRU-HRSS (Hülsing-Rijneveld-Schanck) scheme in one variant
10//! * The implementation is constant-time on software instruction level
11//! * The random number generator is based on AES128 in counter mode
12//!
13//! ## Who should use it?
14//!
15//! Anyone, how wants to use the NTRU scheme to negotiate a key between two parties.
16//!
17//! ## How does one use it?
18//!
19//! Add this to your `Cargo.toml`:
20//! ```toml
21//! [dependencies]
22//! ntrust-native = "1.0"
23//! ```
24//!
25//! To use a specific NTRU variant, you need to import it with the corresponding feature flag:
26//!
27//! ```toml
28//! [dependencies]
29//! ntrust-native = { version = "1.0", features = ["ntruhrss701"] }
30//! ```
31//!
32//!
33//! The `simple` example illustrates the API:
34//! ```rust
35//! use ntrust_native::{AesState, crypto_kem_keypair, crypto_kem_enc, crypto_kem_dec};
36//! use ntrust_native::{CRYPTO_PUBLICKEYBYTES, CRYPTO_SECRETKEYBYTES, CRYPTO_CIPHERTEXTBYTES, CRYPTO_BYTES};
37//!
38//! fn main() -> Result<(), Box<dyn std::error::Error>> {
39//! let mut rng = AesState::new();
40//! let mut pk = [0u8; CRYPTO_PUBLICKEYBYTES];
41//! let mut sk = [0u8; CRYPTO_SECRETKEYBYTES];
42//! crypto_kem_keypair(&mut pk, &mut sk, &mut rng)?;
43//!
44//! let mut ct = [0u8; CRYPTO_CIPHERTEXTBYTES];
45//! let mut ss_bob = [0u8; CRYPTO_BYTES];
46//! crypto_kem_enc(&mut ct, &mut ss_bob, &pk, &mut rng)?;
47//!
48//! let mut ss_alice = [0u8; CRYPTO_BYTES];
49//! crypto_kem_dec(&mut ss_alice, &ct, &sk)?;
50//!
51//! assert_eq!(ss_alice, ss_bob);
52//! Ok(())
53//! }
54//! ```
55//!
56//! ## How does one run it?
57//!
58//! This library comes with two examples:
59//!
60//! ```bash
61//! $ cargo run --example simple
62//! ```
63//!
64//! The output annotates messages with Alice/Bob to illustrate which data is processed by which party.
65//! The `katkem` example implements the classic request/response file structure which is part of the NIST PQC framework.
66//!
67//! ```bash
68//! $ cargo run --example katkem PQCkemKAT_935.req PQCkemKAT_935.rsp
69//! $ cargo run --example katkem PQCkemKAT_935.rsp
70//! ```
71//!
72//! The different variants (`ntruhps2048509, ntruhps2048677, ntruhps4096821, ntruhrss701`) can be enabled through feature flags:
73//!
74//! ```bash
75//! $ cargo run --example katkem --features ntruhrss701 -- PQCkemKAT_1450.req PQCkemKAT_1450.rsp
76//! ```
77//!
78//! `ntruhps2048509` is the default variant. You cannot enable two variants simultaneously.
79//!
80mod api;
81mod cmov;
82mod crypto_sort_int32;
83mod kem;
84mod owcpa;
85mod pack3;
86mod packq;
87mod params;
88mod poly;
89mod poly_lift;
90mod poly_mod;
91mod poly_r2_inv;
92mod poly_rq_mul;
93mod poly_s3_inv;
94mod rng;
95mod sample;
96mod sample_iid;
97
98pub use crate::api::*;
99pub use crate::kem::*;
100pub use crate::rng::{AesState, RNGState};