ed25519_compact/lib.rs
1//! A compact Ed25519 and X25519 implementation for Rust.
2//!
3//! * Formally-verified Curve25519 field arithmetic
4//! * `no_std`-friendly
5//! * WebAssembly-friendly
6//! * Fastly Compute-friendly
7//! * Lightweight
8//! * Zero dependencies if randomness is provided by the application
9//! * Only one portable dependency (`getrandom`) if not
10//! * Supports incremental signatures (streaming API)
11//! * Safe and simple Rust interface.
12//!
13//! Example usage:
14//!
15//! ```rust
16//! use ed25519_compact::*;
17//!
18//! // A message to sign and verify.
19//! let message = b"test";
20//!
21//! // Generates a new key pair using a random seed.
22//! // A given seed will always produce the same key pair.
23//! let key_pair = KeyPair::from_seed(Seed::generate());
24//!
25//! // Computes a signature for this message using the secret part of the key pair.
26//! let signature = key_pair.sk.sign(message, Some(Noise::generate()));
27//!
28//! // Verifies the signature using the public part of the key pair.
29//! key_pair
30//! .pk
31//! .verify(message, &signature)
32//! .expect("Signature didn't verify");
33//!
34//! // Verification of a different message using the same signature and public key fails.
35//! key_pair
36//! .pk
37//! .verify(b"A different message", &signature)
38//! .expect_err("Signature shouldn't verify");
39//!
40//! // All these structures can be viewed as raw bytes simply by dereferencing them:
41//! let signature_as_bytes: &[u8] = signature.as_ref();
42//! println!("Signature as bytes: {:?}", signature_as_bytes);
43//! ```
44//!
45//! ## Incremental API example usage
46//!
47//! Messages can also be supplied as multiple parts (streaming API) in order to
48//! handle large messages without using much memory:
49//!
50//! ```rust
51//! use ed25519_compact::*;
52//!
53//! /// Creates a new key pair.
54//! let kp = KeyPair::generate();
55//!
56//! /// Create a state for an incremental signer.
57//! let mut st = kp.sk.sign_incremental(Noise::default());
58//!
59//! /// Feed the message as any number of chunks, and sign the concatenation.
60//! st.absorb("mes");
61//! st.absorb("sage");
62//! let signature = st.sign();
63//!
64//! /// Create a state for an incremental verifier.
65//! let mut st = kp.pk.verify_incremental(&signature).unwrap();
66//!
67//! /// Feed the message as any number of chunks, and verify the concatenation.
68//! st.absorb("mess");
69//! st.absorb("age");
70//! assert!(st.verify().is_ok());
71//! ```
72//!
73//! Cargo features:
74//!
75//! * `self-verify`: after having computed a new signature, verify that is it
76//! valid. This is slower, but improves resilience against fault attacks. It
77//! is enabled by default on WebAssembly targets.
78//! * `std`: disables `no_std` compatibility in order to make errors implement
79//! the standard `Error` trait.
80//! * `random` (enabled by default): adds `Default` and `generate`
81//! implementations to the `Seed` and `Noise` objects, in order to securely
82//! create random keys and noise.
83//! * `traits`: add support for the traits from the ed25519 and signature
84//! crates.
85//! * `pem`: add support for importing/exporting keys as OpenSSL-compatible PEM
86//! files.
87//! * `blind-keys`: add support for key blinding.
88//! * `opt_size`: Enable size optimizations (based on benchmarks, 8-15% size
89//! reduction at the cost of 6.5-7% performance).
90//! * `x25519`: Enable support for the X25519 key exchange system.
91//! * `disable-signatures`: Disable support for signatures, and only compile
92//! support for X25519.
93
94#![cfg_attr(not(feature = "std"), no_std)]
95#![allow(
96 clippy::needless_range_loop,
97 clippy::many_single_char_names,
98 clippy::unreadable_literal,
99 clippy::let_and_return,
100 clippy::needless_lifetimes,
101 clippy::cast_lossless,
102 clippy::suspicious_arithmetic_impl,
103 clippy::identity_op
104)]
105
106mod common;
107mod error;
108mod field25519;
109mod sha512;
110
111pub use crate::common::*;
112pub use crate::error::*;
113
114#[cfg(not(feature = "disable-signatures"))]
115mod ed25519;
116#[cfg(not(feature = "disable-signatures"))]
117mod edwards25519;
118
119#[cfg(not(feature = "disable-signatures"))]
120pub use crate::ed25519::*;
121
122#[cfg(feature = "x25519")]
123pub mod x25519;
124
125#[cfg(not(feature = "disable-signatures"))]
126#[cfg(feature = "pem")]
127mod pem;