1.\" $OpenBSD: tls_config_set_protocols.3,v 1.12 2023/07/02 06:37:27 beck Exp $ 2.\" 3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> 4.\" Copyright (c) 2015, 2016 Joel Sing <jsing@openbsd.org> 5.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: July 2 2023 $ 20.Dt TLS_CONFIG_SET_PROTOCOLS 3 21.Os 22.Sh NAME 23.Nm tls_config_set_protocols , 24.Nm tls_config_parse_protocols , 25.Nm tls_config_set_alpn , 26.Nm tls_config_set_ciphers , 27.Nm tls_config_set_dheparams , 28.Nm tls_config_set_ecdhecurves , 29.Nm tls_config_prefer_ciphers_client , 30.Nm tls_config_prefer_ciphers_server 31.Nd TLS protocol and cipher selection 32.Sh SYNOPSIS 33.In tls.h 34.Ft int 35.Fo tls_config_set_protocols 36.Fa "struct tls_config *config" 37.Fa "uint32_t protocols" 38.Fc 39.Ft int 40.Fo tls_config_parse_protocols 41.Fa "uint32_t *protocols" 42.Fa "const char *protostr" 43.Fc 44.Ft int 45.Fo tls_config_set_alpn 46.Fa "struct tls_config *config" 47.Fa "const char *alpn" 48.Fc 49.Ft int 50.Fo tls_config_set_ciphers 51.Fa "struct tls_config *config" 52.Fa "const char *ciphers" 53.Fc 54.Ft int 55.Fo tls_config_set_dheparams 56.Fa "struct tls_config *config" 57.Fa "const char *params" 58.Fc 59.Ft int 60.Fo tls_config_set_ecdhecurves 61.Fa "struct tls_config *config" 62.Fa "const char *curves" 63.Fc 64.Ft void 65.Fn tls_config_prefer_ciphers_client "struct tls_config *config" 66.Ft void 67.Fn tls_config_prefer_ciphers_server "struct tls_config *config" 68.Sh DESCRIPTION 69These functions modify a configuration by setting parameters. 70The configuration options apply to both clients and servers, unless noted 71otherwise. 72.Pp 73.Fn tls_config_set_protocols 74specifies which versions of the TLS protocol may be used. 75Possible values are the bitwise OR of: 76.Pp 77.Bl -item -offset indent -compact 78.It 79.Dv TLS_PROTOCOL_TLSv1_2 80.It 81.Dv TLS_PROTOCOL_TLSv1_3 82.El 83.Pp 84Additionally, the values 85.Dv TLS_PROTOCOL_TLSv1 86(TLSv1.2, TLSv1.3), 87.Dv TLS_PROTOCOLS_ALL 88(all supported protocols) and 89.Dv TLS_PROTOCOLS_DEFAULT 90(TLSv1.2 and TLSv1.3) may be used. 91.Pp 92The 93.Fn tls_config_parse_protocols 94utility function parses a protocol string and returns the corresponding 95value via the 96.Ar protocols 97argument. 98This value can then be passed to the 99.Fn tls_config_set_protocols 100function. 101The protocol string is a comma or colon separated list of keywords. 102Valid keywords are: 103.Pp 104.Bl -tag -width "tlsv1.3" -offset indent -compact 105.It Dv tlsv1.2 106.It Dv tlsv1.3 107.It Dv all 108.Pq all supported protocols 109.It Dv default 110.Pq an alias for Dv secure 111.It Dv legacy 112.Pq an alias for Dv all 113.It Dv secure 114.Pq currently TLSv1.2 and TLSv1.3 115.El 116.Pp 117If a value has a negative prefix (in the form of a leading exclamation mark) 118then it is removed from the list of available protocols, rather than being 119added to it. 120.Pp 121.Fn tls_config_set_alpn 122sets the ALPN protocols that are supported. 123The alpn string is a comma separated list of protocols, in order of preference. 124.Pp 125.Fn tls_config_set_ciphers 126sets the list of ciphers that may be used. 127Lists of ciphers are specified by name, and the 128permitted names are: 129.Pp 130.Bl -item -offset indent -compact 131.It 132.Dv secure Pq or alias Dv default 133.It 134.Dv compat 135.It 136.Dv legacy 137.It 138.Dv insecure Pq or alias Dv all 139.El 140.Pp 141Alternatively, libssl cipher strings can be specified. 142See the CIPHERS section of 143.Xr openssl 1 144for further information. 145.Pp 146.Fn tls_config_set_dheparams 147specifies the parameters that will be used during Diffie-Hellman Ephemeral 148(DHE) key exchange. 149Possible values are: 150.Pp 151.Bl -item -offset indent -compact 152.It 153.Dv none 154.It 155.Dv auto 156.It 157.Dv legacy 158.El 159.Pp 160In 161.Dv auto 162mode, the key size for the ephemeral key is automatically selected 163based on the size of the private key being used for signing. 164In 165.Dv legacy 166mode, 1024 bit ephemeral keys are used. 167The default value is 168.Dv none , 169which disables DHE key exchange. 170.Pp 171.Fn tls_config_set_ecdhecurves 172specifies the names of the elliptic curves that may be used during Elliptic 173Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. 174This is a comma separated list, given in order of preference. 175The special value of "default" will use the default curves (currently X25519, 176P-256 and P-384). 177This function replaces 178.Fn tls_config_set_ecdhecurve , 179which is deprecated. 180.Pp 181.Fn tls_config_prefer_ciphers_client 182prefers ciphers in the client's cipher list when selecting a cipher suite 183(server only). 184This is considered to be less secure than preferring the server's list. 185.Pp 186.Fn tls_config_prefer_ciphers_server 187prefers ciphers in the server's cipher list when selecting a cipher suite 188(server only). 189This is considered to be more secure than preferring the client's list and is 190the default. 191.Sh RETURN VALUES 192These functions return 0 on success or -1 on error. 193.Sh SEE ALSO 194.Xr tls_config_ocsp_require_stapling 3 , 195.Xr tls_config_set_session_id 3 , 196.Xr tls_config_verify 3 , 197.Xr tls_init 3 , 198.Xr tls_load_file 3 199.Sh HISTORY 200.Fn tls_config_set_ciphers 201appeared in 202.Ox 5.6 203and got its final name in 204.Ox 5.7 . 205.Pp 206.Fn tls_config_set_protocols , 207.Fn tls_config_parse_protocols , 208.Fn tls_config_set_dheparams , 209and 210.Fn tls_config_set_ecdhecurve 211appeared in 212.Ox 5.7 , 213.Fn tls_config_prefer_ciphers_client 214and 215.Fn tls_config_prefer_ciphers_server 216in 217.Ox 5.9 , 218and 219.Fn tls_config_set_alpn 220in 221.Ox 6.1 . 222.Sh AUTHORS 223.An Joel Sing Aq Mt jsing@openbsd.org 224with contributions from 225.An Ted Unangst Aq Mt tedu@openbsd.org 226.Pq Fn tls_config_set_ciphers 227and 228.An Reyk Floeter Aq Mt reyk@openbsd.org 229.Pq Fn tls_config_set_ecdhecurve 230