Initial CMS API documentation.

doc/crypto/CMS_add0_cert.pod

@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+ CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
+ int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
+ STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
+
+ int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
+ STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
+
+
+=head1 DESCRIPTION
+
+CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms> which
+must be of type signed data or enveloped data. 
+
+CMS_get1_certs() returns all certificates in B<cms>.
+
+CMS_add0_crl() adds CRL B<crl> to B<cms> which must be of type signed data or
+enveloped data. CMS_get1_crls() returns any CRLs in B<cms>.
+
+=head1 NOTES
+
+As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
+must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
+must be freed up.
+
+The same certificate or CRL must not be added to the same cms structure more
+than once.
+
+For signed data CMS types certificates and CRLs are added to the
+B<certificates> and B<crls> fields of the SignedData structure. For enveloped
+data they are added to B<OriginatorInfo>.
+
+=head1 RETURN VALUES
+
+CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() return 1 for success and
+0 for failure. 
+
+CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
+or NULL if there are none or an error occurs. The only error which will occur
+in practice is if the B<cms> type is invalid.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
+first added to OpenSSL 0.9.8
+
+=cut

doc/crypto/CMS_add1_recipient_cert.pod

@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+ CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
+
+ CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType);
+
+=head1 DESCRIPTION
+
+CMS_add1_recipient_cert() adds a recipient certificate B<recip> 
+CMS_ContentInfo enveloped data structure B<cms> as a KeyTransRecipientInfo
+structure.
+
+CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
+wrapping algorithm B<nid>, identifier B<id> or length B<idlen> and optional
+values B<date>, B<otherTypeId> abd B<otherType> to CMS_ContentInfo enveloped
+data structure B<cms> as a KEKRecipientInfo structure.
+
+The CMS_ContentInfo structure should be obtained from an initial call to
+CMS_encrypt() with the flag B<CMS_PARTIAL> set.
+
+=head1 NOTES
+
+The main purpose of this function is to provide finer control over a CMS
+enveloped data structure where the simpler CMS_encrypt() function defaults are
+not appropriate. For example if one or more KEKRecipientInfo structures
+need to be added. New attributes can also be added using the returned
+CMS_RecipientInfo structure and the CMS attribute utility functions.
+
+OpenSSL will by default identify recipient certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if all recipient certificates do not
+have a subject key identifier extension.
+
+Currently only AES based key wrapping algorithms are supported for B<nid>,
+specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
+If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
+consistent with B<keylen>.
+
+=head1 RETURN VALUES
+
+CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
+pointer to the CMS_RecipientInfo structure just added or NULL if an error
+occurs.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>,
+L<CMS_final(3)|CMS_final(3)>,
+
+=head1 HISTORY
+
+CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL
+0.9.8
+
+=cut

doc/crypto/CMS_decrypt.pod

@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+CMS_decrypt - decrypt content from a CMS envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *data, BIO *dcont, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_decrypt() extracts and decrypts the content from a CMS envelopedData
+structure. B<pkey> is the private key of the recipient, B<cert> is the
+recipients certificate, B<data> is a BIO to write the content to and
+B<flags> is an optional set of flags.
+
+The B<dcont> parameter is used in the rare case where the encrypted content
+is detached. It will normally be set to NULL.
+
+=head1 NOTES
+
+OpenSSL_add_all_algorithms() (or equivalent) should be called before using this
+function or errors about unknown algorithms will occur.
+
+Although the recipients certificate is not needed to decrypt the data it is
+needed to locate the appropriate (of possible several) recipients in the CMS
+structure. If B<cert> is set to NULL all possible recipients are tried.
+
+It is possible to determine the correct recipient key by other means (for
+example looking them up in a database) and settin them in the CMS strutucre
+in advance using the CMS utility functions such as CMS_set1_pkey(). In this
+case both B<cert> and B<pkey> should be set to NULL.
+
+To process KEKRecipientInfo types CMS_set1_key() should be used and B<cert>
+and B<pkey> set to NULL.
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+=head1 RETURN VALUES
+
+CMS_decrypt() returns either 1 for success or 0 for failure.
+The error can be obtained from ERR_get_error(3)
+
+=head1 BUGS
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in CMS_verify() also applies to CMS_decrypt().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
+
+=head1 HISTORY
+
+CMS_decrypt() was added to OpenSSL 0.9.8
+
+=cut

doc/crypto/CMS_encrypt.pod

