CMS module documentation

openssl/src/cms.rs

@@ -1,4 +1,12 @@
-//! CMS archive
+//! SMIME implementation using CMS 
+//!
+//! CMS (PKCS#7) is an encyption standard.  It allows signing and ecrypting data using
+//! X.509 certificates.  cms is a command implemented in OpenSSL to support a
+//! SMIME upgrade to e-mail encryption.  Changes to adding CMS to the SMIME implementation
+//! would break SMIME backwards compatbility so the authors of OpenSSL added the CMS
+//! keyword.
+//!
+//!
 
 use ffi;
 use foreign_types::{ForeignType, ForeignTypeRef};
@@ -17,11 +25,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 +70,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 = try!(MemBioSlice::new(smime));