Reformat, fix typos and clarify CMS API docs.

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
 
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/