@@ -0,0 +1,100 @@
+=pod
+
+=head1 NAME
+
+CMS_encrypt - create a CMS envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_encrypt() creates and returns a CMS envelopedData structure. B<certs>
+is a list of recipient certificates. B<in> is the content to be encrypted.
+B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Only certificates carrying RSA keys are supported in CMS and envelopedData so
+the recipient certificates supplied to this function must all contain RSA
+public keys, though they do not have to be signed using the RSA algorithm.
+
+EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
+because most clients will support it.
+
+Some old "export grade" clients may only support weak encryption using 40 or 64
+bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc()
+respectively.
+
+The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
+its parameters. 
+
+Many browsers implement a "sign and encrypt" option which is simply an S/MIME
+envelopedData containing an S/MIME signed message. This can be readily produced
+by storing the S/MIME signed message in a memory BIO and passing it to
+CMS_encrypt().
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
+prepended to the data.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
+B<CMS_TEXT> is ignored.
+
+OpenSSL will by default identify recipient certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if all recipient certificates do not
+have a subject key identifier extension.
+
+If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
+returned suitable for streaming I/O: no data is read from the BIO B<in>.
+
+If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
+returned to which additional recipients and attributes can be added before
+finalization.
+
+The data being encrypted is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
+practice and is not supported by SMIME_write_CMS().
+
+=head1 NOTES
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), d2i_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+The receipients specified in B<certs> use a CMS KeyTransRecipientInfo info
+structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL>
+and CMS_add0_recipient_key().
+
+The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
+added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
+
+=head1 RETURN VALUES
+
+CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
+
+=head1 HISTORY
+
+CMS_decrypt() was added to OpenSSL 0.9.8
+The B<CMS_STREAM> flag was first supported in OpenSSL 0.9.9.
+
+=cut

doc/crypto/CMS_get0_SignerInfos.pod

@@ -0,0 +1,77 @@
+=pod
+
+=head1 NAME
+
+CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
+
+ int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si,
+					ASN1_OCTET_STRING **keyid,
+					X509_NAME **issuer, ASN1_INTEGER **sno);
+ int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
+ void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
+
+=head1 DESCRIPTION
+
+The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
+associated with a CMS signedData structure.
+
+CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
+associated with a specific CMS_SignerInfo structure B<si>. Either the
+keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
+in B<issuer> and B<sno>.
+
+CMS_SignerInfo_cert_cmp() compares the cerificate B<cert> against the signer
+identifier B<si>. It returns zero if the comparison is successful and non zero
+if not.
+
+CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
+B<signer>.
+
+=head1 NOTES
+
+The main purpose of these functions is to enable an application to lookup
+signers certificates using any appropriate technique when the simpler method
+of CMS_verify() is not appropriate.
+
+In typical usage and application will retrieve all CMS_SignerInfo structures
+using CMS_get0_SignerInfo() and retrieve the identifier information using
+CMS. It will then obtain the signer certificate by some unspecified means
+(or return and error if it cannot be found) and set it using
+CMS_SignerInfo_set1_signer_cert().
+
+Once all signer certificates have been set CMS_verify() can be used.
+
+Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if
+there are no signers this is not a problem in practice because the only
+error which can occur is if the B<cms> structure is not of type signedData
+due to application error.
+
+=head1 RETURN VALUES
+
+CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
+are no signers or an error occurs.
+
+CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
+
+CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
+zero otherwise.
+
+CMS_SignerInfo_set1_signer_cert() does not return a value.
+
+Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
+
+=head1 HISTORY
+
+These functions were first was added to OpenSSL 0.9.8
+
+=cut

doc/crypto/CMS_get0_type.pod

@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+ CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
+ int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
+ const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
+
+=head1 DESCRIPTION
+
+CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
+and ASN1_OBJECT pointer. An application can then decide how to process the
+CMS_ContentInfo strutucture based on this value.
+
+CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
+structure. It should be called with CMS functions with the B<CMS_PARTIAL>
+flag and B<before> the strutucre is finalised, otherwise the results are
+undefined.
+
+ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
+content type.
+
+=head1 NOTES
+
+As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal
+pointers which should B<not> be freed up. CMS_set1_eContentType() copies the
+supplied OID and it B<should> be freed up after use.
+
+The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
+using OBJ_obj2nid(). For the currently supported content types the following
+values are returned:
+
+ NID_pkcs7_data
+ NID_pkcs7_signed
+ NID_pkcs7_digest
+ NID_id_smime_ct_compressedData:
+ NID_pkcs7_encrypted
+ NID_pkcs7_enveloped
+
+
+=head1 RETURN VALUES
+
+CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
+
+CMS_set1_eContentType() returns 1 for success or 0 if an error occurred.  The
+error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
+first added to OpenSSL 0.9.8
+
+=cut

