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