Merge branch 'master' of https://github.com/sfackler/rust-openssl

1 files changed, 34 insertions, 7 deletions

diff --git a/openssl/src/cms.rs b/openssl/src/cms.rs
index 9619d0b8..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,26 +22,43 @@ 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();
             let cert = cert.as_ptr();
-            let out = try!(MemBio::new());
+            let out = MemBio::new()?;
             let flags: u32 = 0;
 
-            try!(cvt(ffi::CMS_decrypt(
+            cvt(ffi::CMS_decrypt(
                 self.as_ptr(),
                 pkey,
                 cert,
                 ptr::null_mut(),
                 out.as_ptr(),
                 flags.into(),
-            )));
+            ))?;
 
             Ok(out.get_buf().to_owned())
         }
@@ -45,14 +67,19 @@ 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 = try!(MemBioSlice::new(smime));
+            let bio = MemBioSlice::new(smime)?;
 
-            let cms = try!(cvt_p(ffi::SMIME_read_CMS(
+            let cms = cvt_p(ffi::SMIME_read_CMS(
                 bio.as_ptr(),
                 ptr::null_mut(),
-            )));
+            ))?;
 
             Ok(CmsContentInfo::from_ptr(cms))
         }