SSL_CTX_set_cipher_list

The SSL_CTX_set_cipher_list function sets the Transport Layer Security (TLS) 1.2 and earlier ciphers for use by Secure Sockets Layer (SSL) sessions that are started by using the specified context (CTX) structure. A CTX structure is needed for each application that is running SSL. Each SSL session has an SSL structure that points to a CTX structure.

Last updated

  • Changed in 2024.
  • Changed in 2022.
  • Changed in 2021.
  • Changed in 2020.
  • Changed in 2019.
  • Changed for PUT13.
  • Changed for PUT03.
  • Changed for PUT00.

Format

LIBS := CSSL 
#include <openssl/ssl.h>
int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str)
ctx
A pointer to a token returned on the SSL_CTX_new call or the SSL_CTX_new_shared call.
str
A pointer to a string that contains one or more ciphers that are separated by a colon, comma, or blank. The maximum length is 255 characters.
The z/TPF system supports the following TLS ciphers that can be used for TLS 1.0, 1.1, or 1.2. These ciphers use Rivest-Shamir-Adelman (RSA) key exchange and RSA authentication:
NULL-MD5
No data encryption; MD5 for message integrity.
NULL-SHA
No data encryption; SHA-1 for message integrity.
DES-CBC3-SHA
Triple-DES (168-bit key) for data encryption; SHA-1 for message integrity.
AES128-SHA
AES128 (128-bit key) for data encryption; SHA-1 for message integrity. The AES128 cipher algorithm operates in cipher block chaining mode for SSL data.
AES256-SHA
AES256 (256-bit key) for data encryption; SHA-1 for message integrity. The AES256 cipher algorithm operates in cipher block chaining mode for SSL data.
The z/TPF system supports the following TLS 1.2 ciphers that use RSA key exchange and RSA authentication:
NULL-SHA256

No data encryption; SHA256 for message integrity.

AES128-SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in cipher block chaining mode for SSL data.
AES256-SHA256
AES256 (256-bit key) for data encryption; SHA256 for message integrity. The AES256 cipher algorithm operates in cipher block chaining mode for SSL data.
AES128-GCM-SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in Galois Counter Mode (GCM) for SSL data.
AES256-GCM-SHA384
AES256 (256-bit key) for data encryption; SHA384 for message integrity. The AES256 cipher algorithm operates in GCM for SSL data.
The z/TPF system supports the following TLS 1.2 ciphers that use the Ephemeral Diffie-Hellman (DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE) key exchange and RSA authentication:
DHE-RSA-AES128-GCM-SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in GCM for SSL data. The DHE key creation and cryptographic operations for session startup are performed in software.
DHE-RSA-AES256-GCM-SHA384
AES256 (256-bit key) for data encryption; SHA384 for message integrity. The AES256 cipher algorithm operates in GCM for SSL data. The DHE key creation and cryptographic operations for session startup are performed in software.
ECDHE-RSA-NULL-SHA
No data encryption; SHA for message integrity.
ECDHE-RSA-AES128-SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in cipher block chaining mode for SSL data.
ECDHE-RSA-AES256-SHA384
AES256 (256-bit key) for data encryption; SHA384 for message integrity. The AES256 cipher algorithm operates in cipher block chaining mode for SSL data.
ECDHE-RSA-AES128-GCM-SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in GCM mode for SSL data.
ECDHE-RSA-AES256-GCM-SHA384
AES256 (256-bit key) for data encryption; SHA384 for message integrity. The AES256 cipher algorithm operates in GCM mode for SSL data.

Normal return

A value of 1.

Error return

A value of 0.

Programming considerations

  • To use this function, you must include the library that is specified in the prototype in your makefile.
  • Use the SSL_CTX_set_ciphersuites or SSL_set_ciphersuites function to set TLS 1.3 cipher suites. TLS 1.3 cipher suites cannot be set with this function because they are ignored.
  • A string can be passed as the str parameter that consists of TLS 1.2 and 1.3 ciphers to this function, but only TLS 1.2 ciphers will be set.
  • When an SSL structure is first created by using the SSL_new function, the structure inherits the cipher list that is assigned to the context (CTX) structure that was used to create the SSL structure. The SSL_set_cipher_list function overrides that cipher list for a specific SSL structure.
  • If you are assigning many SSL sessions to the same CTX structure and each session will use the same cipher list, issue the SSL_CTX_set_cipher_list function once to assign the cipher list to the CTX structure rather than issuing the SSL_set_cipher_list function once for each SSL session.
  • If you start a TLS 1.2 or earlier session without issuing the SSL_CTX_set_cipher_list or the SSL_set_cipher_list function, the system default cipher list is used.
    The following ciphers are the default ciphers for the z/TPF system:
    • AES256-SHA256
    • AES128-SHA256
    • AES256-SHA
    • AES128-SHA
    • DES-CBC3-SHA
  • Use the following ciphers only for testing and debugging; do not use these ciphers to secure sensitive data:
    • NULL-MD5
    • NULL-SHA
    • NULL-SHA256
    • ECDHE-RSA-NULL-SHA
  • The cipher algorithms and message digests are processed in the hardware when support is available; otherwise, they are processed in the software.
  • When you use the ECDHE_* ciphers, the OpenSSL default Elliptic Curve Cryptography (ECC) curve list is used. If you want to modify the default curve list with a user-defined ECC curve list, enter the ZSSLD command with the DEFCURVE and DEFINE parameters specified.

Examples

For sample SSL applications, see SSL examples.