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