diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2008-04-10 23:28:25 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2008-04-10 23:28:25 +0000 |
commit | 38d3a7380817e272df7df2e8c32fc22d6b35e332 (patch) | |
tree | b816d45ce1ec153d47b6867cadbb210462ecf6da /doc | |
parent | 73b3c2d8616801cab74368022e7d8edced922e05 (diff) |
Reformat, fix typos and clarify CMS API docs.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BIO_new_CMS.pod | 24 | ||||
-rw-r--r-- | doc/crypto/CMS_add0_cert.pod | 21 | ||||
-rw-r--r-- | doc/crypto/CMS_add1_recipient_cert.pod | 7 | ||||
-rw-r--r-- | doc/crypto/CMS_compress.pod | 4 | ||||
-rw-r--r-- | doc/crypto/CMS_decrypt.pod | 11 | ||||
-rw-r--r-- | doc/crypto/CMS_encrypt.pod | 14 | ||||
-rw-r--r-- | doc/crypto/CMS_final.pod | 2 | ||||
-rw-r--r-- | doc/crypto/CMS_get0_RecipientInfos.pod | 6 | ||||
-rw-r--r-- | doc/crypto/CMS_get0_SignerInfos.pod | 6 | ||||
-rw-r--r-- | doc/crypto/CMS_get1_ReceiptRequest.pod | 13 | ||||
-rw-r--r-- | doc/crypto/CMS_sign.pod | 14 | ||||
-rw-r--r-- | doc/crypto/CMS_sign_add1_signer.pod | 12 | ||||
-rw-r--r-- | doc/crypto/CMS_sign_receipt.pod | 2 | ||||
-rw-r--r-- | doc/crypto/CMS_uncompress.pod | 6 | ||||
-rw-r--r-- | doc/crypto/CMS_verify.pod | 39 | ||||
-rw-r--r-- | doc/crypto/CMS_verify_receipt.pod | 8 | ||||
-rw-r--r-- | doc/crypto/PEM_write_bio_CMS_stream.pod | 2 | ||||
-rw-r--r-- | doc/crypto/SMIME_read_CMS.pod | 35 | ||||
-rw-r--r-- | doc/crypto/SMIME_write_CMS.pod | 29 | ||||
-rw-r--r-- | 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<cms>. The output -of the filter is written to B<out>. Any data written to the returned BIO -is automatically translated to a BER format CMS structure. +of the filter is written to B<out>. 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<CMS_STREAM> flag must be included in the corresponding B<flags> parameter of the B<cms> creation function. -After use BIOs should be removed from the filter using BIO_pop() until -the output BIO B<out> is reached. +If an application wishes to write additional data to B<out> BIOs should be +removed from the chain using BIO_pop() and freed with BIO_free() until B<out> +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<cert> to B<cms> which +CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>. 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>. +CMS_add0_crl() adds CRL B<crl> to B<cms>. CMS_get1_crls() returns any CRLs in +B<cms>. =head1 NOTES +The CMS_ContentInfo structure B<cms> 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<certificates> and +B<crls> fields of SignedData structure. For enveloped data they are added to +B<OriginatorInfo>. + 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. @@ -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<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 @@ -50,7 +53,9 @@ in practice is if the B<cms> type is invalid. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)|ERR_get_error(3)>, +L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> =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<recip> -CMS_ContentInfo enveloped data structure B<cms> as a KeyTransRecipientInfo -structure. +CMS_add1_recipient_cert() adds recipient B<recip> to 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 +wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped data structure B<cms> 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<comp_nid> is the compression algorithm to use or B<NID_undef> to use the default -algorithms (zlib compression). B<in> is the content to be compressed. +algorithm (zlib compression). B<in> is the content to be compressed. B<flags> is an optional set of flags. =head1 NOTES @@ -22,7 +22,7 @@ B<flags> 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<CMS_TEXT> flag is set MIME headers for type B<text/plain> 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<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 +recipient's 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 @@ -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<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. +To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() +and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and +B<cert> and B<pkey> set to NULL. The following flags can be passed in the B<flags> 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<certs> +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. +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<cipher> 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<ri>. 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 <openssl/cms.h> -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<CMS_verify_receipt(3)|CMS_verify_receipt(3)> =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<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. +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<CMS_USE_KEYID> 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<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 +function CMS_sign_add1_signer(), non default digests can be used 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. +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<signcert> and private -key B<pkey> using message digest B<md> to CMS_ContentInfo signed data +key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData 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. +valid CMS_ContentInfo SignedData structure. If the B<md> parameter is B<NULL> 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<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 +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 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<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 certificate 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. +the signing certificate(s). B<store> is a trusted certificate store used for +chain verification. B<indata> is the detached content if the content is not +present in B<cms>. 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 +CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, 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<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. +An attempt is made to locate all the signing certificate(s), first looking in +the B<certs> parameter (if it is not NULL) and then looking in any +certificates contained in the B<cms> structure itself. If any signing +certificate cannot be located the operation fails. -Each signer's certificate is chain verified using the B<smimesign> purpose and +Each signing 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 +CRLs are used in addition to attempting to look them 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) @@ -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<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_NOINTERN> 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<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. @@ -65,7 +64,7 @@ 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 +If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not verified. If B<CMS_NO_ATTR_VERIFY> 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<NULL> if an error occurred. +CMS_get0_signers() returns all signers or 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, +The trusted certificate store is not searched for the signing 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(). +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<rcms> is the signed receipt to verify. B<ocms> is the original SignedData structure containing the -receipt request B<certs> is a set of certificates in which to search for the -signer's certificate. B<store> is a trusted certificate store (used for chain +receipt request. B<certs> is a set of certificates in which to search for the +signing certificate. B<store> is a trusted certificate store (used for chain verification). B<flags> is an optional set of flags, which can be used to modify the verify @@ -42,6 +42,6 @@ L<CMS_verify(3)|CMS_verify(3)>, =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<in> is a BIO to read the message from. -If cleartext signing is used then the content is saved in -a memory bio which is written to B<*bcont>, otherwise -B<*bcont> is set to B<NULL>. +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<NULL> if an +The parsed CMS_ContentInfo structure is returned or NULL if an error occurred. =head1 NOTES -If B<*bcont> is not B<NULL> then the message is clear text -signed. B<*bcont> can then be passed to CMS_verify() with -the B<CMS_DETACHED> flag set. +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<CMS_DETACHED> flag set. Otherwise the type of the returned structure can be determined using CMS_get0_type(). -To support future functionality if B<bcont> is not B<NULL> -B<*bcont> should be initialized to B<NULL>. For example: +To support future functionality if B<bcont> 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<NULL>. 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 |