elliptic_curve/
lib.rs

Help
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_auto_cfg))]
3#![doc = include_str!("../README.md")]
4#![doc(
5    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
6    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
7)]
8#![forbid(unsafe_code)]
9#![warn(
10    clippy::cast_lossless,
11    clippy::cast_possible_truncation,
12    clippy::cast_possible_wrap,
13    clippy::cast_precision_loss,
14    clippy::cast_sign_loss,
15    clippy::checked_conversions,
16    clippy::implicit_saturating_sub,
17    clippy::mod_module_files,
18    clippy::panic,
19    clippy::panic_in_result_fn,
20    clippy::unwrap_used,
21    missing_docs,
22    rust_2018_idioms,
23    unused_lifetimes,
24    unused_qualifications
25)]
26
27//! ## Usage
28//!
29//! This crate provides traits for describing elliptic curves, along with
30//! types which are generic over elliptic curves which can be used as the
31//! basis of curve-agnostic code.
32//!
33//! It's intended to be used with the following concrete elliptic curve
34//! implementations from the [`RustCrypto/elliptic-curves`] project:
35//!
36//! - [`bp256`]: brainpoolP256r1 and brainpoolP256t1
37//! - [`bp384`]: brainpoolP384r1 and brainpoolP384t1
38//! - [`k256`]: secp256k1 a.k.a. K-256
39//! - [`p224`]: NIST P-224 a.k.a. secp224r1
40//! - [`p256`]: NIST P-256 a.k.a secp256r1, prime256v1
41//! - [`p384`]: NIST P-384 a.k.a. secp384r1
42//! - [`p521`]: NIST P-521 a.k.a. secp521r1
43//!
44//! The [`ecdsa`] crate provides a generic implementation of the
45//! Elliptic Curve Digital Signature Algorithm which can be used with any of
46//! the above crates, either via an external ECDSA implementation, or
47//! using native curve arithmetic where applicable.
48//!
49//! ## Type conversions
50//!
51//! The following chart illustrates the various conversions possible between
52//! the various types defined by this crate.
53//!
54//! ![Type Conversion Map](https://raw.githubusercontent.com/RustCrypto/media/master/img/elliptic-curve/type-transforms.svg)
55//!
56//! ## `serde` support
57//!
58//! When the `serde` feature of this crate is enabled, `Serialize` and
59//! `Deserialize` impls are provided for the following types:
60//!
61//! - [`JwkEcKey`]
62//! - [`PublicKey`]
63//! - [`ScalarPrimitive`]
64//!
65//! Please see type-specific documentation for more information.
66//!
67//! [`RustCrypto/elliptic-curves`]: https://github.com/RustCrypto/elliptic-curves
68//! [`bp256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp256
69//! [`bp384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp384
70//! [`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
71//! [`p224`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p224
72//! [`p256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p256
73//! [`p384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p384
74//! [`p521`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p521
75//! [`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
76
77#[cfg(feature = "alloc")]
78#[allow(unused_imports)]
79#[macro_use]
80extern crate alloc;
81#[cfg(feature = "std")]
82extern crate std;
83
84pub mod point;
85pub mod scalar;
86
87#[cfg(feature = "dev")]
88pub mod dev;
89#[cfg(feature = "ecdh")]
90pub mod ecdh;
91#[cfg(feature = "hash2curve")]
92pub mod hash2curve;
93#[cfg(feature = "arithmetic")]
94pub mod ops;
95#[cfg(feature = "sec1")]
96pub mod sec1;
97#[cfg(feature = "arithmetic")]
98pub mod weierstrass;
99
100mod error;
101mod field;
102mod secret_key;
103
104#[cfg(feature = "arithmetic")]
105mod arithmetic;
106#[cfg(feature = "arithmetic")]
107mod public_key;
108
109#[cfg(feature = "jwk")]
110mod jwk;
111
112#[cfg(feature = "voprf")]
113mod voprf;
114
115pub use crate::{
116    error::{Error, Result},
117    field::{FieldBytes, FieldBytesEncoding, FieldBytesSize},
118    scalar::ScalarPrimitive,
119    secret_key::SecretKey,
120};
121pub use crypto_bigint as bigint;
122pub use generic_array::{self, typenum::consts};
123pub use rand_core;
124pub use subtle;
125pub use zeroize;
126
127#[cfg(feature = "arithmetic")]
128pub use {
129    crate::{
130        arithmetic::{CurveArithmetic, PrimeCurveArithmetic},
131        point::{AffinePoint, BatchNormalize, ProjectivePoint},
132        public_key::PublicKey,
133        scalar::{NonZeroScalar, Scalar},
134    },
135    ff::{self, Field, PrimeField},
136    group::{self, Group},
137};
138
139#[cfg(feature = "jwk")]
140pub use crate::jwk::{JwkEcKey, JwkParameters};
141
142#[cfg(feature = "pkcs8")]
143pub use pkcs8;
144
145#[cfg(feature = "voprf")]
146pub use crate::voprf::VoprfParameters;
147
148use core::{
149    fmt::Debug,
150    ops::{Add, ShrAssign},
151};
152use generic_array::ArrayLength;
153
154/// Algorithm [`ObjectIdentifier`][`pkcs8::ObjectIdentifier`] for elliptic
155/// curve public key cryptography (`id-ecPublicKey`).
156///
157/// <http://oid-info.com/get/1.2.840.10045.2.1>
158#[cfg(feature = "pkcs8")]
159pub const ALGORITHM_OID: pkcs8::ObjectIdentifier =
160    pkcs8::ObjectIdentifier::new_unwrap("1.2.840.10045.2.1");
161
162/// Elliptic curve.
163///
164/// This trait is intended to be impl'd by a ZST which represents a concrete
165/// elliptic curve.
166///
167/// Other traits in this crate which are bounded by [`Curve`] are intended to
168/// be impl'd by these ZSTs, facilitating types which are generic over elliptic
169/// curves (e.g. [`SecretKey`]).
170pub trait Curve: 'static + Copy + Clone + Debug + Default + Eq + Ord + Send + Sync {
171    /// Size of a serialized field element in bytes.
172    ///
173    /// This is typically the same as `Self::Uint::ByteSize` but for curves
174    /// with an unusual field modulus (e.g. P-224, P-521) it may be different.
175    type FieldBytesSize: ArrayLength<u8> + Add + Eq;
176
177    /// Integer type used to represent field elements of this elliptic curve.
178    type Uint: bigint::ArrayEncoding
179        + bigint::AddMod<Output = Self::Uint>
180        + bigint::Encoding
181        + bigint::Integer
182        + bigint::NegMod<Output = Self::Uint>
183        + bigint::Random
184        + bigint::RandomMod
185        + bigint::SubMod<Output = Self::Uint>
186        + zeroize::Zeroize
187        + FieldBytesEncoding<Self>
188        + ShrAssign<usize>;
189
190    /// Order of this elliptic curve, i.e. number of elements in the scalar
191    /// field.
192    const ORDER: Self::Uint;
193}
194
195/// Marker trait for elliptic curves with prime order.
196pub trait PrimeCurve: Curve {}
elliptic_curve/lib.rs

elliptic_curve/
lib.rs
