| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | #include <openssl/cms.h>
|
|---|
| 10 |
|
|---|
| 11 | int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store,
|
|---|
| 12 | BIO *indata, BIO *out, unsigned int flags);
|
|---|
| 13 |
|
|---|
| 14 | STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
|
|---|
| 15 |
|
|---|
| 16 | =head1 DESCRIPTION
|
|---|
| 17 |
|
|---|
| 18 | CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
|
|---|
| 19 | structure to verify. B<certs> is a set of certificates in which to search for
|
|---|
| 20 | the signing certificate(s). B<store> is a trusted certificate store used for
|
|---|
| 21 | chain verification. B<indata> is the detached content if the content is not
|
|---|
| 22 | present in B<cms>. The content is written to B<out> if it is not NULL.
|
|---|
| 23 |
|
|---|
| 24 | B<flags> is an optional set of flags, which can be used to modify the verify
|
|---|
| 25 | operation.
|
|---|
| 26 |
|
|---|
| 27 | CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
|
|---|
| 28 | be called after a successful CMS_verify() operation.
|
|---|
| 29 |
|
|---|
| 30 | =head1 VERIFY PROCESS
|
|---|
| 31 |
|
|---|
| 32 | Normally the verify process proceeds as follows.
|
|---|
| 33 |
|
|---|
| 34 | Initially some sanity checks are performed on B<cms>. The type of B<cms> must
|
|---|
| 35 | be SignedData. There must be at least one signature on the data and if
|
|---|
| 36 | the content is detached B<indata> cannot be B<NULL>.
|
|---|
| 37 |
|
|---|
| 38 | An attempt is made to locate all the signing certificate(s), first looking in
|
|---|
| 39 | the B<certs> parameter (if it is not NULL) and then looking in any
|
|---|
| 40 | certificates contained in the B<cms> structure itself. If any signing
|
|---|
| 41 | certificate cannot be located the operation fails.
|
|---|
| 42 |
|
|---|
| 43 | Each signing certificate is chain verified using the B<smimesign> purpose and
|
|---|
| 44 | the supplied trusted certificate store. Any internal certificates in the message
|
|---|
| 45 | are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
|
|---|
| 46 | CRLs are used in addition to attempting to look them up in B<store>. If any
|
|---|
| 47 | chain verify fails an error code is returned.
|
|---|
| 48 |
|
|---|
| 49 | Finally the signed content is read (and written to B<out> if it is not NULL)
|
|---|
| 50 | and the signature's checked.
|
|---|
| 51 |
|
|---|
| 52 | If all signature's verify correctly then the function is successful.
|
|---|
| 53 |
|
|---|
| 54 | Any of the following flags (ored together) can be passed in the B<flags>
|
|---|
| 55 | parameter to change the default verify behaviour.
|
|---|
| 56 |
|
|---|
| 57 | If B<CMS_NOINTERN> is set the certificates in the message itself are not
|
|---|
| 58 | searched when locating the signing certificate(s). This means that all the
|
|---|
| 59 | signing certificates must be in the B<certs> parameter.
|
|---|
| 60 |
|
|---|
| 61 | If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
|
|---|
| 62 | CRLs in the message itself are ignored.
|
|---|
| 63 |
|
|---|
| 64 | If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
|
|---|
| 65 | from the content. If the content is not of type B<text/plain> then an error is
|
|---|
| 66 | returned.
|
|---|
| 67 |
|
|---|
| 68 | If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
|
|---|
| 69 | verified.
|
|---|
| 70 |
|
|---|
| 71 | If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
|
|---|
| 72 | verified.
|
|---|
| 73 |
|
|---|
| 74 | If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
|
|---|
| 75 |
|
|---|
| 76 | =head1 NOTES
|
|---|
| 77 |
|
|---|
| 78 | One application of B<CMS_NOINTERN> is to only accept messages signed by
|
|---|
| 79 | a small number of certificates. The acceptable certificates would be passed
|
|---|
| 80 | in the B<certs> parameter. In this case if the signer is not one of the
|
|---|
| 81 | certificates supplied in B<certs> then the verify will fail because the
|
|---|
| 82 | signer cannot be found.
|
|---|
| 83 |
|
|---|
| 84 | In some cases the standard techniques for looking up and validating
|
|---|
| 85 | certificates are not appropriate: for example an application may wish to
|
|---|
| 86 | lookup certificates in a database or perform customised verification. This
|
|---|
| 87 | can be achieved by setting and verifying the signers certificates manually
|
|---|
| 88 | using the signed data utility functions.
|
|---|
| 89 |
|
|---|
| 90 | Care should be taken when modifying the default verify behaviour, for example
|
|---|
| 91 | setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
|
|---|
| 92 | and any modified content will be considered valid. This combination is however
|
|---|
| 93 | useful if one merely wishes to write the content to B<out> and its validity
|
|---|
| 94 | is not considered important.
|
|---|
| 95 |
|
|---|
| 96 | Chain verification should arguably be performed using the signing time rather
|
|---|
| 97 | than the current time. However since the signing time is supplied by the
|
|---|
| 98 | signer it cannot be trusted without additional evidence (such as a trusted
|
|---|
| 99 | timestamp).
|
|---|
| 100 |
|
|---|
| 101 | =head1 RETURN VALUES
|
|---|
| 102 |
|
|---|
| 103 | CMS_verify() returns 1 for a successful verification and zero if an error
|
|---|
| 104 | occurred.
|
|---|
| 105 |
|
|---|
| 106 | CMS_get0_signers() returns all signers or NULL if an error occurred.
|
|---|
| 107 |
|
|---|
| 108 | The error can be obtained from L<ERR_get_error(3)>
|
|---|
| 109 |
|
|---|
| 110 | =head1 BUGS
|
|---|
| 111 |
|
|---|
| 112 | The trusted certificate store is not searched for the signing certificate,
|
|---|
| 113 | this is primarily due to the inadequacies of the current B<X509_STORE>
|
|---|
| 114 | functionality.
|
|---|
| 115 |
|
|---|
| 116 | The lack of single pass processing means that the signed content must all
|
|---|
| 117 | be held in memory if it is not detached.
|
|---|
| 118 |
|
|---|
| 119 | =head1 SEE ALSO
|
|---|
| 120 |
|
|---|
| 121 | L<ERR_get_error(3)>, L<CMS_sign(3)>
|
|---|
| 122 |
|
|---|
| 123 | =head1 COPYRIGHT
|
|---|
| 124 |
|
|---|
| 125 | Copyright 2008-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 126 |
|
|---|
| 127 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 128 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 129 | in the file LICENSE in the source distribution or at
|
|---|
| 130 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 131 |
|
|---|
| 132 | =cut
|
|---|
