Cipher suite configuration

Edit online

System TLS has infrastructure to support multiple cipher suites.

The cipher suites are specified in different ways for each programming interface. The following table shows the cipher suite specifications, which are shown here in the system value format, that can be supported by System TLS for each protocol version. The supported cipher suite specifications for each protocol are indicated by the "X" in the appropriate column.

Table 1. Supported cipher suite specifications for TLS protocols
QSSLCSL System Value Representation TLSv1.3 TLSv1.2 TLSv1.1 TLSv1.0 SSLv3
*AES_128_GCM_SHA256 X        
*AES_256_GCM_SHA384 X        
*CHACHA20_POLY1305_SHA256 X        
*ECDHE_ECDSA_AES_128_GCM_SHA256   X      
*ECDHE_ECDSA_AES_256_GCM_SHA384   X      
*ECDHE_RSA_AES_128_GCM_SHA256   X      
*ECDHE_RSA_AES_256_GCM_SHA384   X      
*ECDHE_ECDSA_CHACHA20_POLY1305_SHA256   X      
*ECDHE_RSA_CHACHA20_POLY1305_SHA256   X      
*RSA_AES_128_GCM_SHA256   X      
*RSA_AES_256_GCM_SHA384   X      
*ECDHE_ECDSA_AES_128_CBC_SHA256   X      
*ECDHE_ECDSA_AES_256_CBC_SHA384   X      
*ECDHE_RSA_AES_128_CBC_SHA256   X      
*ECDHE_RSA_AES_256_CBC_SHA384   X      
*RSA_AES_128_CBC_SHA256   X      
*RSA_AES_128_CBC_SHA   X X X  
*RSA_AES_256_CBC_SHA256   X      
*RSA_AES_256_CBC_SHA   X X X  
*ECDHE_ECDSA_3DES_EDE_CBC_SHA   X      
*ECDHE_RSA_3DES_EDE_CBC_SHA   X      
*RSA_3DES_EDE_CBC_SHA   X X X X
*ECDHE_ECDSA_RC4_128_SHA   X      
*ECDHE_RSA_RC4_128_SHA   X      
*RSA_RC4_128_SHA   X X X X
*RSA_RC4_128_MD5   X X X X
*RSA_DES_CBC_SHA     X X X
*RSA_EXPORT_RC4_40_MD5       X X
*RSA_EXPORT_RC2_CBC_40_MD5       X X
*ECDHE_ECDSA_NULL_SHA   X      
*ECDHE_RSA_NULL_SHA   X      
*RSA_NULL_SHA256   X      
*RSA_NULL_SHA   X X X X
*RSA_NULL_MD5   X X X X

Enabled cipher suites

The QSSLCSL system value setting identifies the specific cipher suites that are enabled on the system. Applications can negotiate secure sessions with only a cipher suite that is listed in QSSLCSL. No matter what an application does with code or configuration, it cannot negotiate secure sessions with a cipher suite if it is not listed in QSSLCSL. Individual application configuration determines which of the enabled cipher suites are used for that application.

To restrict the System TLS implementation from using a particular cipher suite, follow these steps:
  1. Change QSSLCSLCTL system value to special value *USRDFN to allow the QSSLCSL system value to be edited.
  2. Remove all cipher suites to be restricted from the list in QSSLCSL.

The QSSLCSLCTL system value special value *OPSYS allows the operating system to change the cipher suites that are enabled on the system. The value of QSSLCSLCTL remains the same when the system upgrades to a newer operating system release. If the value of QSSLCSLCTL is *USRDFN, then the administrator must manually add in newer cipher suites to QSSLCSL after the system moves to a new release. Setting QSSLCSLCTL back to *OPSYS also adds the new values to QSSLCSL.

A cipher suite cannot be added to QSSLCSL if the TLS protocol that is required by the cipher suite is not set in QSSLPCL.

The cipher suites that are enabled with QSSLCSLCTL *OPSYS in the latest PTF CUM package are displayed in the QSSLCSL system value. They are as follows:
  • *AES_128_GCM_SHA256
  • *AES_256_GCM_SHA384
  • *CHACHA20_POLY1305_SHA256
  • *ECDHE_ECDSA_AES_128_GCM_SHA256
  • *ECDHE_ECDSA_AES_256_GCM_SHA384
  • *ECDHE_RSA_AES_128_GCM_SHA256
  • *ECDHE_RSA_AES_256_GCM_SHA384
  • *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
  • *ECDHE_RSA_CHACHA20_POLY1305_SHA256
CAUTION:

