You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
126 lines
4.7 KiB
126 lines
4.7 KiB
=pod |
|
|
|
=head1 NAME |
|
|
|
CMS_verify - verify a CMS SignedData structure |
|
|
|
=head1 SYNOPSIS |
|
|
|
#include <openssl/cms.h> |
|
|
|
int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); |
|
|
|
STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); |
|
|
|
=head1 DESCRIPTION |
|
|
|
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 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 signing certificate(s) from B<cms>, it must |
|
be called after a successful CMS_verify() operation. |
|
|
|
=head1 VERIFY PROCESS |
|
|
|
Normally the verify process proceeds as follows. |
|
|
|
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 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 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 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) |
|
and the signature's checked. |
|
|
|
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 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. |
|
|
|
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 signing certificates are not |
|
verified. |
|
|
|
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not |
|
verified. |
|
|
|
If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. |
|
|
|
=head1 NOTES |
|
|
|
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 B<certs> parameter. In this case if the signer is not one of the |
|
certificates supplied in B<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 |
|
using the signed data utility functions. |
|
|
|
Care should be taken when modifying the default verify behaviour, for example |
|
setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification |
|
and any modified content will be considered valid. This combination is however |
|
useful if one merely wishes to write the content to B<out> and its validity |
|
is not considered important. |
|
|
|
Chain verification should arguably be performed using the signing time rather |
|
than the current time. However since the signing time is supplied by the |
|
signer it cannot be trusted without additional evidence (such as a trusted |
|
timestamp). |
|
|
|
=head1 RETURN VALUES |
|
|
|
CMS_verify() returns 1 for a successful verification and zero 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 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 |
|
be held in memory if it is not detached. |
|
|
|
=head1 SEE ALSO |
|
|
|
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> |
|
|
|
=head1 HISTORY |
|
|
|
CMS_verify() was added to OpenSSL 0.9.8 |
|
|
|
=cut
|
|
|