1.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.11 2020/04/11 14:01:59 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 11 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 does not provide 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. 221.It Cm 3DES 222Cipher suites using triple DES for symmetric encryption. 223.It Cm DH 224An alias for 225.Cm kEDH . 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 kEDH Ns :! Ns Cm aNULL 231except for the order of the cipher suites which are 232.Em not 233selected. 234.It Cm DSS 235An alias for 236.Cm aDSS . 237.It Cm ECDH 238An alias for 239.Cm kEECDH . 240.It Cm ECDHE 241Cipher suites using ephemeral ECDH for key exchange, 242but excluding those that don't do any server authentication. 243Similar to 244.Cm kEECDH Ns :! Ns Cm aNULL 245except for the order of the cipher suites which are 246.Em not 247selected. 248.It Cm ECDSA 249An alias for 250.Cm aECDSA . 251.It Cm EDH 252An alias for 253.Cm DHE . 254.It Cm EECDH 255An alias for 256.Cm ECDHE . 257.It Cm eNULL 258Cipher suites that do not use any encryption. 259Not enabled by 260.Cm DEFAULT , 261and not even included in 262.Cm ALL . 263.It Cm GOST89MAC 264Cipher suites using GOST 28147-89 for message authentication 265instead of HMAC. 266.It Cm GOST94 267Cipher suites using HMAC based on GOST R 34.11-94 268for message authentication. 269.It Cm HIGH 270Cipher suites of high strength. 271Currently, these are cipher suites using 272.Cm CHACHA20 , 273.Cm AES , 274.Cm CAMELLIA , 275or GOST-28178-89-CNT symmetric encryption. 276.It Cm IDEA 277Cipher suites using IDEA for symmetric encryption. 278LibreSSL does not provide any such cipher suites. 279.It Cm kEDH 280Cipher suites using ephemeral DH for key exchange. 281.It Cm kEECDH 282Cipher suites using ephemeral ECDH for key exchange. 283.It Cm kGOST 284Cipher suites using VKO 34.10 key exchange, specified in RFC 4357. 285.It Cm kRSA 286Cipher suites using RSA key exchange. 287.It Cm LOW 288Cipher suites of low strength. 289Currently, these are cipher suites using 290.Cm DES 291or 292.Cm RC4 293symmetric encryption. 294.It Cm MD5 295Cipher suites using MD5 for message authentication. 296.It Cm MEDIUM 297Cipher suites of medium strength. 298Currently, these are cipher suites using 299.Cm 3DES 300symmetric encryption. 301.It Cm NULL 302An alias for 303.Cm eNULL . 304.It Cm RC4 305Cipher suites using RC4 for symmetric encryption. 306.It Cm RSA 307Cipher suites using RSA for both key exchange and server authentication. 308Equivalent to 309.Cm kRSA Ns + Ns Cm aRSA . 310.It Cm SHA 311An alias for 312.Cm SHA1 . 313.It Cm SHA1 314Cipher suites using SHA1 for message authentication. 315.It Cm SHA256 316Cipher suites using SHA256 for message authentication. 317.It Cm SHA384 318Cipher suites using SHA384 for message authentication. 319.It Cm SSLv3 320An alias for 321.Cm TLSv1 . 322.It Cm STREEBOG256 323Cipher suites using STREEBOG256 for message authentication. 324.It Cm TLSv1 325Cipher suites usable with the TLSv1.0, TLSv1.1, and TLSv1.2 protocols. 326.It Cm TLSv1.2 327Cipher suites for the TLSv1.2 protocol. 328.It Cm TLSv1.3 329Cipher suites for the TLSv1.3 protocol. 330If the 331.Fa control 332string neither contains the word 333.Cm TLSv1.3 334nor specifically includes nor excludes any TLSv1.3 cipher suites, all the 335.Cm TLSv1.3 336cipher suites are made available. 337.El 338.Pp 339The full words returned by the 340.Xr openssl 1 341.Cm ciphers 342command can be used to select individual cipher suites. 343.Pp 344Unknown words are silently ignored, selecting no cipher suites. 345Failure is only flagged if the 346.Fa control 347string contains invalid bytes 348or if no matching cipher suites are available at all. 349.Pp 350On the client side, including a cipher suite into the list of 351available cipher suites is sufficient for using it. 352On the server side, all cipher suites have additional requirements. 353ADH ciphers don't need a certificate, but DH-parameters must have been set. 354All other cipher suites need a corresponding certificate and key. 355.Pp 356A RSA cipher can only be chosen when an RSA certificate is available. 357RSA ciphers using DHE need a certificate and key and additional DH-parameters 358(see 359.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 360.Pp 361A DSA cipher can only be chosen when a DSA certificate is available. 362DSA ciphers always use DH key exchange and therefore need DH-parameters (see 363.Xr SSL_CTX_set_tmp_dh_callback 3 ) . 364.Pp 365When these conditions are not met 366for any cipher suite in the list (for example, a 367client only supports export RSA ciphers with an asymmetric key length of 512 368bits and the server is not configured to use temporary RSA keys), the 369.Dq no shared cipher 370.Pq Dv SSL_R_NO_SHARED_CIPHER 371error is generated and the handshake will fail. 372.Sh RETURN VALUES 373.Fn SSL_CTX_set_cipher_list 374and 375.Fn SSL_set_cipher_list 376return 1 if any cipher suite could be selected and 0 on complete failure. 377.Sh SEE ALSO 378.Xr ssl 3 , 379.Xr SSL_CTX_set1_groups 3 , 380.Xr SSL_CTX_set_tmp_dh_callback 3 , 381.Xr SSL_CTX_use_certificate 3 , 382.Xr SSL_get_ciphers 3 383.Sh HISTORY 384.Fn SSL_CTX_set_cipher_list 385and 386.Fn SSL_set_cipher_list 387first appeared in SSLeay 0.5.2 and have been available since 388.Ox 2.4 . 389.Sh CAVEATS 390In LibreSSL, 391.Fn SSL_CTX_set_cipher_list 392and 393.Fn SSL_set_cipher_list 394can be used to configure the list of available cipher suites for 395all versions of the TLS protocol, whereas in OpenSSL, they only 396control cipher suites for protocols up to TLSv1.2. 397If compatibility with OpenSSL is required, the list of 398available TLSv1.3 cipher suites can only be changed with 399.Fn SSL_set_ciphersuites . 400