doc/crypto/CMS_sign.pod

@@ -0,0 +1,119 @@
+=pod
+
+=head1 NAME
+
+CMS_sign - create a CMS signedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_sign() creates and returns a CMS signedData structure. B<signcert> is
+the certificate to sign with, B<pkey> is the corresponsding private key.
+B<certs> is an optional additional set of certificates to include in the CMS
+structure (for example any intermediate CAs in the chain). Any or all of
+these parameters can be B<NULL>, see B<NOTES> below.
+
+The data to be signed is read from BIO B<data>.
+
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+Many S/MIME clients expect the signed content to include valid MIME headers. If
+the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
+to the data.
+
+If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
+CMS_ContentInfo structure, the signer's certificate must still be supplied in
+the B<signcert> parameter though. This can reduce the size of the signature if
+the signers certificate can be obtained by other means: for example a
+previously signed message.
+
+The data being signed is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is used for
+CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
+messages for example.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it.
+
+The signedData structure includes several CMS signedAttributes including the
+signing time, the CMS content type and the supported list of ciphers in an
+SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
+will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
+omitted.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
+these algorithms is disabled then it will not be included.
+
+OpenSSL will by default identify signing certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if the signing certificate does not
+have a subject key identifier extension.
+
+If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
+structure is just initialized ready to perform the signing operation. The
+signing is however B<not> performed and the data to be signed is not read from
+the B<data> parameter. Signing is deferred until after the data has been
+written. In this way data can be signed in a single pass.
+
+If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
+output to which additional signers and capabilities can be added before
+finalization.
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), d2i_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+If a signer is specified it will use the default digest for the signing
+algorithm. This is B<SHA1> for both RSA and DSA keys.
+
+If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
+output.
+
+The function CMS_sign() is a basic CMS signing function whose output will be
+suitable for many purposes. For finer control of the output format the
+B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
+B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
+function B<CMS_sign_add1_signer()>, non default digests set and custom
+attributes added. B<CMS_final()> must then be called to finalize the
+structure if streaming is not enabled. 
+
+=head1 BUGS
+
+Some advanced attributes such as counter signatures are not supported.
+
+=head1 RETURN VALUES
+
+CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
+occurred.  The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
+
+=head1 HISTORY
+
+CMS_sign() was added to OpenSSL 0.9.8
+
+The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
+it is supportd for embedded data in OpenSSL 0.9.9 and later.
+
+=cut

doc/crypto/CMS_sign_add1_signer.pod

@@ -0,0 +1,98 @@
+=pod
+
+=head1 NAME
+
+CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
+
+int CMS_SignerInfo_sign(CMS_SignerInfo *si);
+
+
+=head1 DESCRIPTION
+
+CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private
+key B<pkey> using message digest B<md> to CMS_ContentInfo signed data
+structure B<cms>.
+
+The CMS_ContentInfo structure should be obtained from an initial call to
+CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
+valid CMS_ContentInfo signed data structure.
+
+If the B<md> parameter is B<NULL> then the default digest for the public
+key algorithm will be used.
+
+Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
+structure is not complete and must be finalized either by streaming (if
+applicable) or a call to CMS_final().
+
+The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
+structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
+are both set.
+
+=head1 NOTES
+
+The main purpose of this function is to provide finer control over a CMS
+signed data structure where the simpler CMS_sign() function defaults are
+not appropriate. For example if multiple signers or non default digest
+algorithms are needed. New attributes can also be added using the returned
+CMS_SignerInfo struture and the CMS attribute utility functions.
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
+digest value from the CMS_ContentInfo struture: to add a signer to an existing
+structure.  An error occurs if a matching digest value cannot be found to copy.
+The returned CMS_ContentInfo structure will be valid and finalized when this
+flag is set.
+
+If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the 
+B<CMS_SIGNER_INO> structure will not be finalized so additional attributes
+can be added. In this case an explicit call to CMS_SignerInfo_Sign() is
+needed to finalize it.
+
+If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
+CMS_ContentInfo structure, the signer's certificate must still be supplied in
+the B<signcert> parameter though. This can reduce the size of the signature if
+the signers certificate can be obtained by other means: for example a
+previously signed message.
+
+The signedData structure includes several CMS signedAttributes including the
+signing time, the CMS content type and the supported list of ciphers in an
+SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
+will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
+omitted.
+
+OpenSSL will by default identify signing certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if the signing certificate does not
+have a subject key identifier extension.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
+these algorithms is disabled then it will not be included.
+
+CMS_sign_add_signers() returns an internal pointer to the CMS_SIGNER_INFO
+structure just added, this can be used to set additional attributes 
+before it is finalized.
+
+=head1 RETURN VALUES
+
+CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo
+structure just added or NULL if an error occurs.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
+L<CMS_final(3)|CMS_final(3)>,
+
+=head1 HISTORY
+
+PEM_sign_add_signer() was added to OpenSSL 0.9.9
+
+=cut

