ic_ec/
lib.rs

1//! # ic-ec — elliptic-curve cryptography
2//!
3//! Curve25519 in two guises:
4//!
5//! * [`X25519`] — RFC 7748 key agreement.
6//! * [`Ed25519`] — RFC 8032 signatures.
7//!
8//! Both are built on a shared constant-time field implementation
9//! (`field::Fe`) with 51-bit limbs.
10//!
11//! ```
12//! use ic_ec::X25519;
13//! use ic_core::traits::KeyAgreement;
14//!
15//! let alice_sk = [0x11u8; 32];
16//! let bob_sk = [0x22u8; 32];
17//! let (mut alice_pk, mut bob_pk) = ([0u8; 32], [0u8; 32]);
18//! X25519::public_key(&alice_sk, &mut alice_pk)?;
19//! X25519::public_key(&bob_sk, &mut bob_pk)?;
20//!
21//! let (mut s1, mut s2) = ([0u8; 32], [0u8; 32]);
22//! X25519::agree(&alice_sk, &bob_pk, &mut s1)?;
23//! X25519::agree(&bob_sk, &alice_pk, &mut s2)?;
24//! assert_eq!(s1, s2);
25//! # Ok::<(), ic_core::Error>(())
26//! ```
27//!
28//! ## FIPS position
29//!
30//! Curve25519 is **not** on the FIPS 186-5 / SP 800-186 approved list for
31//! signatures, and X25519 is not an approved SP 800-56A scheme. They are here
32//! because modern protocols require them, and the ontology marks them
33//! accordingly so `ic-fips` blocks them in approved mode. The approved curves
34//! (P-256/384/521, ECDSA, ECDH) and the post-quantum FIPS 203/204 schemes are
35//! registered in the ontology with `implementation_status: Planned` — an agent
36//! querying for an approved signature scheme gets an honest "not available
37//! here" rather than a silent substitution.
38#![cfg_attr(not(feature = "std"), no_std)]
39#![forbid(unsafe_code)]
40#![deny(missing_docs)]
41#![warn(clippy::all)]
42
43pub mod ed25519;
44// GF(2^255 - 19). Five 51-bit limbs where a 64x64 multiply is cheap; ten limbs
45// of 26 and 25 bits on 32-bit RISC-V, where 128-bit arithmetic compiles to
46// branches on secret carries. `--cfg ic_limb32` selects the second anywhere, so
47// the Curve25519 vectors can be run against it on a host.
48#[cfg(not(any(target_arch = "riscv32", ic_limb32)))]
49mod field;
50#[cfg(any(target_arch = "riscv32", ic_limb32))]
51#[path = "field32.rs"]
52mod field;
53// Compiled beside the five-limb field under test, to be compared with it.
54#[cfg(all(test, not(any(target_arch = "riscv32", ic_limb32))))]
55mod field32;
56
57mod nist;
58pub mod p256;
59pub mod p384;
60pub mod p521;
61mod scalar;
62pub mod x25519;
63
64pub use ed25519::{Ed25519, Ed25519Key, Ed25519VerifyKey};
65pub use p256::{EcdhP256, EcdsaP256Sha256};
66pub use p384::{EcdhP384, EcdsaP384Sha384};
67pub use x25519::X25519;
68
69/// Build every precomputed table now, rather than on first use.
70///
71/// Under `std`, the generator tables for P-256, P-384 and P-521 and the
72/// Ed25519 basepoint tables are built the first time an operation needs them:
73/// about one scalar multiplication per curve, a few hundred microseconds in
74/// all on a host. They live in statics, so building them allocates nothing
75/// whenever it happens. What this changes is *when* the time is spent: a
76/// caller that wants its first handshake to cost what every later one does can
77/// pay it at start-up instead.
78///
79/// Safe to call more than once and from several threads: the work is done
80/// once, and a second caller waits for the first. Under `no_std` there are no
81/// tables, and this does nothing.
82pub fn prepare() {
83    use nist::gentable::HasGeneratorTable;
84    p256::P256::prepare_generator_table();
85    p384::P384::prepare_generator_table();
86    p521::P521::prepare_generator_table();
87    #[cfg(feature = "std")]
88    ed25519::prepare_tables();
89}
90
91/// Ontology identifiers for the schemes implemented here.
92pub const EC_IDS: &[&str] = &[
93    "x25519",
94    "ed25519",
95    "ecdh-p256",
96    "ecdsa-p256-sha256",
97    "ecdh-p384",
98    "ecdsa-p384-sha384",
99];
ic_ec/lib.rs

ic_ec/
lib.rs
