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