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