SSL_CTX_set_cipher_list

The SSL_CTX_set_cipher_list function sets the Start of changeTransport Layer Security (TLS) 1.2 and earlier End of changeciphers 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

  • Start of changeChanged in 2024.End of change
  • 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.
Start of changeThe z/TPF system supports the following TLS ciphers that can be used for TLS 1.0, 1.1, or 1.2.End of change 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.
  • Start of changeUse 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.End of change
  • Start of changeA 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.End of change
  • 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.
  • Start of changeIf 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.End of change
    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.