1.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.16 2022/12/11 20:53:27 tb Exp $ 2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2018, 2020 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>. 22.\" Copyright (c) 2000, 2001, 2013 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: December 11 2022 $ 69.Dt SSL_CTX_SET_CIPHER_LIST 3 70.Os 71.Sh NAME 72.Nm SSL_CTX_set_cipher_list , 73.Nm SSL_set_cipher_list 74.Nd choose list of available SSL_CIPHERs 75.Sh SYNOPSIS 76.In openssl/ssl.h 77.Ft int 78.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *control" 79.Ft int 80.Fn SSL_set_cipher_list "SSL *ssl" "const char *control" 81.Sh DESCRIPTION 82.Fn SSL_CTX_set_cipher_list 83sets the list of available cipher suites for 84.Fa ctx 85using the 86.Fa control 87string. 88The list of cipher suites is inherited by all 89.Fa ssl 90objects created from 91.Fa ctx . 92.Pp 93.Fn SSL_set_cipher_list 94sets the list of cipher suites only for 95.Fa ssl . 96.Pp 97The control string consists of one or more control words 98separated by colon characters 99.Pq Ql \&: . 100Space 101.Pq Ql \ \& , 102semicolon 103.Pq Ql \&; , 104and comma 105.Pq Ql \&, 106characters can also be used as separators. 107Each control words selects a set of cipher suites 108and can take one of the following optional prefix characters: 109.Bl -tag -width Ds 110.It \&No prefix: 111Those of the selected cipher suites that have not been made available 112yet are added to the end of the list of available cipher suites, 113preserving their order. 114.It Prefixed minus sign Pq Ql \- : 115Those of the selected cipher suites that have been made available 116earlier are moved back from the list of available cipher suites to 117the beginning of the list of unavailable cipher suites, 118also preserving their order. 119.It Prefixed plus sign Pq Ql + : 120Those of the selected cipher suites have been made available earlier 121are moved to end of the list of available cipher suites, reducing 122their priority, but preserving the order among themselves. 123.It Prefixed exclamation mark Pq Ql \&! : 124The selected cipher suites are permanently deleted, no matter whether 125they had earlier been made available or not, and can no longer 126be added or re-added by later words. 127.El 128.Pp 129The following special words can only be used without a prefix: 130.Bl -tag -width Ds 131.It Cm DEFAULT 132An alias for 133.Sm off 134.Cm ALL No :! Cm aNULL No :! Cm eNULL . 135.Sm on 136It can only be used as the first word. 137The 138.Cm DEFAULT 139cipher list can be displayed with the 140.Xr openssl 1 141.Cm ciphers 142command. 143.It Cm @SECLEVEL=n 144Set the security level to n, which should be a number between 145zero and five. 146See 147.Xr SSL_CTX_set_security_level 3 148for details. 149.It Cm @STRENGTH 150Sort the list by decreasing encryption strength, 151preserving the order of cipher suites that have the same strength. 152It is usually given as the last word. 153.El 154.Pp 155The following words can be used to select groups of cipher suites, 156with or without a prefix character. 157If two or more of these words are joined with plus signs 158.Pq Ql + 159to form a longer word, only the intersection of the specified sets 160is selected. 161.Bl -tag -width Ds 162.It Cm ADH 163Cipher suites using ephemeral DH for key exchange 164without doing any server authentication. 165Equivalent to 166.Cm DH Ns + Ns Cm aNULL . 167.It Cm AEAD 168Cipher suites using Authenticated Encryption with Additional Data. 169.It Cm AECDH 170Cipher suites using ephemeral ECDH for key exchange 171without doing any server authentication. 172Equivalent to 173.Cm ECDH Ns + Ns Cm aNULL . 174.It Cm aECDSA 175Cipher suites using ECDSA server authentication. 176.It Cm AES 177Cipher suites using AES or AESGCM for symmetric encryption. 178.It Cm AES128 179Cipher suites using AES(128) or AESGCM(128) for symmetric encryption. 180.It Cm AES256 181Cipher suites using AES(256) or AESGCM(256) for symmetric encryption. 182.It Cm AESGCM 183Cipher suites using AESGCM for symmetric encryption. 184.It Cm aGOST 185An alias for 186.Cm aGOST01 . 187.It Cm aGOST01 188Cipher suites using GOST R 34.10-2001 server authentication. 189.It Cm ALL 190All cipher suites except those selected by 191.Cm eNULL . 192.It Cm aNULL 193Cipher suites that don't do any server authentication. 194Not enabled by 195.Cm DEFAULT . 196Beware of man-in-the-middle attacks. 197.It Cm aRSA 198Cipher suites using RSA server authentication. 199.It Cm CAMELLIA 200Cipher suites using Camellia for symmetric encryption. 201.It Cm CAMELLIA128 202Cipher suites using Camellia(128) for symmetric encryption. 203.It Cm CAMELLIA256 204Cipher suites using Camellia(256) for symmetric encryption. 205.It Cm CHACHA20 206Cipher suites using ChaCha20-Poly1305 for symmetric encryption. 207.It Cm COMPLEMENTOFALL 208Cipher suites that are not included in 209.Cm ALL . 210Currently an alias for 211.Cm eNULL . 212.It Cm COMPLEMENTOFDEFAULT 213Cipher suites that are included in 214.Cm ALL , 215but not included in 216.Cm DEFAULT . 217Currently similar to 218.Cm aNULL Ns :! Ns Cm eNULL 219except for the order of the cipher suites which are 220.Em not 221selected. 222.It Cm 3DES 223Cipher suites using triple DES for symmetric encryption. 224.It Cm DH 225Cipher suites using ephemeral DH for key exchange. 226.It Cm DHE 227Cipher suites using ephemeral DH for key exchange, 228but excluding those that don't do any server authentication. 229Similar to 230.Cm DH Ns :! Ns Cm aNULL 231except for the order of the cipher suites which are 232.Em not 233selected. 234.It Cm ECDH 235Cipher suites using ephemeral ECDH for key exchange. 236.It Cm ECDHE 237Cipher suites using ephemeral ECDH for key exchange, 238but excluding those that don't do any server authentication. 239Similar to 240.Cm ECDH Ns :! Ns Cm aNULL 241except for the order of the cipher suites which are 242.Em not 243selected. 244.It Cm ECDSA 245An alias for 246.Cm aECDSA . 247.It Cm eNULL 248Cipher suites that do not use any encryption. 249Not enabled by 250.Cm DEFAULT , 251and not even included in 252.Cm ALL . 253.It Cm GOST89MAC 254Cipher suites using GOST 28147-89 for message authentication 255instead of HMAC. 256.It Cm GOST94 257Cipher suites using HMAC based on GOST R 34.11-94 258for message authentication. 259.It Cm HIGH 260Cipher suites of high strength. 261.It Cm kGOST 262Cipher suites using VKO 34.10 key exchange, specified in RFC 4357. 263.It Cm kRSA 264Cipher suites using RSA key exchange. 265.It Cm LOW 266Cipher suites of low strength. 267.It Cm MD5 268Cipher suites using MD5 for message authentication. 269.It Cm MEDIUM 270Cipher suites of medium strength. 271.It Cm NULL 272An alias for 273.Cm eNULL . 274.It Cm RC4 275Cipher suites using RC4 for symmetric encryption. 276.It Cm RSA 277Cipher suites using RSA for both key exchange and server authentication. 278Equivalent to 279.Cm kRSA Ns + Ns Cm aRSA . 280.It Cm SHA 281An alias for 282.Cm SHA1 . 283.It Cm SHA1 284Cipher suites using SHA1 for message authentication. 285.It Cm SHA256 286Cipher suites using SHA256 for message authentication. 287.It Cm SHA384 288Cipher suites using SHA384 for message authentication. 289.It Cm SSLv3 290An alias for 291.Cm TLSv1 . 292.It Cm STREEBOG256 293Cipher suites using STREEBOG256 for message authentication. 294.It Cm TLSv1 295Cipher suites usable with the TLSv1.0, TLSv1.1, and TLSv1.2 protocols. 296.It Cm TLSv1.2 297Cipher suites for the TLSv1.2 protocol. 298.It Cm TLSv1.3 299Cipher suites for the TLSv1.3 protocol. 300If the 301.Fa control 302string selects at least one cipher suite but neither contains the word 303.Cm TLSv1.3 304nor specifically includes nor excludes any TLSv1.3 cipher suites, all the 305.Cm TLSv1.3 306cipher suites are made available, too. 307.El 308.Pp 309The full words returned by the 310.Xr openssl 1 311.Cm ciphers 312command can be used to select individual cipher suites. 313.Pp 314The following words do not match anything because 315LibreSSL no longer provides any such cipher suites: 316.Pp 317.Bl -tag -width Ds -compact 318.It Cm DES 319Cipher suites using single DES for symmetric encryption. 320.It Cm DSS 321Cipher suites using DSS server authentication. 322.It Cm IDEA 323Cipher suites using IDEA for symmetric encryption. 324.El 325.Pp 326The following are deprecated aliases: 327.Pp 328.Bl -column kEECDH ECDHE -compact -offset indent 329.It avoid: Ta use: 330.It Cm EDH Ta Cm DHE 331.It Cm EECDH Ta Cm ECDHE 332.It Cm kEDH Ta Cm DH 333.It Cm kEECDH Ta Cm ECDH 334.El 335.Pp 336Unknown words are silently ignored, selecting no cipher suites. 337Failure is only flagged if the 338.Fa control 339string contains invalid bytes 340or if no matching cipher suites are available at all. 341.Pp 342On the client side, including a cipher suite into the list of 343available cipher suites is sufficient for using it. 344On the server side, all cipher suites have additional requirements. 345ADH ciphers don't need a certificate, but DH-parameters must have been set. 346All other cipher suites need a corresponding certificate and key. 347.Pp 348A RSA cipher can only be chosen when an RSA certificate is available. 349RSA ciphers using DHE need a certificate and key and additional DH-parameters 350(see 351.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 352.Pp 353A DSA cipher can only be chosen when a DSA certificate is available. 354DSA ciphers always use DH key exchange and therefore need DH-parameters (see 355.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 356.Pp 357When these conditions are not met 358for any cipher suite in the list (for example, a 359client only supports export RSA ciphers with an asymmetric key length of 512 360bits and the server is not configured to use temporary RSA keys), the 361.Dq no shared cipher 362.Pq Dv SSL_R_NO_SHARED_CIPHER 363error is generated and the handshake will fail. 364.Sh RETURN VALUES 365.Fn SSL_CTX_set_cipher_list 366and 367.Fn SSL_set_cipher_list 368return 1 if any cipher suite could be selected and 0 on complete failure. 369.Sh SEE ALSO 370.Xr ssl 3 , 371.Xr SSL_CTX_set1_groups 3 , 372.Xr SSL_CTX_set_tmp_dh_callback 3 , 373.Xr SSL_CTX_use_certificate 3 , 374.Xr SSL_get_ciphers 3 375.Sh HISTORY 376.Fn SSL_CTX_set_cipher_list 377and 378.Fn SSL_set_cipher_list 379first appeared in SSLeay 0.5.2 and have been available since 380.Ox 2.4 . 381.Sh CAVEATS 382In LibreSSL, 383.Fn SSL_CTX_set_cipher_list 384and 385.Fn SSL_set_cipher_list 386can be used to configure the list of available cipher suites for 387all versions of the TLS protocol, whereas in OpenSSL, they only 388control cipher suites for protocols up to TLSv1.2. 389If compatibility with OpenSSL is required, the list of 390available TLSv1.3 cipher suites can only be changed with 391.Fn SSL_set_ciphersuites . 392