summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_LOOKUP_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509_LOOKUP_new.3')
-rw-r--r--src/lib/libcrypto/man/X509_LOOKUP_new.3460
1 files changed, 0 insertions, 460 deletions
diff --git a/src/lib/libcrypto/man/X509_LOOKUP_new.3 b/src/lib/libcrypto/man/X509_LOOKUP_new.3
deleted file mode 100644
index 559dbbb594..0000000000
--- a/src/lib/libcrypto/man/X509_LOOKUP_new.3
+++ /dev/null
@@ -1,460 +0,0 @@
1.\" $OpenBSD: X509_LOOKUP_new.3,v 1.12 2024/09/06 07:48:20 tb 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: September 6 2024 $
18.Dt X509_LOOKUP_NEW 3
19.Os
20.Sh NAME
21.Nm X509_LOOKUP_free ,
22.Nm X509_LOOKUP_ctrl ,
23.Nm X509_LOOKUP_add_dir ,
24.Nm X509_LOOKUP_load_file ,
25.Nm X509_LOOKUP_add_mem ,
26.Nm X509_get_default_cert_dir ,
27.Nm X509_get_default_cert_file ,
28.Nm X509_get_default_cert_dir_env ,
29.Nm X509_get_default_cert_file_env
30.\" X509_get_default_private_dir is intentionally undocumented
31.\" because it appears to be unused by any real-world software
32.\" and because it doesn't do much in the first place.
33.Nd certificate lookup object
34.Sh SYNOPSIS
35.In openssl/x509_vfy.h
36.Ft void
37.Fn X509_LOOKUP_free "X509_LOOKUP *lookup"
38.Ft int
39.Fo X509_LOOKUP_ctrl
40.Fa "X509_LOOKUP *lookup"
41.Fa "int command"
42.Fa "const char *source"
43.Fa "long type"
44.Fa "char **ret"
45.Fc
46.Ft int
47.Fo X509_LOOKUP_add_dir
48.Fa "X509_LOOKUP *lookup"
49.Fa "const char *source"
50.Fa "long type"
51.Fc
52.Ft int
53.Fo X509_LOOKUP_load_file
54.Fa "X509_LOOKUP *lookup"
55.Fa "const char *source"
56.Fa "long type"
57.Fc
58.Ft int
59.Fo X509_LOOKUP_add_mem
60.Fa "X509_LOOKUP *lookup"
61.Fa "const struct iovec *source"
62.Fa "long type"
63.Fc
64.In openssl/x509.h
65.Ft const char *
66.Fn X509_get_default_cert_dir void
67.Ft const char *
68.Fn X509_get_default_cert_file void
69.Ft const char *
70.Fn X509_get_default_cert_dir_env void
71.Ft const char *
72.Fn X509_get_default_cert_file_env void
73.Sh DESCRIPTION
74.Fn X509_LOOKUP_free
75is a deprecated function that
76releases the memory used by
77.Fa lookup .
78It is provided for compatibility only.
79If
80.Fa lookup
81is a
82.Dv NULL
83pointer, no action occurs.
84.Pp
85The operation of
86.Fn X509_LOOKUP_ctrl
87depends on the
88.Vt X509_LOOKUP_METHOD
89used by
90.Fa lookup :
91.Bl -tag -width 4n
92.It Xr X509_LOOKUP_hash_dir 3
93The
94.Fa command
95is required to be
96.Dv X509_L_ADD_DIR
97and the
98.Fa source
99argument is interpreted
100as a colon-separated, NUL-terminated list of directory names.
101These directories are added to an internal list of directories to search
102for certificate files of the given
103.Fa type .
104.Pp
105If
106.Fa type
107is
108.Dv X509_FILETYPE_DEFAULT ,
109the
110.Fa source
111argument is ignored and
112.Pa /etc/ssl/certs
113and a type of
114.Dv X509_FILETYPE_PEM
115are used instead.
116.Pp
117.Fn X509_LOOKUP_add_dir
118is a macro that calls
119.Fn X509_LOOKUP_ctrl
120with a
121.Fa command
122of
123.Dv X509_L_ADD_DIR
124and
125.Fa ret
126set to
127.Dv NULL .
128.Pp
129This lookup method is peculiar in so far as calling
130.Fn X509_LOOKUP_ctrl
131on a lookup object using it does not yet add any certificates to the associated
132.Vt X509_STORE
133object.
134.It Xr X509_LOOKUP_file 3
135The
136.Fa command
137is required to be
138.Dv X509_L_FILE_LOAD
139and the
140.Fa source
141argument is interpreted as a NUL-terminated file name.
142If the
143.Fa type
144is
145.Dv X509_FILETYPE_PEM ,
146the file is read with
147.Xr BIO_new_file 3
148and
149.Xr PEM_X509_INFO_read_bio 3
150and the certificates and revocation lists found are added to the
151.Vt X509_STORE
152object associated with
153.Fa lookup
154using
155.Xr X509_STORE_add_cert 3
156and
157.Xr X509_STORE_add_crl 3 .
158If
159.Fa type
160is
161.Dv X509_FILETYPE_DEFAULT ,
162the
163.Fa source
164argument is ignored and
165.Pa /etc/ssl/certs.pem
166and a type of
167.Dv X509_FILETYPE_PEM
168are used instead.
169If
170.Fa type
171is
172.Dv X509_FILETYPE_ASN1 ,
173the file is read with
174.Xr d2i_X509_bio 3
175and the single certificate is added to the
176.Vt X509_STORE
177object associated with
178.Fa lookup
179using
180.Xr X509_STORE_add_cert 3 .
181.Pp
182.Fn X509_LOOKUP_load_file
183is a macro calling
184.Fn X509_LOOKUP_ctrl
185with a
186.Fa command
187of
188.Dv X509_L_FILE_LOAD
189and
190.Fa ret
191set to
192.Dv NULL .
193.It Xr X509_LOOKUP_mem 3
194The
195.Fa command
196and
197.Fa type
198are required to be
199.Dv X509_L_MEM
200and
201.Dv X509_FILETYPE_PEM ,
202respectively.
203The
204.Fa source
205argument is interpreted as a pointer to an
206.Vt iovec
207structure defined in
208.In sys/uio.h .
209The memory area described by that structure is read with
210.Xr BIO_new_mem_buf 3
211and
212.Xr PEM_X509_INFO_read_bio 3
213and the certificates and revocation lists found are added to the
214.Vt X509_STORE
215object associated with
216.Fa lookup
217using
218.Xr X509_STORE_add_cert 3
219and
220.Xr X509_STORE_add_crl 3 .
221.Pp
222.Fn X509_LOOKUP_add_mem
223is a macro calling
224.Fn X509_LOOKUP_ctrl
225with a command of
226.Dv X509_L_MEM
227and
228.Fa ret
229set to
230.Dv NULL .
231.El
232.Pp
233With LibreSSL,
234.Fn X509_LOOKUP_ctrl
235always ignores the
236.Fa ret
237argument.
238.Pp
239If the
240.Fa type
241is
242.Dv X509_LU_X509 ,
243it searches the configured directories for files having that name,
244with a file name extension that is a small, non-negative decimal integer
245starting at
246.Qq ".0" .
247These files are read with
248.Xr X509_load_cert_file 3 .
249In each directory, the search is ended once a file with the expected name
250and extension does not exists.
251.Pp
252If the
253.Fa type
254is
255.Dv X509_LU_CRL ,
256the file name extensions are expected to have a prefix of
257.Qq "r" ,
258i.e. they start with
259.Qq ".r0" ,
260and the files are read with
261.Xr X509_load_crl_file 3 .
262.Pp
263In case of success, the first match is returned in the
264.Pf * Fa object
265provided by the caller, overwriting any previous content.
266.Sh RETURN VALUES
267.Fn X509_LOOKUP_ctrl
268returns 1 for success or 0 for failure.
269With library implementations other than LibreSSL,
270it might also return \-1 for internal errors.
271.Pp
272.Fn X509_get_default_cert_dir
273returns a pointer to the constant string
274.Qq /etc/ssl/certs ,
275.Fn X509_get_default_cert_file
276to
277.Qq /etc/ssl/certs.pem ,
278.Fn X509_get_default_cert_dir_env
279to
280.Qq SSL_CERT_DIR ,
281and
282.Fn X509_get_default_cert_file_env
283to
284.Qq SSL_CERT_FILE .
285.Sh ENVIRONMENT
286For reasons of security and simplicity,
287LibreSSL ignores the environment variables
288.Ev SSL_CERT_DIR
289and
290.Ev SSL_CERT_FILE ,
291but other library implementations may use their contents instead
292of the standard locations for trusted certificates, and a few
293third-party application programs also inspect these variables
294directly and may pass their values to
295.Fn X509_LOOKUP_add_dir
296and
297.Fn X509_LOOKUP_load_file .
298.Sh FILES
299.Bl -tag -width /etc/ssl/certs.pem -compact
300.It Pa /etc/ssl/certs/
301default directory for storing trusted certificates
302.It Pa /etc/ssl/certs.pem
303default file for storing trusted certificates
304.El
305.Sh ERRORS
306The following diagnostics can be retrieved with
307.Xr ERR_get_error 3 ,
308.Xr ERR_GET_REASON 3 ,
309and
310.Xr ERR_reason_error_string 3 :
311.Bl -tag -width Ds
312.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib"
313.Xr d2i_X509_bio 3
314failed in
315.Fn X509_LOOKUP_ctrl .
316.It Dv X509_R_BAD_X509_FILETYPE Qq "bad x509 filetype"
317.Fn X509_LOOKUP_ctrl
318was called with an invalid
319.Fa type .
320.It Dv ERR_R_BUF_LIB Qq "BUF lib"
321Memory allocation failed.
322.It Dv X509_R_INVALID_DIRECTORY Qq "invalid directory"
323The
324.Fa source
325argument of
326.Fn X509_LOOKUP_ctrl
327with
328.Dv X509_L_ADD_DIR
329or
330.Fn X509_LOOKUP_add_dir
331was
332.Dv NULL
333or an empty string.
334.It Dv X509_R_LOADING_CERT_DIR Qq "loading cert dir"
335.Fn X509_LOOKUP_ctrl
336with
337.Dv X509_L_ADD_DIR
338or
339.Fn X509_LOOKUP_add_dir
340was called with
341.Dv X509_FILETYPE_DEFAULT
342and adding the default directories failed.
343This error is added after and in addition to a more specific diagnostic.
344.It Dv X509_R_LOADING_DEFAULTS Qq "loading defaults"
345.Fn X509_LOOKUP_ctrl
346with
347.Dv X509_L_FILE_LOAD
348or
349.Fn X509_LOOKUP_load_file
350was called with
351.Dv X509_FILETYPE_DEFAULT
352and adding the certificates and revocation lists failed.
353This error is added after and in addition to a more specific diagnostic.
354.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
355Memory allocation failed.
356.It Dv ERR_R_PEM_LIB Qq "PEM lib"
357.Xr PEM_X509_INFO_read_bio 3 ,
358.Xr PEM_read_bio_X509_AUX 3 ,
359or
360.Xr PEM_read_bio_X509_CRL 3
361failed in
362.Fn X509_LOOKUP_ctrl .
363.It Dv ERR_R_SYS_LIB Qq "system lib"
364.Xr BIO_new 3 ,
365.Xr BIO_new_file 3 ,
366or
367.Xr BIO_read_filename 3
368failed in
369.Fn X509_LOOKUP_ctrl .
370.It Dv X509_R_WRONG_LOOKUP_TYPE Qq "wrong lookup type"
371.Xr X509_STORE_CTX_get_by_subject 3
372was called with an invalid
373.Fa type .
374.El
375.Pp
376Passing an invalid
377.Fa command
378to
379.Fn X509_LOOKUP_ctrl
380causes failure but provides no diagnostics.
381.Sh SEE ALSO
382.Xr d2i_X509_bio 3 ,
383.Xr PEM_read_bio_X509_AUX 3 ,
384.Xr PEM_X509_INFO_read_bio 3 ,
385.Xr X509_load_cert_file 3 ,
386.Xr X509_LOOKUP_hash_dir 3 ,
387.Xr X509_NAME_hash 3 ,
388.Xr X509_NAME_new 3 ,
389.Xr X509_new 3 ,
390.Xr X509_OBJECT_get_type 3 ,
391.Xr X509_STORE_add_cert 3 ,
392.Xr X509_STORE_get_by_subject 3
393.Sh HISTORY
394.Fn X509_get_default_cert_dir ,
395.Fn X509_get_default_cert_file ,
396.Fn X509_get_default_cert_dir_env ,
397and
398.Fn X509_get_default_cert_file_env
399first appeared in SSLeay 0.4.1 and have been available since
400.Ox 2.4 .
401.Pp
402.Fn X509_LOOKUP_add_mem
403first appeared in
404.Ox 5.7 .
405.Pp
406The other functions first appeared in SSLeay 0.8.0
407and have been available since
408.Ox 2.4 .
409.Sh BUGS
410If the
411.Fa type
412is
413.Dv X509_FILETYPE_DEFAULT
414or
415.Dv X509_FILETYPE_PEM ,
416.Fn X509_LOOKUP_ctrl
417with
418.Dv X509_L_FILE_LOAD
419and
420.Fn X509_LOOKUP_load_file
421silently ignore failure of
422.Xr X509_STORE_add_cert 3
423and
424.Xr X509_STORE_add_crl 3
425and indicate success anyway.
426.Pp
427Handling of a
428.Dv NULL
429.Fa source
430is inconsistent for
431.Fn X509_LOOKUP_ctrl
432with
433.Dv X509_L_FILE_LOAD
434and for
435.Fn X509_LOOKUP_load_file .
436With
437.Dv X509_FILETYPE_PEM ,
438it causes failure, but with
439.Dv X509_FILETYPE_ASN1 ,
440no action occurs and success is indicated.
441.Pp
442When called on a
443.Fa lookup
444object using
445.Xr X509_LOOKUP_mem 3 ,
446.Fn X509_LOOKUP_ctrl
447raises
448.Dv ERR_R_PEM_LIB
449when called with an invalid
450.Fa command
451or
452.Fa type ,
453when
454.Xr BIO_new_mem_buf 3
455fails, when
456.Fa source
457contains zero objects, or when
458.Xr X509_STORE_add_cert 3
459fails on the first object encountered, which is all inconsistent
460with the behaviour of the other lookup methods.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-07 15:42:30 +0000