SSL_CTX_SET_CIPHER_LIST(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

🎀 SSL_CTX_SET_CIPHER_LIST (3ossl) 🎀

okay bestie, so this is one of those OpenSSL pages — you know, the OpenSSL manual family 💅 — and it's literally all about picking which ciphers are allowed. cipher shopping, if you will. let's get into it 🛍️✨

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
int SSL_set_cipher_list(SSL *ssl, const char *str);

int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str);
int SSL_set_ciphersuites(SSL *s, const char *str);

const char *OSSL_default_cipher_list(void);
const char *OSSL_default_ciphersuites(void);

that's the whole squad 🫶 six functions, one mission.

💖 DESCRIPTION 💖

the TLSv1.2-and-below girlies

  • SSL_CTX_set_cipher_list() — sets the list of available ciphers (TLSv1.2 and below 🕰️) for ctx, using the control string str. the format of that string is described over in openssl-ciphers(1) — go read it, it's giving lore. the cipher list is inherited by every single ssl object created from ctx, so you set it once and all the babies get it. important though: this function does not touch TLSv1.3 ciphersuites — use SSL_CTX_set_ciphersuites() for those bestie. and ctx MUST NOT be NULL, no cap, that's a hard rule. 💀
  • SSL_set_cipher_list() — same energy, but sets the list of ciphers (TLSv1.2 and below) for ssl only. no inheritance, just that one object. lowkey the introvert of the group 🙈

the TLSv1.3 ciphersuite girlies ✨

SSL_CTX_set_ciphersuites() is how you configure the available TLSv1.3 ciphersuites for ctx. it's a simple colon (":") separated list of TLSv1.3 ciphersuite names, listed in order of preference — first one is your main character 👑.

valid TLSv1.3 ciphersuite names are:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_CCM_SHA256
  • TLS_AES_128_CCM_8_SHA256
  • TLS_SHA384_SHA384 — integrity-only 🫶
  • TLS_SHA256_SHA256 — integrity-only 🫶

an empty list is permissible (yes, for real, that's allowed 🫠). the default value for this setting is:

"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

SSL_set_ciphersuites() is literally the same as SSL_CTX_set_ciphersuites() except it configures the ciphersuites for ssl instead of ctx. twins 💅

the default-havers 🌈

  • OSSL_default_cipher_list() — returns the default cipher string for TLSv1.2 (and earlier) ciphers.
  • OSSL_default_ciphersuites() — returns the default cipher string for TLSv1.3 ciphersuites.

🦋 NOTES 🦋

okay so the control string str for SSL_CTX_set_cipher_list(), SSL_set_cipher_list(), SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() should be universally usable and should not depend on details of the library configuration (like which ciphers are compiled in). because of that, no syntax checking takes place 👀 — items that aren't recognized, whether because the corresponding ciphers aren't compiled in or because they're just mistyped, are simply ignored. failure is only flagged if no ciphers could be collected at all. so like... typos just get ghosted, not yelled at 🫥

also important, bestie: including a cipher in the list is a necessary condition for it being used. on the client side, inclusion is also sufficient — unless the security level excludes it. on the server side though, additional restrictions apply. 😤

all ciphers have additional requirements, fr fr:

  • ADH ciphers don't need a certificate — but DH-parameters must have been set.
  • all other ciphers need a corresponding certificate and key. 🔑

more detail, because we don't skip:

  • an RSA cipher can only be chosen when an RSA certificate is available. RSA ciphers using DHE need a certificate and key and additional DH-parameters (see SSL_CTX_set_tmp_dh_callback(3)).
  • a DSA cipher can only be chosen when a DSA certificate is available. DSA ciphers always use DH key exchange and therefore need DH-parameters (see SSL_CTX_set_tmp_dh_callback(3)).

when these conditions aren't met for any cipher in the list — for example a client only supports export RSA ciphers with an asymmetric key length of 512 bits and the server is not configured to use temporary RSA keys — then the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated and the handshake will fail. 💀😭 literally the worst-case scenario, do not let this be you.

also: OSSL_default_cipher_list() and OSSL_default_ciphersuites() replace SSL_DEFAULT_CIPHER_LIST and TLS_DEFAULT_CIPHERSUITES, respectively. the cipher list defines are deprecated as of 3.0 ⚠️ so like, retire them, they've served their time 🕊️

🌸 RETURN VALUES 🌸

  • SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher could be selected, and 0 on complete failure. 🎉 / 💀
  • SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() return 1 if the requested ciphersuite list was configured, and 0 otherwise.

🎀 SEE ALSO 🎀

ssl(7), SSL_get_ciphers(3), SSL_CTX_use_certificate(3), SSL_CTX_set_tmp_dh_callback(3), openssl-ciphers(1)

go read them, they're all linked in the group chat 💬

💜 HISTORY 💜

OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0. ✨ (yes, that spelling is exactly how it's written here, i don't make the rules 🙈)

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole thing bestie, you ate that 🫶💅 version 3.5.0, dated 2026-09-25, from the SSL_CTX_SET_CIPHER_LIST(3ossl) era — mwah, go configure some ciphers, icon 🧚‍♀️⭐

📦 where this page comes from