1.\" $OpenBSD: tls_load_file.3,v 1.5 2017/01/31 20:53:50 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: January 31 2017 $ 21.Dt TLS_LOAD_FILE 3 22.Os 23.Sh NAME 24.Nm tls_load_file , 25.Nm tls_config_set_ca_file , 26.Nm tls_config_set_ca_path , 27.Nm tls_config_set_ca_mem , 28.Nm tls_config_set_cert_file , 29.Nm tls_config_set_cert_mem , 30.Nm tls_config_set_key_file , 31.Nm tls_config_set_key_mem , 32.Nm tls_config_set_ocsp_staple_mem , 33.Nm tls_config_set_ocsp_staple_file , 34.Nm tls_config_set_keypair_file , 35.Nm tls_config_set_keypair_mem , 36.Nm tls_config_set_keypair_ocsp_file , 37.Nm tls_config_set_keypair_ocsp_mem , 38.Nm tls_config_add_keypair_file , 39.Nm tls_config_add_keypair_ocsp_mem , 40.Nm tls_config_add_keypair_ocsp_file , 41.Nm tls_config_add_keypair_mem , 42.Nm tls_config_clear_keys , 43.Nm tls_config_set_verify_depth , 44.Nm tls_config_verify_client , 45.Nm tls_config_verify_client_optional 46.Nd TLS certificate and key configuration 47.Sh SYNOPSIS 48.In tls.h 49.Ft uint8_t * 50.Fo tls_load_file 51.Fa "const char *file" 52.Fa "size_t *len" 53.Fa "char *password" 54.Fc 55.Ft int 56.Fo tls_config_set_ca_file 57.Fa "struct tls_config *config" 58.Fa "const char *ca_file" 59.Fc 60.Ft int 61.Fo tls_config_set_ca_path 62.Fa "struct tls_config *config" 63.Fa "const char *ca_path" 64.Fc 65.Ft int 66.Fo tls_config_set_ca_mem 67.Fa "struct tls_config *config" 68.Fa "const uint8_t *cert" 69.Fa "size_t len" 70.Fc 71.Ft int 72.Fo tls_config_set_cert_file 73.Fa "struct tls_config *config" 74.Fa "const char *cert_file" 75.Fc 76.Ft int 77.Fo tls_config_set_cert_mem 78.Fa "struct tls_config *config" 79.Fa "const uint8_t *cert" 80.Fa "size_t len" 81.Fc 82.Ft int 83.Fo tls_config_set_key_file 84.Fa "struct tls_config *config" 85.Fa "const char *key_file" 86.Fc 87.Ft int 88.Fo tls_config_set_key_mem 89.Fa "struct tls_config *config" 90.Fa "const uint8_t *key" 91.Fa "size_t len" 92.Fc 93.Ft int 94.Fo tls_config_set_ocsp_staple_mem 95.Fa "struct tls_config *config" 96.Fa "const uint8_t *staple" 97.Fa "size_t len" 98.Fc 99.Ft int 100.Fo tls_config_set_ocsp_staple_file 101.Fa "struct tls_config *config" 102.Fa "const uint8_t *staple_file" 103.Fc 104.Ft int 105.Fo tls_config_set_keypair_file 106.Fa "struct tls_config *config" 107.Fa "const char *cert_file" 108.Fa "const char *key_file" 109.Fc 110.Ft int 111.Fo tls_config_set_keypair_mem 112.Fa "struct tls_config *config" 113.Fa "const uint8_t *cert" 114.Fa "size_t cert_len" 115.Fa "const uint8_t *key" 116.Fa "size_t key_len" 117.Fc 118.Ft int 119.Fo tls_config_set_keypair_ocsp_file 120.Fa "struct tls_config *config" 121.Fa "const char *cert_file" 122.Fa "const char *key_file" 123.Fa "const char *staple_file" 124.Fc 125.Ft int 126.Fo tls_config_set_keypair_ocsp_mem 127.Fa "struct tls_config *config" 128.Fa "const uint8_t *cert" 129.Fa "size_t cert_len" 130.Fa "const uint8_t *key" 131.Fa "size_t key_len" 132.Fa "const uint8_t *staple" 133.Fa "size_t staple_len" 134.Fc 135.Ft int 136.Fo tls_config_add_keypair_file 137.Fa "struct tls_config *config" 138.Fa "const char *cert_file" 139.Fa "const char *key_file" 140.Fc 141.Ft int 142.Fo tls_config_add_keypair_mem 143.Fa "struct tls_config *config" 144.Fa "const uint8_t *cert" 145.Fa "size_t cert_len" 146.Fa "const uint8_t *key" 147.Fa "size_t key_len" 148.Fc 149.Ft int 150.Fo tls_config_add_keypair_ocsp_file 151.Fa "struct tls_config *config" 152.Fa "const char *cert_file" 153.Fa "const char *key_file" 154.Fa "const char *staple_file" 155.Fc 156.Ft int 157.Fo tls_config_add_keypair_ocsp_mem 158.Fa "struct tls_config *config" 159.Fa "const uint8_t *cert" 160.Fa "size_t cert_len" 161.Fa "const uint8_t *key" 162.Fa "size_t key_len" 163.Fa "const uint8_t *staple" 164.Fa "size_t staple_len" 165.Fc 166.Ft void 167.Fn tls_config_clear_keys "struct tls_config *config" 168.Ft int 169.Fo tls_config_set_verify_depth 170.Fa "struct tls_config *config" 171.Fa "int verify_depth" 172.Fc 173.Ft void 174.Fn tls_config_verify_client "struct tls_config *config" 175.Ft void 176.Fn tls_config_verify_client_optional "struct tls_config *config" 177.Sh DESCRIPTION 178.Fn tls_load_file 179loads a certificate or key from disk into memory to be loaded with 180.Fn tls_config_set_ca_mem , 181.Fn tls_config_set_cert_mem 182or 183.Fn tls_config_set_key_mem . 184A private key will be decrypted if the optional 185.Ar password 186argument is specified. 187.Pp 188.Fn tls_config_set_ca_file 189sets the filename used to load a file 190containing the root certificates. 191.Pp 192.Fn tls_config_set_ca_path 193sets the path (directory) which should be searched for root 194certificates. 195.Pp 196.Fn tls_config_set_ca_mem 197sets the root certificates directly from memory. 198.Pp 199.Fn tls_config_set_cert_file 200sets file from which the public certificate will be read. 201.Pp 202.Fn tls_config_set_cert_mem 203sets the public certificate directly from memory. 204.Pp 205.Fn tls_config_set_key_file 206sets the file from which the private key will be read. 207.Pp 208.Fn tls_config_set_key_mem 209directly sets the private key from memory. 210.Pp 211.Fn tls_config_set_ocsp_staple_file 212sets a DER-encoded OCSP response to be stapled during the TLS handshake from 213the specified file. 214.Pp 215.Fn tls_config_set_ocsp_staple_mem 216sets a DER-encoded OCSP response to be stapled during the TLS handshake from 217memory. 218.Pp 219.Fn tls_config_set_keypair_file 220sets the files from which the public certificate, and private key will be read. 221.Pp 222.Fn tls_config_set_keypair_mem 223directly sets the public certificate, and private key from memory. 224.Pp 225.Fn tls_config_set_keypair_file 226sets the files from which the public certificate, private key, and DER encoded 227OCSP staple will be read. 228.Pp 229.Fn tls_config_set_keypair_ocsp_mem 230directly sets the public certificate, private key, and DER encoded OCSP staple 231from memory. 232.Pp 233.Fn tls_config_add_keypair_file 234adds an additional public certificate, and private key from the specified files, 235used as an alternative certificate for Server Name Indication (server only). 236.Pp 237.Fn tls_config_add_keypair_mem 238adds an additional public certificate, and private key from memory, used as an 239alternative certificate for Server Name Indication (server only). 240.Pp 241.Fn tls_config_add_keypair_ocsp_file 242adds an additional public certificate, private key, and DER encoded OCSP staple 243from the specified files, used as an alternative certificate for Server Name 244Indication (server only). 245.Pp 246.Fn tls_config_add_keypair_ocsp_mem 247adds an additional public certificate, private key, and DER encoded OCSP staple 248from memory, used as an alternative certificate for Server Name Indication 249(server only). 250.Pp 251.Fn tls_config_clear_keys 252clears any secret keys from memory. 253.Pp 254.Fn tls_config_set_verify_depth 255limits the number of intermediate certificates that will be followed during 256certificate validation. 257.Pp 258.Fn tls_config_verify_client 259enables client certificate verification, requiring the client to send 260a certificate (server only). 261.Pp 262.Fn tls_config_verify_client_optional 263enables client certificate verification, without requiring the client 264to send a certificate (server only). 265.Sh RETURN VALUES 266.Fn tls_load_file 267returns 268.Dv NULL 269on error or an out of memory condition. 270.Pp 271The other functions return 0 on success or -1 on error. 272.Sh SEE ALSO 273.Xr tls_config_ocsp_require_stapling 3 , 274.Xr tls_config_set_protocols 3 , 275.Xr tls_config_set_session_id 3 , 276.Xr tls_configure 3 , 277.Xr tls_init 3 278.Sh HISTORY 279.Fn tls_config_set_ca_file , 280.Fn tls_config_set_ca_path , 281.Fn tls_config_set_cert_file , 282.Fn tls_config_set_cert_mem , 283.Fn tls_config_set_key_file , 284.Fn tls_config_set_key_mem , 285and 286.Fn tls_config_set_verify_depth 287appeared in 288.Ox 5.6 289and got their final names in 290.Ox 5.7 . 291.Pp 292.Fn tls_load_file , 293.Fn tls_config_set_ca_mem , 294and 295.Fn tls_config_clear_keys 296appeared in 297.Ox 5.7 . 298.Pp 299.Fn tls_config_verify_client 300and 301.Fn tls_config_verify_client_optional 302appeared in 303.Ox 5.9 . 304.Pp 305.Fn tls_config_set_keypair_file 306and 307.Fn tls_config_set_keypair_mem 308appeared in 309.Ox 6.0 , 310and 311.Fn tls_config_add_keypair_file 312and 313.Fn tls_config_add_keypair_mem 314in 315.Ox 6.1 . 316.Sh AUTHORS 317.An Joel Sing Aq Mt jsing@openbsd.org 318with contibutions from 319.An Ted Unangst Aq Mt tedu@openbsd.org 320and 321.An Bob Beck Aq Mt beck@openbsd.org . 322.Pp 323.Fn tls_load_file 324and 325.Fn tls_config_set_ca_mem 326were written by 327.An Reyk Floeter Aq Mt reyk@openbsd.org . 328