Debian Codegraph @

upstream/debian-unstable/man3/PKCS7_verify.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PKCS7_VERIFY 3SSL"
58 .TH PKCS7_VERIFY 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 PKCS7_verify, PKCS7_get0_signers \- verify a PKCS#7 signedData structure
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/pkcs7.h>
69 \&
70 \& int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store,
71 \& BIO *indata, BIO *out, int flags);
72 \&
73 \& STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 \&\fBPKCS7_verify()\fR is very similar to \fBCMS_verify\fR\|(3).
78 It verifies a PKCS#7 signedData structure given in \fIp7\fR.
79 The optional \fIcerts\fR parameter refers to a set of certificates
80 in which to search for signer's certificates.
81 It is also used
82 as a source of untrusted intermediate CA certificates for chain building.
83 \&\fIp7\fR may contain extra untrusted CA certificates that may be used for
84 chain building as well as CRLs that may be used for certificate validation.
85 \&\fIstore\fR may be NULL or point to
86 the trusted certificate store to use for chain verification.
87 \&\fIindata\fR refers to the signed data if the content is detached from \fIp7\fR.
88 Otherwise \fIindata\fR should be NULL, and then the signed data must be in \fIp7\fR.
89 The content is written to the BIO \fIout\fR unless it is NULL.
90 \&\fIflags\fR is an optional set of flags, which can be used to modify the operation.
91 .PP
92 \&\fBPKCS7_get0_signers()\fR retrieves the signer's certificates from \fIp7\fR, it does
93 \&\fBnot\fR check their validity or whether any signatures are valid. The \fIcerts\fR
94 and \fIflags\fR parameters have the same meanings as in \fBPKCS7_verify()\fR.
95 .SH "VERIFY PROCESS"
96 .IX Header "VERIFY PROCESS"
97 Normally the verify process proceeds as follows.
98 .PP
99 Initially some sanity checks are performed on \fIp7\fR. The type of \fIp7\fR must
100 be SignedData. There must be at least one signature on the data and if
101 the content is detached \fIindata\fR cannot be NULL. If the content is
102 not detached and \fIindata\fR is not NULL then the structure has both
103 embedded and external content. To treat this as an error, use the flag
104 \&\fBPKCS7_NO_DUAL_CONTENT\fR.
105 The default behavior allows this, for compatibility with older
106 versions of OpenSSL.
107 .PP
108 An attempt is made to locate all the signer's certificates, first looking in
109 the \fIcerts\fR parameter (if it is not NULL). Then they are looked up in any
110 certificates contained in the \fIp7\fR structure unless \fBPKCS7_NOINTERN\fR is set.
111 If any signer's certificates cannot be located the operation fails.
112 .PP
113 Each signer's certificate is chain verified using the \fBsmimesign\fR purpose and
114 using the trusted certificate store \fIstore\fR if supplied.
115 Any internal certificates in the message, which may have been added using
116 \&\fBPKCS7_add_certificate\fR\|(3), are used as untrusted CAs unless \fBPKCS7_NOCHAIN\fR
117 is set.
118 If CRL checking is enabled in \fIstore\fR and \fBPKCS7_NOCRL\fR is not set,
119 any internal CRLs, which may have been added using \fBPKCS7_add_crl\fR\|(3),
120 are used in addition to attempting to look them up in \fIstore\fR.
121 If \fIstore\fR is not NULL and any chain verify fails an error code is returned.
122 .PP
123 Finally the signed content is read (and written to \fIout\fR unless it is NULL)
124 and the signature is checked.
125 .PP
126 If all signatures verify correctly then the function is successful.
127 .PP
128 Any of the following flags (ored together) can be passed in the \fIflags\fR
129 parameter to change the default verify behaviour.
130 Only the flag \fBPKCS7_NOINTERN\fR is meaningful to \fBPKCS7_get0_signers()\fR.
131 .PP
132 If \fBPKCS7_NOINTERN\fR is set the certificates in the message itself are not
133 searched when locating the signer's certificates.
134 This means that all the signer's certificates must be in the \fIcerts\fR parameter.
135 .PP
136 If \fBPKCS7_NOCRL\fR is set and CRL checking is enabled in \fIstore\fR then any
137 CRLs in the message itself are ignored.
138 .PP
139 If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted
140 from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is
141 returned.
142 .PP
143 If \fBPKCS7_NOVERIFY\fR is set the signer's certificates are not chain verified.
144 .PP
145 If \fBPKCS7_NOCHAIN\fR is set then the certificates contained in the message are
146 not used as untrusted CAs. This means that the whole verify chain (apart from
147 the signer's certificates) must be contained in the trusted store.
148 .PP
149 If \fBPKCS7_NOSIGS\fR is set then the signatures on the data are not checked.
150 .SH NOTES
151 .IX Header "NOTES"
152 One application of \fBPKCS7_NOINTERN\fR is to only accept messages signed by
153 a small number of certificates. The acceptable certificates would be passed
154 in the \fIcerts\fR parameter. In this case if the signer's certificate is not one
155 of the certificates supplied in \fIcerts\fR then the verify will fail because the
156 signer cannot be found.
157 .PP
158 Care should be taken when modifying the default verify behaviour, for example
159 setting \f(CW\*(C`PKCS7_NOVERIFY|PKCS7_NOSIGS\*(C'\fR will totally disable all verification
160 and any signed message will be considered valid. This combination is however
161 useful if one merely wishes to write the content to \fIout\fR and its validity
162 is not considered important.
163 .PP
164 Chain verification should arguably be performed using the signing time rather
165 than the current time. However, since the signing time is supplied by the
166 signer it cannot be trusted without additional evidence (such as a trusted
167 timestamp).
168 .SH "RETURN VALUES"
169 .IX Header "RETURN VALUES"
170 \&\fBPKCS7_verify()\fR returns 1 for a successful verification and 0 if an error occurs.
171 .PP
172 \&\fBPKCS7_get0_signers()\fR returns all signers or NULL if an error occurred.
173 .PP
174 The error can be obtained from \fBERR_get_error\fR\|(3).
175 .SH BUGS
176 .IX Header "BUGS"
177 The trusted certificate store is not searched for the signer's certificates.
178 This is primarily due to the inadequacies of the current \fBX509_STORE\fR
179 functionality.
180 .PP
181 The lack of single pass processing means that the signed content must all
182 be held in memory if it is not detached.
183 .SH "SEE ALSO"
184 .IX Header "SEE ALSO"
185 \&\fBCMS_verify\fR\|(3), \fBPKCS7_add_certificate\fR\|(3), \fBPKCS7_add_crl\fR\|(3),
186 \&\fBERR_get_error\fR\|(3), \fBPKCS7_sign\fR\|(3)
187 .SH COPYRIGHT
188 .IX Header "COPYRIGHT"
189 Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved.
190 .PP
191 Licensed under the Apache License 2.0 (the "License"). You may not use
192 this file except in compliance with the License. You can obtain a copy
193 in the file LICENSE in the source distribution or at
194 <https://www.openssl.org/source/license.html>.