Reformat, fix typos and clarify CMS API docs.

openssl · Apr 10, 2008 · 38d3a73 · 38d3a73
1 parent 73b3c2d
commit 38d3a73
Show file tree

Hide file tree

Showing 20 changed files with 128 additions and 129 deletions.
diff --git 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
@@ -18,27 +18,30 @@
 
 =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.
 
 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
@@ -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
@@ -14,15 +14,15 @@ 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
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2,17 +2,15 @@
 
 =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
 
  #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_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
@@ -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
@@ -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
@@ -2,26 +2,26 @@
 
 =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
 
  #include <openssl/cms.h>
 
  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
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-CMS_sign_receipt - create a CMS signed receipt
+ CMS_sign_receipt - create a CMS signed receipt
 
 =head1 SYNOPSIS