diff options
Diffstat (limited to 'openssl/src')
| -rw-r--r-- | openssl/src/pkey.rs | 75 |
1 files changed, 75 insertions, 0 deletions
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())?; |