elliptic_curve/
lib.rs

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#![deny(unsafe_code)] // Only allowed for newtype casts.
9#![warn(clippy::panic, clippy::panic_in_result_fn)]
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//! - [`p224`]: NIST P-224 a.k.a. secp224r1
24//! - [`p256`]: NIST P-256 a.k.a secp256r1, prime256v1
25//! - [`p384`]: NIST P-384 a.k.a. secp384r1
26//! - [`p521`]: NIST P-521 a.k.a. secp521r1
27//!
28//! The [`ecdsa`] crate provides a generic implementation of the
29//! Elliptic Curve Digital Signature Algorithm which can be used with any of
30//! the above crates, either via an external ECDSA implementation, or
31//! using native curve arithmetic where applicable.
32//!
33//! ## Type conversions
34//!
35//! The following chart illustrates the various conversions possible between
36//! the various types defined by this crate.
37//!
38//! ![Type Conversion Map](https://raw.githubusercontent.com/RustCrypto/media/master/img/elliptic-curve/type-transforms.svg)
39//!
40//! ## `serde` support
41//!
42//! When the `serde` feature of this crate is enabled, `Serialize` and
43//! `Deserialize` impls are provided for the following types:
44//!
45//! - [`PublicKey`]
46//! - [`ScalarValue`]
47//!
48//! Please see type-specific documentation for more information.
49//!
50//! [`RustCrypto/elliptic-curves`]: https://github.com/RustCrypto/elliptic-curves
51//! [`bp256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp256
52//! [`bp384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp384
53//! [`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
54//! [`p224`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p224
55//! [`p256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p256
56//! [`p384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p384
57//! [`p521`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p521
58//! [`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
59
60#[cfg(feature = "alloc")]
61#[allow(unused_imports)]
62#[macro_use]
63extern crate alloc;
64
65#[cfg(feature = "dev")]
66pub mod dev;
67#[cfg(feature = "ecdh")]
68pub mod ecdh;
69pub mod field;
70#[cfg(feature = "arithmetic")]
71pub mod hazmat;
72#[cfg(feature = "arithmetic")]
73pub mod ops;
74pub mod point;
75pub mod scalar;
76#[cfg(feature = "sec1")]
77pub mod sec1;
78
79#[cfg(feature = "arithmetic")]
80mod arithmetic;
81mod error;
82mod macros;
83#[cfg(feature = "arithmetic")]
84mod public_key;
85mod secret_key;
86
87pub use crate::{
88    error::{Error, Result},
89    field::{FieldBytes, FieldBytesSize},
90    scalar::ScalarValue,
91    secret_key::SecretKey,
92};
93pub use array;
94pub use array::typenum::consts;
95pub use bigint::{self, ByteOrder, ctutils};
96pub use common;
97pub use common::Generate;
98pub use rand_core;
99pub use subtle;
100pub use zeroize;
101
102#[cfg(any(feature = "pkcs8", feature = "sec1"))]
103pub use crate::error::{DecodeError, DecodeResult};
104#[cfg(feature = "pkcs8")]
105pub use pkcs8;
106#[cfg(feature = "arithmetic")]
107pub use {
108    crate::{
109        arithmetic::{CurveArithmetic, PrimeCurveArithmetic},
110        point::{AffinePoint, BatchNormalize, ProjectivePoint},
111        public_key::PublicKey,
112        scalar::{NonZeroScalar, Scalar},
113    },
114    ff::{self, Field, PrimeField},
115    group::{self, Curve as CurveGroup, CurveAffine, Group},
116};
117
118use array::{ArraySize, sizes::U1};
119use bigint::Odd;
120use core::{
121    fmt::Debug,
122    ops::{Add, ShrAssign},
123};
124
125/// Algorithm [`ObjectIdentifier`][`pkcs8::ObjectIdentifier`] for elliptic curve public key
126/// cryptography (`id-ecPublicKey`).
127///
128/// <https://oid-base.com/get/1.2.840.10045.2.1>
129#[cfg(feature = "pkcs8")]
130pub const ALGORITHM_OID: pkcs8::ObjectIdentifier =
131    pkcs8::ObjectIdentifier::new_unwrap("1.2.840.10045.2.1");
132
133/// Elliptic curve.
134///
135/// This trait is intended to be impl'd by a ZST which represents a concrete elliptic curve.
136///
137/// Other traits in this crate which are bounded by [`Curve`] are intended to be impl'd by these
138/// ZSTs, facilitating types which are generic over elliptic curves (e.g. [`SecretKey`]).
139pub trait Curve: 'static + Copy + Clone + Debug + Default + Eq + Ord + Send + Sync {
140    /// Size of a serialized field element in bytes (base field or scalar).
141    ///
142    /// This currently assumes that the base and scalar fields have the same-sized modulus in bytes,
143    /// though that isn't strictly true and will eventually need to be fixed.
144    ///
145    /// This is typically the same as `Self::Uint::ByteSize` but for curves with an unusual field
146    /// modulus (e.g. P-224, P-521) it may be different.
147    ///
148    /// The bounds cover common sizes for tables based on precomputed scalars, and is also useful
149    /// for serialized point sizes for e.g. SEC1 where relevant.
150    type FieldBytesSize: ArraySize<ArrayType<u8>: Copy>
151        + Add<Output: Add<U1, Output: ArraySize<ArrayType<u8>: Copy>>>
152        + Add<U1, Output: ArraySize<ArrayType<u8>: Copy>>
153        + Eq;
154
155    /// Integer type used to represent field elements of this elliptic curve.
156    type Uint: bigint::ArrayEncoding
157        + bigint::Encoding
158        + bigint::FixedInteger
159        + bigint::Random
160        + bigint::RandomMod
161        + bigint::Unsigned
162        + zeroize::Zeroize
163        + ShrAssign<usize>;
164
165    /// Order of this curve's prime order subgroup, i.e. number of elements in the scalar field.
166    const ORDER: Odd<Self::Uint>;
167
168    /// Endianness used for serializing field elements of this curve.
169    const FIELD_ENDIANNESS: ByteOrder = ByteOrder::BigEndian;
170}
171
172/// Marker trait for elliptic curves with prime order.
173pub trait PrimeCurve: Curve {}
elliptic_curve/lib.rs

elliptic_curve/
lib.rs
