From 15420eb44a471c331b3ba5a69e82099b49d67db4 Mon Sep 17 00:00:00 2001 From: Ansley Peduru Date: Sun, 7 Jan 2018 14:13:17 -0500 Subject: [PATCH 1/5] 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; + /// Reference to `PKey`. pub struct PKeyRef; } impl PKeyRef { /// 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, ErrorStack> { unsafe { let rsa = cvt_p(ffi::EVP_PKEY_get1_RSA(self.as_ptr()))?; @@ -68,6 +115,10 @@ impl PKeyRef { } /// 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, ErrorStack> { unsafe { let dsa = cvt_p(ffi::EVP_PKEY_get1_DSA(self.as_ptr()))?; @@ -76,6 +127,10 @@ impl PKeyRef { } /// 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, ErrorStack> { unsafe { let dh = cvt_p(ffi::EVP_PKEY_get1_DH(self.as_ptr()))?; @@ -84,6 +139,10 @@ impl PKeyRef { } /// 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, ErrorStack> { unsafe { let ec_key = cvt_p(ffi::EVP_PKEY_get1_EC_KEY(self.as_ptr()))?; @@ -172,6 +231,10 @@ where impl PKey { /// 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) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; @@ -187,6 +250,10 @@ impl PKey { } /// 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) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; @@ -202,6 +269,10 @@ impl PKey { } /// 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) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; @@ -217,6 +288,10 @@ impl PKey { } /// 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) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; From 33ec3a57849ed54b6d644c0ecb11e09f2e4fbbc0 Mon Sep 17 00:00:00 2001 From: Ansley Peduru Date: Sun, 7 Jan 2018 14:15:17 -0500 Subject: [PATCH 2/5] Missing colon --- openssl/src/pkey.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openssl/src/pkey.rs b/openssl/src/pkey.rs index b064a2a6..d48c31fc 100644 --- a/openssl/src/pkey.rs +++ b/openssl/src/pkey.rs @@ -30,7 +30,7 @@ //! //! extern crate openssl; //! -//! use openssl::rsa:Rsa; +//! use openssl::rsa::Rsa; //! use openssl::pkey::Pkey; //! //! fn main() { From b9eace65698e07ccf6de5e3e017cdba779266beb Mon Sep 17 00:00:00 2001 From: Ansley Peduru Date: Sun, 7 Jan 2018 14:17:03 -0500 Subject: [PATCH 3/5] Fix import in pkey docs --- openssl/src/pkey.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openssl/src/pkey.rs b/openssl/src/pkey.rs index d48c31fc..419288b6 100644 --- a/openssl/src/pkey.rs +++ b/openssl/src/pkey.rs @@ -31,11 +31,11 @@ //! extern crate openssl; //! //! use openssl::rsa::Rsa; -//! use openssl::pkey::Pkey; +//! use openssl::pkey::PKey; //! //! fn main() { //! let rsa = Rsa::generate(2048).unwrap(); -//! let pkey = Pkey::from_rsa(rsa).unwrap(); +//! let pkey = PKey::from_rsa(rsa).unwrap(); //! } //! ``` From 6552a9cbfda31680684edf6b5e309d10dd9fa6ed Mon Sep 17 00:00:00 2001 From: Ansley Peduru Date: Tue, 23 Jan 2018 22:43:53 -0500 Subject: [PATCH 4/5] Print the public key in PKey example --- openssl/src/pkey.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/openssl/src/pkey.rs b/openssl/src/pkey.rs index 419288b6..9f100075 100644 --- a/openssl/src/pkey.rs +++ b/openssl/src/pkey.rs @@ -24,7 +24,7 @@ //! //! # Example //! -//! Generate a 2048-bit RSA public/private key pair. +//! Generate a 2048-bit RSA public/private key pair and print the public key. //! //! ```rust //! @@ -32,10 +32,14 @@ //! //! use openssl::rsa::Rsa; //! use openssl::pkey::PKey; +//! use std::str; //! //! fn main() { //! let rsa = Rsa::generate(2048).unwrap(); //! let pkey = PKey::from_rsa(rsa).unwrap(); +//! +//! let pub_key: Vec = pkey.public_key_to_pem().unwrap(); +//! println!("{:?}", str::from_utf8(pub_key.as_slice()).unwrap()); //! } //! ``` From d3169a565e26258bedd99337045e263ead675d5d Mon Sep 17 00:00:00 2001 From: Ansley Peduru Date: Wed, 24 Jan 2018 09:53:28 -0500 Subject: [PATCH 5/5] Add HMAC to Pkey docs --- openssl/src/pkey.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openssl/src/pkey.rs b/openssl/src/pkey.rs index 9f100075..8f7c4e4e 100644 --- a/openssl/src/pkey.rs +++ b/openssl/src/pkey.rs @@ -7,7 +7,7 @@ //! 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: +//! This module offers support for five popular algorithms: //! //! * RSA //! @@ -17,6 +17,8 @@ //! //! * Elliptic Curves //! +//! * HMAC +//! //! 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