1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.1 2021/10/18 14:46:37 schwarze Exp $
.\"
.\" Copyright (c) 2018, 2021 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 18 2021 $
.Dt X509_VERIFY_PARAM_NEW 3
.Os
.Sh NAME
.Nm X509_VERIFY_PARAM_new ,
.Nm X509_VERIFY_PARAM_free ,
.Nm X509_VERIFY_PARAM_add0_table ,
.Nm X509_VERIFY_PARAM_lookup ,
.Nm X509_VERIFY_PARAM_get_count ,
.Nm X509_VERIFY_PARAM_get0 ,
.Nm X509_VERIFY_PARAM_table_cleanup
.Nd X509 verification parameter object
.Sh SYNOPSIS
.In openssl/x509_vfy.h
.Ft X509_VERIFY_PARAM *
.Fo X509_VERIFY_PARAM_new
.Fa void
.Fc
.Ft void
.Fo X509_VERIFY_PARAM_free
.Fa "X509_VERIFY_PARAM *param"
.Fc
.Ft int
.Fo X509_VERIFY_PARAM_add0_table
.Fa "X509_VERIFY_PARAM *param"
.Fc
.Ft const X509_VERIFY_PARAM *
.Fo X509_VERIFY_PARAM_lookup
.Fa "const char *name"
.Fc
.Ft int
.Fo X509_VERIFY_PARAM_get_count
.Fa void
.Fc
.Ft const X509_VERIFY_PARAM *
.Fo X509_VERIFY_PARAM_get0
.Fa "int id"
.Fc
.Ft void
.Fo X509_VERIFY_PARAM_table_cleanup
.Fa void
.Fc
.Sh DESCRIPTION
.Fn X509_VERIFY_PARAM_new
allocates and initializes an empty
.Vt X509_VERIFY_PARAM
object.
.Pp
.Fn X509_VERIFY_PARAM_free
clears all data contained in
.Fa param
and releases all memory used by it.
If
.Fa param
is a
.Dv NULL
pointer, no action occurs.
.Pp
.Fn X509_VERIFY_PARAM_add0_table
adds
.Fa param
to a static list of
.Vt X509_VERIFY_PARAM
objects maintained by the library.
This function is extremely dangerous because contrary to the name
of the function, if the list already contains an object that happens
to have the same name, that old object is not only silently removed
from the list, but also silently freed, which may silently invalidate
various pointers existing elsewhere in the program.
.Pp
.Fn X509_VERIFY_PARAM_lookup
searches this list for an object of the given
.Fa name .
If no match is found, the predefined objects built-in to the library
are also inspected.
.Pp
.Fn X509_VERIFY_PARAM_get_count
returns the sum of the number of objects on this list and the number
of predefined objects built-in to the library.
Note that this is not necessarily the total number of
.Vt X509_VERIFY_PARAM
objects existing in the program because there may be additional such
objects that were never added to the list.
.Pp
.Fn X509_VERIFY_PARAM_get0
accesses predefined and user-defined objects using
.Fa id
as an index, useful for looping over objects without knowing their names.
An argument less than the number of predefined objects selects
one of the predefined objects; a higher argument selects an object
from the list.
.Pp
.Fn X509_VERIFY_PARAM_table_cleanup
deletes all objects from this list.
It is extremely dangerous because it also invalidates all data that
was contained in all objects that were on the list and because it
frees all these objects, which may invalidate various pointers
existing elsewhere in the program.
.Sh RETURN VALUES
.Fn X509_VERIFY_PARAM_new
returns a pointer to the new object, or
.Dv NULL
on allocation failure.
.Pp
.Fn X509_VERIFY_PARAM_add0_table
returns 1 for success or 0 for failure.
.Pp
.Fn X509_VERIFY_PARAM_lookup
and
.Fn X509_VERIFY_PARAM_get0
return a pointer to an existing built-in or user-defined object, or
.Dv NULL
if no object with the given
.Fa name
is found, or if
.Fa id
is at least
.Fn X509_VERIFY_PARAM_get_count .
.Pp
.Fn X509_VERIFY_PARAM_get_count
returns a number of objects.
.Sh SEE ALSO
.Xr SSL_set1_param 3 ,
.Xr X509_STORE_CTX_set0_param 3 ,
.Xr X509_STORE_set1_param 3 ,
.Xr X509_verify_cert 3 ,
.Xr X509_VERIFY_PARAM_set_flags 3
.Sh HISTORY
.Fn X509_VERIFY_PARAM_new ,
.Fn X509_VERIFY_PARAM_free ,
.Fn X509_VERIFY_PARAM_add0_table ,
.Fn X509_VERIFY_PARAM_lookup ,
and
.Fn X509_VERIFY_PARAM_table_cleanup
first appeared in OpenSSL 0.9.8 and have been available since
.Ox 4.5 .
.Pp
.Fn X509_VERIFY_PARAM_get_count
and
.Fn X509_VERIFY_PARAM_get0
first appeared in OpenSSL 1.0.2 and have been available since
.Ox 6.3 .
|
