Merge pull request #748 from AndyGauge/doc-cms

//! 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};

    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();

}

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)?;