1.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.18 2025/01/18 12:20:02 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: January 18 2025 $ 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 are deprecated aliases: 315.Pp 316.Bl -column kEECDH ECDHE -compact -offset indent 317.It avoid: Ta use: 318.It Cm EDH Ta Cm DHE 319.It Cm EECDH Ta Cm ECDHE 320.It Cm kEDH Ta Cm DH 321.It Cm kEECDH Ta Cm ECDH 322.El 323.Pp 324Unknown words are silently ignored, selecting no cipher suites. 325Failure is only flagged if the 326.Fa control 327string contains invalid bytes 328or if no matching cipher suites are available at all. 329.Pp 330On the client side, including a cipher suite into the list of 331available cipher suites is sufficient for using it. 332On the server side, all cipher suites have additional requirements. 333ADH ciphers don't need a certificate, but DH-parameters must have been set. 334All other cipher suites need a corresponding certificate and key. 335.Pp 336A RSA cipher can only be chosen when an RSA certificate is available. 337RSA ciphers using DHE need a certificate and key and additional DH-parameters 338(see 339.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 340.Pp 341When these conditions are not met 342for any cipher suite in the list (for example, a 343client only supports export RSA ciphers with an asymmetric key length of 512 344bits and the server is not configured to use temporary RSA keys), the 345.Dq no shared cipher 346.Pq Dv SSL_R_NO_SHARED_CIPHER 347error is generated and the handshake will fail. 348.Sh RETURN VALUES 349.Fn SSL_CTX_set_cipher_list 350and 351.Fn SSL_set_cipher_list 352return 1 if any cipher suite could be selected and 0 on complete failure. 353.Sh SEE ALSO 354.Xr ssl 3 , 355.Xr SSL_CTX_set1_groups 3 , 356.Xr SSL_CTX_set_tmp_dh_callback 3 , 357.Xr SSL_CTX_use_certificate 3 , 358.Xr SSL_get_ciphers 3 359.Sh HISTORY 360.Fn SSL_CTX_set_cipher_list 361and 362.Fn SSL_set_cipher_list 363first appeared in SSLeay 0.5.2 and have been available since 364.Ox 2.4 . 365.Sh CAVEATS 366In LibreSSL, 367.Fn SSL_CTX_set_cipher_list 368and 369.Fn SSL_set_cipher_list 370can be used to configure the list of available cipher suites for 371all versions of the TLS protocol, whereas in OpenSSL, they only 372control cipher suites for protocols up to TLSv1.2. 373If compatibility with OpenSSL is required, the list of 374available TLSv1.3 cipher suites can only be changed with 375.Fn SSL_set_ciphersuites . 376