Reformat, fix typos and clarify CMS API docs.
[openssl.git] / doc / crypto / CMS_verify.pod
index 0dfcf3d..8f26fda 100644 (file)
@@ -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