elliptic_curve/
lib.rs

Help
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_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, clippy::unwrap_used)]
9#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
10
11//! ## Usage
12//!
13//! This crate provides traits for describing elliptic curves, along with
14//! types which are generic over elliptic curves which can be used as the
15//! basis of curve-agnostic code.
16//!
17//! It's intended to be used with the following concrete elliptic curve
18//! implementations from the [`RustCrypto/elliptic-curves`] project:
19//!
20//! - [`bp256`]: brainpoolP256r1 and brainpoolP256t1
21//! - [`bp384`]: brainpoolP384r1 and brainpoolP384t1
22//! - [`k256`]: secp256k1 a.k.a. K-256
23//! - [`p256`]: NIST P-256 a.k.a secp256r1, prime256v1
24//! - [`p384`]: NIST P-384 a.k.a. secp384r1
25//!
26//! The [`ecdsa`] crate provides a generic implementation of the
27//! Elliptic Curve Digital Signature Algorithm which can be used with any of
28//! the above crates, either via an external ECDSA implementation, or
29//! using native curve arithmetic where applicable.
30//!
31//! ## Type conversions
32//!
33//! The following chart illustrates the various conversions possible between
34//! the various types defined by this crate.
35//!
36//! ![Type Conversion Map](https://raw.githubusercontent.com/RustCrypto/media/master/img/elliptic-curve/type-transforms.svg)
37//!
38//! ## `serde` support
39//!
40//! When the `serde` feature of this crate is enabled, `Serialize` and
41//! `Deserialize` impls are provided for the following types:
42//!
43//! - [`JwkEcKey`]
44//! - [`PublicKey`]
45//! - [`ScalarCore`]
46//!
47//! Please see type-specific documentation for more information.
48//!
49//! [`RustCrypto/elliptic-curves`]: https://github.com/RustCrypto/elliptic-curves
50//! [`bp256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp256
51//! [`bp384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp384
52//! [`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
53//! [`p256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p256
54//! [`p384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p384
55//! [`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
56
57#[cfg(feature = "alloc")]
58#[allow(unused_imports)]
59#[macro_use]
60extern crate alloc;
61
62#[cfg(feature = "std")]
63extern crate std;
64
65#[cfg(feature = "rand_core")]
66#[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
67pub use rand_core;
68
69#[macro_use]
70mod macros;
71
72pub mod ops;
73
74#[cfg(feature = "dev")]
75#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
76pub mod dev;
77
78#[cfg(feature = "ecdh")]
79#[cfg_attr(docsrs, doc(cfg(feature = "ecdh")))]
80pub mod ecdh;
81
82#[cfg(feature = "hash2curve")]
83#[cfg_attr(docsrs, doc(cfg(feature = "hash2curve")))]
84pub mod hash2curve;
85
86#[cfg(feature = "sec1")]
87#[cfg_attr(docsrs, doc(cfg(feature = "sec1")))]
88pub mod sec1;
89
90#[cfg(feature = "arithmetic")]
91#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
92pub mod weierstrass;
93
94mod error;
95mod point;
96mod scalar;
97mod secret_key;
98
99#[cfg(feature = "arithmetic")]
100mod arithmetic;
101#[cfg(feature = "arithmetic")]
102mod public_key;
103
104#[cfg(feature = "jwk")]
105mod jwk;
106
107pub use crate::{
108    error::{Error, Result},
109    point::{
110        AffineXCoordinate, DecompactPoint, DecompressPoint, PointCompaction, PointCompression,
111    },
112    scalar::{core::ScalarCore, IsHigh},
113    secret_key::SecretKey,
114};
115pub use crypto_bigint as bigint;
116pub use generic_array::{self, typenum::consts};
117pub use rand_core;
118pub use subtle;
119pub use zeroize;
120
121#[cfg(feature = "arithmetic")]
122pub use {
123    crate::{
124        arithmetic::{
125            AffineArithmetic, PrimeCurveArithmetic, ProjectiveArithmetic, ScalarArithmetic,
126        },
127        public_key::PublicKey,
128        scalar::{nonzero::NonZeroScalar, Scalar},
129    },
130    ff::{self, Field, PrimeField},
131    group::{self, Group},
132};
133
134#[cfg(feature = "bits")]
135pub use crate::scalar::ScalarBits;
136
137#[cfg(feature = "jwk")]
138pub use crate::jwk::{JwkEcKey, JwkParameters};
139
140#[cfg(feature = "pkcs8")]
141pub use pkcs8;
142
143use core::fmt::Debug;
144use generic_array::GenericArray;
145
146/// Algorithm [`ObjectIdentifier`][`pkcs8::ObjectIdentifier`] for elliptic
147/// curve public key cryptography (`id-ecPublicKey`).
148///
149/// <http://oid-info.com/get/1.2.840.10045.2.1>
150#[cfg(feature = "pkcs8")]
151#[cfg_attr(docsrs, doc(cfg(feature = "pkcs8")))]
152pub const ALGORITHM_OID: pkcs8::ObjectIdentifier =
153    pkcs8::ObjectIdentifier::new_unwrap("1.2.840.10045.2.1");
154
155/// Elliptic curve.
156///
157/// This trait is intended to be impl'd by a ZST which represents a concrete
158/// elliptic curve.
159///
160/// Other traits in this crate which are bounded by [`Curve`] are intended to
161/// be impl'd by these ZSTs, facilitating types which are generic over elliptic
162/// curves (e.g. [`SecretKey`]).
163pub trait Curve: 'static + Copy + Clone + Debug + Default + Eq + Ord + Send + Sync {
164    /// Integer type used to represent field elements of this elliptic curve.
165    // TODO(tarcieri): replace this with an e.g. `const Curve::MODULUS: UInt`.
166    // Requires rust-lang/rust#60551, i.e. `const_evaluatable_checked`
167    type UInt: bigint::AddMod<Output = Self::UInt>
168        + bigint::ArrayEncoding
169        + bigint::Encoding
170        + bigint::Integer
171        + bigint::NegMod<Output = Self::UInt>
172        + bigint::Random
173        + bigint::RandomMod
174        + bigint::SubMod<Output = Self::UInt>
175        + zeroize::Zeroize;
176
177    /// Order constant.
178    ///
179    /// Subdivided into either 32-bit or 64-bit "limbs" (depending on the
180    /// target CPU's word size), specified from least to most significant.
181    const ORDER: Self::UInt;
182}
183
184/// Marker trait for elliptic curves with prime order.
185pub trait PrimeCurve: Curve {}
186
187/// Size of field elements of this elliptic curve.
188pub type FieldSize<C> = <<C as Curve>::UInt as bigint::ArrayEncoding>::ByteSize;
189
190/// Byte representation of a base/scalar field element of a given curve.
191pub type FieldBytes<C> = GenericArray<u8, FieldSize<C>>;
192
193/// Affine point type for a given curve with a [`ProjectiveArithmetic`]
194/// implementation.
195#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
196#[cfg(feature = "arithmetic")]
197pub type AffinePoint<C> = <C as AffineArithmetic>::AffinePoint;
198
199/// Projective point type for a given curve with a [`ProjectiveArithmetic`]
200/// implementation.
201#[cfg(feature = "arithmetic")]
202#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
203pub type ProjectivePoint<C> = <C as ProjectiveArithmetic>::ProjectivePoint;
204
205/// Elliptic curve parameters used by VOPRF.
206#[cfg(feature = "voprf")]
207#[cfg_attr(docsrs, doc(cfg(feature = "voprf")))]
208pub trait VoprfParameters: Curve {
209    /// The `ID` parameter which identifies a particular elliptic curve
210    /// as defined in [section 4 of `draft-irtf-cfrg-voprf-08`][voprf].
211    ///
212    /// [voprf]: https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html#section-4
213    const ID: u16;
214
215    /// The `Hash` parameter which assigns a particular hash function to this
216    /// ciphersuite as defined in [section 4 of `draft-irtf-cfrg-voprf-08`][voprf].
217    ///
218    /// [voprf]: https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-08.html#section-4
219    type Hash: digest::Digest;
220}
elliptic_curve/lib.rs

elliptic_curve/
lib.rs
