tls_load_file(3)

1TLS_LOAD_FILE(3)         BSD Library Functions Manual         TLS_LOAD_FILE(3)
2

NAME

4     tls_load_file, tls_unload_file, tls_config_set_ca_file,
5     tls_config_set_ca_path, tls_config_set_ca_mem, tls_config_set_cert_file,
6     tls_config_set_cert_mem, tls_config_set_crl_file, tls_config_set_crl_mem,
7     tls_config_set_key_file, tls_config_set_key_mem,
8     tls_config_set_ocsp_staple_mem, tls_config_set_ocsp_staple_file,
9     tls_config_set_keypair_file, tls_config_set_keypair_mem,
10     tls_config_set_keypair_ocsp_file, tls_config_set_keypair_ocsp_mem,
11     tls_config_add_keypair_file, tls_config_add_keypair_ocsp_mem,
12     tls_config_add_keypair_ocsp_file, tls_config_add_keypair_mem,
13     tls_config_clear_keys, tls_config_set_verify_depth,
14     tls_config_verify_client, tls_config_verify_client_optional,
15     tls_default_ca_cert_file — TLS certificate and key configuration
16

SYNOPSIS

18     #include <tls.h>
19
20     uint8_t *
21     tls_load_file(const char *file, size_t *len, char *password);
22
23     void
24     tls_unload_file(uint8_t *buf, size_t len);
25
26     int
27     tls_config_set_ca_file(struct tls_config *config, const char *ca_file);
28
29     int
30     tls_config_set_ca_path(struct tls_config *config, const char *ca_path);
31
32     int
33     tls_config_set_ca_mem(struct tls_config *config, const uint8_t *cert,
34         size_t len);
35
36     int
37     tls_config_set_cert_file(struct tls_config *config,
38         const char *cert_file);
39
40     int
41     tls_config_set_cert_mem(struct tls_config *config, const uint8_t *cert,
42         size_t len);
43
44     int
45     tls_config_set_crl_file(struct tls_config *config, const char *crl_file);
46
47     int
48     tls_config_set_crl_mem(struct tls_config *config, const uint8_t *crl,
49         size_t len);
50
51     int
52     tls_config_set_key_file(struct tls_config *config, const char *key_file);
53
54     int
55     tls_config_set_key_mem(struct tls_config *config, const uint8_t *key,
56         size_t len);
57
58     int
59     tls_config_set_ocsp_staple_mem(struct tls_config *config,
60         const uint8_t *staple, size_t len);
61
62     int
63     tls_config_set_ocsp_staple_file(struct tls_config *config,
64         const char *staple_file);
65
66     int
67     tls_config_set_keypair_file(struct tls_config *config,
68         const char *cert_file, const char *key_file);
69
70     int
71     tls_config_set_keypair_mem(struct tls_config *config,
72         const uint8_t *cert, size_t cert_len, const uint8_t *key,
73         size_t key_len);
74
75     int
76     tls_config_set_keypair_ocsp_file(struct tls_config *config,
77         const char *cert_file, const char *key_file,
78         const char *staple_file);
79
80     int
81     tls_config_set_keypair_ocsp_mem(struct tls_config *config,
82         const uint8_t *cert, size_t cert_len, const uint8_t *key,
83         size_t key_len, const uint8_t *staple, size_t staple_len);
84
85     int
86     tls_config_add_keypair_file(struct tls_config *config,
87         const char *cert_file, const char *key_file);
88
89     int
90     tls_config_add_keypair_mem(struct tls_config *config,
91         const uint8_t *cert, size_t cert_len, const uint8_t *key,
92         size_t key_len);
93
94     int
95     tls_config_add_keypair_ocsp_file(struct tls_config *config,
96         const char *cert_file, const char *key_file,
97         const char *staple_file);
98
99     int
100     tls_config_add_keypair_ocsp_mem(struct tls_config *config,
101         const uint8_t *cert, size_t cert_len, const uint8_t *key,
102         size_t key_len, const uint8_t *staple, size_t staple_len);
103
104     void
105     tls_config_clear_keys(struct tls_config *config);
106
107     int
108     tls_config_set_verify_depth(struct tls_config *config, int verify_depth);
109
110     void
111     tls_config_verify_client(struct tls_config *config);
112
113     void
114     tls_config_verify_client_optional(struct tls_config *config);
115
116     const char *
117     tls_default_ca_cert_file(void);
118

DESCRIPTION

