From 4e59fab75399776cbbf6c7d496c4eeb58a4eb087 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 3 Oct 2017 11:07:35 -0700 Subject: [PATCH 1/2] CMS module documentation --- openssl/src/cms.rs | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/openssl/src/cms.rs b/openssl/src/cms.rs index 9619d0b8..381b048d 100644 --- a/openssl/src/cms.rs +++ b/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, 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 { unsafe { let bio = try!(MemBioSlice::new(smime)); From 040287dbb54b86ec633b22e00489dc4c6845d13c Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Wed, 4 Oct 2017 08:22:40 -0700 Subject: [PATCH 2/2] Module level documentaiton rewrite --- openssl/src/cms.rs | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/openssl/src/cms.rs b/openssl/src/cms.rs index 381b048d..6745e8a6 100644 --- a/openssl/src/cms.rs +++ b/openssl/src/cms.rs @@ -1,12 +1,9 @@ -//! SMIME implementation using CMS +//! 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. -//! -//! +//! 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};