=head1 DESCRIPTION
-CMS_verify() verifies a B<CMS SignedData> structure
-contained in a structure of type B<CMS_ContentInfo>.
+CMS_verify() is very similar to L<PKCS7_verify(3)>. It verifies a
+B<CMS SignedData> structure contained in a structure of type B<CMS_ContentInfo>.
I<cms> points to the B<CMS_ContentInfo> structure to verify.
-I<certs> is a set of certificates in which to search for signing certificate(s).
-I<store> is a trusted certificate store used for chain verification.
-I<detached_data> refers to the content if the content is not present in I<cms>.
-The content is written to the BIO I<out> if it is not NULL.
-I<flags> is an optional set of flags, which can be used to modify the verify
-operation.
+The optional I<certs> parameter refers to a set of certificates
+in which to search for signing certificates.
+I<cms> may contain extra untrusted CA certificates that may be used for
+chain building as well as CRLs that may be used for certificate validation.
+I<store> may be NULL or point to
+the trusted certificate store to use for chain verification.
+I<detached_data> refers to the signed data if the content is detached from I<cms>.
+Otherwise I<detached_data> should be NULL and the signed data must be in I<cms>.
+The content is written to the BIO I<out> unless it is NULL.
+I<flags> is an optional set of flags, which can be used to modify the operation.
CMS_SignedData_verify() is like CMS_verify() except that
it operates on B<CMS SignedData> input in the I<sd> argument,
An attempt is made to locate all the signing certificate(s), first looking in
the I<certs> parameter (if it is not NULL) and then looking in any
-certificates contained in the I<cms> structure itself. If any signing
-certificate cannot be located the operation fails.
+certificates contained in the I<cms> structure unless B<CMS_NOINTERN> is set.
+If any signing certificate cannot be located the operation fails.
Each signing certificate is chain verified using the I<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 I<store> any internal
-CRLs are used in addition to attempting to look them up in I<store>. If any
-chain verify fails an error code is returned.
+using the trusted certificate store I<store> if supplied.
+Any internal certificates in the message, which may have been added using
+L<CMS_add1_cert(3)>, are used as untrusted CAs.
+If CRL checking is enabled in I<store> and B<CMS_NOCRL> is not set,
+any internal CRLs, which may have been added using L<CMS_add1_crl(3)>,
+are used in addition to attempting to look them up in I<store>.
+If I<store> is not NULL and any chain verify fails an error code is returned.
-Finally the signed content is read (and written to I<out> if it is not NULL)
-and the signature's checked.
+Finally the signed content is read (and written to I<out> unless it is NULL)
+and the signature is checked.
-If all signature's verify correctly then the function is successful.
+If all signatures verify correctly then the function is successful.
Any of the following flags (ored together) can be passed in the I<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 signing certificate(s). This means that all the
-signing certificates must be in the I<certs> parameter.
+searched when locating the signing certificate(s).
+This means that all the signing certificates must be in the I<certs> parameter.
If B<CMS_NOCRL> is set and CRL checking is enabled in I<store> then any
CRLs in the message itself and provided via the I<crls> parameter are ignored.
returned.
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
-verified, unless CMS_CADES flag is also set.
+chain verified, unless B<CMS_CADES> flag is also set.
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
verified, unless CMS_CADES flag is also set.
One application of B<CMS_NOINTERN> is to only accept messages signed by
a small number of certificates. The acceptable certificates would be passed
-in the I<certs> parameter. In this case if the signer is not one of the
-certificates supplied in I<certs> then the verify will fail because the
+in the I<certs> parameter. In this case if the signer certificate is not one
+of the certificates supplied in I<certs> then the verify will fail because the
signer cannot be found.
In some cases the standard techniques for looking up and validating
certificates are not appropriate: for example an application may wish to
lookup certificates in a database or perform customised verification. This
-can be achieved by setting and verifying the signers certificates manually
+can be achieved by setting and verifying the signer certificates manually
using the signed data utility functions.
Care should be taken when modifying the default verify behaviour, for example
=head1 RETURN VALUES
-CMS_verify() returns 1 for a successful verification and zero if an error
-occurred.
+CMS_verify() returns 1 for a successful verification and 0 if an error occurred.
CMS_SignedData_verify() returns a memory BIO containing the verfied content,
or NULL on error.
=head1 BUGS
-The trusted certificate store is not searched for the signing certificate,
-this is primarily due to the inadequacies of the current B<X509_STORE>
+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 means that the signed content must all
=head1 SEE ALSO
+L<PKCS7_verify(3)>, L<CMS_add1_cert(3)>, L<CMS_add1_crl(3)>,
L<OSSL_ESS_check_signing_certs(3)>,
L<ERR_get_error(3)>, L<CMS_sign(3)>
projects / openssl.git / blobdiff