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