summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3')
-rw-r--r--src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3306
1 files changed, 0 insertions, 306 deletions
diff --git a/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3 b/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
deleted file mode 100644
index a22d2b1b4b..0000000000
--- a/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
+++ /dev/null
@@ -1,306 +0,0 @@
1.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.5 2023/05/24 09:57:50 tb Exp $
2.\"
3.\" Copyright (c) 2018, 2021 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: May 24 2023 $
18.Dt X509_VERIFY_PARAM_NEW 3
19.Os
20.Sh NAME
21.Nm X509_VERIFY_PARAM_new ,
22.Nm X509_VERIFY_PARAM_inherit ,
23.Nm X509_VERIFY_PARAM_set1 ,
24.Nm X509_VERIFY_PARAM_free ,
25.Nm X509_VERIFY_PARAM_add0_table ,
26.Nm X509_VERIFY_PARAM_lookup ,
27.Nm X509_VERIFY_PARAM_get_count ,
28.Nm X509_VERIFY_PARAM_get0 ,
29.Nm X509_VERIFY_PARAM_table_cleanup
30.\" The following constants defined in the public header <openssl/x509_vfy.h>
31.\" are intentionally undocumented because X509_VERIFY_PARAM is an opaque
32.\" struct and LibreSSL provides neither X509_VERIFY_PARAM_set_inh_flags(3)
33.\" nor X509_VERIFY_PARAM_get_inh_flags(3):
34.\" X509_VP_FLAG_DEFAULT
35.\" X509_VP_FLAG_OVERWRITE
36.\" X509_VP_FLAG_RESET_FLAGS
37.\" X509_VP_FLAG_LOCKED
38.\" X509_VP_FLAG_ONCE
39.Nd X509 verification parameter objects
40.Sh SYNOPSIS
41.In openssl/x509_vfy.h
42.Ft X509_VERIFY_PARAM *
43.Fo X509_VERIFY_PARAM_new
44.Fa void
45.Fc
46.Ft int
47.Fo X509_VERIFY_PARAM_inherit
48.Fa "X509_VERIFY_PARAM *destination"
49.Fa "const X509_VERIFY_PARAM *source"
50.Fc
51.Ft int
52.Fo X509_VERIFY_PARAM_set1
53.Fa "X509_VERIFY_PARAM *destination"
54.Fa "const X509_VERIFY_PARAM *source"
55.Fc
56.Ft void
57.Fo X509_VERIFY_PARAM_free
58.Fa "X509_VERIFY_PARAM *param"
59.Fc
60.Ft int
61.Fo X509_VERIFY_PARAM_add0_table
62.Fa "X509_VERIFY_PARAM *param"
63.Fc
64.Ft const X509_VERIFY_PARAM *
65.Fo X509_VERIFY_PARAM_lookup
66.Fa "const char *name"
67.Fc
68.Ft int
69.Fo X509_VERIFY_PARAM_get_count
70.Fa void
71.Fc
72.Ft const X509_VERIFY_PARAM *
73.Fo X509_VERIFY_PARAM_get0
74.Fa "int id"
75.Fc
76.Ft void
77.Fo X509_VERIFY_PARAM_table_cleanup
78.Fa void
79.Fc
80.Sh DESCRIPTION
81.Fn X509_VERIFY_PARAM_new
82allocates and initializes an empty
83.Vt X509_VERIFY_PARAM
84object.
85.Pp
86.Fn X509_VERIFY_PARAM_inherit
87copies some data from the
88.Fa source
89object to the
90.Fa destination
91object.
92.Pp
93The verification flags set with
94.Xr X509_VERIFY_PARAM_set_flags 3
95in the
96.Fa source
97object are always OR'ed into the verification flags of the
98.Fa destination
99object.
100.Pp
101Fields having their default value in the
102.Fa source
103object are not copied.
104.Pp
105By default, fields in the
106.Fa destination
107object already having a non-default value are not overwritten.
108However, if at least one of the
109.Fa source
110or
111.Fa destination
112objects was created during a call to
113.Xr X509_STORE_CTX_init 3
114that did not have a
115.Fa store
116argument, and if that object was not previously used as the
117.Fa destination
118in an earlier call to
119.Fn X509_VERIFY_PARAM_inherit ,
120this restriction is waived and even non-default fields in the
121.Fa destination
122object get overwritten.
123If fields overwritten in this way contain pointers to allocated memory,
124that memory is freed.
125.Pp
126As far as permitted by the above rules, the following fields are copied:
127.Bl -bullet -width 1n
128.It
129the verification purpose identifier set with
130.Xr X509_VERIFY_PARAM_set_purpose 3
131.It
132the trust setting set with
133.Xr X509_VERIFY_PARAM_set_trust 3
134.It
135the verification time set with
136.Xr X509_VERIFY_PARAM_set_time 3 ;
137in this case, the only condition is that
138.Dv X509_V_FLAG_USE_CHECK_TIME
139is not set in the
140.Fa destination
141object, whereas the time value in the
142.Fa destination
143object is not inspected before overwriting it
144.It
145the acceptable policy set with
146.Xr X509_VERIFY_PARAM_set1_policies 3
147.It
148the maximum verification depth set with
149.Xr X509_VERIFY_PARAM_set_depth 3
150.It
151flags that were set with
152.Xr X509_VERIFY_PARAM_set_hostflags 3
153.It
154the list of expected DNS hostnames built with
155.Xr X509_VERIFY_PARAM_set1_host 3
156and
157.Xr X509_VERIFY_PARAM_add1_host 3
158.It
159the expected RFC 822 email address set with
160.Xr X509_VERIFY_PARAM_set1_email 3
161.It
162the expected IP address set with
163.Xr X509_VERIFY_PARAM_set1_ip 3
164or
165.Xr X509_VERIFY_PARAM_set1_ip_asc 3
166.El
167.Pp
168Some data that may be contained in the
169.Fa source
170object is never copied, for example the subject name of the peer
171certificate that can be retrieved with
172.Xr X509_VERIFY_PARAM_get0_peername 3 .
173.Pp
174If
175.Fa source
176is a
177.Dv NULL
178pointer, the function has no effect but returns successfully.
179.Pp
180.Fn X509_VERIFY_PARAM_set1
181is identical to
182.Fn X509_VERIFY_PARAM_inherit
183except that fields in the
184.Fa destination
185object are overwritten even if they do not match their default values.
186Still, fields having their default value in the
187.Fa source
188object are not copied.
189.Pp
190If
191.Fn X509_VERIFY_PARAM_inherit
192or
193.Fn X509_VERIFY_PARAM_set1
194fail, partial copying may have occurred, so all data in the
195.Fa destination
196object should be regarded as invalid.
197.Pp
198.Fn X509_VERIFY_PARAM_inherit
199is used internally by
200.Xr X509_STORE_CTX_init 3
201and by
202.Xr X509_STORE_CTX_set_default 3 ,
203and
204.Fn X509_VERIFY_PARAM_set1
205is used internally by
206.Xr X509_STORE_set1_param 3 .
207.Pp
208.Fn X509_VERIFY_PARAM_free
209clears all data contained in
210.Fa param
211and releases all memory used by it.
212If
213.Fa param
214is a
215.Dv NULL
216pointer, no action occurs.
217.Pp
218.Fn X509_VERIFY_PARAM_add0_table
219adds
220.Fa param
221to a static list of
222.Vt X509_VERIFY_PARAM
223objects maintained by the library.
224This function is extremely dangerous because contrary to the name
225of the function, if the list already contains an object that happens
226to have the same name, that old object is not only silently removed
227from the list, but also silently freed, which may silently invalidate
228various pointers existing elsewhere in the program.
229.Pp
230.Fn X509_VERIFY_PARAM_lookup
231searches this list for an object of the given
232.Fa name .
233If no match is found, the predefined objects built-in to the library
234are also inspected.
235.Pp
236.Fn X509_VERIFY_PARAM_get_count
237returns the sum of the number of objects on this list and the number
238of predefined objects built-in to the library.
239Note that this is not necessarily the total number of
240.Vt X509_VERIFY_PARAM
241objects existing in the program because there may be additional such
242objects that were never added to the list.
243.Pp
244.Fn X509_VERIFY_PARAM_get0
245accesses predefined and user-defined objects using
246.Fa id
247as an index, useful for looping over objects without knowing their names.
248An argument less than the number of predefined objects selects
249one of the predefined objects; a higher argument selects an object
250from the list.
251.Pp
252.Fn X509_VERIFY_PARAM_table_cleanup
253deletes all objects from this list.
254It is extremely dangerous because it also invalidates all data that
255was contained in all objects that were on the list and because it
256frees all these objects, which may invalidate various pointers
257existing elsewhere in the program.
258.Sh RETURN VALUES
259.Fn X509_VERIFY_PARAM_new
260returns a pointer to the new object, or
261.Dv NULL
262on allocation failure.
263.Pp
264.Fn X509_VERIFY_PARAM_inherit ,
265.Fn X509_VERIFY_PARAM_set1 ,
266and
267.Fn X509_VERIFY_PARAM_add0_table
268return 1 for success or 0 for failure.
269.Pp
270.Fn X509_VERIFY_PARAM_lookup
271and
272.Fn X509_VERIFY_PARAM_get0
273return a pointer to an existing built-in or user-defined object, or
274.Dv NULL
275if no object with the given
276.Fa name
277is found, or if
278.Fa id
279is at least
280.Fn X509_VERIFY_PARAM_get_count .
281.Pp
282.Fn X509_VERIFY_PARAM_get_count
283returns a number of objects.
284.Sh SEE ALSO
285.Xr SSL_set1_param 3 ,
286.Xr X509_STORE_CTX_set0_param 3 ,
287.Xr X509_STORE_set1_param 3 ,
288.Xr X509_verify_cert 3 ,
289.Xr X509_VERIFY_PARAM_set_flags 3
290.Sh HISTORY
291.Fn X509_VERIFY_PARAM_new ,
292.Fn X509_VERIFY_PARAM_inherit ,
293.Fn X509_VERIFY_PARAM_set1 ,
294.Fn X509_VERIFY_PARAM_free ,
295.Fn X509_VERIFY_PARAM_add0_table ,
296.Fn X509_VERIFY_PARAM_lookup ,
297and
298.Fn X509_VERIFY_PARAM_table_cleanup
299first appeared in OpenSSL 0.9.8 and have been available since
300.Ox 4.5 .
301.Pp
302.Fn X509_VERIFY_PARAM_get_count
303and
304.Fn X509_VERIFY_PARAM_get0
305first appeared in OpenSSL 1.0.2 and have been available since
306.Ox 6.3 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-08 04:28:00 +0000