diff options
Diffstat (limited to 'src/lib')
-rw-r--r-- | src/lib/libcrypto/man/Makefile | 3 | ||||
-rw-r--r-- | src/lib/libcrypto/man/X509_TRUST_set.3 | 286 | ||||
-rw-r--r-- | src/lib/libcrypto/man/X509_check_trust.3 | 45 | ||||
-rw-r--r-- | src/lib/libcrypto/man/X509_new.3 | 5 |
4 files changed, 5 insertions, 334 deletions
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 3bb9348af2..d4633edddf 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile | |||
@@ -1,4 +1,4 @@ | |||
1 | # $OpenBSD: Makefile,v 1.288 2024/07/10 08:51:28 tb Exp $ | 1 | # $OpenBSD: Makefile,v 1.289 2024/08/17 09:16:37 tb Exp $ |
2 | 2 | ||
3 | .include <bsd.own.mk> | 3 | .include <bsd.own.mk> |
4 | 4 | ||
@@ -349,7 +349,6 @@ MAN= \ | |||
349 | X509_STORE_new.3 \ | 349 | X509_STORE_new.3 \ |
350 | X509_STORE_set1_param.3 \ | 350 | X509_STORE_set1_param.3 \ |
351 | X509_STORE_set_verify_cb_func.3 \ | 351 | X509_STORE_set_verify_cb_func.3 \ |
352 | X509_TRUST_set.3 \ | ||
353 | X509_VERIFY_PARAM_new.3 \ | 352 | X509_VERIFY_PARAM_new.3 \ |
354 | X509_VERIFY_PARAM_set_flags.3 \ | 353 | X509_VERIFY_PARAM_set_flags.3 \ |
355 | X509_add1_trust_object.3 \ | 354 | X509_add1_trust_object.3 \ |
diff --git a/src/lib/libcrypto/man/X509_TRUST_set.3 b/src/lib/libcrypto/man/X509_TRUST_set.3 deleted file mode 100644 index f363ead18b..0000000000 --- a/src/lib/libcrypto/man/X509_TRUST_set.3 +++ /dev/null | |||
@@ -1,286 +0,0 @@ | |||
1 | .\" $OpenBSD: X509_TRUST_set.3,v 1.1 2021/07/24 14:33:14 schwarze Exp $ | ||
2 | .\" | ||
3 | .\" Copyright (c) 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: July 24 2021 $ | ||
18 | .Dt X509_TRUST_SET 3 | ||
19 | .Os | ||
20 | .Sh NAME | ||
21 | .Nm X509_TRUST_set , | ||
22 | .Nm X509_TRUST_get_by_id , | ||
23 | .Nm X509_TRUST_add , | ||
24 | .Nm X509_TRUST_get_count , | ||
25 | .Nm X509_TRUST_cleanup , | ||
26 | .Nm X509_TRUST_get0 , | ||
27 | .Nm X509_TRUST_get_trust , | ||
28 | .Nm X509_TRUST_get0_name , | ||
29 | .Nm X509_TRUST_get_flags | ||
30 | .Nd trust objects, indices, and identifiers | ||
31 | .Sh SYNOPSIS | ||
32 | .In openssl/x509.h | ||
33 | .Ft int | ||
34 | .Fo X509_TRUST_set | ||
35 | .Fa "int *id_out" | ||
36 | .Fa "int id_in" | ||
37 | .Fc | ||
38 | .Ft int | ||
39 | .Fn X509_TRUST_get_by_id "int identifier" | ||
40 | .Ft int | ||
41 | .Fo X509_TRUST_add | ||
42 | .Fa "int identifier" | ||
43 | .Fa "int flags" | ||
44 | .Fa "int (*check_trust)(X509_TRUST *, X509 *, int)" | ||
45 | .Fa "const char *name" | ||
46 | .Fa "int arg1" | ||
47 | .Fa "void *arg2" | ||
48 | .Fc | ||
49 | .Ft int | ||
50 | .Fn X509_TRUST_get_count void | ||
51 | .Ft void | ||
52 | .Fn X509_TRUST_cleanup void | ||
53 | .Ft X509_TRUST * | ||
54 | .Fn X509_TRUST_get0 "int index" | ||
55 | .Ft int | ||
56 | .Fn X509_TRUST_get_trust "const X509_TRUST *object" | ||
57 | .Ft char * | ||
58 | .Fn X509_TRUST_get0_name "const X509_TRUST *object" | ||
59 | .Ft int | ||
60 | .Fn X509_TRUST_get_flags "const X509_TRUST *object" | ||
61 | .Sh DESCRIPTION | ||
62 | The purposes that an X.509 certificate is trusted for | ||
63 | can be identified in three equivalent ways: | ||
64 | .Bl -enum | ||
65 | .It | ||
66 | By trust identifiers, which are positive integer constants. | ||
67 | Standard trust identifiers lie in the range from | ||
68 | .Dv X509_TRUST_MIN | ||
69 | to | ||
70 | .Dv X509_TRUST_MAX , | ||
71 | inclusive. | ||
72 | User defined trust identifiers are larger than | ||
73 | .Dv X509_TRUST_MAX . | ||
74 | .It | ||
75 | By trust indices, which are non-negative integer constants but | ||
76 | differ from the trust identifiers expressing the same kind of trust. | ||
77 | Standard trust indices are smaller than | ||
78 | .Dv X509_TRUST_MAX . | ||
79 | User defined trust indices are larger than or equal to | ||
80 | .Dv X509_TRUST_MAX . | ||
81 | .It | ||
82 | By trust objects of the type | ||
83 | .Vt X509_TRUST . | ||
84 | Standard trust objects are available in static storage. | ||
85 | User defined trust objects can be created with | ||
86 | .Fn X509_TRUST_add . | ||
87 | .El | ||
88 | .Pp | ||
89 | Application programmers cannot choose the way to identify kinds of trust | ||
90 | that they like best; depending on the circumstances, all three ways | ||
91 | are needed. | ||
92 | Be warned that the naming of most functions is misleading. | ||
93 | .Pp | ||
94 | Most API functions documented outside the present manual page | ||
95 | use trust identifiers rather than trust indices. | ||
96 | .Pp | ||
97 | ASN.1 object identifiers and NIDs provide a fourth and a fifth way | ||
98 | to identify purposes that a certificate is trusted for. | ||
99 | These are almost, but not exactly, equivalent | ||
100 | to the three ways listed above; see the | ||
101 | .Xr X509_check_trust 3 | ||
102 | manual for details. | ||
103 | .Ss Using trust identifiers | ||
104 | .Fn X509_TRUST_set | ||
105 | validates the trust identifier | ||
106 | .Fa id_in . | ||
107 | If it is valid, it is copied to | ||
108 | .Pf * Fa id_out . | ||
109 | Otherwise, | ||
110 | .Pf * Fa id_out | ||
111 | remains unchanged. | ||
112 | .Pp | ||
113 | .Fn X509_TRUST_get_by_id | ||
114 | converts the trust | ||
115 | .Fa identifier | ||
116 | to the corresponding trust | ||
117 | .Fa index . | ||
118 | To find the corresponding trust object, pass the result to | ||
119 | .Fn X509_TRUST_get0 . | ||
120 | .Pp | ||
121 | .Fn X509_TRUST_add | ||
122 | defines a purpose certificates can be trusted for with the given | ||
123 | .Fa identifier | ||
124 | or modifies its properties if it already exists. | ||
125 | The trust | ||
126 | .Fa identifier , | ||
127 | the | ||
128 | .Fa flags , | ||
129 | the | ||
130 | .Fa check_trust | ||
131 | function, the | ||
132 | .Fa name , | ||
133 | the number | ||
134 | .Fa arg1 , | ||
135 | and the pointer | ||
136 | .Fa arg2 | ||
137 | are copied into the | ||
138 | .Vt X509_TRUST | ||
139 | object. | ||
140 | When modifying an existing trust object, previous | ||
141 | values of fields are overwritten and a previous | ||
142 | .Fa name | ||
143 | string is freed if it was dynamically allocated. | ||
144 | When creating a new trust object, | ||
145 | it is added to the global array of user-defined trust objects. | ||
146 | .Pp | ||
147 | .Dv X509_TRUST_DYNAMIC | ||
148 | and | ||
149 | .Dv X509_TRUST_DYNAMIC_NAME | ||
150 | are always ignored in the | ||
151 | .Fa flags | ||
152 | argument. | ||
153 | .Dv X509_TRUST_DYNAMIC | ||
154 | is automatically set if the object was created by the user. | ||
155 | It is never set for standard objects, | ||
156 | not even if they were modified by the user. | ||
157 | .Dv X509_trust_DYNAMIC_NAME | ||
158 | is automatically set if the object was created or modified by the user. | ||
159 | It is only unset for unmodified standard objects. | ||
160 | The library does not appear to define any other flags, | ||
161 | so the flags argument is probably useless | ||
162 | unless users define their own flags and use them in the | ||
163 | .Fa check_trust | ||
164 | function. | ||
165 | .Pp | ||
166 | The third and final argument of the | ||
167 | .Fa check_trust | ||
168 | function is the | ||
169 | .Fa flags | ||
170 | argument of | ||
171 | .Fn X509_check_trust . | ||
172 | .Pp | ||
173 | The built-in trust checking functions documented in the | ||
174 | .Xr X509_check_trust 3 | ||
175 | manual page use | ||
176 | .Fa arg1 | ||
177 | as the corresponding ASN.1 object NID and ignore | ||
178 | .Fa arg2 | ||
179 | and | ||
180 | .Fa flags , | ||
181 | but a user-supplied | ||
182 | .Fa check_trust | ||
183 | function can use these fields in any arbitrary way. | ||
184 | .Pp | ||
185 | .Fn X509_TRUST_get_count | ||
186 | returns the total number of trust objects currently existing, | ||
187 | including both standard and user-defined objects. | ||
188 | If no user-defined objects exist, the returned value is | ||
189 | .Dv X509_TRUST_MAX . | ||
190 | .Pp | ||
191 | .Fn X509_TRUST_cleanup | ||
192 | deletes all user-defined trust objects | ||
193 | and invalidates their trust identifiers and trust indices. | ||
194 | If any of the standard trust objects were modified by the user, | ||
195 | those changes are | ||
196 | .Em not | ||
197 | reverted. | ||
198 | .Ss Using trust indices | ||
199 | .Fn X509_TRUST_get0 | ||
200 | converts the trust | ||
201 | .Fa index | ||
202 | to a pointer to the corresponding trust object. | ||
203 | To find the corresponding trust identifier, pass the result to | ||
204 | .Fn X509_TRUST_get_trust . | ||
205 | .Ss Using trust objects | ||
206 | .Fn X509_TRUST_get_trust | ||
207 | converts a pointer to a trust | ||
208 | .Fa object | ||
209 | to the corresponding trust identifier. | ||
210 | To find the corresponding trust index, pass the result to | ||
211 | .Fn X509_TRUST_get_by_id . | ||
212 | .Pp | ||
213 | .Fn X509_TRUST_get0_name | ||
214 | and | ||
215 | .Fn X509_TRUST_get_flags | ||
216 | retrieve the name and flags from the | ||
217 | .Fa object , | ||
218 | respectively. | ||
219 | .Sh RETURN VALUES | ||
220 | .Fn X509_TRUST_set | ||
221 | returns 1 if | ||
222 | .Fa id_in | ||
223 | is valid or 0 otherwise. | ||
224 | .Pp | ||
225 | .Fn X509_TRUST_get_by_id | ||
226 | returns the corresponding trust index or -1 if the | ||
227 | .Fa identifier | ||
228 | is invalid. | ||
229 | .Pp | ||
230 | .Fn X509_TRUST_add | ||
231 | returns 1 for success or 0 for failure. | ||
232 | .Pp | ||
233 | .Fn X509_TRUST_get_count | ||
234 | returns the total number of trust objects currently existing. | ||
235 | .Pp | ||
236 | .Fn X509_TRUST_get0 | ||
237 | returns a standard or user-defined trust object or | ||
238 | .Dv NULL | ||
239 | if the | ||
240 | .Fa index | ||
241 | is invalid. | ||
242 | .Pp | ||
243 | .Fn X509_TRUST_get_trust | ||
244 | always returns a valid trust identifier. | ||
245 | .Pp | ||
246 | .Fn X509_TRUST_get0_name | ||
247 | returns a pointer to storage owned by the | ||
248 | .Fa object . | ||
249 | .Pp | ||
250 | .Fn X509_TRUST_get_flags | ||
251 | returns the flags associated with the | ||
252 | .Fa object . | ||
253 | .Sh ERRORS | ||
254 | The following diagnostics can be retrieved with | ||
255 | .Xr ERR_get_error 3 , | ||
256 | .Xr ERR_GET_REASON 3 , | ||
257 | and | ||
258 | .Xr ERR_reason_error_string 3 : | ||
259 | .Bl -tag -width Ds | ||
260 | .It Dv X509_R_INVALID_TRUST Qq "invalid trust" | ||
261 | .Fn X509_TRUST_set | ||
262 | was called with an invalid | ||
263 | .Fa id_in | ||
264 | argument. | ||
265 | .It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" | ||
266 | .Fn X509_TRUST_add | ||
267 | failed to allocate memory. | ||
268 | .El | ||
269 | .Pp | ||
270 | The other functions provide no diagnostics. | ||
271 | .Sh SEE ALSO | ||
272 | .Xr X509_check_trust 3 , | ||
273 | .Xr X509_new 3 , | ||
274 | .Xr X509_PURPOSE_set 3 , | ||
275 | .Xr X509_VERIFY_PARAM_set_trust 3 | ||
276 | .Sh HISTORY | ||
277 | .Fn X509_TRUST_set | ||
278 | first appeared in OpenSSL 0.9.7 and has been available since | ||
279 | .Ox 3.2 . | ||
280 | .Pp | ||
281 | The other functions first appeared in OpenSSL 0.9.5 | ||
282 | and have been available since | ||
283 | .Ox 2.7 . | ||
284 | .Sh CAVEATS | ||
285 | The difference between trust identifiers and trust indices | ||
286 | provides an ideal breeding ground for off-by-one bugs. | ||
diff --git a/src/lib/libcrypto/man/X509_check_trust.3 b/src/lib/libcrypto/man/X509_check_trust.3 index 0f02a1b1ef..3a4e020950 100644 --- a/src/lib/libcrypto/man/X509_check_trust.3 +++ b/src/lib/libcrypto/man/X509_check_trust.3 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: X509_check_trust.3,v 1.8 2023/04/30 14:49:47 tb Exp $ | 1 | .\" $OpenBSD: X509_check_trust.3,v 1.9 2024/08/17 09:16:37 tb Exp $ |
2 | .\" | 2 | .\" |
3 | .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> | 3 | .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> |
4 | .\" | 4 | .\" |
@@ -14,12 +14,11 @@ | |||
14 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | 14 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
15 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | 15 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
16 | .\" | 16 | .\" |
17 | .Dd $Mdocdate: April 30 2023 $ | 17 | .Dd $Mdocdate: August 17 2024 $ |
18 | .Dt X509_CHECK_TRUST 3 | 18 | .Dt X509_CHECK_TRUST 3 |
19 | .Os | 19 | .Os |
20 | .Sh NAME | 20 | .Sh NAME |
21 | .Nm X509_check_trust , | 21 | .Nm X509_check_trust , |
22 | .Nm X509_TRUST_set_default | ||
23 | .Nd check whether a certificate is trusted | 22 | .Nd check whether a certificate is trusted |
24 | .Sh SYNOPSIS | 23 | .Sh SYNOPSIS |
25 | .In openssl/x509.h | 24 | .In openssl/x509.h |
@@ -29,12 +28,6 @@ | |||
29 | .Fa "int trust" | 28 | .Fa "int trust" |
30 | .Fa "int flags" | 29 | .Fa "int flags" |
31 | .Fc | 30 | .Fc |
32 | .Ft int | ||
33 | .Fo "(*X509_TRUST_set_default(int (*handler)(int, X509 *, int)))" | ||
34 | .Fa "int trust" | ||
35 | .Fa "X509 *certificate" | ||
36 | .Fa "int flags" | ||
37 | .Fc | ||
38 | .Sh DESCRIPTION | 31 | .Sh DESCRIPTION |
39 | .Fn X509_check_trust | 32 | .Fn X509_check_trust |
40 | checks whether the | 33 | checks whether the |
@@ -183,27 +176,6 @@ identifiers listed above, or it may have installed additional, | |||
183 | user-supplied checking functions for user-defined | 176 | user-supplied checking functions for user-defined |
184 | .Fa trust | 177 | .Fa trust |
185 | identifiers not listed above. | 178 | identifiers not listed above. |
186 | .Pp | ||
187 | If the function | ||
188 | .Fn X509_TRUST_set_default | ||
189 | was called, the | ||
190 | .Fa handler | ||
191 | function passed to it is used instead of the standard algorithm, | ||
192 | but only in the case where the | ||
193 | .Fa trust | ||
194 | argument of | ||
195 | .Fn X509_check_trust | ||
196 | is invalid. | ||
197 | The compatibility step is not used in this case. | ||
198 | .Pp | ||
199 | If the return value of the first call to | ||
200 | .Fn X509_TRUST_set_default | ||
201 | is saved and passed back to | ||
202 | .Fn X509_TRUST_set_default | ||
203 | later on, the standard behaviour | ||
204 | of using the standard algorithm for invalid | ||
205 | .Fa trust | ||
206 | arguments is restored. | ||
207 | .Sh RETURN VALUES | 179 | .Sh RETURN VALUES |
208 | .Fn X509_check_trust | 180 | .Fn X509_check_trust |
209 | returns the following values: | 181 | returns the following values: |
@@ -222,27 +194,14 @@ The | |||
222 | is neither trusted nor explicitly rejected, | 194 | is neither trusted nor explicitly rejected, |
223 | which implies that it is not trusted. | 195 | which implies that it is not trusted. |
224 | .El | 196 | .El |
225 | .Pp | ||
226 | .Fn X509_TRUST_set_default | ||
227 | returns a pointer to the handler function for invalid | ||
228 | .Fa trust | ||
229 | that was installed before the call, which may either be a pointer | ||
230 | to a function installed by a previous call to | ||
231 | .Fn X509_TRUST_set_default | ||
232 | or a pointer to the built-in function implementing the standard algorithm if | ||
233 | .Fn X509_TRUST_set_default | ||
234 | was never called before. | ||
235 | .Sh SEE ALSO | 197 | .Sh SEE ALSO |
236 | .Xr PEM_read_X509_AUX 3 , | 198 | .Xr PEM_read_X509_AUX 3 , |
237 | .Xr X509_add1_trust_object 3 , | 199 | .Xr X509_add1_trust_object 3 , |
238 | .Xr X509_CERT_AUX_new 3 , | 200 | .Xr X509_CERT_AUX_new 3 , |
239 | .Xr X509_check_purpose 3 , | 201 | .Xr X509_check_purpose 3 , |
240 | .Xr X509_new 3 , | 202 | .Xr X509_new 3 , |
241 | .Xr X509_TRUST_set 3 , | ||
242 | .Xr X509_VERIFY_PARAM_set_trust 3 | 203 | .Xr X509_VERIFY_PARAM_set_trust 3 |
243 | .Sh HISTORY | 204 | .Sh HISTORY |
244 | .Fn X509_check_trust | 205 | .Fn X509_check_trust |
245 | and | ||
246 | .Fn X509_TRUST_set_default | ||
247 | first appeared in OpenSSL 0.9.5 and has been available since | 206 | first appeared in OpenSSL 0.9.5 and has been available since |
248 | .Ox 2.7 . | 207 | .Ox 2.7 . |
diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3 index 3e7fb0a79f..9bc3ee95c8 100644 --- a/src/lib/libcrypto/man/X509_new.3 +++ b/src/lib/libcrypto/man/X509_new.3 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: X509_new.3,v 1.43 2023/09/29 08:57:49 tb Exp $ | 1 | .\" $OpenBSD: X509_new.3,v 1.44 2024/08/17 09:16:37 tb Exp $ |
2 | .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 | 2 | .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 |
3 | .\" | 3 | .\" |
4 | .\" This file is a derived work. | 4 | .\" This file is a derived work. |
@@ -66,7 +66,7 @@ | |||
66 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | 66 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
67 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. | 67 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. |
68 | .\" | 68 | .\" |
69 | .Dd $Mdocdate: September 29 2023 $ | 69 | .Dd $Mdocdate: August 17 2024 $ |
70 | .Dt X509_NEW 3 | 70 | .Dt X509_NEW 3 |
71 | .Os | 71 | .Os |
72 | .Sh NAME | 72 | .Sh NAME |
@@ -241,7 +241,6 @@ if an error occurs. | |||
241 | .Xr X509_STORE_CTX_new 3 , | 241 | .Xr X509_STORE_CTX_new 3 , |
242 | .Xr X509_STORE_get_by_subject 3 , | 242 | .Xr X509_STORE_get_by_subject 3 , |
243 | .Xr X509_STORE_new 3 , | 243 | .Xr X509_STORE_new 3 , |
244 | .Xr X509_TRUST_set 3 , | ||
245 | .Xr X509v3_addr_add_inherit 3 , | 244 | .Xr X509v3_addr_add_inherit 3 , |
246 | .Xr X509v3_addr_get_range 3 , | 245 | .Xr X509v3_addr_get_range 3 , |
247 | .Xr X509v3_addr_inherits 3 , | 246 | .Xr X509v3_addr_inherits 3 , |