IBM strongly recommends that you always run your IBM i server with the following cipher suites disabled. Using configuration options that are provided by IBM to enable the weak cipher suites results in your IBM i server being configured to allow use of the weak cipher suite list. This configuration results in your IBM i server potentially being at risk of a network security breach. IBM DISCLAIMS AND YOU ASSUME ALL RESPONSIBILITY AND LIABILITY FOR ANY DAMAGE OR LOSS, INCLUDING LOSS OF DATA, ARISING OUT OF OR RELATED TO YOUR USE OF THE SPECIFIED CIPHER SUITES.

Weak cipher suites (as of November 2021):
  • SSL_RSA_WITH_RC4_128_SHA
  • SSL_RSA_WITH_RC4_128_MD5
  • SSL_RSA_WITH_NULL_MD5
  • SSL_RSA_WITH_NULL_SHA
  • TLS_RSA_WITH_NULL_SHA256
  • SSL_RSA_WITH_DES_CBC_SHA
  • SSL_RSA_EXPORT_WITH_RC4_40_MD5
  • SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
  • TLS_ECDHE_ECDSA_WITH_NULL_SHA
  • TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
  • TLS_ECDHE_RSA_WITH_NULL_SHA
  • TLS_ECDHE_RSA_WITH_RC4_128_SHA
  • TLS_ECDHE_ECDSA_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_3DES_EDE_CBC_SHA
  • TLS_RSA_3DES_EDE_CBC_SHA
  • Start of changeTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256End of change
  • Start of changeTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384End of change
  • Start of changeTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256End of change
  • Start of changeTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384End of change
  • Start of changeTLS_RSA_WITH_AES_128_CBC_SHAEnd of change
  • Start of changeTLS_RSA_WITH_AES_128_CBC_SHA256End of change
  • Start of changeTLS_RSA_WITH_AES_256_CBC_SHAEnd of change
  • Start of changeTLS_RSA_WITH_AES_256_CBC_SHA256End of change

Default cipher suites

When an application does not specify the cipher suites to enable, the ordered System TLS default cipher suite list is used. Applications use this design to pick up future new TLS support without requiring application code changes. The default cipher suite setting has no meaning for applications that explicitly specify the cipher suites to enable for the application.

The default cipher suites on a system are the intersection of the enabled cipher suites from QSSLCSL and the eligible default cipher suites. The eligible default cipher suites list is configured by using the System Service Tools (SST) Advanced Analysis command TLSCONFIG. The order of the default cipher suite list is the order the cipher suites appear in the QSSLCSL system value. To change the order, change QSSLCSL.

To determine the current value of the eligible default cipher suite list and the default cipher suite list on the system, use TLSCONFIG option display. The Retrieve TLS Attributes (QsoRtvTLSA) API retrieves TLS attributes allowing the eligible default cipher suite list to be retrieved from a program.

An administrator should only consider changing the default cipher suite list settings when no other configuration setting allows an application to interoperate with peers successfully. It is preferred to enable an older cipher suite for only the specific application that requires it. When the application has an “application definition,” then this enablement is accomplished through the Digital Certificate Manager (DCM).

Warning: Adding an older cipher suite to the default list results in opening up all applications that use the default list to known security vulnerabilities. Loading a Group Security PTF might result in the removal of a cipher suite from the default cipher suite list. Subscribe to the Security Bulletin to receive notification when a security mitigation includes this type of change. If an administrator adds back an eligible cipher suite that was removed by a Security PTF, the system remembers this change and does not remove it a second time when the next Security PTF is applied.

If the default cipher suite list must be changed on the system, use TLSCONFIG option eligibleDefaultCipherSuites to change the value. TLSCONFIG Option h displays the help panel that describes how to specify the changed cipher suite list. The help text includes the short hand values that are required by the option. Only cipher suites that are listed in the help text can be added to the list.

Note: The TLSCONFIG eligibleDefaultCipherSuites setting is reset by installing the Licensed Internal Code (LIC).
Example of setting only ECDHE cipher suites as the default on the system: 
TLSCONFIG -eligibleDefaultCipherSuites:YF,YG,YH,YE,YD,YC,YB,YA,Y9,Y8,Y7
The cipher suites included in the shipped eligible default cipher suite list with the latest PTF CUM package installed are as follows:
  • *AES_128_GCM_SHA256
  • *AES_256_GCM_SHA384
  • *CHACHA20_POLY1305_SHA256
  • *ECDHE_ECDSA_AES_128_GCM_SHA256
  • *ECDHE_ECDSA_AES_256_GCM_SHA384
  • *ECDHE_RSA_AES_128_GCM_SHA256
  • *ECDHE_RSA_AES_256_GCM_SHA384
  • *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
  • *ECDHE_RSA_CHACHA20_POLY1305_SHA256