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/// Ontology identifiers for the schemes implemented here.
70pub const EC_IDS: &[&str] = &[
71 "x25519",
72 "ed25519",
73 "ecdh-p256",
74 "ecdsa-p256-sha256",
75 "ecdh-p384",
76 "ecdsa-p384-sha384",
77];