SSL_CTX_set_ciphersuites

Use this function to set the Transport Layer Security (TLS) 1.3 cipher suites 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

Added in 2024.

Format

LIBS := CSSL 
#include <openssl/ssl.h>
int SSL_CTX_set_ciphersuites(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. The maximum length is 255 characters.

The z/TPF system supports the following TLS 1.3 ciphers. These ciphers use Elliptic Curve Ephemeral Diffie-Hellman (ECDHE) key exchange to enforce perfect forward secrecy.

TLS_AES_128_GCM_SHA256
AES128 (128-bit key) for data encryption; SHA256 for message integrity. The AES128 cipher algorithm operates in GCM mode for SSL data.
TLS_AES_256_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 indicates that the requested cipher suite list was not configured.

Programming considerations

  • To use this function, you must include the library that is specified in the prototype in your makefile.
  • Use SSL_CTX_set_cipher_list or SSL_set_cipher_list to set TLS 1.2 and earlier ciphers. TLS 1.2 and earlier ciphers cannot be set with this function and 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.3 cipher suites will be set.
  • If you are assigning many SSL sessions to the same CTX structure and each session will use the same cipher suites, issue this function once to assign the cipher suite list to the CTX structure rather than issuing the SSL_set_ciphersuites function once for each SSL session.
  • If you start a TLS 1.3 session without issuing this function or the SSL_set_ciphersuites function, the system default cipher suites list that is set in SSL_CTX_new can be overridden by subsequent calls to the SSL_CTX_set_ciphersuites or SSL_set_ciphersuites function.
    The following ciphers suites are the default ciphers suites for the z/TPF system:
    • TLS_AES_256_GCM_SHA384
    • TLS_AES_128_GCM_SHA256
  • The cipher algorithms and message digests are processed in the hardware when support is available; otherwise, they are processed in the software.
  • With TLS 1.3 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.