Debian Codegraph @

upstream/debian-unstable/man3/CMS_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 "CMS_VERIFY 3SSL"
58 .TH CMS_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 CMS_verify, CMS_SignedData_verify,
65 CMS_get0_signers \- verify a CMS SignedData structure
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/cms.h>
70 \&
71 \& int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store,
72 \& BIO *detached_data, BIO *out, unsigned int flags);
73 \& BIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data,
74 \& STACK_OF(X509) *scerts, X509_STORE *store,
75 \& STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls,
76 \& unsigned int flags,
77 \& OSSL_LIB_CTX *libctx, const char *propq);
78 \&
79 \& STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 \&\fBCMS_verify()\fR is very similar to \fBPKCS7_verify\fR\|(3). It verifies a
84 \&\fBCMS SignedData\fR structure contained in a structure of type \fBCMS_ContentInfo\fR.
85 \&\fIcms\fR points to the \fBCMS_ContentInfo\fR structure to verify.
86 The optional \fIcerts\fR parameter refers to a set of certificates
87 in which to search for signing certificates.
88 It is also used
89 as a source of untrusted intermediate CA certificates for chain building.
90 \&\fIcms\fR may contain extra untrusted CA certificates that may be used for
91 chain building as well as CRLs that may be used for certificate validation.
92 \&\fIstore\fR may be NULL or point to
93 the trusted certificate store to use for chain verification.
94 \&\fIdetached_data\fR refers to the signed data if the content is detached from \fIcms\fR.
95 Otherwise \fIdetached_data\fR should be NULL and the signed data must be in \fIcms\fR.
96 The content is written to the BIO \fIout\fR unless it is NULL.
97 \&\fIflags\fR is an optional set of flags, which can be used to modify the operation.
98 .PP
99 \&\fBCMS_SignedData_verify()\fR is like \fBCMS_verify()\fR except that
100 it operates on \fBCMS SignedData\fR input in the \fIsd\fR argument,
101 it has some additional parameters described next,
102 and on success it returns the verified content as a memory BIO.
103 The optional \fIextra\fR parameter may be used to provide untrusted CA
104 certificates that may be helpful for chain building in certificate validation.
105 This list of certificates must not contain duplicates.
106 The optional \fIcrls\fR parameter may be used to provide extra CRLs.
107 Also the list of CRLs must not contain duplicates.
108 The optional parameters library context \fIlibctx\fR and property query \fIpropq\fR
109 are used when retrieving algorithms from providers.
110 .PP
111 \&\fBCMS_get0_signers()\fR retrieves the signing certificate(s) from \fIcms\fR; it may only
112 be called after a successful \fBCMS_verify()\fR or \fBCMS_SignedData_verify()\fR operation.
113 .SH "VERIFY PROCESS"
114 .IX Header "VERIFY PROCESS"
115 Normally the verify process proceeds as follows.
116 .PP
117 Initially some sanity checks are performed on \fIcms\fR. The type of \fIcms\fR must
118 be SignedData. There must be at least one signature on the data and if
119 the content is detached \fIdetached_data\fR cannot be NULL.
120 .PP
121 An attempt is made to locate all the signing certificate(s), first looking in
122 the \fIcerts\fR parameter (if it is not NULL) and then looking in any
123 certificates contained in the \fIcms\fR structure unless \fBCMS_NOINTERN\fR is set.
124 If any signing certificate cannot be located the operation fails.
125 .PP
126 Each signing certificate is chain verified using the \fIsmimesign\fR purpose and
127 using the trusted certificate store \fIstore\fR if supplied.
128 Any internal certificates in the message, which may have been added using
129 \&\fBCMS_add1_cert\fR\|(3), are used as untrusted CAs.
130 If CRL checking is enabled in \fIstore\fR and \fBCMS_NOCRL\fR is not set,
131 any internal CRLs, which may have been added using \fBCMS_add1_crl\fR\|(3),
132 are used in addition to attempting to look them up in \fIstore\fR.
133 If \fIstore\fR is not NULL and any chain verify fails an error code is returned.
134 .PP
135 Finally the signed content is read (and written to \fIout\fR unless it is NULL)
136 and the signature is checked.
137 .PP
138 If all signatures verify correctly then the function is successful.
139 .PP
140 Any of the following flags (ored together) can be passed in the \fIflags\fR
141 parameter to change the default verify behaviour.
142 .PP
143 If \fBCMS_NOINTERN\fR is set the certificates in the message itself are not
144 searched when locating the signing certificate(s).
145 This means that all the signing certificates must be in the \fIcerts\fR parameter.
146 .PP
147 If \fBCMS_NOCRL\fR is set and CRL checking is enabled in \fIstore\fR then any
148 CRLs in the message itself and provided via the \fIcrls\fR parameter are ignored.
149 .PP
150 If the \fBCMS_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted
151 from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is
152 returned.
153 .PP
154 If \fBCMS_NO_SIGNER_CERT_VERIFY\fR is set the signing certificates are not
155 chain verified, unless \fBCMS_CADES\fR flag is also set.
156 .PP
157 If \fBCMS_NO_ATTR_VERIFY\fR is set the signed attributes signature is not
158 verified, unless CMS_CADES flag is also set.
159 .PP
160 If \fBCMS_CADES\fR is set, each signer certificate is checked against the
161 ESS signingCertificate or ESS signingCertificateV2 extension
162 that is required in the signed attributes of the signature.
163 .PP
164 If \fBCMS_NO_CONTENT_VERIFY\fR is set then the content digest is not checked.
165 .SH NOTES
166 .IX Header "NOTES"
167 One application of \fBCMS_NOINTERN\fR is to only accept messages signed by
168 a small number of certificates. The acceptable certificates would be passed
169 in the \fIcerts\fR parameter. In this case if the signer certificate is not one
170 of the certificates supplied in \fIcerts\fR then the verify will fail because the
171 signer cannot be found.
172 .PP
173 In some cases the standard techniques for looking up and validating
174 certificates are not appropriate: for example an application may wish to
175 lookup certificates in a database or perform customised verification. This
176 can be achieved by setting and verifying the signer certificates manually
177 using the signed data utility functions.
178 .PP
179 Care should be taken when modifying the default verify behaviour, for example
180 setting \fBCMS_NO_CONTENT_VERIFY\fR will totally disable all content verification
181 and any modified content will be considered valid. This combination is however
182 useful if one merely wishes to write the content to \fIout\fR and its validity
183 is not considered important.
184 .PP
185 Chain verification should arguably be performed using the signing time rather
186 than the current time. However, since the signing time is supplied by the
187 signer it cannot be trusted without additional evidence (such as a trusted
188 timestamp).
189 .SH "RETURN VALUES"
190 .IX Header "RETURN VALUES"
191 \&\fBCMS_verify()\fR returns 1 for a successful verification and 0 if an error occurred.
192 .PP
193 \&\fBCMS_SignedData_verify()\fR returns a memory BIO containing the verified content,
194 or NULL on error.
195 .PP
196 \&\fBCMS_get0_signers()\fR returns all signers or NULL if an error occurred.
197 .PP
198 The error can be obtained from \fBERR_get_error\fR\|(3).
199 .SH BUGS
200 .IX Header "BUGS"
201 The trusted certificate store is not searched for the signing certificate.
202 This is primarily due to the inadequacies of the current \fBX509_STORE\fR
203 functionality.
204 .PP
205 The lack of single pass processing means that the signed content must all
206 be held in memory if it is not detached.
207 .SH "SEE ALSO"
208 .IX Header "SEE ALSO"
209 \&\fBPKCS7_verify\fR\|(3), \fBCMS_add1_cert\fR\|(3), \fBCMS_add1_crl\fR\|(3),
210 \&\fBOSSL_ESS_check_signing_certs\fR\|(3),
211 \&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3)
212 .SH HISTORY
213 .IX Header "HISTORY"
214 \&\fBCMS_SignedData_verify()\fR was added in OpenSSL 3.2.
215 .SH COPYRIGHT
216 .IX Header "COPYRIGHT"
217 Copyright 2008\-2024 The OpenSSL Project Authors. All Rights Reserved.
218 .PP
219 Licensed under the Apache License 2.0 (the "License"). You may not use
220 this file except in compliance with the License. You can obtain a copy
221 in the file LICENSE in the source distribution or at
222 <https://www.openssl.org/source/license.html>.