1 .\" $OpenBSD: tls_load_file.3,v 1.15 2025年07月07日 10:54:00 schwarze 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: July 7 2025 $ 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 .Nm tls_default_ca_cert_file 50 .Nd TLS certificate and key configuration 51 .Sh SYNOPSIS 52 .Lb libtls libssl libcrypto 53 .In tls.h 54 .Ft uint8_t * 55 .Fo tls_load_file 56 .Fa "const char *file" 57 .Fa "size_t *len" 58 .Fa "char *password" 59 .Fc 60 .Ft void 61 .Fo tls_unload_file 62 .Fa "uint8_t *buf" 63 .Fa "size_t len" 64 .Fc 65 .Ft int 66 .Fo tls_config_set_ca_file 67 .Fa "struct tls_config *config" 68 .Fa "const char *ca_file" 69 .Fc 70 .Ft int 71 .Fo tls_config_set_ca_path 72 .Fa "struct tls_config *config" 73 .Fa "const char *ca_path" 74 .Fc 75 .Ft int 76 .Fo tls_config_set_ca_mem 77 .Fa "struct tls_config *config" 78 .Fa "const uint8_t *cert" 79 .Fa "size_t len" 80 .Fc 81 .Ft int 82 .Fo tls_config_set_cert_file 83 .Fa "struct tls_config *config" 84 .Fa "const char *cert_file" 85 .Fc 86 .Ft int 87 .Fo tls_config_set_cert_mem 88 .Fa "struct tls_config *config" 89 .Fa "const uint8_t *cert" 90 .Fa "size_t len" 91 .Fc 92 .Ft int 93 .Fo tls_config_set_crl_file 94 .Fa "struct tls_config *config" 95 .Fa "const char *crl_file" 96 .Fc 97 .Ft int 98 .Fo tls_config_set_crl_mem 99 .Fa "struct tls_config *config" 100 .Fa "const uint8_t *crl" 101 .Fa "size_t len" 102 .Fc 103 .Ft int 104 .Fo tls_config_set_key_file 105 .Fa "struct tls_config *config" 106 .Fa "const char *key_file" 107 .Fc 108 .Ft int 109 .Fo tls_config_set_key_mem 110 .Fa "struct tls_config *config" 111 .Fa "const uint8_t *key" 112 .Fa "size_t len" 113 .Fc 114 .Ft int 115 .Fo tls_config_set_ocsp_staple_mem 116 .Fa "struct tls_config *config" 117 .Fa "const uint8_t *staple" 118 .Fa "size_t len" 119 .Fc 120 .Ft int 121 .Fo tls_config_set_ocsp_staple_file 122 .Fa "struct tls_config *config" 123 .Fa "const char *staple_file" 124 .Fc 125 .Ft int 126 .Fo tls_config_set_keypair_file 127 .Fa "struct tls_config *config" 128 .Fa "const char *cert_file" 129 .Fa "const char *key_file" 130 .Fc 131 .Ft int 132 .Fo tls_config_set_keypair_mem 133 .Fa "struct tls_config *config" 134 .Fa "const uint8_t *cert" 135 .Fa "size_t cert_len" 136 .Fa "const uint8_t *key" 137 .Fa "size_t key_len" 138 .Fc 139 .Ft int 140 .Fo tls_config_set_keypair_ocsp_file 141 .Fa "struct tls_config *config" 142 .Fa "const char *cert_file" 143 .Fa "const char *key_file" 144 .Fa "const char *staple_file" 145 .Fc 146 .Ft int 147 .Fo tls_config_set_keypair_ocsp_mem 148 .Fa "struct tls_config *config" 149 .Fa "const uint8_t *cert" 150 .Fa "size_t cert_len" 151 .Fa "const uint8_t *key" 152 .Fa "size_t key_len" 153 .Fa "const uint8_t *staple" 154 .Fa "size_t staple_len" 155 .Fc 156 .Ft int 157 .Fo tls_config_add_keypair_file 158 .Fa "struct tls_config *config" 159 .Fa "const char *cert_file" 160 .Fa "const char *key_file" 161 .Fc 162 .Ft int 163 .Fo tls_config_add_keypair_mem 164 .Fa "struct tls_config *config" 165 .Fa "const uint8_t *cert" 166 .Fa "size_t cert_len" 167 .Fa "const uint8_t *key" 168 .Fa "size_t key_len" 169 .Fc 170 .Ft int 171 .Fo tls_config_add_keypair_ocsp_file 172 .Fa "struct tls_config *config" 173 .Fa "const char *cert_file" 174 .Fa "const char *key_file" 175 .Fa "const char *staple_file" 176 .Fc 177 .Ft int 178 .Fo tls_config_add_keypair_ocsp_mem 179 .Fa "struct tls_config *config" 180 .Fa "const uint8_t *cert" 181 .Fa "size_t cert_len" 182 .Fa "const uint8_t *key" 183 .Fa "size_t key_len" 184 .Fa "const uint8_t *staple" 185 .Fa "size_t staple_len" 186 .Fc 187 .Ft void 188 .Fn tls_config_clear_keys "struct tls_config *config" 189 .Ft int 190 .Fo tls_config_set_verify_depth 191 .Fa "struct tls_config *config" 192 .Fa "int verify_depth" 193 .Fc 194 .Ft void 195 .Fn tls_config_verify_client "struct tls_config *config" 196 .Ft void 197 .Fn tls_config_verify_client_optional "struct tls_config *config" 198 .Ft const char * 199 .Fn tls_default_ca_cert_file "void" 200 .Sh DESCRIPTION 201 .Fn tls_load_file 202loads a certificate or key from disk into memory to be used with 203 .Fn tls_config_set_ca_mem , 204 .Fn tls_config_set_cert_mem , 205 .Fn tls_config_set_crl_mem 206or 207 .Fn tls_config_set_key_mem . 208A private key will be decrypted if the optional 209 .Ar password 210argument is specified. 211 .Pp 212 .Fn tls_unload_file 213unloads the memory that was returned from an earlier 214 .Fn tls_load_file 215call, ensuring that the memory contents is discarded. 216 .Pp 217 .Fn tls_default_ca_cert_file 218returns the path of the file that contains the default root certificates. 219 .Pp 220 .Fn tls_config_set_ca_file 221loads a file containing the root certificates. 222 .Pp 223 .Fn tls_config_set_ca_path 224sets the path (directory) which should be searched for root 225certificates. 226 .Pp 227 .Fn tls_config_set_ca_mem 228sets the root certificates directly from memory. 229 .Pp 230 .Fn tls_config_set_cert_file 231loads a file containing the public certificate. 232 .Pp 233 .Fn tls_config_set_cert_mem 234sets the public certificate directly from memory. 235 .Pp 236 .Fn tls_config_set_crl_file 237loads a file containing the Certificate Revocation List (CRL). 238 .Pp 239 .Fn tls_config_set_crl_mem 240sets the CRL directly from memory. 241 .Pp 242 .Fn tls_config_set_key_file 243loads a file containing the private key. 244 .Pp 245 .Fn tls_config_set_key_mem 246directly sets the private key from memory. 247 .Pp 248 .Fn tls_config_set_ocsp_staple_file 249loads a file containing a DER-encoded OCSP response to be stapled 250during the TLS handshake. 251 .Pp 252 .Fn tls_config_set_ocsp_staple_mem 253sets a DER-encoded OCSP response to be stapled during the TLS handshake from 254memory. 255 .Pp 256 .Fn tls_config_set_keypair_file 257loads two files from which the public certificate and private key will be read. 258 .Pp 259 .Fn tls_config_set_keypair_mem 260directly sets the public certificate and private key from memory. 261 .Pp 262 .Fn tls_config_set_keypair_ocsp_file 263loads three files containing the public certificate, private key, 264and DER-encoded OCSP staple. 265 .Pp 266 .Fn tls_config_set_keypair_ocsp_mem 267directly sets the public certificate, private key, and DER-encoded OCSP staple 268from memory. 269 .Pp 270 .Fn tls_config_add_keypair_file 271adds an additional public certificate and private key from the specified files, 272used as an alternative certificate for Server Name Indication (server only). 273 .Pp 274 .Fn tls_config_add_keypair_mem 275adds an additional public certificate and private key from memory, used as an 276alternative certificate for Server Name Indication (server only). 277 .Pp 278 .Fn tls_config_add_keypair_ocsp_file 279adds an additional public certificate, private key, and DER-encoded OCSP staple 280from the specified files, used as an alternative certificate for Server Name 281Indication (server only). 282 .Pp 283 .Fn tls_config_add_keypair_ocsp_mem 284adds an additional public certificate, private key, and DER-encoded OCSP staple 285from memory, used as an alternative certificate for Server Name Indication 286(server only). 287 .Pp 288 .Fn tls_config_clear_keys 289clears any secret keys from memory. 290 .Pp 291 .Fn tls_config_set_verify_depth 292limits the number of intermediate certificates that will be followed during 293certificate validation. 294 .Pp 295 .Fn tls_config_verify_client 296enables client certificate verification, requiring the client to send 297a certificate (server only). 298 .Pp 299 .Fn tls_config_verify_client_optional 300enables client certificate verification, without requiring the client 301to send a certificate (server only). 302 .Sh RETURN VALUES 303 .Fn tls_load_file 304returns 305 .Dv NULL 306on error or an out of memory condition. 307 .Pp 308The other functions return 0 on success or -1 on error. 309 .Sh SEE ALSO 310 .Xr tls_config_ocsp_require_stapling 3 , 311 .Xr tls_config_set_protocols 3 , 312 .Xr tls_config_set_session_id 3 , 313 .Xr tls_configure 3 , 314 .Xr tls_init 3 315 .Sh HISTORY 316 .Fn tls_config_set_ca_file , 317 .Fn tls_config_set_ca_path , 318 .Fn tls_config_set_cert_file , 319 .Fn tls_config_set_cert_mem , 320 .Fn tls_config_set_key_file , 321 .Fn tls_config_set_key_mem , 322and 323 .Fn tls_config_set_verify_depth 324appeared in 325 .Ox 5.6 326and got their final names in 327 .Ox 5.7 . 328 .Pp 329 .Fn tls_load_file , 330 .Fn tls_config_set_ca_mem , 331and 332 .Fn tls_config_clear_keys 333appeared in 334 .Ox 5.7 . 335 .Pp 336 .Fn tls_config_verify_client 337and 338 .Fn tls_config_verify_client_optional 339appeared in 340 .Ox 5.9 . 341 .Pp 342 .Fn tls_config_set_keypair_file 343and 344 .Fn tls_config_set_keypair_mem 345appeared in 346 .Ox 6.0 , 347and 348 .Fn tls_config_add_keypair_file 349and 350 .Fn tls_config_add_keypair_mem 351in 352 .Ox 6.1 . 353 .Pp 354 .Fn tls_config_set_crl_file 355and 356 .Fn tls_config_set_crl_mem 357appeared in 358 .Ox 6.2 . 359 .Sh AUTHORS 360 .An Joel Sing Aq Mt jsing@openbsd.org 361with contributions from 362 .An Ted Unangst Aq Mt tedu@openbsd.org 363and 364 .An Bob Beck Aq Mt beck@openbsd.org . 365 .Pp 366 .Fn tls_load_file 367and 368 .Fn tls_config_set_ca_mem 369were written by 370 .An Reyk Floeter Aq Mt reyk@openbsd.org . 371