From e33ffaca12c67a115142d9327405babd21718e97 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Tue, 8 Apr 2008 22:27:10 +0000 Subject: [PATCH] Initial CMS API documentation. --- doc/crypto/CMS_add0_cert.pod | 60 +++++++++++ doc/crypto/CMS_add1_recipient_cert.pod | 63 ++++++++++++ doc/crypto/CMS_decrypt.pod | 64 ++++++++++++ doc/crypto/CMS_encrypt.pod | 100 +++++++++++++++++++ doc/crypto/CMS_get0_SignerInfos.pod | 77 ++++++++++++++ doc/crypto/CMS_get0_type.pod | 63 ++++++++++++ doc/crypto/CMS_sign.pod | 119 ++++++++++++++++++++++ doc/crypto/CMS_sign_add1_signer.pod | 98 ++++++++++++++++++ doc/crypto/CMS_verify.pod | 127 ++++++++++++++++++++++++ doc/crypto/PEM_write_bio_CMS_stream.pod | 41 ++++++++ doc/crypto/SMIME_read_CMS.pod | 73 ++++++++++++++ doc/crypto/SMIME_write_CMS.pod | 65 ++++++++++++ doc/crypto/i2d_CMS_bio_stream.pod | 44 ++++++++ 13 files changed, 994 insertions(+) create mode 100644 doc/crypto/CMS_add0_cert.pod create mode 100644 doc/crypto/CMS_add1_recipient_cert.pod create mode 100644 doc/crypto/CMS_decrypt.pod create mode 100644 doc/crypto/CMS_encrypt.pod create mode 100644 doc/crypto/CMS_get0_SignerInfos.pod create mode 100644 doc/crypto/CMS_get0_type.pod create mode 100644 doc/crypto/CMS_sign.pod create mode 100644 doc/crypto/CMS_sign_add1_signer.pod create mode 100644 doc/crypto/CMS_verify.pod create mode 100644 doc/crypto/PEM_write_bio_CMS_stream.pod create mode 100644 doc/crypto/SMIME_read_CMS.pod create mode 100644 doc/crypto/SMIME_write_CMS.pod create mode 100644 doc/crypto/i2d_CMS_bio_stream.pod diff --git a/doc/crypto/CMS_add0_cert.pod b/doc/crypto/CMS_add0_cert.pod new file mode 100644 index 0000000000..8e7c9ac5fa --- /dev/null +++ b/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 + + 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 to B which +must be of type signed data or enveloped data. + +CMS_get1_certs() returns all certificates in B. + +CMS_add0_crl() adds CRL B to B which must be of type signed data or +enveloped data. CMS_get1_crls() returns any CRLs in B. + +=head1 NOTES + +As the B<0> implies CMS_add0_cert() adds B internally to B and it +must not be freed up after the call as opposed to CMS_add1_cert() where B +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 and B fields of the SignedData structure. For enveloped +data they are added to B. + +=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 type is invalid. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all +first added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/CMS_add1_recipient_cert.pod b/doc/crypto/CMS_add1_recipient_cert.pod new file mode 100644 index 0000000000..5e737e29fd --- /dev/null +++ b/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 + + 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 +CMS_ContentInfo enveloped data structure B as a KeyTransRecipientInfo +structure. + +CMS_add0_recipient_key() adds symmetric key B of length B using +wrapping algorithm B, identifier B or length B and optional +values B, B abd B to CMS_ContentInfo enveloped +data structure B as a KEKRecipientInfo structure. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_encrypt() with the flag B 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 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, +specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. +If B is set to B then an AES wrap algorithm will be used +consistent with B. + +=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, L, +L, + +=head1 HISTORY + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL +0.9.8 + +=cut diff --git a/doc/crypto/CMS_decrypt.pod b/doc/crypto/CMS_decrypt.pod new file mode 100644 index 0000000000..239069bd78 --- /dev/null +++ b/doc/crypto/CMS_decrypt.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +CMS_decrypt - decrypt content from a CMS envelopedData structure + +=head1 SYNOPSIS + + #include + + 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 is the private key of the recipient, B is the +recipients certificate, B is a BIO to write the content to and +B is an optional set of flags. + +The B 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 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 and B should be set to NULL. + +To process KEKRecipientInfo types CMS_set1_key() should be used and B +and B set to NULL. + +The following flags can be passed in the B parameter. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B 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, L + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/CMS_encrypt.pod b/doc/crypto/CMS_encrypt.pod new file mode 100644 index 0000000000..d6cd47f600 --- /dev/null +++ b/doc/crypto/CMS_encrypt.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +CMS_encrypt - create a CMS envelopedData structure + +=head1 SYNOPSIS + + #include + + 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 +is a list of recipient certificates. B is the content to be encrypted. +B is the symmetric cipher to use. B 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 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 parameter. + +If the B flag is set MIME headers for type B are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B 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 is set then +B is ignored. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B 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 flag is set a partial B structure is +returned suitable for streaming I/O: no data is read from the BIO B. + +If the B flag is set a partial B 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 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 is set the returned B structure is +B complete and outputting its contents via a function that does not +properly finalize the B 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 directly using +BIO_new_CMS(). + +The receipients specified in B use a CMS KeyTransRecipientInfo info +structure. KEKRecipientInfo is also supported using the flag B +and CMS_add0_recipient_key(). + +The parameter B may be NULL if B 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, L + +=head1 HISTORY + +CMS_decrypt() was added to OpenSSL 0.9.8 +The B flag was first supported in OpenSSL 0.9.9. + +=cut diff --git a/doc/crypto/CMS_get0_SignerInfos.pod b/doc/crypto/CMS_get0_SignerInfos.pod new file mode 100644 index 0000000000..7276e70224 --- /dev/null +++ b/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 + + 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. Either the +keyidentifier will be set in B or B issuer name and serial number +in B and B. + +CMS_SignerInfo_cert_cmp() compares the cerificate B against the signer +identifier B. It returns zero if the comparison is successful and non zero +if not. + +CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B to +B. + +=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 if +there are no signers this is not a problem in practice because the only +error which can occur is if the B 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 + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These functions were first was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/CMS_get0_type.pod b/doc/crypto/CMS_get0_type.pod new file mode 100644 index 0000000000..6f8f8f6578 --- /dev/null +++ b/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 + + 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 +flag and B 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 be freed up. CMS_set1_eContentType() copies the +supplied OID and it B be freed up after use. + +The B values returned can be converted to an integer B 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 + +=head1 HISTORY + +CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all +first added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/CMS_sign.pod b/doc/crypto/CMS_sign.pod new file mode 100644 index 0000000000..8f573018c2 --- /dev/null +++ b/doc/crypto/CMS_sign.pod @@ -0,0 +1,119 @@ +=pod + +=head1 NAME + +CMS_sign - create a CMS signedData structure + +=head1 SYNOPSIS + + #include + + 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 is +the certificate to sign with, B is the corresponsding private key. +B 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, see B below. + +The data to be signed is read from BIO B. + +B is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B +parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B flag is set MIME headers for type B are prepended +to the data. + +If B 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 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 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 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 is set then no signedAttributes +will be used. If B 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 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 is set then the returned B +structure is just initialized ready to perform the signing operation. The +signing is however B performed and the data to be signed is not read from +the B 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 flag is set a partial B structure is +output to which additional signers and capabilities can be added before +finalization. + +If the flag B is set the returned B structure is +B complete and outputting its contents via a function that does not +properly finalize the B 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 directly using +BIO_new_CMS(). + +If a signer is specified it will use the default digest for the signing +algorithm. This is B for both RSA and DSA keys. + +If B and B 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, B and B parameters can all be B and the +B flag set. Then one or more signers can be added using the +function B, non default digests set and custom +attributes added. B 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, L + +=head1 HISTORY + +CMS_sign() was added to OpenSSL 0.9.8 + +The B 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 diff --git a/doc/crypto/CMS_sign_add1_signer.pod b/doc/crypto/CMS_sign_add1_signer.pod new file mode 100644 index 0000000000..6513885f8f --- /dev/null +++ b/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 + + 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 and private +key B using message digest B to CMS_ContentInfo signed data +structure B. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_sign() with the flag B set or in the case or re-signing a +valid CMS_ContentInfo signed data structure. + +If the B parameter is B then the default digest for the public +key algorithm will be used. + +Unless the B 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 and B 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 +parameter. + +If B 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 is set in addition to B then the +B 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 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 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 is set then no signedAttributes +will be used. If B is set then just the SMIMECapabilities are +omitted. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B 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, L, +L, + +=head1 HISTORY + +PEM_sign_add_signer() was added to OpenSSL 0.9.9 + +=cut diff --git a/doc/crypto/CMS_verify.pod b/doc/crypto/CMS_verify.pod new file mode 100644 index 0000000000..74c09e25fd --- /dev/null +++ b/doc/crypto/CMS_verify.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +CMS_verify - verify a CMS signedData structure + +=head1 SYNOPSIS + + #include + + 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 is the CMS_ContentInfo +structure to verify. B is a set of certificates in which to search for +the signer's certificate. B is a trusted certficate store (used for +chain verification). B is the signed data if the content is not +present in B (that is it is detached). The content is written to B +if it is not NULL. + +B 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, 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. The type of B must +be signedData. There must be at least one signature on the data and if +the content is detached B cannot be B. + +An attempt is made to locate all the signer's certificates, first looking in +the B parameter (if it is not B) and then looking in any +certificates contained in the B structure itself. If any signer's +certificates cannot be located the operation fails. + +Each signer's certificate is chain verified using the B 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 any internal +CRLs are used in addition to attempting to look the up in B. If any +chain verify fails an error code is returned. + +Finally the signed content is read (and written to B 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 +parameter to change the default verify behaviour. + +If B 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 parameter. + +If B is set and CRL checking is enabled in B then any +CRLs in the message itself are ignored. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B then an error is +returned. + +If B is set the signer's certificates are not +verified. + +If B is set the signed attributes signature is not +verified. + +If B is set then the content digest is not checked. + +=head1 NOTES + +One application of B is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B parameter. In this case if the signer is not one of the +certificates supplied in B 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 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 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 if an error occurred. + +The error can be obtained from L + +=head1 BUGS + +The trusted certificate store is not searched for the signers certificate, +this is primarily due to the inadequacies of the current B +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, L + +=head1 HISTORY + +CMS_verify() was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/PEM_write_bio_CMS_stream.pod b/doc/crypto/PEM_write_bio_CMS_stream.pod new file mode 100644 index 0000000000..0d88551b97 --- /dev/null +++ b/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 + #include + + 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, L, +L, L +L, +L, +L + +=head1 HISTORY + +PEM_write_bio_CMS_stream() was added to OpenSSL 0.9.9 + +=cut diff --git a/doc/crypto/SMIME_read_CMS.pod b/doc/crypto/SMIME_read_CMS.pod new file mode 100644 index 0000000000..84fbc0dd8b --- /dev/null +++ b/doc/crypto/SMIME_read_CMS.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SMIME_read_CMS - parse S/MIME message. + +=head1 SYNOPSIS + + #include + + CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); + +=head1 DESCRIPTION + +SMIME_read_CMS() parses a message in S/MIME format. + +B 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. + +The parsed CMS_ContentInfo structure is returned or B if an +error occurred. + +=head1 NOTES + +If B<*bcont> is not B then the message is clear text +signed. B<*bcont> can then be passed to CMS_verify() with +the B flag set. + +Otherwise the type of the returned structure can be determined +using CMS_get0_type(). + +To support future functionality if B is not B +B<*bcont> should be initialized to B. 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 structure or B +if an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L +L, L, +L, L +L + +=head1 HISTORY + +SMIME_read_CMS() was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/SMIME_write_CMS.pod b/doc/crypto/SMIME_write_CMS.pod new file mode 100644 index 0000000000..6319876b7d --- /dev/null +++ b/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 + + 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 is the BIO to write the data to. B is the appropriate +B structure. If streaming is enabled then the content must be +supplied in the B argument. B is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B parameter. + +If B is set then cleartext signing will be used, +this option only makes sense for signedData where B +is also set when CMS_sign() is called. + +If the B flag is set MIME headers for type B +are added to the content, this only makes sense if B +is also set. + +If the B flag is set streaming is performed. This flag should +only be set if B was also set in the previous call to a +CMS_ContentInfo creation function. + +If cleartext signing is being used and B 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, L, +L, L +L + +=head1 HISTORY + +SMIME_write_CMS() was added to OpenSSL 0.9.8 + +=cut diff --git a/doc/crypto/i2d_CMS_bio_stream.pod b/doc/crypto/i2d_CMS_bio_stream.pod new file mode 100644 index 0000000000..6d499375f8 --- /dev/null +++ b/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 + + 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, L, +L, L +L, +L, +L + +=head1 HISTORY + +d2i_CMS_bio_stream() was added to OpenSSL 0.9.9 + +=cut -- 2.25.1