1.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.14 2020/04/25 13:50:05 schwarze 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: April 25 2020 $ 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 @STRENGTH 144Sort the list by decreasing encryption strength, 145preserving the order of cipher suites that have the same strength. 146It is usually given as the last word. 147.El 148.Pp 149The following words can be used to select groups of cipher suites, 150with or without a prefix character. 151If two or more of these words are joined with plus signs 152.Pq Ql + 153to form a longer word, only the intersection of the specified sets 154is selected. 155.Bl -tag -width Ds 156.It Cm ADH 157Cipher suites using ephemeral DH for key exchange 158without doing any server authentication. 159Equivalent to 160.Cm kEDH Ns + Ns Cm aNULL . 161.It Cm aDSS 162Cipher suites using DSS server authentication. 163LibreSSL no longer provides any such cipher suites. 164.It Cm AEAD 165Cipher suites using Authenticated Encryption with Additional Data. 166.It Cm AECDH 167Cipher suites using ephemeral ECDH for key exchange 168without doing any server authentication. 169Equivalent to 170.Cm kEECDH Ns + Ns Cm aNULL . 171.It Cm aECDSA 172Cipher suites using ECDSA server authentication. 173.It Cm AES 174Cipher suites using AES or AESGCM for symmetric encryption. 175.It Cm AES128 176Cipher suites using AES(128) or AESGCM(128) for symmetric encryption. 177.It Cm AES256 178Cipher suites using AES(256) or AESGCM(256) for symmetric encryption. 179.It Cm AESGCM 180Cipher suites using AESGCM for symmetric encryption. 181.It Cm aGOST 182An alias for 183.Cm aGOST01 . 184.It Cm aGOST01 185Cipher suites using GOST R 34.10-2001 server authentication. 186.It Cm ALL 187All cipher suites except those selected by 188.Cm eNULL . 189.It Cm aNULL 190Cipher suites that don't do any server authentication. 191Not enabled by 192.Cm DEFAULT . 193Beware of man-in-the-middle attacks. 194.It Cm aRSA 195Cipher suites using RSA server authentication. 196.It Cm CAMELLIA 197Cipher suites using Camellia for symmetric encryption. 198.It Cm CAMELLIA128 199Cipher suites using Camellia(128) for symmetric encryption. 200.It Cm CAMELLIA256 201Cipher suites using Camellia(256) for symmetric encryption. 202.It Cm CHACHA20 203Cipher suites using ChaCha20-Poly1305 for symmetric encryption. 204.It Cm COMPLEMENTOFALL 205Cipher suites that are not included in 206.Cm ALL . 207Currently an alias for 208.Cm eNULL . 209.It Cm COMPLEMENTOFDEFAULT 210Cipher suites that are included in 211.Cm ALL , 212but not included in 213.Cm DEFAULT . 214Currently similar to 215.Cm aNULL Ns :! Ns Cm eNULL 216except for the order of the cipher suites which are 217.Em not 218selected. 219.It Cm DES 220Cipher suites using single DES for symmetric encryption. 221LibreSSL no longer provides any such cipher suites. 222.It Cm 3DES 223Cipher suites using triple DES for symmetric encryption. 224.It Cm DH 225An alias for 226.Cm kEDH . 227.It Cm DHE 228Cipher suites using ephemeral DH for key exchange, 229but excluding those that don't do any server authentication. 230Similar to 231.Cm kEDH Ns :! Ns Cm aNULL 232except for the order of the cipher suites which are 233.Em not 234selected. 235.It Cm DSS 236An alias for 237.Cm aDSS . 238.It Cm ECDH 239An alias for 240.Cm kEECDH . 241.It Cm ECDHE 242Cipher suites using ephemeral ECDH for key exchange, 243but excluding those that don't do any server authentication. 244Similar to 245.Cm kEECDH Ns :! Ns Cm aNULL 246except for the order of the cipher suites which are 247.Em not 248selected. 249.It Cm ECDSA 250An alias for 251.Cm aECDSA . 252.It Cm EDH 253An alias for 254.Cm DHE . 255.It Cm EECDH 256An alias for 257.Cm ECDHE . 258.It Cm eNULL 259Cipher suites that do not use any encryption. 260Not enabled by 261.Cm DEFAULT , 262and not even included in 263.Cm ALL . 264.It Cm GOST89MAC 265Cipher suites using GOST 28147-89 for message authentication 266instead of HMAC. 267.It Cm GOST94 268Cipher suites using HMAC based on GOST R 34.11-94 269for message authentication. 270.It Cm HIGH 271Cipher suites of high strength. 272.It Cm IDEA 273Cipher suites using IDEA for symmetric encryption. 274LibreSSL does not provide any such cipher suites. 275.It Cm kEDH 276Cipher suites using ephemeral DH for key exchange. 277.It Cm kEECDH 278Cipher suites using ephemeral ECDH for key exchange. 279.It Cm kGOST 280Cipher suites using VKO 34.10 key exchange, specified in RFC 4357. 281.It Cm kRSA 282Cipher suites using RSA key exchange. 283.It Cm LOW 284Cipher suites of low strength. 285.It Cm MD5 286Cipher suites using MD5 for message authentication. 287.It Cm MEDIUM 288Cipher suites of medium strength. 289.It Cm NULL 290An alias for 291.Cm eNULL . 292.It Cm RC4 293Cipher suites using RC4 for symmetric encryption. 294.It Cm RSA 295Cipher suites using RSA for both key exchange and server authentication. 296Equivalent to 297.Cm kRSA Ns + Ns Cm aRSA . 298.It Cm SHA 299An alias for 300.Cm SHA1 . 301.It Cm SHA1 302Cipher suites using SHA1 for message authentication. 303.It Cm SHA256 304Cipher suites using SHA256 for message authentication. 305.It Cm SHA384 306Cipher suites using SHA384 for message authentication. 307.It Cm SSLv3 308An alias for 309.Cm TLSv1 . 310.It Cm STREEBOG256 311Cipher suites using STREEBOG256 for message authentication. 312.It Cm TLSv1 313Cipher suites usable with the TLSv1.0, TLSv1.1, and TLSv1.2 protocols. 314.It Cm TLSv1.2 315Cipher suites for the TLSv1.2 protocol. 316.It Cm TLSv1.3 317Cipher suites for the TLSv1.3 protocol. 318If the 319.Fa control 320string selects at least one cipher suite but neither contains the word 321.Cm TLSv1.3 322nor specifically includes nor excludes any TLSv1.3 cipher suites, all the 323.Cm TLSv1.3 324cipher suites are made available, too. 325.El 326.Pp 327The full words returned by the 328.Xr openssl 1 329.Cm ciphers 330command can be used to select individual cipher suites. 331.Pp 332Unknown words are silently ignored, selecting no cipher suites. 333Failure is only flagged if the 334.Fa control 335string contains invalid bytes 336or if no matching cipher suites are available at all. 337.Pp 338On the client side, including a cipher suite into the list of 339available cipher suites is sufficient for using it. 340On the server side, all cipher suites have additional requirements. 341ADH ciphers don't need a certificate, but DH-parameters must have been set. 342All other cipher suites need a corresponding certificate and key. 343.Pp 344A RSA cipher can only be chosen when an RSA certificate is available. 345RSA ciphers using DHE need a certificate and key and additional DH-parameters 346(see 347.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 348.Pp 349A DSA cipher can only be chosen when a DSA certificate is available. 350DSA ciphers always use DH key exchange and therefore need DH-parameters (see 351.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 352.Pp 353When these conditions are not met 354for any cipher suite in the list (for example, a 355client only supports export RSA ciphers with an asymmetric key length of 512 356bits and the server is not configured to use temporary RSA keys), the 357.Dq no shared cipher 358.Pq Dv SSL_R_NO_SHARED_CIPHER 359error is generated and the handshake will fail. 360.Sh RETURN VALUES 361.Fn SSL_CTX_set_cipher_list 362and 363.Fn SSL_set_cipher_list 364return 1 if any cipher suite could be selected and 0 on complete failure. 365.Sh SEE ALSO 366.Xr ssl 3 , 367.Xr SSL_CTX_set1_groups 3 , 368.Xr SSL_CTX_set_tmp_dh_callback 3 , 369.Xr SSL_CTX_use_certificate 3 , 370.Xr SSL_get_ciphers 3 371.Sh HISTORY 372.Fn SSL_CTX_set_cipher_list 373and 374.Fn SSL_set_cipher_list 375first appeared in SSLeay 0.5.2 and have been available since 376.Ox 2.4 . 377.Sh CAVEATS 378In LibreSSL, 379.Fn SSL_CTX_set_cipher_list 380and 381.Fn SSL_set_cipher_list 382can be used to configure the list of available cipher suites for 383all versions of the TLS protocol, whereas in OpenSSL, they only 384control cipher suites for protocols up to TLSv1.2. 385If compatibility with OpenSSL is required, the list of 386available TLSv1.3 cipher suites can only be changed with 387.Fn SSL_set_ciphersuites . 388