From 38d3a7380817e272df7df2e8c32fc22d6b35e332 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Thu, 10 Apr 2008 23:28:25 +0000 Subject: [PATCH] Reformat, fix typos and clarify CMS API docs. --- doc/crypto/BIO_new_CMS.pod | 24 ++++++++------- doc/crypto/CMS_add0_cert.pod | 21 ++++++++----- doc/crypto/CMS_add1_recipient_cert.pod | 7 ++--- doc/crypto/CMS_compress.pod | 4 +-- doc/crypto/CMS_decrypt.pod | 11 +++---- doc/crypto/CMS_encrypt.pod | 14 ++++----- doc/crypto/CMS_final.pod | 2 +- doc/crypto/CMS_get0_RecipientInfos.pod | 6 ++-- doc/crypto/CMS_get0_SignerInfos.pod | 6 ++-- doc/crypto/CMS_get1_ReceiptRequest.pod | 13 +++++---- doc/crypto/CMS_sign.pod | 14 +++++---- doc/crypto/CMS_sign_add1_signer.pod | 12 ++++---- doc/crypto/CMS_sign_receipt.pod | 2 +- doc/crypto/CMS_uncompress.pod | 6 ++-- doc/crypto/CMS_verify.pod | 39 ++++++++++++------------- doc/crypto/CMS_verify_receipt.pod | 8 ++--- doc/crypto/PEM_write_bio_CMS_stream.pod | 2 +- doc/crypto/SMIME_read_CMS.pod | 35 ++++++++++------------ doc/crypto/SMIME_write_CMS.pod | 29 +++++++++--------- doc/crypto/i2d_CMS_bio_stream.pod | 2 +- 20 files changed, 128 insertions(+), 129 deletions(-) diff --git a/doc/crypto/BIO_new_CMS.pod b/doc/crypto/BIO_new_CMS.pod index f73ab4c05a..c5aab9b2aa 100644 --- a/doc/crypto/BIO_new_CMS.pod +++ b/doc/crypto/BIO_new_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME -BIO_new_CMS - CMS streaming filter BIO + BIO_new_CMS - CMS streaming filter BIO =head1 SYNOPSIS @@ -13,28 +13,30 @@ BIO_new_CMS - CMS streaming filter BIO =head1 DESCRIPTION BIO_new_CMS() returns a streaming filter BIO chain based on B. The output -of the filter is written to B. Any data written to the returned BIO -is automatically translated to a BER format CMS structure. +of the filter is written to B. Any data written to the chain is +automatically translated to a BER format CMS structure of the appropriate type. =head1 NOTES -The BIO returned by this functions behaves like a standard filter BIO. It -supports non blocking I/O. Content is processes and streamed on the fly and not +The chain returned by this function behaves like a standard filter BIO. It +supports non blocking I/O. Content is processed and streamed on the fly and not all held in memory at once: so it is possible to encode very large structures. -After all content has been written through the BIO BIO_flush() must be called +After all content has been written through the chain BIO_flush() must be called to finalise the structure. The B flag must be included in the corresponding B parameter of the B creation function. -After use BIOs should be removed from the filter using BIO_pop() until -the output BIO B is reached. +If an application wishes to write additional data to B BIOs should be +removed from the chain using BIO_pop() and freed with BIO_free() until B +is reached. If no additional data needs to be written BIO_free_all() can be +called to free up the whole chain. -Any content written through the filter is uses "as-is" and no canonical +Any content written through the filter is used verbatim: no canonical translation is performed. -It is possible to chain multiple BIOs to for example create a triple wrapped -signed, enveloped signed structure. In this case it is the applications +It is possible to chain multiple BIOs to, for example, create a triple wrapped +signed, enveloped, signed structure. In this case it is the applications responsibility to set the inner content type of any outer CMS_ContentInfo structures. diff --git a/doc/crypto/CMS_add0_cert.pod b/doc/crypto/CMS_add0_cert.pod index 942c172ef0..2670bfa925 100644 --- a/doc/crypto/CMS_add0_cert.pod +++ b/doc/crypto/CMS_add0_cert.pod @@ -18,16 +18,23 @@ =head1 DESCRIPTION -CMS_add0_cert() and CMS_add1_cert() add certificate B to B which +CMS_add0_cert() and CMS_add1_cert() add certificate B to B. 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. +CMS_add0_crl() adds CRL B to B. CMS_get1_crls() returns any CRLs in +B. =head1 NOTES +The CMS_ContentInfo structure B must be of type signed data or enveloped +data or an error will be returned. + +For signed data certificates and CRLs are added to the B and +B fields of SignedData structure. For enveloped data they are added to +B. + 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. @@ -35,10 +42,6 @@ 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 @@ -50,7 +53,9 @@ in practice is if the B type is invalid. =head1 SEE ALSO -L +L, +L, +L =head1 HISTORY diff --git a/doc/crypto/CMS_add1_recipient_cert.pod b/doc/crypto/CMS_add1_recipient_cert.pod index d1e4104bb8..d7d8e2532c 100644 --- a/doc/crypto/CMS_add1_recipient_cert.pod +++ b/doc/crypto/CMS_add1_recipient_cert.pod @@ -14,12 +14,11 @@ =head1 DESCRIPTION -CMS_add1_recipient_cert() adds a recipient certificate B -CMS_ContentInfo enveloped data structure B as a KeyTransRecipientInfo -structure. +CMS_add1_recipient_cert() adds recipient B to 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 +wrapping algorithm B, identifier B of length B and optional values B, B and B to CMS_ContentInfo enveloped data structure B as a KEKRecipientInfo structure. diff --git a/doc/crypto/CMS_compress.pod b/doc/crypto/CMS_compress.pod index ce933d6342..f017e9f041 100644 --- a/doc/crypto/CMS_compress.pod +++ b/doc/crypto/CMS_compress.pod @@ -14,7 +14,7 @@ CMS_compress - create a CMS CompressedData structure CMS_compress() creates and returns a CMS CompressedData structure. B is the compression algorithm to use or B to use the default -algorithms (zlib compression). B is the content to be compressed. +algorithm (zlib compression). B is the content to be compressed. B is an optional set of flags. =head1 NOTES @@ -22,7 +22,7 @@ B is an optional set of flags. The only currently supported compression algorithm is zlib using the NID NID_zlib_compression. -If zlib support is not compiled into OpenSSL this CMS_compress() will return +If zlib support is not compiled into OpenSSL then CMS_compress() will return an error. If the B flag is set MIME headers for type B are diff --git a/doc/crypto/CMS_decrypt.pod b/doc/crypto/CMS_decrypt.pod index b6bb3b1188..cacab3819c 100644 --- a/doc/crypto/CMS_decrypt.pod +++ b/doc/crypto/CMS_decrypt.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_decrypt - decrypt content from a CMS envelopedData structure + CMS_decrypt - decrypt content from a CMS envelopedData structure =head1 SYNOPSIS @@ -12,9 +12,9 @@ CMS_decrypt - decrypt content from a CMS envelopedData structure =head1 DESCRIPTION -CMS_decrypt() extracts and decrypts the content from a CMS envelopedData +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 +recipient's 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 @@ -34,8 +34,9 @@ example looking them up in a database) and setting them in the CMS structure 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. +To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() +and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and +B and B set to NULL. The following flags can be passed in the B parameter. diff --git a/doc/crypto/CMS_encrypt.pod b/doc/crypto/CMS_encrypt.pod index 0e3c79e4b3..8d4975573b 100644 --- a/doc/crypto/CMS_encrypt.pod +++ b/doc/crypto/CMS_encrypt.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_encrypt - create a CMS envelopedData structure + CMS_encrypt - create a CMS envelopedData structure =head1 SYNOPSIS @@ -12,23 +12,19 @@ CMS_encrypt - create a CMS envelopedData structure =head1 DESCRIPTION -CMS_encrypt() creates and returns a CMS envelopedData structure. B +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. +Only certificates carrying RSA keys are supported 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. diff --git a/doc/crypto/CMS_final.pod b/doc/crypto/CMS_final.pod index e4bcdfca81..36cf96b8a0 100644 --- a/doc/crypto/CMS_final.pod +++ b/doc/crypto/CMS_final.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_final - finalise a CMS_ContentInfo structure + CMS_final - finalise a CMS_ContentInfo structure =head1 SYNOPSIS diff --git a/doc/crypto/CMS_get0_RecipientInfos.pod b/doc/crypto/CMS_get0_RecipientInfos.pod index 7b9a31cf56..e0355423e6 100644 --- a/doc/crypto/CMS_get0_RecipientInfos.pod +++ b/doc/crypto/CMS_get0_RecipientInfos.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines + CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines =head1 SYNOPSIS @@ -24,7 +24,7 @@ CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_sig =head1 DESCRIPTION The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo -structures associated with a CMS envelopedData structure. +structures associated with a CMS EnvelopedData structure. CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B. It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, @@ -76,7 +76,7 @@ In typical usage and application will retrieve all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and check the type of each using CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure can be ignored or its key identifier data retrieved using an appropriate -function. Then if the corresponding secret or private key can be obtained by +function. Then if the corresponding secret or private key can be obtained by any appropriate means it can then associated with the structure and CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called with a NULL key to decrypt the enveloped content. diff --git a/doc/crypto/CMS_get0_SignerInfos.pod b/doc/crypto/CMS_get0_SignerInfos.pod index a992f04865..47f6d2a047 100644 --- a/doc/crypto/CMS_get0_SignerInfos.pod +++ b/doc/crypto/CMS_get0_SignerInfos.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions. + CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions. =head1 SYNOPSIS @@ -10,9 +10,7 @@ CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CM 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_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); diff --git a/doc/crypto/CMS_get1_ReceiptRequest.pod b/doc/crypto/CMS_get1_ReceiptRequest.pod index 7cbb0c67f3..f546376a1e 100644 --- a/doc/crypto/CMS_get1_ReceiptRequest.pod +++ b/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -8,10 +8,10 @@ #include -CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); -int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); -int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); -void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); + CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); + int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); + int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); + void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); =head1 DESCRIPTION @@ -62,7 +62,8 @@ L =head1 HISTORY -CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were -added to OpenSSL 0.9.8 +CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), +CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to +OpenSSL 0.9.8 =cut diff --git a/doc/crypto/CMS_sign.pod b/doc/crypto/CMS_sign.pod index 88258cec15..3fb63f2e31 100644 --- a/doc/crypto/CMS_sign.pod +++ b/doc/crypto/CMS_sign.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_sign - create a CMS SignedData structure + CMS_sign - create a CMS SignedData structure =head1 SYNOPSIS @@ -54,8 +54,10 @@ 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. +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. OpenSSL will by default identify signing certificates using issuer name and serial number. If B is set it will use the subject key @@ -92,18 +94,18 @@ 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 +function CMS_sign_add1_signer(), non default digests can be used 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. +Some 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). +occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO diff --git a/doc/crypto/CMS_sign_add1_signer.pod b/doc/crypto/CMS_sign_add1_signer.pod index 6ebd102018..c5e4f198d5 100644 --- a/doc/crypto/CMS_sign_add1_signer.pod +++ b/doc/crypto/CMS_sign_add1_signer.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. =head1 SYNOPSIS @@ -10,18 +10,18 @@ CMS_sign_add_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo sig CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); -int CMS_SignerInfo_sign(CMS_SignerInfo *si); + 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 +key B using message digest B to CMS_ContentInfo SignedData 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. +valid CMS_ContentInfo SignedData structure. If the B parameter is B then the default digest for the public key algorithm will be used. @@ -36,7 +36,7 @@ are both set. =head1 NOTES -The main purpose of this CMS_sign_add1_signer() is to provide finer control +The main purpose of CMS_sign_add1_signer() 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 @@ -63,7 +63,7 @@ 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 +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 diff --git a/doc/crypto/CMS_sign_receipt.pod b/doc/crypto/CMS_sign_receipt.pod index f603ab66f0..cae1f83384 100644 --- a/doc/crypto/CMS_sign_receipt.pod +++ b/doc/crypto/CMS_sign_receipt.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_sign_receipt - create a CMS signed receipt + CMS_sign_receipt - create a CMS signed receipt =head1 SYNOPSIS diff --git a/doc/crypto/CMS_uncompress.pod b/doc/crypto/CMS_uncompress.pod index 56d6de5158..c6056b027d 100644 --- a/doc/crypto/CMS_uncompress.pod +++ b/doc/crypto/CMS_uncompress.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_uncompress - uncompress a CMS CompressedData structure + CMS_uncompress - uncompress a CMS CompressedData structure =head1 SYNOPSIS @@ -21,8 +21,8 @@ is detached. It will normally be set to NULL. =head1 NOTES -The only currently supported compression algorithm is zlib if the structure -indicates the use of any other algorithm and error is returned. +The only currently supported compression algorithm is zlib: if the structure +indicates the use of any other algorithm an error is returned. If zlib support is not compiled into OpenSSL then CMS_uncompress() will always return an error. diff --git a/doc/crypto/CMS_verify.pod b/doc/crypto/CMS_verify.pod index 0dfcf3dab4..8f26fdab09 100644 --- a/doc/crypto/CMS_verify.pod +++ b/doc/crypto/CMS_verify.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_verify - verify a CMS SignedData structure + CMS_verify - verify a CMS SignedData structure =head1 SYNOPSIS @@ -16,15 +16,14 @@ CMS_verify - verify a CMS SignedData structure 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 certificate 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. +the signing certificate(s). B is a trusted certificate store used for +chain verification. B is the detached content if the content is not +present in B. 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 +CMS_get0_signers() retrieves the signing certificate(s) from B, it must be called after a successful CMS_verify() operation. =head1 VERIFY PROCESS @@ -35,15 +34,15 @@ 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. +An attempt is made to locate all the signing certificate(s), first looking in +the B parameter (if it is not NULL) and then looking in any +certificates contained in the B structure itself. If any signing +certificate cannot be located the operation fails. -Each signer's certificate is chain verified using the B purpose and +Each signing 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 +CRLs are used in addition to attempting to look them 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) @@ -54,9 +53,9 @@ 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 the certificates in the message itself are not +searched when locating the signing certificate(s). This means that all the +signing 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. @@ -65,7 +64,7 @@ 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 +If B is set the signing certificates are not verified. If B is set the signed attributes signature is not @@ -103,18 +102,18 @@ timestamp). CMS_verify() returns 1 for a successful verification and zero if an error occurred. -CMS_get0_signers() returns all signers or B if an error occurred. +CMS_get0_signers() returns all signers or NULL if an error occurred. The error can be obtained from L =head1 BUGS -The trusted certificate store is not searched for the signers certificate, +The trusted certificate store is not searched for the signing 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(). +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. =head1 SEE ALSO diff --git a/doc/crypto/CMS_verify_receipt.pod b/doc/crypto/CMS_verify_receipt.pod index d90f161bcf..9283e0e04b 100644 --- a/doc/crypto/CMS_verify_receipt.pod +++ b/doc/crypto/CMS_verify_receipt.pod @@ -2,7 +2,7 @@ =head1 NAME -CMS_verify - verify a CMS signed receipt + CMS_verify_receipt - verify a CMS signed receipt =head1 SYNOPSIS @@ -14,8 +14,8 @@ CMS_verify - verify a CMS signed receipt CMS_verify_receipt() verifies a CMS signed receipt. B is the signed receipt to verify. B is the original SignedData structure containing the -receipt request B is a set of certificates in which to search for the -signer's certificate. B is a trusted certificate store (used for chain +receipt request. B is a set of certificates in which to search for the +signing certificate. B is a trusted certificate store (used for chain verification). B is an optional set of flags, which can be used to modify the verify @@ -42,6 +42,6 @@ L, =head1 HISTORY -CMS_verify() was added to OpenSSL 0.9.8 +CMS_verify_receipt() 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 index bbb865a371..aa7047eab5 100644 --- a/doc/crypto/PEM_write_bio_CMS_stream.pod +++ b/doc/crypto/PEM_write_bio_CMS_stream.pod @@ -2,7 +2,7 @@ =head1 NAME -PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. + PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. =head1 SYNOPSIS diff --git a/doc/crypto/SMIME_read_CMS.pod b/doc/crypto/SMIME_read_CMS.pod index 84fbc0dd8b..acc5524c14 100644 --- a/doc/crypto/SMIME_read_CMS.pod +++ b/doc/crypto/SMIME_read_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME -SMIME_read_CMS - parse S/MIME message. + SMIME_read_CMS - parse S/MIME message. =head1 SYNOPSIS @@ -16,24 +16,22 @@ 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. +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 NULL. -The parsed CMS_ContentInfo structure is returned or B if an +The parsed CMS_ContentInfo structure is returned or NULL 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. +If B<*bcont> is not NULL 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: +To support future functionality if B is not NULL B<*bcont> should be +initialized to NULL. For example: BIO *cont = NULL; CMS_ContentInfo *cms; @@ -42,17 +40,16 @@ B<*bcont> should be initialized to B. For example: =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 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 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. +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 diff --git a/doc/crypto/SMIME_write_CMS.pod b/doc/crypto/SMIME_write_CMS.pod index ccec6cafa8..04bedfb429 100644 --- a/doc/crypto/SMIME_write_CMS.pod +++ b/doc/crypto/SMIME_write_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME -SMIME_write_CMS - convert CMS structure to S/MIME format. + SMIME_write_CMS - convert CMS structure to S/MIME format. =head1 SYNOPSIS @@ -23,21 +23,20 @@ supplied in the B argument. B is an optional set of flags. 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 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 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 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 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 constructed encoding except in the case of signed data with detached @@ -45,8 +44,8 @@ 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. +SMIME_write_CMS() always base64 encodes CMS structures, there should be an +option to disable this. =head1 RETURN VALUES diff --git a/doc/crypto/i2d_CMS_bio_stream.pod b/doc/crypto/i2d_CMS_bio_stream.pod index d8b8e58156..496c67a112 100644 --- a/doc/crypto/i2d_CMS_bio_stream.pod +++ b/doc/crypto/i2d_CMS_bio_stream.pod @@ -2,7 +2,7 @@ =head1 NAME -i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format. + i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format. =head1 SYNOPSIS