Merge pull request #761 from AndyGauge/doc-ec

Doc ec module

1 files changed, 212 insertions, 4 deletions

diff --git a/openssl/src/ec.rs b/openssl/src/ec.rs
index 5e158ae4..ddf8c029 100644
--- a/openssl/src/ec.rs
+++ b/openssl/src/ec.rs
@@ -1,3 +1,36 @@
+//! 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) }
     }