Debian Codegraph @

upstream/debian-unstable/man3/SSL_load_client_CA_file.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_LOAD_CLIENT_CA_FILE 3SSL"
58 .TH SSL_LOAD_CLIENT_CA_FILE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_load_client_CA_file_ex, SSL_load_client_CA_file,
65 SSL_add_file_cert_subjects_to_stack,
66 SSL_add_dir_cert_subjects_to_stack,
67 SSL_add_store_cert_subjects_to_stack
68 \&\- load certificate names
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/ssl.h>
73 \&
74 \& STACK_OF(X509_NAME) *SSL_load_client_CA_file_ex(const char *file,
75 \& OSSL_LIB_CTX *libctx,
76 \& const char *propq);
77 \& STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
78 \&
79 \& int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
80 \& const char *file);
81 \& int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
82 \& const char *dir);
83 \& int SSL_add_store_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
84 \& const char *store);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 \&\fBSSL_load_client_CA_file_ex()\fR reads certificates from \fIfile\fR and returns
89 a STACK_OF(X509_NAME) with the subject names found. The library context \fIlibctx\fR
90 and property query \fIpropq\fR are used when fetching algorithms from providers.
91 .PP
92 \&\fBSSL_load_client_CA_file()\fR is similar to \fBSSL_load_client_CA_file_ex()\fR
93 but uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR.
94 .PP
95 \&\fBSSL_add_file_cert_subjects_to_stack()\fR reads certificates from \fIfile\fR,
96 and adds their subject name to the already existing \fIstack\fR.
97 .PP
98 \&\fBSSL_add_dir_cert_subjects_to_stack()\fR reads certificates from every
99 file in the directory \fIdir\fR, and adds their subject name to the
100 already existing \fIstack\fR.
101 .PP
102 \&\fBSSL_add_store_cert_subjects_to_stack()\fR loads certificates from the
103 \&\fIstore\fR URI, and adds their subject name to the already existing
104 \&\fIstack\fR.
105 .SH NOTES
106 .IX Header "NOTES"
107 \&\fBSSL_load_client_CA_file()\fR reads a file of PEM formatted certificates and
108 extracts the X509_NAMES of the certificates found. While the name suggests
109 the specific usage as support function for
110 \&\fBSSL_CTX_set_client_CA_list\fR\|(3),
111 it is not limited to CA certificates.
112 .SH "RETURN VALUES"
113 .IX Header "RETURN VALUES"
114 The following return values can occur for \fBSSL_load_client_CA_file_ex()\fR, and
115 \&\fBSSL_load_client_CA_file()\fR:
116 .IP NULL 4
117 .IX Item "NULL"
118 The operation failed, check out the error stack for the reason.
119 .IP "Pointer to STACK_OF(X509_NAME)" 4
120 .IX Item "Pointer to STACK_OF(X509_NAME)"
121 Pointer to the subject names of the successfully read certificates.
122 .PP
123 The following return values can occur for \fBSSL_add_file_cert_subjects_to_stack()\fR,
124 \&\fBSSL_add_dir_cert_subjects_to_stack()\fR, and \fBSSL_add_store_cert_subjects_to_stack()\fR:
125 .IP "0 (Failure)" 4
126 .IX Item "0 (Failure)"
127 The operation failed.
128 .IP "1 (Success)" 4
129 .IX Item "1 (Success)"
130 The operation succeeded.
131 .SH EXAMPLES
132 .IX Header "EXAMPLES"
133 Load names of CAs from file and use it as a client CA list:
134 .PP
135 .Vb 2
136 \& SSL_CTX *ctx;
137 \& STACK_OF(X509_NAME) *cert_names;
138 \&
139 \& ...
140 \& cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
141 \& if (cert_names != NULL)
142 \& SSL_CTX_set_client_CA_list(ctx, cert_names);
143 \& else
144 \& /* error */
145 \& ...
146 .Ve
147 .SH "SEE ALSO"
148 .IX Header "SEE ALSO"
149 \&\fBssl\fR\|(7),
150 \&\fBossl_store\fR\|(7),
151 \&\fBSSL_CTX_set_client_CA_list\fR\|(3)
152 .SH HISTORY
153 .IX Header "HISTORY"
154 \&\fBSSL_load_client_CA_file_ex()\fR and \fBSSL_add_store_cert_subjects_to_stack()\fR
155 were added in OpenSSL 3.0.
156 .SH COPYRIGHT
157 .IX Header "COPYRIGHT"
158 Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
159 .PP
160 Licensed under the Apache License 2.0 (the "License"). You may not use
161 this file except in compliance with the License. You can obtain a copy
162 in the file LICENSE in the source distribution or at
163 <https://www.openssl.org/source/license.html>.