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;
44pub mod field;
45
46pub mod nist;
47pub mod p256;
48pub mod p384;
49pub mod p521;
50pub mod scalar;
51pub mod x25519;
52
53pub use ed25519::{Ed25519, Ed25519Key, Ed25519VerifyKey};
54pub use p256::{EcdhP256, EcdsaP256Sha256};
55pub use p384::{EcdhP384, EcdsaP384Sha384};
56pub use x25519::X25519;
57
58/// Ontology identifiers for the schemes implemented here.
59pub const EC_IDS: &[&str] = &[
60 "x25519",
61 "ed25519",
62 "ecdh-p256",
63 "ecdsa-p256-sha256",
64 "ecdh-p384",
65 "ecdsa-p384-sha384",
66];