From df10bcf9605ef6b4aeb48d796f27cfc540d5cb86 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 24 Oct 2017 16:43:01 -0700 Subject: [PATCH] Update documentation for EC module --- openssl/src/ec.rs | 210 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 204 insertions(+), 6 deletions(-) diff --git a/openssl/src/ec.rs b/openssl/src/ec.rs index c6012050..38c412fc 100644 --- a/openssl/src/ec.rs +++ b/openssl/src/ec.rs @@ -6,8 +6,31 @@ //! 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`] +//! 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; @@ -19,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); @@ -43,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 { unsafe { init(); @@ -59,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, @@ -78,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, @@ -98,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, @@ -133,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, @@ -158,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, @@ -218,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( @@ -229,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, @@ -265,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, @@ -282,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, @@ -301,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, @@ -324,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 { 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], @@ -351,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; } @@ -359,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()); @@ -370,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()); @@ -381,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()); @@ -393,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 { unsafe { cvt_p(ffi::EC_KEY_dup(self.as_ptr())).map(EcKey) } } @@ -407,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 { unsafe { init(); @@ -467,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 { unsafe { init(); @@ -479,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()); @@ -489,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, @@ -505,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) } }