diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2008-04-08 22:27:10 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2008-04-08 22:27:10 +0000 |
commit | e33ffaca12c67a115142d9327405babd21718e97 (patch) | |
tree | 46bc035248002c47f9fa5d88642673b51a73a643 | |
parent | 853eae51e0ef43d8079bbe1a56155db6f49f5624 (diff) |
Initial CMS API documentation.
-rw-r--r-- | doc/crypto/CMS_add0_cert.pod | 60 | ||||
-rw-r--r-- | doc/crypto/CMS_add1_recipient_cert.pod | 63 | ||||
-rw-r--r-- | doc/crypto/CMS_decrypt.pod | 64 | ||||
-rw-r--r-- | doc/crypto/CMS_encrypt.pod | 100 | ||||
-rw-r--r-- | doc/crypto/CMS_get0_SignerInfos.pod | 77 | ||||
-rw-r--r-- | doc/crypto/CMS_get0_type.pod | 63 | ||||
-rw-r--r-- | doc/crypto/CMS_sign.pod | 119 | ||||
-rw-r--r-- | doc/crypto/CMS_sign_add1_signer.pod | 98 | ||||
-rw-r--r-- | doc/crypto/CMS_verify.pod | 127 | ||||
-rw-r--r-- | doc/crypto/PEM_write_bio_CMS_stream.pod | 41 | ||||
-rw-r--r-- | doc/crypto/SMIME_read_CMS.pod | 73 | ||||
-rw-r--r-- | doc/crypto/SMIME_write_CMS.pod | 65 | ||||
-rw-r--r-- | doc/crypto/i2d_CMS_bio_stream.pod | 44 |
13 files changed, 994 insertions, 0 deletions
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 <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 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 <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 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 <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 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 <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 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 <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 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 <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 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 <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 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 <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 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 <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 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 <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)& |