1.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.6 2021/11/17 16:08:32 schwarze Exp $
2.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2019 Claudio Jeker <claudio@openbsd.org>
9.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
10.\"
11.\" Permission to use, copy, modify, and distribute this software for any
12.\" purpose with or without fee is hereby granted, provided that the above
13.\" copyright notice and this permission notice appear in all copies.
14.\"
15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22.\"
23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
24.\" Copyright (c) 2009 The OpenSSL Project.  All rights reserved.
25.\"
26.\" Redistribution and use in source and binary forms, with or without
27.\" modification, are permitted provided that the following conditions
28.\" are met:
29.\"
30.\" 1. Redistributions of source code must retain the above copyright
31.\"    notice, this list of conditions and the following disclaimer.
32.\"
33.\" 2. Redistributions in binary form must reproduce the above copyright
34.\"    notice, this list of conditions and the following disclaimer in
35.\"    the documentation and/or other materials provided with the
36.\"    distribution.
37.\"
38.\" 3. All advertising materials mentioning features or use of this
39.\"    software must display the following acknowledgment:
40.\"    "This product includes software developed by the OpenSSL Project
41.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
42.\"
43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
44.\"    endorse or promote products derived from this software without
45.\"    prior written permission. For written permission, please contact
46.\"    openssl-core@openssl.org.
47.\"
48.\" 5. Products derived from this software may not be called "OpenSSL"
49.\"    nor may "OpenSSL" appear in their names without prior written
50.\"    permission of the OpenSSL Project.
51.\"
52.\" 6. Redistributions of any form whatsoever must retain the following
53.\"    acknowledgment:
54.\"    "This product includes software developed by the OpenSSL Project
55.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
56.\"
57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
60.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68.\" OF THE POSSIBILITY OF SUCH DAMAGE.
69.\"
70.Dd $Mdocdate: November 17 2021 $
71.Dt X509_STORE_CTX_SET_FLAGS 3
72.Os
73.Sh NAME
74.Nm X509_STORE_CTX_set_flags ,
75.Nm X509_STORE_CTX_set_time ,
76.Nm X509_STORE_CTX_set_depth ,
77.Nm X509_STORE_CTX_set_trust ,
78.Nm X509_STORE_CTX_set_purpose ,
79.Nm X509_STORE_CTX_purpose_inherit ,
80.Nm X509_STORE_CTX_get0_param ,
81.Nm X509_STORE_CTX_set0_param ,
82.Nm X509_STORE_CTX_set_default
83.Nd X509_STORE_CTX parameter initialisation
84.Sh SYNOPSIS
85.In openssl/x509_vfy.h
86.Ft void
87.Fo X509_STORE_CTX_set_flags
88.Fa "X509_STORE_CTX *ctx"
89.Fa "unsigned long flags"
90.Fc
91.Ft void
92.Fo X509_STORE_CTX_set_time
93.Fa "X509_STORE_CTX *ctx"
94.Fa "unsigned long dummy"
95.Fa "time_t time"
96.Fc
97.Ft void
98.Fo X509_STORE_CTX_set_depth
99.Fa "X509_STORE_CTX *ctx"
100.Fa "int depth"
101.Fc
102.Ft int
103.Fo X509_STORE_CTX_set_trust
104.Fa "X509_STORE_CTX *ctx"
105.Fa "int trust"
106.Fc
107.Ft int
108.Fo X509_STORE_CTX_set_purpose
109.Fa "X509_STORE_CTX *ctx"
110.Fa "int purpose"
111.Fc
112.Ft int
113.Fo X509_STORE_CTX_purpose_inherit
114.Fa "X509_STORE_CTX *ctx"
115.Fa "int def_purpose"
116.Fa "int purpose"
117.Fa "int trust"
118.Fc
119.Ft X509_VERIFY_PARAM *
120.Fo X509_STORE_CTX_get0_param
121.Fa "X509_STORE_CTX *ctx"
122.Fc
123.Ft void
124.Fo X509_STORE_CTX_set0_param
125.Fa "X509_STORE_CTX *ctx"
126.Fa "X509_VERIFY_PARAM *param"
127.Fc
128.Ft int
129.Fo X509_STORE_CTX_set_default
130.Fa "X509_STORE_CTX *ctx"
131.Fa "const char *name"
132.Fc
133.Sh DESCRIPTION
134These functions operate on the
135.Vt X509_VERIFY_PARAM
136object used by
137.Fa ctx .
138Usually,
139.Xr X509_STORE_CTX_init 3
140is called on
141.Fa ctx
142before these functions, and
143.Xr X509_verify_cert 3
144afterwards.
145.Pp
146.Fn X509_STORE_CTX_set_flags
147sets the internal verification parameter flags to
148.Fa flags .
149See
150.Xr X509_VERIFY_PARAM_set_flags 3
151for a description of the verification flags.
152.Pp
153.Fn X509_STORE_CTX_set_time
154sets the verification
155.Fa time
156using
157.Xr X509_VERIFY_PARAM_set_time 3 .
158The
159.Fa dummy
160argument is ignored.
161.Pp
162.Fn X509_STORE_CTX_set_depth
163sets the maximum verification
164.Fa depth
165using
166.Xr X509_VERIFY_PARAM_set_depth 3 .
167That is the maximum number of untrusted CA certificates
168that can appear in a chain.
169.Pp
170.Fn X509_STORE_CTX_set_trust
171sets the
172.Fa trust
173identifier that can also be set using
174.Xr X509_VERIFY_PARAM_set_trust 3 .
175If the
176.Fa trust
177argument is 0 or invalid
178or the trust identifier is already set to a non-zero value in the
179.Vt X509_VERIFY_PARAM
180object, no action occurs.
181Here and in the following,
182.Dv X509_TRUST_DEFAULT
183counts as invalid.
184.Pp
185.Fn X509_STORE_CTX_set_purpose
186sets the
187.Fa purpose
188identifier that can also be set using
189.Xr X509_VERIFY_PARAM_set_purpose 3 .
190If the
191.Fa purpose
192argument is 0 or any failure occurs, nothing is changed.
193.Pp
194In the following, the trust identifier contained in the
195.Vt X509_PURPOSE
196object associated with
197.Fa purpose
198is called the
199.Dq associated trust .
200.Pp
201The function fails if the
202.Fa purpose
203argument or the associated trust is not 0 but invalid; otherwise,
204.Fn X509_STORE_CTX_set_purpose
205also does the equivalent of calling
206.Fn X509_STORE_CTX_set_trust
207with the associated trust.
208.Pp
209If the purpose identifier is already set to a non-zero value in the
210.Vt X509_VERIFY_PARAM
211object, it is not changed, even if the
212.Fa purpose
213argument is valid, too.
214.Pp
215.Fn X509_STORE_CTX_purpose_inherit
216is similar to
217.Fn X509_STORE_CTX_set_purpose ,
218with the following modifications:
219.Bl -bullet
220.It
221If the
222.Fa purpose
223argument is 0,
224.Fa def_purpose
225is used instead.
226.It
227If the associated trust is
228.Dv X509_TRUST_DEFAULT ,
229the trust associated with
230.Fa def_purpose
231is used instead, or if
232.Fa def_purpose
233is 0 or invalid, the function fails.
234.It
235If the
236.Fa trust
237argument is not 0, it is used instead of the associated trust,
238and the equivalent of calling
239.Fn X509_STORE_CTX_set_trust
240is done even if both
241.Fa purpose
242and
243.Fa def_purpose
244are 0.
245Even if the
246.Fa trust
247argument is not 0, if the (then unused) associated trust is
248.Dv X509_TRUST_DEFAULT ,
249.Fa def_purpose
250is still required to be valid.
251.El
252.Pp
253Note that, even if all arguments are valid and the return value is 1,
254it is possible that nothing changed, or that only either one of the
255purpose and trust identifiers were set, or that both were set.
256It can also happen that the purpose identifier gets set according to the
257.Fa purpose
258argument, but the trust identifier gets set according to the
259.Fa def_purpose
260argument in the same call.
261.Pp
262The intended way of using this function is to pass the purpose and
263trust attributes of another structure of an arbitrary type as the
264.Fa purpose
265and
266.Fa trust
267arguments, and to provide
268.Fa def_purpose
269as a fallback in case the settings in the other structure are incomplete.
270.Pp
271.Fn X509_STORE_CTX_get0_param
272retrieves an internal pointer to the verification parameters associated
273with
274.Fa ctx .
275.Pp
276.Fn X509_STORE_CTX_set0_param
277sets the internal verification parameter pointer to
278.Fa param .
279After this call
280.Fa param
281should not be used.
282.Pp
283.Fn X509_STORE_CTX_set_default
284looks up and sets the default verification method to
285.Fa name .
286This uses the function
287.Xr X509_VERIFY_PARAM_lookup 3
288to find an appropriate set of parameters from
289.Fa name
290and copies them using
291.Xr X509_VERIFY_PARAM_inherit 3 .
292.Sh RETURN VALUES
293.Fn X509_STORE_CTX_set_trust
294returns 1 if the
295.Fa trust
296argument is 0 or valid or 0 if it is not 0 but invalid.
297A return value of 1 does
298.Em not
299imply that the trust identifier stored in the
300.Vt X509_VERIFY_PARAM
301object was changed.
302.Pp
303.Fn X509_STORE_CTX_set_purpose
304returns 1 if both the
305.Fa purpose
306argument and the associated trust are 0 or valid.
307It returns 0 if either the
308.Fa purpose
309argument or the associated trust is not 0 but invalid.
310A return value of 1 does not imply that any data was changed.
311.Pp
312.Fn X509_STORE_CTX_purpose_inherit
313returns 0 if:
314.Bl -bullet
315.It
316The
317.Fa purpose
318argument is not 0 and invalid.
319.It
320The
321.Fa purpose
322argument is 0 and the
323.Fa def_purpose
324argument is not 0 and invalid.
325.It
326The associated trust is
327.Dv X509_TRUST_DEFAULT
328and the
329.Fa def_purpose
330argument is 0 or invalid,
331or the trust identifier associated with it is not 0 but invalid.
332.It
333The
334.Fa trust
335argument is not 0 and invalid.
336.It
337The
338.Fa trust
339argument is 0 and the associated trust is neither 0 nor
340.Dv X509_TRUST_DEFAULT
341but invalid.
342.El
343.Pp
344Otherwise,
345.Fn X509_STORE_CTX_purpose_inherit
346returns 1, which does not imply that any data was changed.
347.Pp
348.Fn X509_STORE_CTX_get0_param
349returns a pointer to an
350.Vt X509_VERIFY_PARAM
351structure or
352.Dv NULL
353if an error occurred.
354.Pp
355.Fn X509_STORE_CTX_set_default
356returns 1 for success or 0 if an error occurred.
357.Sh ERRORS
358For
359.Fn X509_STORE_CTX_set_trust ,
360.Fn X509_STORE_CTX_set_purpose ,
361and
362.Fn X509_STORE_CTX_purpose_inherit ,
363the following diagnostics can be retrieved with
364.Xr ERR_get_error 3 ,
365.Xr ERR_GET_REASON 3 ,
366and
367.Xr ERR_reason_error_string 3 :
368.Bl -tag -width Ds
369.It Dv X509_R_UNKNOWN_TRUST_ID Qq "unknown trust id"
370The
371.Fa trust
372argument or the trust identifier associated with
373.Fa purpose
374or
375.Fa def_purpose
376is not 0 but invalid,
377.It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id"
378The
379.Fa purpose
380argument is not 0 and invalid.
381Or it is 0 and the
382.Fa def_purpose
383argument is not 0 and invalid.
384Or the associated trust is
385.Dv X509_TRUST_DEFAULT
386and
387.Fa def_purpose
388is 0 or invalid.
389.El
390.Pp
391The other functions provide no diagnostics.
392.Sh SEE ALSO
393.Xr X509_STORE_CTX_get_error 3 ,
394.Xr X509_STORE_CTX_new 3 ,
395.Xr X509_STORE_CTX_set_verify 3 ,
396.Xr X509_STORE_CTX_set_verify_cb 3 ,
397.Xr X509_STORE_new 3 ,
398.Xr X509_STORE_set1_param 3 ,
399.Xr X509_STORE_set_verify_cb 3 ,
400.Xr X509_verify_cert 3 ,
401.Xr X509_VERIFY_PARAM_new 3 ,
402.Xr X509_VERIFY_PARAM_set_flags 3
403.Sh HISTORY
404.Fn X509_STORE_CTX_set_depth
405first appeared in OpenSSL 0.9.3 and has been available since
406.Ox 2.4 .
407.Pp
408.Fn X509_STORE_CTX_set_trust ,
409.Fn X509_STORE_CTX_set_purpose ,
410and
411.Fn X509_STORE_CTX_purpose_inherit
412first appeared in OpenSSL 0.9.5 and have been available since
413.Ox 2.7 .
414.Pp
415.Fn X509_STORE_CTX_set_flags
416and
417.Fn X509_STORE_CTX_set_time
418first appeared in OpenSSL 0.9.6 and have been available since
419.Ox 2.9 .
420.Pp
421.Fn X509_STORE_CTX_get0_param ,
422.Fn X509_STORE_CTX_set0_param ,
423and
424.Fn X509_STORE_CTX_set_default
425first appeared in OpenSSL 0.9.8 and have been available since
426.Ox 4.5 .
427