1.\" $OpenBSD: tls_config_set_protocols.3,v 1.11 2021/01/02 19:58:44 schwarze 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: January 2 2021 $ 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_0 80.It 81.Dv TLS_PROTOCOL_TLSv1_1 82.It 83.Dv TLS_PROTOCOL_TLSv1_2 84.It 85.Dv TLS_PROTOCOL_TLSv1_3 86.El 87.Pp 88Additionally, the values 89.Dv TLS_PROTOCOL_TLSv1 90(TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3), 91.Dv TLS_PROTOCOLS_ALL 92(all supported protocols) and 93.Dv TLS_PROTOCOLS_DEFAULT 94(TLSv1.2 and TLSv1.3) may be used. 95.Pp 96The 97.Fn tls_config_parse_protocols 98utility function parses a protocol string and returns the corresponding 99value via the 100.Ar protocols 101argument. 102This value can then be passed to the 103.Fn tls_config_set_protocols 104function. 105The protocol string is a comma or colon separated list of keywords. 106Valid keywords are: 107.Pp 108.Bl -tag -width "tlsv1.3" -offset indent -compact 109.It Dv tlsv1.0 110.It Dv tlsv1.1 111.It Dv tlsv1.2 112.It Dv tlsv1.3 113.It Dv all 114.Pq all supported protocols 115.It Dv default 116.Pq an alias for Dv secure 117.It Dv legacy 118.Pq an alias for Dv all 119.It Dv secure 120.Pq currently TLSv1.2 and TLSv1.3 121.El 122.Pp 123If a value has a negative prefix (in the form of a leading exclamation mark) 124then it is removed from the list of available protocols, rather than being 125added to it. 126.Pp 127.Fn tls_config_set_alpn 128sets the ALPN protocols that are supported. 129The alpn string is a comma separated list of protocols, in order of preference. 130.Pp 131.Fn tls_config_set_ciphers 132sets the list of ciphers that may be used. 133Lists of ciphers are specified by name, and the 134permitted names are: 135.Pp 136.Bl -item -offset indent -compact 137.It 138.Dv secure Pq or alias Dv default 139.It 140.Dv compat 141.It 142.Dv legacy 143.It 144.Dv insecure Pq or alias Dv all 145.El 146.Pp 147Alternatively, libssl cipher strings can be specified. 148See the CIPHERS section of 149.Xr openssl 1 150for further information. 151.Pp 152.Fn tls_config_set_dheparams 153specifies the parameters that will be used during Diffie-Hellman Ephemeral 154(DHE) key exchange. 155Possible values are: 156.Pp 157.Bl -item -offset indent -compact 158.It 159.Dv none 160.It 161.Dv auto 162.It 163.Dv legacy 164.El 165.Pp 166In 167.Dv auto 168mode, the key size for the ephemeral key is automatically selected 169based on the size of the private key being used for signing. 170In 171.Dv legacy 172mode, 1024 bit ephemeral keys are used. 173The default value is 174.Dv none , 175which disables DHE key exchange. 176.Pp 177.Fn tls_config_set_ecdhecurves 178specifies the names of the elliptic curves that may be used during Elliptic 179Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. 180This is a comma separated list, given in order of preference. 181The special value of "default" will use the default curves (currently X25519, 182P-256 and P-384). 183This function replaces 184.Fn tls_config_set_ecdhecurve , 185which is deprecated. 186.Pp 187.Fn tls_config_prefer_ciphers_client 188prefers ciphers in the client's cipher list when selecting a cipher suite 189(server only). 190This is considered to be less secure than preferring the server's list. 191.Pp 192.Fn tls_config_prefer_ciphers_server 193prefers ciphers in the server's cipher list when selecting a cipher suite 194(server only). 195This is considered to be more secure than preferring the client's list and is 196the default. 197.Sh RETURN VALUES 198These functions return 0 on success or -1 on error. 199.Sh SEE ALSO 200.Xr tls_config_ocsp_require_stapling 3 , 201.Xr tls_config_set_session_id 3 , 202.Xr tls_config_verify 3 , 203.Xr tls_init 3 , 204.Xr tls_load_file 3 205.Sh HISTORY 206.Fn tls_config_set_ciphers 207appeared in 208.Ox 5.6 209and got its final name in 210.Ox 5.7 . 211.Pp 212.Fn tls_config_set_protocols , 213.Fn tls_config_parse_protocols , 214.Fn tls_config_set_dheparams , 215and 216.Fn tls_config_set_ecdhecurve 217appeared in 218.Ox 5.7 , 219.Fn tls_config_prefer_ciphers_client 220and 221.Fn tls_config_prefer_ciphers_server 222in 223.Ox 5.9 , 224and 225.Fn tls_config_set_alpn 226in 227.Ox 6.1 . 228.Sh AUTHORS 229.An Joel Sing Aq Mt jsing@openbsd.org 230with contributions from 231.An Ted Unangst Aq Mt tedu@openbsd.org 232.Pq Fn tls_config_set_ciphers 233and 234.An Reyk Floeter Aq Mt reyk@openbsd.org 235.Pq Fn tls_config_set_ecdhecurve 236