]>
Commit | Line | Data |
---|---|---|
7e9db7ce DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure |
7e9db7ce DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
c264592d | 9 | #include <openssl/pkcs7.h> |
7e9db7ce | 10 | |
e9b77246 BB |
11 | int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, |
12 | BIO *indata, BIO *out, int flags); | |
c264592d UM |
13 | |
14 | STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); | |
7e9db7ce DSH |
15 | |
16 | =head1 DESCRIPTION | |
17 | ||
18 | PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 | |
19 | structure to verify. B<certs> is a set of certificates in which to search for | |
186bb907 | 20 | the signer's certificate. B<store> is a trusted certificate store (used for |
7e9db7ce DSH |
21 | chain verification). B<indata> is the signed data if the content is not |
22 | present in B<p7> (that is it is detached). The content is written to B<out> | |
23 | if it is not NULL. | |
24 | ||
25 | B<flags> is an optional set of flags, which can be used to modify the verify | |
26 | operation. | |
27 | ||
28 | PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does | |
29 | B<not> check their validity or whether any signatures are valid. The B<certs> | |
30 | and B<flags> parameters have the same meanings as in PKCS7_verify(). | |
31 | ||
32 | =head1 VERIFY PROCESS | |
33 | ||
34 | Normally the verify process proceeds as follows. | |
35 | ||
36 | Initially some sanity checks are performed on B<p7>. The type of B<p7> must | |
37 | be signedData. There must be at least one signature on the data and if | |
6b2ebe43 RS |
38 | the content is detached B<indata> cannot be B<NULL>. If the content is |
39 | not detached and B<indata> is not B<NULL>, then the structure has both | |
40 | embedded and external content. To treat this as an error, use the flag | |
41 | B<PKCS7_NO_DUAL_CONTENT>. | |
42 | The default behavior allows this, for compatibility with older | |
43 | versions of OpenSSL. | |
7e9db7ce DSH |
44 | |
45 | An attempt is made to locate all the signer's certificates, first looking in | |
46 | the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates | |
47 | contained in the B<p7> structure itself. If any signer's certificates cannot be | |
48 | located the operation fails. | |
49 | ||
50 | Each signer's certificate is chain verified using the B<smimesign> purpose and | |
51 | the supplied trusted certificate store. Any internal certificates in the message | |
52 | are used as untrusted CAs. If any chain verify fails an error code is returned. | |
53 | ||
54 | Finally the signed content is read (and written to B<out> is it is not NULL) and | |
55 | the signature's checked. | |
56 | ||
57 | If all signature's verify correctly then the function is successful. | |
58 | ||
59 | Any of the following flags (ored together) can be passed in the B<flags> parameter | |
60 | to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is | |
61 | meaningful to PKCS7_get0_signers(). | |
62 | ||
1bc74519 | 63 | If B<PKCS7_NOINTERN> is set the certificates in the message itself are not |
7e9db7ce DSH |
64 | searched when locating the signer's certificate. This means that all the signers |
65 | certificates must be in the B<certs> parameter. | |
66 | ||
67 | If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted | |
68 | from the content. If the content is not of type B<text/plain> then an error is | |
69 | returned. | |
70 | ||
71 | If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. | |
72 | ||
73 | If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are | |
74 | not used as untrusted CAs. This means that the whole verify chain (apart from | |
75 | the signer's certificate) must be contained in the trusted store. | |
76 | ||
77 | If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. | |
78 | ||
79 | =head1 NOTES | |
80 | ||
81 | One application of B<PKCS7_NOINTERN> is to only accept messages signed by | |
82 | a small number of certificates. The acceptable certificates would be passed | |
83 | in the B<certs> parameter. In this case if the signer is not one of the | |
84 | certificates supplied in B<certs> then the verify will fail because the | |
85 | signer cannot be found. | |
86 | ||
87 | Care should be taken when modifying the default verify behaviour, for example | |
1bc74519 | 88 | setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification |
7e9db7ce DSH |
89 | and any signed message will be considered valid. This combination is however |
90 | useful if one merely wishes to write the content to B<out> and its validity | |
91 | is not considered important. | |
92 | ||
93 | Chain verification should arguably be performed using the signing time rather | |
94 | than the current time. However since the signing time is supplied by the | |
95 | signer it cannot be trusted without additional evidence (such as a trusted | |
96 | timestamp). | |
97 | ||
98 | =head1 RETURN VALUES | |
99 | ||
4f13dabe RS |
100 | PKCS7_verify() returns one for a successful verification and zero |
101 | if an error occurs. | |
7e9db7ce DSH |
102 | |
103 | PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. | |
104 | ||
9b86974e | 105 | The error can be obtained from L<ERR_get_error(3)> |
7e9db7ce DSH |
106 | |
107 | =head1 BUGS | |
108 | ||
109 | The trusted certificate store is not searched for the signers certificate, | |
110 | this is primarily due to the inadequacies of the current B<X509_STORE> | |
111 | functionality. | |
112 | ||
4e1b50e2 DSH |
113 | The lack of single pass processing and need to hold all data in memory as |
114 | mentioned in PKCS7_sign() also applies to PKCS7_verify(). | |
115 | ||
7e9db7ce DSH |
116 | =head1 SEE ALSO |
117 | ||
9b86974e | 118 | L<ERR_get_error(3)>, L<PKCS7_sign(3)> |
7e9db7ce | 119 | |
e2f92610 RS |
120 | =head1 COPYRIGHT |
121 | ||
122 | Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. | |
123 | ||
124 | Licensed under the OpenSSL license (the "License"). You may not use | |
125 | this file except in compliance with the License. You can obtain a copy | |
126 | in the file LICENSE in the source distribution or at | |
127 | L<https://www.openssl.org/source/license.html>. | |
128 | ||
129 | =cut |