doc/crypto/CMS_verify.pod

@@ -0,0 +1,127 @@
+=pod
+
+=head1 NAME
+
+CMS_verify - verify a CMS signedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
+
+ STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
+
+=head1 DESCRIPTION
+
+CMS_verify() verifies a CMS signedData structure. B<cms> is the CMS_ContentInfo
+structure to verify. B<certs> is a set of certificates in which to search for
+the signer's certificate. B<store> is a trusted certficate store (used for
+chain verification). B<indata> is the signed data if the content is not
+present in B<cms> (that is it is detached). The content is written to B<out>
+if it is not NULL.
+
+B<flags> is an optional set of flags, which can be used to modify the verify
+operation.
+
+CMS_get0_signers() retrieves the signer's certificate(s) from B<cms>, it must
+be called after a succeful CMS_verify() operation.
+
+=head1 VERIFY PROCESS
+
+Normally the verify process proceeds as follows.
+
+Initially some sanity checks are performed on B<cms>. The type of B<cms> must
+be signedData. There must be at least one signature on the data and if
+the content is detached B<indata> cannot be B<NULL>.
+
+An attempt is made to locate all the signer's certificates, first looking in
+the B<certs> parameter (if it is not B<NULL>) and then looking in any
+certificates contained in the B<cms> structure itself. If any signer's
+certificates cannot be located the operation fails.
+
+Each signer's certificate is chain verified using the B<smimesign> purpose and
+the supplied trusted certificate store. Any internal certificates in the message
+are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
+CRLs are used in addition to attempting to look the up in B<store>. If any
+chain verify fails an error code is returned.
+
+Finally the signed content is read (and written to B<out> is it is not NULL)
+and the signature's checked.
+
+If all signature's verify correctly then the function is successful.
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter to change the default verify behaviour.
+
+If B<CMS_NOINTERN> is set the certificates in the message itself are not 
+searched when locating the signer's certificate. This means that all the signers
+certificates must be in the B<certs> parameter.
+
+If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
+CRLs in the message itself are ignored.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signer's certificates are not
+verified.
+
+If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not 
+verified.
+
+If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
+
+=head1 NOTES
+
+One application of B<CMS_NOINTERN> is to only accept messages signed by
+a small number of certificates. The acceptable certificates would be passed
+in the B<certs> parameter. In this case if the signer is not one of the
+certificates supplied in B<certs> then the verify will fail because the
+signer cannot be found.
+
+In some cases the standard techniques for looking up and validating
+certificates are not appropriate: for example an application may wish to 
+lookup certificates in a database or perform customised verification. This
+can be achieved by setting and verifying the signers certificates manually 
+using the signed data utility functions.
+
+Care should be taken when modifying the default verify behaviour, for example
+setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification 
+and any modified content will be considered valid. This combination is however
+useful if one merely wishes to write the content to B<out> and its validity
+is not considered important.
+
+Chain verification should arguably be performed using the signing time rather
+than the current time. However since the signing time is supplied by the
+signer it cannot be trusted without additional evidence (such as a trusted
+timestamp).
+
+=head1 RETURN VALUES
+
+CMS_verify() returns 1 for a successful verification and zero if an error
+occured.
+
+CMS_get0_signers() returns all signers or B<NULL> if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 BUGS
+
+The trusted certificate store is not searched for the signers certificate,
+this is primarily due to the inadequacies of the current B<X509_STORE>
+functionality.
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in CMS_sign() also applies to CMS_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>
+
+=head1 HISTORY
+
+CMS_verify() was added to OpenSSL 0.9.8
+
+=cut

doc/crypto/PEM_write_bio_CMS_stream.pod

@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+ #include <openssl/pem.h>
+
+ int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format.
+
+It is otherwise identical to the function SMIME_write_CMS().
+
+=head1 NOTES
+
+This function is effectively a version of the PEM_write_bio_CMS() supporting
+streaming.
+
+=head1 RETURN VALUES
+
+PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
+L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
+L<CMS_decrypt(3)|CMS_decrypt(3)>,
+L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>,
+L<d2i_CMS_bio_stream(3)|d2i_CMS_bio_stream(3)>
+
+=head1 HISTORY
+
+PEM_write_bio_CMS_stream() was added to OpenSSL 0.9.9
+
+=cut

