From 15420eb44a471c331b3ba5a69e82099b49d67db4 Mon Sep 17 00:00:00 2001
From: Ansley Peduru <ansleypeduru96@gmail.com>
Date: Sun, 7 Jan 2018 14:13:17 -0500
Subject: [PATCH] Add Pkey docs

---
 openssl/src/pkey.rs | 75 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/openssl/src/pkey.rs b/openssl/src/pkey.rs
index fddcca05..b064a2a6 100644
--- a/openssl/src/pkey.rs
+++ b/openssl/src/pkey.rs
@@ -1,3 +1,44 @@
+//! Public/private key processing.
+//!
+//! Asymmetric public key algorithms solve the problem of establishing and sharing
+//! secret keys to securely send and receive messages.
+//! This system uses a pair of keys: a public key, which can be freely
+//! distributed, and a private key, which is kept to oneself. An entity may
+//! encrypt information using a user's public key. The encrypted information can
+//! only be deciphered using that user's private key.
+//!
+//! This module offers support for four popular algorithms:
+//!
+//! * RSA
+//!
+//! * DSA
+//!
+//! * Diffie-Hellman
+//!
+//! * Elliptic Curves
+//!
+//! These algorithms rely on hard mathematical problems - namely integer factorization,
+//! discrete logarithms, and elliptic curve relationships - that currently do not
+//! yield efficient solutions. This property ensures the security of these
+//! cryptographic algorithms.
+//!
+//! # Example
+//!
+//! Generate a 2048-bit RSA public/private key pair.
+//!
+//! ```rust
+//!
+//! extern crate openssl;
+//!
+//! use openssl::rsa:Rsa;
+//! use openssl::pkey::Pkey;
+//!
+//! fn main() {
+//!     let rsa = Rsa::generate(2048).unwrap();
+//!     let pkey = Pkey::from_rsa(rsa).unwrap();
+//! }
+//! ```
+
 use libc::c_int;
 use std::ptr;
 use std::mem;
@@ -54,12 +95,18 @@ generic_foreign_type_and_impl_send_sync! {
     type CType = ffi::EVP_PKEY;
     fn drop = ffi::EVP_PKEY_free;
 
+    /// A public or private key.
     pub struct PKey<T>;
+    /// Reference to `PKey`.
     pub struct PKeyRef<T>;
 }
 
 impl<T> PKeyRef<T> {
     /// Returns a copy of the internal RSA key.
+    ///
+    /// This corresponds to [`EVP_PKEY_get1_RSA`].
+    ///
+    /// [`EVP_PKEY_get1_RSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_RSA.html
     pub fn rsa(&self) -> Result<Rsa<T>, ErrorStack> {
         unsafe {
             let rsa = cvt_p(ffi::EVP_PKEY_get1_RSA(self.as_ptr()))?;
@@ -68,6 +115,10 @@ impl<T> PKeyRef<T> {
     }
 
     /// Returns a copy of the internal DSA key.
+    ///
+    /// This corresponds to [`EVP_PKEY_get1_DSA`].
+    ///
+    /// [`EVP_PKEY_get1_DSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_DSA.html
     pub fn dsa(&self) -> Result<Dsa<T>, ErrorStack> {
         unsafe {
             let dsa = cvt_p(ffi::EVP_PKEY_get1_DSA(self.as_ptr()))?;
@@ -76,6 +127,10 @@ impl<T> PKeyRef<T> {
     }
 
     /// Returns a copy of the internal DH key.
+    ///
+    /// This corresponds to [`EVP_PKEY_get1_DH`].
+    ///
+    /// [`EVP_PKEY_get1_DH`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_DH.html
     pub fn dh(&self) -> Result<Dh<T>, ErrorStack> {
         unsafe {
             let dh = cvt_p(ffi::EVP_PKEY_get1_DH(self.as_ptr()))?;
@@ -84,6 +139,10 @@ impl<T> PKeyRef<T> {
     }
 
     /// Returns a copy of the internal elliptic curve key.
+    ///
+    /// This corresponds to [`EVP_PKEY_get1_EC_KEY`].
+    ///
+    /// [`EVP_PKEY_get1_EC_KEY`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_EC_KEY.html
     pub fn ec_key(&self) -> Result<EcKey<T>, ErrorStack> {
         unsafe {
             let ec_key = cvt_p(ffi::EVP_PKEY_get1_EC_KEY(self.as_ptr()))?;
@@ -172,6 +231,10 @@ where
 
 impl<T> PKey<T> {
     /// Creates a new `PKey` containing an RSA key.
+    ///
+    /// This corresponds to [`EVP_PKEY_assign_RSA`].
+    ///
+    /// [`EVP_PKEY_assign_RSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_RSA.html
     pub fn from_rsa(rsa: Rsa<T>) -> Result<PKey<T>, ErrorStack> {
         unsafe {
             let evp = cvt_p(ffi::EVP_PKEY_new())?;
@@ -187,6 +250,10 @@ impl<T> PKey<T> {
     }
 
     /// Creates a new `PKey` containing a DSA key.
+    ///
+    /// This corresponds to [`EVP_PKEY_assign_DSA`].
+    ///
+    /// [`EVP_PKEY_assign_DSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_DSA.html
     pub fn from_dsa(dsa: Dsa<T>) -> Result<PKey<T>, ErrorStack> {
         unsafe {
             let evp = cvt_p(ffi::EVP_PKEY_new())?;
@@ -202,6 +269,10 @@ impl<T> PKey<T> {
     }
 
     /// Creates a new `PKey` containing a Diffie-Hellman key.
+    ///
+    /// This corresponds to [`EVP_PKEY_assign_DH`].
+    ///
+    /// [`EVP_PKEY_assign_DH`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_DH.html
     pub fn from_dh(dh: Dh<T>) -> Result<PKey<T>, ErrorStack> {
         unsafe {
             let evp = cvt_p(ffi::EVP_PKEY_new())?;
@@ -217,6 +288,10 @@ impl<T> PKey<T> {
     }
 
     /// Creates a new `PKey` containing an elliptic curve key.
+    ///
+    /// This corresponds to [`EVP_PKEY_assign_EC_KEY`].
+    ///
+    /// [`EVP_PKEY_assign_EC_KEY`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_EC_KEY.html
     pub fn from_ec_key(ec_key: EcKey<T>) -> Result<PKey<T>, ErrorStack> {
         unsafe {
             let evp = cvt_p(ffi::EVP_PKEY_new())?;