Merge pull request #761 from AndyGauge/doc-ec (f79d92dd) · Commits · Public Repositories / Rust Openssl

openssl/src/ec.rs

+212 −4

Original line number	Diff line number	Diff line
		//! Elliptic Curve
		//!
		//! Cryptology relies on the difficulty of solving mathematical problems, such as the factor
		//! of large integers composed of two large prime numbers and the discrete logarithm of a
		//! random eliptic curve. This module provides low-level features of the latter.
		//! Elliptic Curve protocols can provide the same security with smaller keys.
		//!
		//! There are 2 forms of elliptic curves, `Fp` and `F2^m`. These curves use irreducible
		//! trinomial or pentanomial . Being a generic interface to a wide range of algorithms,
		//! the cuves are generally referenced by [`EcGroup`]. There are many built in groups
		//! found in [`Nid`].
		//!
		//! OpenSSL Wiki explains the fields and curves in detail at [Eliptic Curve Cryptography].
		//!
		//! [`EcGroup`]: struct.EcGroup.html
		//! [`Nid`]: ../nid/struct.Nid.html
		//! [Eliptic Curve Cryptography]: https://wiki.openssl.org/index.php/Elliptic_Curve_Cryptography
		//!
		//! # Examples
		//!
		//! ```
		//! use openssl::ec::{EcGroup, EcPoint};
		//! use openssl::nid;
		//! use openssl::error::ErrorStack;
		//! fn get_ec_point() -> Result< EcPoint, ErrorStack > {
		//! let group = EcGroup::from_curve_name(nid::SECP224R1)?;
		//! let point = EcPoint::new(&group)?;
		//! Ok(point)
		//! }
		//! # fn main() {
		//! # let _ = get_ec_point();
		//! # }
		//! ```
		use ffi;
		use foreign_types::{ForeignType, ForeignTypeRef};
		use std::ptr;
		@@ -9,23 +42,59 @@ use bn::{BigNumRef, BigNumContextRef};
		use error::ErrorStack;
		use nid::Nid;

		/// Compressed conversion from point value (Default)
		pub const POINT_CONVERSION_COMPRESSED: PointConversionForm =
		PointConversionForm(ffi::point_conversion_form_t::POINT_CONVERSION_COMPRESSED);

		/// Uncompressed conversion from point value (Binary curve default)
		pub const POINT_CONVERSION_UNCOMPRESSED: PointConversionForm =
		PointConversionForm(ffi::point_conversion_form_t::POINT_CONVERSION_UNCOMPRESSED);

		/// Performs both compressed and uncompressed conversions
		pub const POINT_CONVERSION_HYBRID: PointConversionForm =
		PointConversionForm(ffi::point_conversion_form_t::POINT_CONVERSION_HYBRID);

		// OPENSSL_EC_EXPLICIT_CURVE, but that was only added in 1.1.
		// Man page documents that 0 can be used in older versions.
		/// Curve defined using polynomial parameters
		///
		/// Most applications use a named EC_GROUP curve, however, support
		/// is included to explicitly define the curve used to calculate keys
		/// This information would need to be known by both endpoint to make communication
		/// effective.
		///
		/// OPENSSL_EC_EXPLICIT_CURVE, but that was only added in 1.1.
		/// Man page documents that 0 can be used in older versions.
		///
		/// OpenSSL documentation at [`EC_GROUP`]
		///
		/// [`EC_GROUP`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_seed_len.html
		pub const EXPLICIT_CURVE: Asn1Flag = Asn1Flag(0);

		/// Standard Curves
		///
		/// Curves that make up the typical encryption use cases. The collection of curves
		/// are well known but extensible.
		///
		/// OpenSSL documentation at [`EC_GROUP`]
		///
		/// [`EC_GROUP`]: https://www.openssl.org/docs/manmaster/man3/EC_GROUP_order_bits.html
		pub const NAMED_CURVE: Asn1Flag = Asn1Flag(ffi::OPENSSL_EC_NAMED_CURVE);

		/// Compressed or Uncompressed conversion
		///
		/// Conversion from the binary value of the point on the curve is performed in one of
		/// compressed, uncompressed, or hybrid conversions. The default is compressed, except
		/// for binary curves.
		///
		/// Further documentation is available in the [X9.62] standard.
		///
		/// [X9.62]: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.202.2977&rep=rep1&type=pdf
		#[derive(Copy, Clone)]
		pub struct PointConversionForm(ffi::point_conversion_form_t);

		/// Named Curve or Explicit
		///
		/// This type acts as a boolean as to whether the EC_Group is named or
		/// explicit.
		#[derive(Copy, Clone)]
		pub struct Asn1Flag(c_int);

		@@ -33,12 +102,35 @@ foreign_type! {
		type CType = ffi::EC_GROUP;
		fn drop = ffi::EC_GROUP_free;

		/// Describes the curve
		///
		/// A curve can be of the named curve type. These curves can be discovered
		/// using openssl binary `openssl ecparam -list_curves`. Other operations
		/// are available in the [wiki]. These named curves are available in the
		/// [`Nid`] module.
		///
		/// Curves can also be generated using prime field parameters or a binary field.
		///
		/// Prime fields use the formula `y^2 mod p = x^3 + ax + b mod p`. Binary
		/// fields use the formula `y^2 + xy = x^3 + ax^2 + b`. Named curves have
		/// assured security. To prevent accidental vulnerabilities, they should
		/// be prefered.
		///
		/// [wiki]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations
		/// [`Nid`]: ../nid/index.html
		pub struct EcGroup;
		/// Reference to [`EcGroup`]
		///
		/// [`EcGroup`]: struct.EcGroup.html
		pub struct EcGroupRef;
		}

		impl EcGroup {
		/// Returns the group of a standard named curve.
		///
		/// OpenSSL documentation at [`EC_GROUP_new`].
		///
		/// [`EC_GROUP_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_new.html
		pub fn from_curve_name(nid: Nid) -> Result<EcGroup, ErrorStack> {
		unsafe {
		init();
		@@ -49,6 +141,11 @@ impl EcGroup {

		impl EcGroupRef {
		/// Places the components of a curve over a prime field in the provided `BigNum`s.
		/// The components make up the formula `y^2 mod p = x^3 + ax + b mod p`.
		///
		/// OpenSSL documentation available at [`EC_GROUP_get_curve_GFp`]
		///
		/// [`EC_GROUP_get_curve_GFp`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_curve_GFp.html
		pub fn components_gfp(
		&self,
		p: &mut BigNumRef,
		@@ -68,6 +165,15 @@ impl EcGroupRef {
		}

		/// Places the components of a curve over a binary field in the provided `BigNum`s.
		/// The components make up the formula `y^2 + xy = x^3 + ax^2 + b`.
		///
		/// In this form `p` relates to the irreducible polynomial. Each bit represents
		/// a term in the polynomial. It will be set to 3 `1`s or 5 `1`s depending on
		/// using a trinomial or pentanomial.
		///
		/// OpenSSL documentation at [`EC_GROUP_get_curve_GF2m`].
		///
		/// [`EC_GROUP_get_curve_GF2m`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_curve_GF2m.html
		#[cfg(not(osslconf = "OPENSSL_NO_EC2M"))]
		pub fn components_gf2m(
		&self,
		@@ -88,11 +194,19 @@ impl EcGroupRef {
		}

		/// Returns the degree of the curve.
		///
		/// OpenSSL documentation at [`EC_GROUP_get_degree`]
		///
		/// [`EC_GROUP_get_degree`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_degree.html
		pub fn degree(&self) -> u32 {
		unsafe { ffi::EC_GROUP_get_degree(self.as_ptr()) as u32 }
		}

		/// Places the order of the curve in the provided `BigNum`.
		///
		/// OpenSSL documentation at [`EC_GROUP_get_order`]
		///
		/// [`EC_GROUP_get_order`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_order.html
		pub fn order(
		&self,
		order: &mut BigNumRef,
		@@ -123,12 +237,24 @@ foreign_type! {
		type CType = ffi::EC_POINT;
		fn drop = ffi::EC_POINT_free;

		/// Represents a point on the curve
		///
		/// OpenSSL documentation at [`EC_POINT_new`]
		///
		/// [`EC_POINT_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_new.html
		pub struct EcPoint;
		/// Reference to [`EcPoint`]
		///
		/// [`EcPoint`]: struct.EcPoint.html
		pub struct EcPointRef;
		}

		impl EcPointRef {
		/// Computes `a + b`, storing the result in `self`.
		///
		/// OpenSSL documentation at [`EC_POINT_add`]
		///
		/// [`EC_POINT_add`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_add.html
		pub fn add(
		&mut self,
		group: &EcGroupRef,
		@@ -148,6 +274,10 @@ impl EcPointRef {
		}

		/// Computes `q * m`, storing the result in `self`.
		///
		/// OpenSSL documentation at [`EC_POINT_mul`]
		///
		/// [`EC_POINT_mul`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_mul.html
		pub fn mul(
		&mut self,
		group: &EcGroupRef,
		@@ -208,6 +338,10 @@ impl EcPointRef {
		}

		/// Inverts `self`.
		///
		/// OpenSSL documentation at [`EC_POINT_invert`]
		///
		/// [`EC_POINT_invert`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_invert.html
		pub fn invert(&mut self, group: &EcGroupRef, ctx: &BigNumContextRef) -> Result<(), ErrorStack> {
		unsafe {
		cvt(ffi::EC_POINT_invert(
		@@ -219,6 +353,10 @@ impl EcPointRef {
		}

		/// Serializes the point to a binary representation.
		///
		/// OpenSSL documentation at [`EC_POINT_point2oct`]
		///
		/// [`EC_POINT_point2oct`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_point2oct.html
		pub fn to_bytes(
		&self,
		group: &EcGroupRef,
		@@ -255,6 +393,10 @@ impl EcPointRef {
		}

		/// Determines if this point is equal to another.
		///
		/// OpenSSL doucmentation at [`EC_POINT_cmp`]
		///
		/// [`EC_POINT_cmp`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_cmp.html
		pub fn eq(
		&self,
		group: &EcGroupRef,
		@@ -272,7 +414,12 @@ impl EcPointRef {
		}
		}

		/// Place affine coordinates of a curve over a prime field in the provided x and y BigNum's
		/// Place affine coordinates of a curve over a prime field in the provided
		/// `x` and `y` `BigNum`s
		///
		/// OpenSSL documentation at [`EC_POINT_get_affine_coordinates_GFp`]
		///
		/// [`EC_POINT_get_affine_coordinates_GFp`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_get_affine_coordinates_GFp.html
		pub fn affine_coordinates_gfp(
		&self,
		group: &EcGroupRef,
		@@ -291,7 +438,12 @@ impl EcPointRef {
		}
		}

		/// Place affine coordinates of a curve over a binary field in the provided x and y BigNum's
		/// Place affine coordinates of a curve over a binary field in the provided
		/// `x` and `y` `BigNum`s
		///
		/// OpenSSL documentation at [`EC_POINT_get_affine_coordinates_GF2m`]
		///
		/// [`EC_POINT_get_affine_coordinates_GF2m`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_get_affine_coordinates_GF2m.html
		#[cfg(not(osslconf = "OPENSSL_NO_EC2M"))]
		pub fn affine_coordinates_gf2m(
		&self,
		@@ -314,10 +466,19 @@ impl EcPointRef {

		impl EcPoint {
		/// Creates a new point on the specified curve.
		///
		/// OpenSSL documentation at [`EC_POINT_new`]
		///
		/// [`EC_POINT_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_new.html
		pub fn new(group: &EcGroupRef) -> Result<EcPoint, ErrorStack> {
		unsafe { cvt_p(ffi::EC_POINT_new(group.as_ptr())).map(EcPoint) }
		}

		/// Creates point from a binary representation
		///
		/// OpenSSL documentation at [`EC_POINT_oct2point`]
		///
		/// [`EC_POINT_oct2point`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_oct2point.html
		pub fn from_bytes(
		group: &EcGroupRef,
		buf: &[u8],
		@@ -341,7 +502,15 @@ foreign_type! {
		type CType = ffi::EC_KEY;
		fn drop = ffi::EC_KEY_free;

		/// Public and optional Private key on the given curve
		///
		/// OpenSSL documentation at [`EC_KEY_new`]
		///
		/// [`EC_KEY_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_new.html
		pub struct EcKey;
		/// Reference to [`EcKey`]
		///
		/// [`EcKey`]: struct.EcKey.html
		pub struct EcKeyRef;
		}

		@@ -349,6 +518,11 @@ impl EcKeyRef {
		private_key_to_pem!(ffi::PEM_write_bio_ECPrivateKey);
		private_key_to_der!(ffi::i2d_ECPrivateKey);

		/// Return [`EcGroup`] of the `EcKey`
		///
		/// OpenSSL documentation at [`EC_KEY_get0_group`]
		///
		/// [`EC_KEY_get0_group`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_group.html
		pub fn group(&self) -> Option<&EcGroupRef> {
		unsafe {
		let ptr = ffi::EC_KEY_get0_group(self.as_ptr());
		@@ -360,6 +534,11 @@ impl EcKeyRef {
		}
		}

		/// Return [`EcPoint`] associated with the public key
		///
		/// OpenSSL documentation at [`EC_KEY_get0_pubic_key`]
		///
		/// [`EC_KEY_get0_pubic_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_public_key.html
		pub fn public_key(&self) -> Option<&EcPointRef> {
		unsafe {
		let ptr = ffi::EC_KEY_get0_public_key(self.as_ptr());
		@@ -371,6 +550,11 @@ impl EcKeyRef {
		}
		}

		/// Return [`EcPoint`] associated with the private key
		///
		/// OpenSSL documentation at [`EC_KEY_get0_private_key`]
		///
		/// [`EC_KEY_get0_private_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_private_key.html
		pub fn private_key(&self) -> Option<&BigNumRef> {
		unsafe {
		let ptr = ffi::EC_KEY_get0_private_key(self.as_ptr());
		@@ -383,10 +567,15 @@ impl EcKeyRef {
		}

		/// Checks the key for validity.
		///
		/// OpenSSL documenation at [`EC_KEY_check_key`]
		///
		/// [`EC_KEY_check_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_check_key.html
		pub fn check_key(&self) -> Result<(), ErrorStack> {
		unsafe { cvt(ffi::EC_KEY_check_key(self.as_ptr())).map(\|_\| ()) }
		}

		/// Create a copy of the `EcKey` to allow modification
		pub fn to_owned(&self) -> Result<EcKey, ErrorStack> {
		unsafe { cvt_p(ffi::EC_KEY_dup(self.as_ptr())).map(EcKey) }
		}
		@@ -397,6 +586,10 @@ impl EcKey {
		///
		/// It will not have an associated public or private key. This kind of key is primarily useful
		/// to be provided to the `set_tmp_ecdh` methods on `Ssl` and `SslContextBuilder`.
		///
		/// OpenSSL documenation at [`EC_KEY_new_by_curve_name`]
		///
		/// [`EC_KEY_new_by_curve_name`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_new_by_curve_name.html
		pub fn from_curve_name(nid: Nid) -> Result<EcKey, ErrorStack> {
		unsafe {
		init();
		@@ -457,11 +650,18 @@ foreign_type! {
		type CType = ffi::EC_KEY;
		fn drop = ffi::EC_KEY_free;

		/// Builder pattern for key generation
		///
		/// Returns a `EcKeyBuilder` to be consumed by `build`
		pub struct EcKeyBuilder;
		/// Reference to [`EcKeyBuilder`]
		///
		/// [`EcKeyBuilder`]: struct.EcKeyBuilder.html
		pub struct EcKeyBuilderRef;
		}

		impl EcKeyBuilder {
		/// Creates an empty `EcKeyBuilder` to be chained with additonal methods
		pub fn new() -> Result<EcKeyBuilder, ErrorStack> {
		unsafe {
		init();
		@@ -469,6 +669,9 @@ impl EcKeyBuilder {
		}
		}

		/// Consume the `EcKeyBuilder` and return [`EcKey`]
		///
		/// [`EcKey`]: struct.EcKey.html
		pub fn build(self) -> EcKey {
		unsafe {
		let key = EcKey::from_ptr(self.as_ptr());
		@@ -479,10 +682,14 @@ impl EcKeyBuilder {
		}

		impl EcKeyBuilderRef {
		/// Set the [`EcGroup`] explicitly
		///
		/// [`EcGroup`]: struct.EcGroup.html
		pub fn set_group(&mut self, group: &EcGroupRef) -> Result<&mut EcKeyBuilderRef, ErrorStack> {
		unsafe { cvt(ffi::EC_KEY_set_group(self.as_ptr(), group.as_ptr())).map(\|_\| self) }
		}

		/// Set public key to given `EcPoint`
		pub fn set_public_key(
		&mut self,
		public_key: &EcPointRef,
		@@ -495,6 +702,7 @@ impl EcKeyBuilderRef {
		}
		}

		/// Generate public and private keys.
		pub fn generate_key(&mut self) -> Result<&mut EcKeyBuilderRef, ErrorStack> {
		unsafe { cvt(ffi::EC_KEY_generate_key(self.as_ptr())).map(\|_\| self) }
		}