1 .\" $OpenBSD: tls_config_set_protocols.3,v 1.13 2025年07月07日 10:54:00 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: July 7 2025 $ 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_set_ecdhecurve is intentionally undocumented. 30 .Nm tls_config_prefer_ciphers_client , 31 .Nm tls_config_prefer_ciphers_server 32 .Nd TLS protocol and cipher selection 33 .Sh SYNOPSIS 34 .Lb libtls libssl libcrypto 35 .In tls.h 36 .Ft int 37 .Fo tls_config_set_protocols 38 .Fa "struct tls_config *config" 39 .Fa "uint32_t protocols" 40 .Fc 41 .Ft int 42 .Fo tls_config_parse_protocols 43 .Fa "uint32_t *protocols" 44 .Fa "const char *protostr" 45 .Fc 46 .Ft int 47 .Fo tls_config_set_alpn 48 .Fa "struct tls_config *config" 49 .Fa "const char *alpn" 50 .Fc 51 .Ft int 52 .Fo tls_config_set_ciphers 53 .Fa "struct tls_config *config" 54 .Fa "const char *ciphers" 55 .Fc 56 .Ft int 57 .Fo tls_config_set_dheparams 58 .Fa "struct tls_config *config" 59 .Fa "const char *params" 60 .Fc 61 .Ft int 62 .Fo tls_config_set_ecdhecurves 63 .Fa "struct tls_config *config" 64 .Fa "const char *curves" 65 .Fc 66 .Ft void 67 .Fn tls_config_prefer_ciphers_client "struct tls_config *config" 68 .Ft void 69 .Fn tls_config_prefer_ciphers_server "struct tls_config *config" 70 .Sh DESCRIPTION 71These functions modify a configuration by setting parameters. 72The configuration options apply to both clients and servers, unless noted 73otherwise. 74 .Pp 75 .Fn tls_config_set_protocols 76specifies which versions of the TLS protocol may be used. 77Possible values are the bitwise OR of: 78 .Pp 79 .Bl -item -offset indent -compact 80 .It 81 .Dv TLS_PROTOCOL_TLSv1_2 82 .It 83 .Dv TLS_PROTOCOL_TLSv1_3 84 .El 85 .Pp 86Additionally, the values 87 .Dv TLS_PROTOCOL_TLSv1 88(TLSv1.2, TLSv1.3), 89 .Dv TLS_PROTOCOLS_ALL 90(all supported protocols) and 91 .Dv TLS_PROTOCOLS_DEFAULT 92(TLSv1.2 and TLSv1.3) may be used. 93 .Pp 94The 95 .Fn tls_config_parse_protocols 96utility function parses a protocol string and returns the corresponding 97value via the 98 .Ar protocols 99argument. 100This value can then be passed to the 101 .Fn tls_config_set_protocols 102function. 103The protocol string is a comma or colon separated list of keywords. 104Valid keywords are: 105 .Pp 106 .Bl -tag -width "tlsv1.3" -offset indent -compact 107 .It Dv tlsv1.2 108 .It Dv tlsv1.3 109 .It Dv all 110 .Pq all supported protocols 111 .It Dv default 112 .Pq an alias for Dv secure 113 .It Dv legacy 114 .Pq an alias for Dv all 115 .It Dv secure 116 .Pq currently TLSv1.2 and TLSv1.3 117 .El 118 .Pp 119If a value has a negative prefix (in the form of a leading exclamation mark) 120then it is removed from the list of available protocols, rather than being 121added to it. 122 .Pp 123 .Fn tls_config_set_alpn 124sets the ALPN protocols that are supported. 125The alpn string is a comma separated list of protocols, in order of preference. 126 .Pp 127 .Fn tls_config_set_ciphers 128sets the list of ciphers that may be used. 129Lists of ciphers are specified by name, and the 130permitted names are: 131 .Pp 132 .Bl -item -offset indent -compact 133 .It 134 .Dv secure Pq or alias Dv default 135 .It 136 .Dv compat 137 .It 138 .Dv legacy 139 .It 140 .Dv insecure Pq or alias Dv all 141 .El 142 .Pp 143Alternatively, libssl cipher strings can be specified. 144See the CIPHERS section of 145 .Xr openssl 1 146for further information. 147 .Pp 148 .Fn tls_config_set_dheparams 149specifies the parameters that will be used during Diffie-Hellman Ephemeral 150(DHE) key exchange. 151Possible values are: 152 .Pp 153 .Bl -item -offset indent -compact 154 .It 155 .Dv none 156 .It 157 .Dv auto 158 .It 159 .Dv legacy 160 .El 161 .Pp 162In 163 .Dv auto 164mode, the key size for the ephemeral key is automatically selected 165based on the size of the private key being used for signing. 166In 167 .Dv legacy 168mode, 1024 bit ephemeral keys are used. 169The default value is 170 .Dv none , 171which disables DHE key exchange. 172 .Pp 173 .Fn tls_config_set_ecdhecurves 174specifies the names of the elliptic curves that may be used during Elliptic 175Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. 176This is a comma separated list, given in order of preference. 177The special value of "default" will use the default curves (currently X25519, 178P-256 and P-384). 179This function replaces 180 .Fn tls_config_set_ecdhecurve , 181which is deprecated. 182 .Pp 183 .Fn tls_config_prefer_ciphers_client 184prefers ciphers in the client's cipher list when selecting a cipher suite 185(server only). 186This is considered to be less secure than preferring the server's list. 187 .Pp 188 .Fn tls_config_prefer_ciphers_server 189prefers ciphers in the server's cipher list when selecting a cipher suite 190(server only). 191This is considered to be more secure than preferring the client's list and is 192the default. 193 .Sh RETURN VALUES 194These functions return 0 on success or -1 on error. 195 .Sh SEE ALSO 196 .Xr tls_config_ocsp_require_stapling 3 , 197 .Xr tls_config_set_session_id 3 , 198 .Xr tls_config_verify 3 , 199 .Xr tls_init 3 , 200 .Xr tls_load_file 3 201 .Sh HISTORY 202 .Fn tls_config_set_ciphers 203appeared in 204 .Ox 5.6 205and got its final name in 206 .Ox 5.7 . 207 .Pp 208 .Fn tls_config_set_protocols , 209 .Fn tls_config_parse_protocols , 210 .Fn tls_config_set_dheparams , 211and 212 .Fn tls_config_set_ecdhecurve 213appeared in 214 .Ox 5.7 , 215 .Fn tls_config_prefer_ciphers_client 216and 217 .Fn tls_config_prefer_ciphers_server 218in 219 .Ox 5.9 , 220and 221 .Fn tls_config_set_alpn 222in 223 .Ox 6.1 . 224 .Sh AUTHORS 225 .An Joel Sing Aq Mt jsing@openbsd.org 226with contributions from 227 .An Ted Unangst Aq Mt tedu@openbsd.org 228 .Pq Fn tls_config_set_ciphers 229and 230 .An Reyk Floeter Aq Mt reyk@openbsd.org 231 .Pq Fn tls_config_set_ecdhecurve 232