elliptic-curve 0.14.1

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
)]
#![deny(unsafe_code)] // Only allowed for newtype casts.
#![warn(clippy::panic, clippy::panic_in_result_fn)]

//! ## Usage
//!
//! This crate provides traits for describing elliptic curves, along with
//! types which are generic over elliptic curves which can be used as the
//! basis of curve-agnostic code.
//!
//! It's intended to be used with the following concrete elliptic curve
//! implementations from the [`RustCrypto/elliptic-curves`] project:
//!
//! - [`bp256`]: brainpoolP256r1 and brainpoolP256t1
//! - [`bp384`]: brainpoolP384r1 and brainpoolP384t1
//! - [`k256`]: secp256k1 a.k.a. K-256
//! - [`p224`]: NIST P-224 a.k.a. secp224r1
//! - [`p256`]: NIST P-256 a.k.a secp256r1, prime256v1
//! - [`p384`]: NIST P-384 a.k.a. secp384r1
//! - [`p521`]: NIST P-521 a.k.a. secp521r1
//!
//! The [`ecdsa`] crate provides a generic implementation of the
//! Elliptic Curve Digital Signature Algorithm which can be used with any of
//! the above crates, either via an external ECDSA implementation, or
//! using native curve arithmetic where applicable.
//!
//! ## Type conversions
//!
//! The following chart illustrates the various conversions possible between
//! the various types defined by this crate.
//!
//! ![Type Conversion Map](https://raw.githubusercontent.com/RustCrypto/media/master/img/elliptic-curve/type-transforms.svg)
//!
//! ## `serde` support
//!
//! When the `serde` feature of this crate is enabled, `Serialize` and
//! `Deserialize` impls are provided for the following types:
//!
//! - [`PublicKey`]
//! - [`ScalarValue`]
//!
//! Please see type-specific documentation for more information.
//!
//! [`RustCrypto/elliptic-curves`]: https://github.com/RustCrypto/elliptic-curves
//! [`bp256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp256
//! [`bp384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp384
//! [`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
//! [`p224`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p224
//! [`p256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p256
//! [`p384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p384
//! [`p521`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p521
//! [`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa

#[cfg(feature = "alloc")]
#[allow(unused_imports)]
#[macro_use]
extern crate alloc;

#[cfg(feature = "dev")]
pub mod dev;
#[cfg(feature = "ecdh")]
pub mod ecdh;
pub mod field;
#[cfg(feature = "arithmetic")]
pub mod hazmat;
#[cfg(feature = "arithmetic")]
pub mod ops;
pub mod point;
pub mod scalar;
#[cfg(feature = "sec1")]
pub mod sec1;

#[cfg(feature = "arithmetic")]
mod arithmetic;
mod error;
mod macros;
#[cfg(feature = "arithmetic")]
mod public_key;
mod secret_key;

pub use crate::{
    error::{Error, Result},
    field::{FieldBytes, FieldBytesSize},
    scalar::ScalarValue,
    secret_key::SecretKey,
};
pub use array;
pub use array::typenum::consts;
pub use bigint::{self, ByteOrder, ctutils};
pub use common;
pub use common::Generate;
pub use rand_core;
pub use subtle;
pub use zeroize;

#[cfg(any(feature = "pkcs8", feature = "sec1"))]
pub use crate::error::{DecodeError, DecodeResult};
#[cfg(feature = "pkcs8")]
pub use pkcs8;
#[cfg(feature = "arithmetic")]
pub use {
    crate::{
        arithmetic::{CurveArithmetic, PrimeCurveArithmetic},
        point::{AffinePoint, BatchNormalize, ProjectivePoint},
        public_key::PublicKey,
        scalar::{NonZeroScalar, Scalar},
    },
    ff::{self, Field, PrimeField},
    group::{self, Curve as CurveGroup, CurveAffine, Group},
};

use array::{ArraySize, sizes::U1};
use bigint::Odd;
use core::{
    fmt::Debug,
    ops::{Add, ShrAssign},
};

/// Algorithm [`ObjectIdentifier`][`pkcs8::ObjectIdentifier`] for elliptic curve public key
/// cryptography (`id-ecPublicKey`).
///
/// <https://oid-base.com/get/1.2.840.10045.2.1>
#[cfg(feature = "pkcs8")]
pub const ALGORITHM_OID: pkcs8::ObjectIdentifier =
    pkcs8::ObjectIdentifier::new_unwrap("1.2.840.10045.2.1");

/// Elliptic curve.
///
/// This trait is intended to be impl'd by a ZST which represents a concrete elliptic curve.
///
/// Other traits in this crate which are bounded by [`Curve`] are intended to be impl'd by these
/// ZSTs, facilitating types which are generic over elliptic curves (e.g. [`SecretKey`]).
pub trait Curve: 'static + Copy + Clone + Debug + Default + Eq + Ord + Send + Sync {
    /// Size of a serialized field element in bytes (base field or scalar).
    ///
    /// This currently assumes that the base and scalar fields have the same-sized modulus in bytes,
    /// though that isn't strictly true and will eventually need to be fixed.
    ///
    /// This is typically the same as `Self::Uint::ByteSize` but for curves with an unusual field
    /// modulus (e.g. P-224, P-521) it may be different.
    ///
    /// The bounds cover common sizes for tables based on precomputed scalars, and is also useful
    /// for serialized point sizes for e.g. SEC1 where relevant.
    type FieldBytesSize: ArraySize<ArrayType<u8>: Copy>
        + Add<Output: Add<U1, Output: ArraySize<ArrayType<u8>: Copy>>>
        + Add<U1, Output: ArraySize<ArrayType<u8>: Copy>>
        + Eq;

    /// Integer type used to represent field elements of this elliptic curve.
    type Uint: bigint::ArrayEncoding
        + bigint::Encoding
        + bigint::FixedInteger
        + bigint::Random
        + bigint::RandomMod
        + bigint::Unsigned
        + zeroize::Zeroize
        + ShrAssign<usize>;

    /// Order of this curve's prime order subgroup, i.e. number of elements in the scalar field.
    const ORDER: Odd<Self::Uint>;

    /// Endianness used for serializing field elements of this curve.
    const FIELD_ENDIANNESS: ByteOrder = ByteOrder::BigEndian;
}

/// Marker trait for elliptic curves with prime order.
pub trait PrimeCurve: Curve {}