doc/crypto/SMIME_read_CMS.pod

@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+SMIME_read_CMS - parse S/MIME message.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
+
+=head1 DESCRIPTION
+
+SMIME_read_CMS() parses a message in S/MIME format.
+
+B<in> is a BIO to read the message from.
+
+If cleartext signing is used then the content is saved in
+a memory bio which is written to B<*bcont>, otherwise
+B<*bcont> is set to B<NULL>.
+
+The parsed CMS_ContentInfo structure is returned or B<NULL> if an
+error occurred.
+
+=head1 NOTES
+
+If B<*bcont> is not B<NULL> then the message is clear text
+signed. B<*bcont> can then be passed to CMS_verify() with
+the B<CMS_DETACHED> flag set.
+
+Otherwise the type of the returned structure can be determined
+using CMS_get0_type().
+
+To support future functionality if B<bcont> is not B<NULL>
+B<*bcont> should be initialized to B<NULL>. For example:
+
+ BIO *cont = NULL;
+ CMS_ContentInfo *cms;
+
+ cms = SMIME_read_CMS(in, &cont);
+
+=head1 BUGS
+
+The MIME parser used by SMIME_read_CMS() is somewhat primitive.
+While it will handle most S/MIME messages more complex compound
+formats may not work.
+
+The parser assumes that the CMS_ContentInfo structure is always base64
+encoded and will not handle the case where it is in binary format
+or uses quoted printable format.
+
+The use of a memory BIO to hold the signed content limits the size
+of message which can be processed due to memory restraints: a
+streaming single pass option should be available.
+
+=head1 RETURN VALUES
+
+SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL>
+if an error occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)>
+L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>,
+L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
+L<CMS_decrypt(3)|CMS_decrypt(3)>
+
+=head1 HISTORY
+
+SMIME_read_CMS() was added to OpenSSL 0.9.8
+
+=cut

doc/crypto/SMIME_write_CMS.pod

@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+SMIME_write_CMS - convert CMS structure to S/MIME format.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+SMIME_write_CMS() adds the appropriate MIME headers to a CMS
+structure to produce an S/MIME message.
+
+B<out> is the BIO to write the data to. B<cms> is the appropriate
+B<CMS_ContentInfo> structure. If streaming is enabled then the content must be
+supplied in the B<data> argument. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The following flags can be passed in the B<flags> parameter.
+
+If B<CMS_DETACHED> is set then cleartext signing will be used,
+this option only makes sense for signedData where B<CMS_DETACHED>
+is also set when CMS_sign() is called.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain>
+are added to the content, this only makes sense if B<CMS_DETACHED>
+is also set.
+
+If the B<CMS_STREAM> flag is set streaming is performed. This flag should
+only be set if B<CMS_STREAM> was also set in the previous call to a
+CMS_ContentInfo creation function.
+
+If cleartext signing is being used and B<CMS_STREAM> not set then
+the data must be read twice: once to compute the signature in CMS_sign()
+and once to output the S/MIME message.
+
+If streaming is performed the content is output in BER format using indefinite
+length constructuted encoding except in the case of signed data with detached
+content where the content is absent and DER format is used.
+
+=head1 BUGS
+
+SMIME_write_CMS() always base64 encodes CMS structures, there
+should be an option to disable this.
+
+=head1 RETURN VALUES
+
+SMIME_write_CMS() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
+L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
+L<CMS_decrypt(3)|CMS_decrypt(3)>
+
+=head1 HISTORY
+
+SMIME_write_CMS() was added to OpenSSL 0.9.8
+
+=cut

doc/crypto/i2d_CMS_bio_stream.pod

@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+d2i_CMS_bio_stream - output CMS_ContentInfo structure in BER format.
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format.
+
+It is otherwise identical to the function SMIME_write_CMS().
+
+=head1 NOTES
+
+This function is effectively a version of the i2d_CMS_bio() supporting
+streaming.
+
+=head1 BUGS
+
+The prefix "i2d" is arguably wrong because the function outputs BER format.
+
+=head1 RETURN VALUES
+
+i2d_CMS_bio_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
+L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
+L<CMS_decrypt(3)|CMS_decrypt(3)>,
+L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>,
+L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)>
+
+=head1 HISTORY
+
+d2i_CMS_bio_stream() was added to OpenSSL 0.9.9
+
+=cut