120     tls_load_file() loads a certificate or key from disk into memory to be
121     used with tls_config_set_ca_mem(), tls_config_set_cert_mem(),
122     tls_config_set_crl_mem() or tls_config_set_key_mem().  A private key will
123     be decrypted if the optional password argument is specified.
124
125     tls_unload_file() unloads the memory that was returned from an earlier
126     tls_load_file() call, ensuring that the memory contents is discarded.
127
128     tls_default_ca_cert_file() returns the path of the file that contains the
129     default root certificates.
130
131     tls_config_set_ca_file() loads a file containing the root certificates.
132
133     tls_config_set_ca_path() sets the path (directory) which should be
134     searched for root certificates.
135
136     tls_config_set_ca_mem() sets the root certificates directly from memory.
137
138     tls_config_set_cert_file() loads a file containing the public certifi‐
139     cate.
140
141     tls_config_set_cert_mem() sets the public certificate directly from mem‐
142     ory.
143
144     tls_config_set_crl_file() loads a file containing the Certificate Revoca‐
145     tion List (CRL).
146
147     tls_config_set_crl_mem() sets the CRL directly from memory.
148
149     tls_config_set_key_file() loads a file containing the private key.
150
151     tls_config_set_key_mem() directly sets the private key from memory.
152
153     tls_config_set_ocsp_staple_file() loads a file containing a DER-encoded
154     OCSP response to be stapled during the TLS handshake.
155
156     tls_config_set_ocsp_staple_mem() sets a DER-encoded OCSP response to be
157     stapled during the TLS handshake from memory.
158
159     tls_config_set_keypair_file() loads two files from which the public cer‐
160     tificate and private key will be read.
161
162     tls_config_set_keypair_mem() directly sets the public certificate and
163     private key from memory.
164
165     tls_config_set_keypair_ocsp_file() loads three files containing the pub‐
166     lic certificate, private key, and DER-encoded OCSP staple.
167
168     tls_config_set_keypair_ocsp_mem() directly sets the public certificate,
169     private key, and DER-encoded OCSP staple from memory.
170
171     tls_config_add_keypair_file() adds an additional public certificate and
172     private key from the specified files, used as an alternative certificate
173     for Server Name Indication (server only).
174
175     tls_config_add_keypair_mem() adds an additional public certificate and
176     private key from memory, used as an alternative certificate for Server
177     Name Indication (server only).
178
179     tls_config_add_keypair_ocsp_file() adds an additional public certificate,
180     private key, and DER-encoded OCSP staple from the specified files, used
181     as an alternative certificate for Server Name Indication (server only).
182
183     tls_config_add_keypair_ocsp_mem() adds an additional public certificate,
184     private key, and DER-encoded OCSP staple from memory, used as an alterna‐
185     tive certificate for Server Name Indication (server only).
186
187     tls_config_clear_keys() clears any secret keys from memory.
188
189     tls_config_set_verify_depth() limits the number of intermediate certifi‐
190     cates that will be followed during certificate validation.
191
192     tls_config_verify_client() enables client certificate verification, re‐
193     quiring the client to send a certificate (server only).
194
195     tls_config_verify_client_optional() enables client certificate verifica‐
196     tion, without requiring the client to send a certificate (server only).
197

RETURN VALUES

199     tls_load_file() returns NULL on error or an out of memory condition.
200
201     The other functions return 0 on success or -1 on error.
202

HISTORY

208     tls_config_set_ca_file(), tls_config_set_ca_path(),
209     tls_config_set_cert_file(), tls_config_set_cert_mem(),
210     tls_config_set_key_file(), tls_config_set_key_mem(), and
211     tls_config_set_verify_depth() appeared in OpenBSD 5.6 and got their final
212     names in OpenBSD 5.7.
213
214     tls_load_file(), tls_config_set_ca_mem(), and tls_config_clear_keys() ap‐
215     peared in OpenBSD 5.7.
216
217     tls_config_verify_client() and tls_config_verify_client_optional() ap‐
218     peared in OpenBSD 5.9.
219
220     tls_config_set_keypair_file() and tls_config_set_keypair_mem() appeared
221     in OpenBSD 6.0, and tls_config_add_keypair_file() and
222     tls_config_add_keypair_mem() in OpenBSD 6.1.
223
224     tls_config_set_crl_file() and tls_config_set_crl_mem() appeared in
225     OpenBSD 6.2.
226

AUTHORS

228     Joel Sing <jsing@openbsd.org> with contibutions from
229     Ted Unangst <tedu@openbsd.org> and
230     Bob Beck <beck@openbsd.org>.
231
232     tls_load_file() and tls_config_set_ca_mem() were written by
233     Reyk Floeter <reyk@openbsd.org>.
234
235BSD                              June 22, 2021                             BSD

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO

HISTORY

AUTHORS