| blob | 957e65503e2fb3a23a825fcb9d992246b9cd91e6 |
1 .\" $OpenBSD: tls_load_file.3,v 1.8 2017/08/01 08:41:36 jmc Exp $
2 .\"
3 .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4 .\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org>
5 .\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
6 .\" Copyright (c) 2016, 2017 Joel Sing <jsing@openbsd.org>
7 .\"
8 .\" Permission to use, copy, modify, and distribute this software for any
9 .\" purpose with or without fee is hereby granted, provided that the above
10 .\" copyright notice and this permission notice appear in all copies.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 .\"
20 .Dd $Mdocdate: August 1 2017 $
21 .Dt TLS_LOAD_FILE 3
22 .Os
23 .Sh NAME
24 .Nm tls_load_file ,
25 .Nm tls_unload_file ,
26 .Nm tls_config_set_ca_file ,
27 .Nm tls_config_set_ca_path ,
28 .Nm tls_config_set_ca_mem ,
29 .Nm tls_config_set_cert_file ,
30 .Nm tls_config_set_cert_mem ,
31 .Nm tls_config_set_crl_file ,
32 .Nm tls_config_set_crl_mem ,
33 .Nm tls_config_set_key_file ,
34 .Nm tls_config_set_key_mem ,
35 .Nm tls_config_set_ocsp_staple_mem ,
36 .Nm tls_config_set_ocsp_staple_file ,
37 .Nm tls_config_set_keypair_file ,
38 .Nm tls_config_set_keypair_mem ,
39 .Nm tls_config_set_keypair_ocsp_file ,
40 .Nm tls_config_set_keypair_ocsp_mem ,
41 .Nm tls_config_add_keypair_file ,
42 .Nm tls_config_add_keypair_ocsp_mem ,
43 .Nm tls_config_add_keypair_ocsp_file ,
44 .Nm tls_config_add_keypair_mem ,
45 .Nm tls_config_clear_keys ,
46 .Nm tls_config_set_verify_depth ,
47 .Nm tls_config_verify_client ,
48 .Nm tls_config_verify_client_optional
49 .Nd TLS certificate and key configuration
50 .Sh SYNOPSIS
51 .In tls.h
52 .Ft uint8_t *
53 .Fo tls_load_file
54 .Fa "const char *file"
55 .Fa "size_t *len"
56 .Fa "char *password"
57 .Fc
58 .Ft void
59 .Fo tls_unload_file
60 .Fa "uint8_t *buf"
61 .Fa "size_t len"
62 .Fc
63 .Ft int
64 .Fo tls_config_set_ca_file
65 .Fa "struct tls_config *config"
66 .Fa "const char *ca_file"
67 .Fc
68 .Ft int
69 .Fo tls_config_set_ca_path
70 .Fa "struct tls_config *config"
71 .Fa "const char *ca_path"
72 .Fc
73 .Ft int
74 .Fo tls_config_set_ca_mem
75 .Fa "struct tls_config *config"
76 .Fa "const uint8_t *cert"
77 .Fa "size_t len"
78 .Fc
79 .Ft int
80 .Fo tls_config_set_cert_file
81 .Fa "struct tls_config *config"
82 .Fa "const char *cert_file"
83 .Fc
84 .Ft int
85 .Fo tls_config_set_cert_mem
86 .Fa "struct tls_config *config"
87 .Fa "const uint8_t *cert"
88 .Fa "size_t len"
89 .Fc
90 .Ft int
91 .Fo tls_config_set_crl_file
92 .Fa "struct tls_config *config"
93 .Fa "const char *crl_file"
94 .Fc
95 .Ft int
96 .Fo tls_config_set_crl_mem
97 .Fa "struct tls_config *config"
98 .Fa "const uint8_t *crl"
99 .Fa "size_t len"
100 .Fc
101 .Ft int
102 .Fo tls_config_set_key_file
103 .Fa "struct tls_config *config"
104 .Fa "const char *key_file"
105 .Fc
106 .Ft int
107 .Fo tls_config_set_key_mem
108 .Fa "struct tls_config *config"
109 .Fa "const uint8_t *key"
110 .Fa "size_t len"
111 .Fc
112 .Ft int
113 .Fo tls_config_set_ocsp_staple_mem
114 .Fa "struct tls_config *config"
115 .Fa "const uint8_t *staple"
116 .Fa "size_t len"
117 .Fc
118 .Ft int
119 .Fo tls_config_set_ocsp_staple_file
120 .Fa "struct tls_config *config"
121 .Fa "const uint8_t *staple_file"
122 .Fc
123 .Ft int
124 .Fo tls_config_set_keypair_file
125 .Fa "struct tls_config *config"
126 .Fa "const char *cert_file"
127 .Fa "const char *key_file"
128 .Fc
129 .Ft int
130 .Fo tls_config_set_keypair_mem
131 .Fa "struct tls_config *config"
132 .Fa "const uint8_t *cert"
133 .Fa "size_t cert_len"
134 .Fa "const uint8_t *key"
135 .Fa "size_t key_len"
136 .Fc
137 .Ft int
138 .Fo tls_config_set_keypair_ocsp_file
139 .Fa "struct tls_config *config"
140 .Fa "const char *cert_file"
141 .Fa "const char *key_file"
142 .Fa "const char *staple_file"
143 .Fc
144 .Ft int
145 .Fo tls_config_set_keypair_ocsp_mem
146 .Fa "struct tls_config *config"
147 .Fa "const uint8_t *cert"
148 .Fa "size_t cert_len"
149 .Fa "const uint8_t *key"
150 .Fa "size_t key_len"
151 .Fa "const uint8_t *staple"
152 .Fa "size_t staple_len"
153 .Fc
154 .Ft int
155 .Fo tls_config_add_keypair_file
156 .Fa "struct tls_config *config"
157 .Fa "const char *cert_file"
158 .Fa "const char *key_file"
159 .Fc
160 .Ft int
161 .Fo tls_config_add_keypair_mem
162 .Fa "struct tls_config *config"
163 .Fa "const uint8_t *cert"
164 .Fa "size_t cert_len"
165 .Fa "const uint8_t *key"
166 .Fa "size_t key_len"
167 .Fc
168 .Ft int
169 .Fo tls_config_add_keypair_ocsp_file
170 .Fa "struct tls_config *config"
171 .Fa "const char *cert_file"
172 .Fa "const char *key_file"
173 .Fa "const char *staple_file"
174 .Fc
175 .Ft int
176 .Fo tls_config_add_keypair_ocsp_mem
177 .Fa "struct tls_config *config"
178 .Fa "const uint8_t *cert"
179 .Fa "size_t cert_len"
180 .Fa "const uint8_t *key"
181 .Fa "size_t key_len"
182 .Fa "const uint8_t *staple"
183 .Fa "size_t staple_len"
184 .Fc
185 .Ft void
186 .Fn tls_config_clear_keys "struct tls_config *config"
187 .Ft int
188 .Fo tls_config_set_verify_depth
189 .Fa "struct tls_config *config"
190 .Fa "int verify_depth"
191 .Fc
192 .Ft void
193 .Fn tls_config_verify_client "struct tls_config *config"
194 .Ft void
195 .Fn tls_config_verify_client_optional "struct tls_config *config"
196 .Sh DESCRIPTION
197 .Fn tls_load_file
198 loads a certificate or key from disk into memory to be used with
199 .Fn tls_config_set_ca_mem ,
200 .Fn tls_config_set_cert_mem ,
201 .Fn tls_config_set_crl_mem
202 or
203 .Fn tls_config_set_key_mem .
204 A private key will be decrypted if the optional
205 .Ar password
206 argument is specified.
207 .Pp
208 .Fn tls_unload_file
209 unloads the memory that was returned from an earlier
210 .Fn tls_load_file
211 call, ensuring that the memory contents is discarded.
212 .Pp
213 .Fn tls_config_set_ca_file
214 sets the filename used to load a file
215 containing the root certificates.
216 .Pp
217 .Fn tls_config_set_ca_path
218 sets the path (directory) which should be searched for root
219 certificates.
220 .Pp
221 .Fn tls_config_set_ca_mem
222 sets the root certificates directly from memory.
223 .Pp
224 .Fn tls_config_set_cert_file
225 sets file from which the public certificate will be read.
226 .Pp
227 .Fn tls_config_set_cert_mem
228 sets the public certificate directly from memory.
229 .Pp
230 .Fn tls_config_set_crl_file
231 sets the filename used to load a file containing the
232 Certificate Revocation List (CRL).
233 .Pp
234 .Fn tls_config_set_crl_mem
235 sets the CRL directly from memory.
236 .Pp
237 .Fn tls_config_set_key_file
238 sets the file from which the private key will be read.
239 .Pp
240 .Fn tls_config_set_key_mem
241 directly sets the private key from memory.
242 .Pp
243 .Fn tls_config_set_ocsp_staple_file
244 sets a DER-encoded OCSP response to be stapled during the TLS handshake from
245 the specified file.
246 .Pp
247 .Fn tls_config_set_ocsp_staple_mem
248 sets a DER-encoded OCSP response to be stapled during the TLS handshake from
249 memory.
250 .Pp
251 .Fn tls_config_set_keypair_file
252 sets the files from which the public certificate, and private key will be read.
253 .Pp
254 .Fn tls_config_set_keypair_mem
255 directly sets the public certificate, and private key from memory.
256 .Pp
257 .Fn tls_config_set_keypair_ocsp_file
258 sets the files from which the public certificate, private key, and DER encoded
259 OCSP staple will be read.
260 .Pp
261 .Fn tls_config_set_keypair_ocsp_mem
262 directly sets the public certificate, private key, and DER encoded OCSP staple
263 from memory.
264 .Pp
265 .Fn tls_config_add_keypair_file
266 adds an additional public certificate, and private key from the specified files,
267 used as an alternative certificate for Server Name Indication (server only).
268 .Pp
269 .Fn tls_config_add_keypair_mem
270 adds an additional public certificate, and private key from memory, used as an
271 alternative certificate for Server Name Indication (server only).
272 .Pp
273 .Fn tls_config_add_keypair_ocsp_file
274 adds an additional public certificate, private key, and DER encoded OCSP staple
275 from the specified files, used as an alternative certificate for Server Name
276 Indication (server only).
277 .Pp
278 .Fn tls_config_add_keypair_ocsp_mem
279 adds an additional public certificate, private key, and DER encoded OCSP staple
280 from memory, used as an alternative certificate for Server Name Indication
281 (server only).
282 .Pp
283 .Fn tls_config_clear_keys
284 clears any secret keys from memory.
285 .Pp
286 .Fn tls_config_set_verify_depth
287 limits the number of intermediate certificates that will be followed during
288 certificate validation.
289 .Pp
290 .Fn tls_config_verify_client
291 enables client certificate verification, requiring the client to send
292 a certificate (server only).
293 .Pp
294 .Fn tls_config_verify_client_optional
295 enables client certificate verification, without requiring the client
296 to send a certificate (server only).
297 .Sh RETURN VALUES
298 .Fn tls_load_file
299 returns
300 .Dv NULL
301 on error or an out of memory condition.
302 .Pp
303 The other functions return 0 on success or -1 on error.
304 .Sh SEE ALSO
305 .Xr tls_config_ocsp_require_stapling 3 ,
306 .Xr tls_config_set_protocols 3 ,
307 .Xr tls_config_set_session_id 3 ,
308 .Xr tls_configure 3 ,
309 .Xr tls_init 3
310 .Sh HISTORY
311 .Fn tls_config_set_ca_file ,
312 .Fn tls_config_set_ca_path ,
313 .Fn tls_config_set_cert_file ,
314 .Fn tls_config_set_cert_mem ,
315 .Fn tls_config_set_key_file ,
316 .Fn tls_config_set_key_mem ,
317 and
318 .Fn tls_config_set_verify_depth
319 appeared in
320 .Ox 5.6
321 and got their final names in
322 .Ox 5.7 .
323 .Pp
324 .Fn tls_load_file ,
325 .Fn tls_config_set_ca_mem ,
326 and
327 .Fn tls_config_clear_keys
328 appeared in
329 .Ox 5.7 .
330 .Pp
331 .Fn tls_config_verify_client
332 and
333 .Fn tls_config_verify_client_optional
334 appeared in
335 .Ox 5.9 .
336 .Pp
337 .Fn tls_config_set_keypair_file
338 and
339 .Fn tls_config_set_keypair_mem
340 appeared in
341 .Ox 6.0 ,
342 and
343 .Fn tls_config_add_keypair_file
344 and
345 .Fn tls_config_add_keypair_mem
346 in
347 .Ox 6.1 .
348 .Pp
349 .Fn tls_config_set_crl_file
350 and
351 .Fn tls_config_set_crl_mem
352 appeared in
353 .Ox 6.2 .
354 .Sh AUTHORS
355 .An Joel Sing Aq Mt jsing@openbsd.org
356 with contibutions from
357 .An Ted Unangst Aq Mt tedu@openbsd.org
358 and
359 .An Bob Beck Aq Mt beck@openbsd.org .
360 .Pp
361 .Fn tls_load_file
362 and
363 .Fn tls_config_set_ca_mem
364 were written by
365 .An Reyk Floeter Aq Mt reyk@openbsd.org .