Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / PKCS7_verify.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH PKCS7_verify 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191PKCS7_verify \- verify a PKCS#7 signedData structure
192.SH "SYNOPSIS"
74dab6c2 193int \fIPKCS7_verify\fR\|(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
984263bc 194.PP
74dab6c2 195int \fIPKCS7_get0_signers\fR\|(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
984263bc 196.SH "DESCRIPTION"
74dab6c2 197\fIPKCS7_verify()\fR verifies a PKCS#7 signedData structure. \fBp7\fR is the PKCS7
984263bc
MD
198structure to verify. \fBcerts\fR is a set of certificates in which to search for
199the signer's certificate. \fBstore\fR is a trusted certficate store (used for
200chain verification). \fBindata\fR is the signed data if the content is not
201present in \fBp7\fR (that is it is detached). The content is written to \fBout\fR
74dab6c2 202if it is not NULL.
984263bc 203.PP
74dab6c2 204\fBflags\fR is an optional set of flags, which can be used to modify the verify
984263bc
MD
205operation.
206.PP
74dab6c2
JR
207\fIPKCS7_get0_signers()\fR retrieves the signer's certificates from \fBp7\fR, it does
208\fBnot\fR check their validity or whether any signatures are valid. The \fBcerts\fR
984263bc
MD
209and \fBflags\fR parameters have the same meanings as in \fIPKCS7_verify()\fR.
210.SH "VERIFY PROCESS"
984263bc
MD
211Normally the verify process proceeds as follows.
212.PP
213Initially some sanity checks are performed on \fBp7\fR. The type of \fBp7\fR must
214be signedData. There must be at least one signature on the data and if
74dab6c2 215the content is detached \fBindata\fR cannot be \fBNULL\fR.
984263bc
MD
216.PP
217An attempt is made to locate all the signer's certificates, first looking in
74dab6c2 218the \fBcerts\fR parameter (if it is not \fBNULL\fR) and then looking in any certificates
984263bc
MD
219contained in the \fBp7\fR structure itself. If any signer's certificates cannot be
220located the operation fails.
221.PP
222Each signer's certificate is chain verified using the \fBsmimesign\fR purpose and
223the supplied trusted certificate store. Any internal certificates in the message
224are used as untrusted CAs. If any chain verify fails an error code is returned.
225.PP
74dab6c2 226Finally the signed content is read (and written to \fBout\fR is it is not NULL) and
984263bc
MD
227the signature's checked.
228.PP
229If all signature's verify correctly then the function is successful.
230.PP
231Any of the following flags (ored together) can be passed in the \fBflags\fR parameter
74dab6c2 232to change the default verify behaviour. Only the flag \fBPKCS7_NOINTERN\fR is
984263bc
MD
233meaningful to \fIPKCS7_get0_signers()\fR.
234.PP
74dab6c2 235If \fBPKCS7_NOINTERN\fR is set the certificates in the message itself are not
984263bc
MD
236searched when locating the signer's certificate. This means that all the signers
237certificates must be in the \fBcerts\fR parameter.
238.PP
74dab6c2 239If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are deleted
984263bc
MD
240from the content. If the content is not of type \fBtext/plain\fR then an error is
241returned.
242.PP
74dab6c2 243If \fBPKCS7_NOVERIFY\fR is set the signer's certificates are not chain verified.
984263bc 244.PP
74dab6c2 245If \fBPKCS7_NOCHAIN\fR is set then the certificates contained in the message are
984263bc
MD
246not used as untrusted CAs. This means that the whole verify chain (apart from
247the signer's certificate) must be contained in the trusted store.
248.PP
74dab6c2 249If \fBPKCS7_NOSIGS\fR is set then the signatures on the data are not checked.
984263bc 250.SH "NOTES"
74dab6c2 251One application of \fBPKCS7_NOINTERN\fR is to only accept messages signed by
984263bc
MD
252a small number of certificates. The acceptable certificates would be passed
253in the \fBcerts\fR parameter. In this case if the signer is not one of the
254certificates supplied in \fBcerts\fR then the verify will fail because the
255signer cannot be found.
256.PP
257Care should be taken when modifying the default verify behaviour, for example
258setting \fBPKCS7_NOVERIFY|PKCS7_NOSIGS\fR will totally disable all verification
259and any signed message will be considered valid. This combination is however
260useful if one merely wishes to write the content to \fBout\fR and its validity
261is not considered important.
262.PP
263Chain verification should arguably be performed using the signing time rather
264than the current time. However since the signing time is supplied by the
265signer it cannot be trusted without additional evidence (such as a trusted
266timestamp).
267.SH "RETURN VALUES"
74dab6c2 268\fIPKCS7_verify()\fR returns 1 for a successful verification and zero or a negative
984263bc
MD
269value if an error occurs.
270.PP
74dab6c2 271\fIPKCS7_get0_signers()\fR returns all signers or \fBNULL\fR if an error occurred.
984263bc
MD
272.PP
273The error can be obtained from ERR_get_error(3)
274.SH "BUGS"
984263bc
MD
275The trusted certificate store is not searched for the signers certificate,
276this is primarily due to the inadequacies of the current \fBX509_STORE\fR
277functionality.
278.PP
279The lack of single pass processing and need to hold all data in memory as
280mentioned in \fIPKCS7_sign()\fR also applies to \fIPKCS7_verify()\fR.
281.SH "SEE ALSO"
984263bc
MD
282ERR_get_error(3), PKCS7_sign(3)
283.SH "HISTORY"
74dab6c2
JR
284\fIPKCS7_verify()\fR was added to OpenSSL 0.9.5
285
286.rn }` ''
287.IX Title "PKCS7_verify 3"
288.IX Name "PKCS7_verify - verify a PKCS#7 signedData structure"
289
290.IX Header "NAME"
291
292.IX Header "SYNOPSIS"
293
294.IX Header "DESCRIPTION"
295
296.IX Header "VERIFY PROCESS"
297
298.IX Header "NOTES"
299
300.IX Header "RETURN VALUES"
301
302.IX Header "BUGS"
303
304.IX Header "SEE ALSO"
305
984263bc 306.IX Header "HISTORY"
74dab6c2 307