]>
Commit | Line | Data |
---|---|---|
e33ffaca DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | CMS_verify, CMS_get0_signers - verify a CMS SignedData structure |
e33ffaca DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/cms.h> | |
10 | ||
e9b77246 BB |
11 | int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, |
12 | BIO *indata, BIO *out, unsigned int flags); | |
e33ffaca DSH |
13 | |
14 | STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); | |
15 | ||
16 | =head1 DESCRIPTION | |
17 | ||
360bb61d | 18 | CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo |
e33ffaca | 19 | structure to verify. B<certs> is a set of certificates in which to search for |
38d3a738 DSH |
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. | |
e33ffaca DSH |
23 | |
24 | B<flags> is an optional set of flags, which can be used to modify the verify | |
25 | operation. | |
26 | ||
38d3a738 | 27 | CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must |
c420fab5 | 28 | be called after a successful CMS_verify() operation. |
e33ffaca DSH |
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 | |
360bb61d | 35 | be SignedData. There must be at least one signature on the data and if |
e33ffaca DSH |
36 | the content is detached B<indata> cannot be B<NULL>. |
37 | ||
38d3a738 DSH |
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. | |
e33ffaca | 42 | |
38d3a738 | 43 | Each signing certificate is chain verified using the B<smimesign> purpose and |
e33ffaca DSH |
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 | |
38d3a738 | 46 | CRLs are used in addition to attempting to look them up in B<store>. If any |
e33ffaca DSH |
47 | chain verify fails an error code is returned. |
48 | ||
49 | Finally the signed content is read (and written to B<out> is 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 | ||
38d3a738 DSH |
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. | |
e33ffaca DSH |
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 | ||
38d3a738 | 68 | If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not |
e33ffaca DSH |
69 | verified. |
70 | ||
1bc74519 | 71 | If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not |
e33ffaca DSH |
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 | |
1bc74519 | 85 | certificates are not appropriate: for example an application may wish to |
e33ffaca | 86 | lookup certificates in a database or perform customised verification. This |
1bc74519 | 87 | can be achieved by setting and verifying the signers certificates manually |
e33ffaca DSH |
88 | using the signed data utility functions. |
89 | ||
90 | Care should be taken when modifying the default verify behaviour, for example | |
1bc74519 | 91 | setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification |
e33ffaca DSH |
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 | |
c420fab5 | 104 | occurred. |
e33ffaca | 105 | |
38d3a738 | 106 | CMS_get0_signers() returns all signers or NULL if an error occurred. |
e33ffaca | 107 | |
9b86974e | 108 | The error can be obtained from L<ERR_get_error(3)> |
e33ffaca DSH |
109 | |
110 | =head1 BUGS | |
111 | ||
38d3a738 | 112 | The trusted certificate store is not searched for the signing certificate, |
e33ffaca DSH |
113 | this is primarily due to the inadequacies of the current B<X509_STORE> |
114 | functionality. | |
115 | ||
38d3a738 DSH |
116 | The lack of single pass processing means that the signed content must all |
117 | be held in memory if it is not detached. | |
e33ffaca DSH |
118 | |
119 | =head1 SEE ALSO | |
120 | ||
9b86974e | 121 | L<ERR_get_error(3)>, L<CMS_sign(3)> |
e33ffaca | 122 | |
e2f92610 RS |
123 | =head1 COPYRIGHT |
124 | ||
125 | Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. | |
126 | ||
4746f25a | 127 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |