Initial CMS API documentation.

=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

=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

=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

=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

=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