SSL_set_ciphersuites

Use this function to set the Transport Layer Security (TLS) 1.3 cipher suites for use by a specific Secure Sockets Layer (SSL) session that is started by using the specified SSL structure.

Last updated

Added in 2024.

Format

LIBS := CSSL 
#include <openssl/ssl.h>
int SSL_set_ciphersuites(SSL *ssl, const char *str)
ssl
A pointer to a token returned on the SSL_new 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 the SSL_CTX_set_ciphersuites 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_CTX_set_ciphersuites or SSL_set_ciphersuites function, the system default cipher suite list that is set in SSL_CTX_new can be overridden by subsequent calls to this function or the SSL_CTX_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.