Merge pull request #748 from AndyGauge/doc-cms

CMS module documentation

1 files changed, 28 insertions, 1 deletions

diff --git a/openssl/src/cms.rs b/openssl/src/cms.rs
index ee4b0816..59866df1 100644
--- a/openssl/src/cms.rs
+++ b/openssl/src/cms.rs
@@ -1,4 +1,9 @@
-//! CMS archive
+//! SMIME implementation using CMS
+//!
+//! CMS (PKCS#7) is an encyption standard.  It allows signing and ecrypting data using
+//! X.509 certificates.  The OpenSSL implementation of CMS is used in email encryption
+//! generated from a `Vec` of bytes.  This `Vec` follows the smime protocol standards.
+//! Data accepted by this module will be smime type `enveloped-data`.
 
 use ffi;
 use foreign_types::{ForeignType, ForeignTypeRef};
@@ -17,11 +22,28 @@ foreign_type! {
     type CType = ffi::CMS_ContentInfo;
     fn drop = ffi::CMS_ContentInfo_free;
 
+    /// High level CMS wrapper
+    ///
+    /// CMS supports nesting various types of data, including signatures, certificates,
+    /// encrypted data, smime messages (encrypted email), and data digest.  The ContentInfo
+    /// content type is the encapsulation of all those content types.  [`RFC 5652`] describes
+    /// CMS and OpenSSL follows this RFC's implmentation.
+    ///
+    /// [`RFC 5652`]: https://tools.ietf.org/html/rfc5652#page-6
     pub struct CmsContentInfo;
+    /// Reference to [`CMSContentInfo`]
+    ///
+    /// [`CMSContentInfo`]:struct.CmsContentInfo.html
     pub struct CmsContentInfoRef;
 }
 
 impl CmsContentInfoRef {
+    /// Given the sender's private key, `pkey` and the recipient's certificiate, `cert`,
+    /// decrypt the data in `self`.
+    ///
+    /// OpenSSL documentation at [`CMS_decrypt`]
+    ///
+    /// [`CMS_decrypt`]: https://www.openssl.org/docs/man1.1.0/crypto/CMS_decrypt.html
     pub fn decrypt(&self, pkey: &PKeyRef, cert: &X509) -> Result<Vec<u8>, ErrorStack> {
         unsafe {
             let pkey = pkey.as_ptr();
@@ -45,6 +67,11 @@ impl CmsContentInfoRef {
 }
 
 impl CmsContentInfo {
+    /// Parses a smime formatted `vec` of bytes into a `CmsContentInfo`.
+    ///
+    /// OpenSSL documentation at [`SMIME_read_CMS`]
+    ///
+    /// [`SMIME_read_CMS`]: https://www.openssl.org/docs/man1.0.2/crypto/SMIME_read_CMS.html
     pub fn smime_read_cms(smime: &[u8]) -> Result<CmsContentInfo, ErrorStack> {
         unsafe {
             let bio = MemBioSlice::new(smime)?;