Configuring Your IBM i System Secure Sockets Layer (SSL)/Transport Layer Security (TLS) Protocols and Cipher Suites

Please refer to the IBM i 7.2 System SSL Properties Information Center document for more information on the IBM i 7.2 System SSL/TLS protocols, Shipped SSL/TLS Supported protocols, Shipped SSL/TLS Default protocols, SSL/TLS cipher suites, Shipped SSL/TLS Supported cipher specification list, and Shipped SSL/TLS Default cipher specification list.

NOTE: The process of changing the eligible and default IBM i System SSL/TLS protocols and cipher suites has changed with the following PTFs.

IBM i 7.2 = 5770SS1-SI57320 & 5770999-MF60432

If you do not have the above PTFs applied to your IBM i OS, please skip step 4 since it does not yet apply to your system.

NOTE: When the following PTFs are applied, applications coded to use the System SSL/TLS default values will no longer negotiate the use of Triple DES (3DES) cipher suites with peers. For more information, please refer to the following IBM Technical Document.

Security Bulletin: IBM i is affected by several vulnerabilities (CVE-2016-2183 and CVE-2016-6329)

IBM i 7.2 = 5770SS1-SI62464, 5733SC1-SI62622 & 5770999-MF62778


Process to change your SSL/TLS protocols and cipher suites at IBM i 7.2.0.

When configuring your IBM i System SSL/TLS protocols and cipher suites, it is not always required to change your existing configuration. In some cases, only your SSL/TLS protocol configuration needs to be changed. In reverse, some cases will only require you to change your SSL/TLS cipher suite configuration. IBM recommends you carefully consider your SSL/TLS protocol and cipher suite requirements before making any changes.

• 1) If needed, update your QSSLPCL IBM i System Value to set up your System SSL/TLS supported protocols.
  
  
  • i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
    ii) Enter option 5 next to QSSLPCL and press ENTER.
    iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLPCL and press ENTER. Otherwise, continue on to step 2.
    iv) Specify the SSL/TLS Protocol Value(s) to modify your IBM i System SSL/TLS Protocol list and then press ENTER.
    • - *OPSYS =*TLSV1.2, *TLSV1.1, *TLSV1. This value cannot be combined with any other value. Please refer to the IBM i 7.2 System SSL Properties Information Center document for more information.
      -*TLSV1.2 = Transport Layer Security v1.2
      -*TLSV1.1 = Transport Layer Security v1.1
      - *TLSV1 = Transport Layer Security v1.0
      
      i.e.
      CHGSYSVAL SYSVAL(QSSLPCL) VALUE(*OPSYS) - This will set the System SSL/TLS Supported Protocol List to *TLSV1.2, *TLSV1.1 and *TLSV1.
      
      CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1.2') - This will set the System SSL/TLS Supported Protocol List to only support the TLSv1.2 protocol.
  
  2) If needed, update your QSSLCSLCTL and QSSLCSL IBM i System Values to set up your System SSL/TLS supported cipher suites.
  
  
  • i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
    ii) Enter option 5 next to QSSLCSLCTL and press ENTER.
    iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLCSLCTL and press ENTER. Otherwise, continue on to step 3.
    iv) Specify either *OPSYS or *USRDFN to define how you want your System SSL/TLS cipher suites supported list managed on the server and then press ENTER.
    
    
    • - *OPSYS = Operating System determines the supported cipher suites. Please refer to the IBM i 7.2 System SSL Properties Information Center document for more information.
      - *USRDFN = The user will define the cipher suite list via the QSSLCSL system value.
    
    v) Enter option 2 next to QSSLCSL to modify the System SSL/TLS cipher suite list and then press ENTER. This step (as well as step vi) are only allowed if QSSLCSLCTL is set to *USRDFN.
    vi) Specify the SSL/TLS cipher suites you want System SSL/TLS to support in the order of how you want them prioritized. The list of supported SSL/TLS cipher suites that can be specified here can be found here, IBM i 7.2 System SSL Properties Information Center under "SSL cipher suites". Press ENTER once you are done to confirm your changes.
  
  3) If needed, update your Digital Certificate Manager (DCM) applications to support the required SSL/TLS protocols and cipher suites.
  
  NOTE: IBM HTTP Server applications listed in DCM cannot be edited. Please refer to the mod_ssl HTTP directives if you want to customize your IBM HTTP Server's SSL/TLS configuration.
  • i) Open a web browser to the URL where <server> is your IBM i server's IP address or TCP/IP host name.
    http://<server>:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0
    ii) Sign in when prompted with an IBM i user profile with *ALLOBJ and *IOSYSCFG special authorities.
    iii) Click the "Select a Certificate Store" button on the left, vertical menu bar.
    iv) Select the "*SYSTEM" store and press the "Continue" button.
    NOTE: If you do not see the *SYSTEM store, please refer to the following URL: http://www-01.ibm.com/support/docview.wss?uid=nas8N1010320
    v) Enter the *SYSTEM certificate store password and press the "Continue" button. You can click the "Reset Password" button to reset your password if you cannot remember it.
    vi) Expand the "Fast Path" section in the left, vertical menu bar.
    vii) Click the "Work with server applications" OR "Work with client applications" link depending on whether you want to manage your server or client applications.
    viii) Select the application from the list and click the "Work with Application" button at the bottom of the list of applications.
    ix) To customize the SSL/TLS protocol configuration for the specific application, change the "SSL protocols" section from *PGM to "Define protocols supported" and then checkmark the specific SSL Protocols you would like the application to support.
    x) To customize the SSL/TLS cipher suite configuration for the specific application, change the "SSL cipher specification option" section from *PGM to "Define cipher specification list" and then set up the order of the cipher suites under the "Order" column. To disable a cipher suite, change the value to "Disable" under the "Order" column next to the cipher suite you want to disable.
    xi) Click the "Apply" button to implement the changes to the application.
    
    
    • NOTE: The changes to the application definition will not be implemented until the application type is restarted.
    
    xii) Repeat steps vii) through x) to modify additional application definitions.
  
  4) If needed, update your Eligible Default protocols or Eligible Default cipher suites using the SSLCONFIG System Service Tools (SST) Advanced Analysis Command.
  
  NOTE: The eligible default protocols and cipher suites are only used by applications when specific protocols and cipher suites are NOT specified by the application. The default protocols and cipher suites on a system are the intersection of the enabled protocols and cipher suites from QSSLPCL, QSSLCSLCTL, QSSLCSL and the eligible default protocols and cipher suites. The eligible default protocol and cipher suite list are configured using SSLCONFIG. SSLCONFIG is a System Service Tools (SST) Advanced Analysis Command.
  
  To determine the current value of the eligible default protocol and cipher suite list as well as the default protocol and cipher suite list on the system, use SSLCONFIG option “–display”.
  
  
  • i) On the command line, type STRSST.
    ii) Type your service tools user name and password.
    iii) Select option 1 (Start a service tool).
    iv) Select option 4 (Display/Alter/Dump).
    v) Select option 1 (Display/Alter storage).
    vi) Select option 2 (Licensed Internal Code (LIC) data).
    vii) Select option 14 (Advanced analysis).
    viii) Select option 1 (SSLCONFIG).
    ix) Enter -h and press ENTER to review the "-display", "-eligibleDefaultProtocols", and "-eligibleDefaultCipherSuites" SSLCONFIG options and their values.
    • -display                                      
              Display current configuration settings.
      
      -eligibleDefaultProtocols:<ProtocolNumber>[,<ProtocolNumber>...]    
              Set the System SSL eligible default protocol list.          
              This option takes a comma-separated list of numbers        
              to determine the System SSL eligible default protocol list.
              This list is used along with QSSLPCL to generate the default
              protocol list used by System SSL.      
                         
              ProtocolNumber             ProtocolName                    
              -----------------          ---------------
                      02                 SSLv3
                      04                 TLSv1.0                          
                      08                 TLSv1.1                          
                      10                 TLSv1.2
      
      -eligibleDefaultCipherSuites:<cipherSuiteNumber>[,<cipherSuiteNumber>...]
              Set the System SSL eligible default cipher suite list.
              This option takes a comma-separated list of numbers
              to determine the eligible default cipher suites.  This list
              is used along with QSSLCSL to generate the default cipher
              suite list used by System SSL.
      
              CipherSuiteNumber          CipherSuiteName
              -----------------          ---------------
                      05                 RSA_RC4_128_SHA
                      0A                 RSA_3DES_EDE_CBC_SHA
                      2F                 RSA_AES_128_CBC_SHA
                      35                 RSA_AES_256_CBC_SHA
                      3C                 RSA_AES_128_CBC_SHA256        
                      3D                 RSA_AES_256_CBC_SHA256        
                      9C                 RSA_AES_128_GCM_SHA256        
                      9D                 RSA_AES_256_GCM_SHA384        
                      Y2                 ECDHE_ECDSA_RC4_128_SHA      
                      Y3                 ECDHE_ECDSA_3DES_EDE_CBC_SHA  
                      Y5                 ECDHE_RSA_RC4_128_SHA        
                      Y6                 ECDHE_RSA_3DES_EDE_CBC_SHA    
                      Y7                 ECDHE_ECDSA_AES_128_CBC_SHA256
                      Y8                 ECDHE_ECDSA_AES_256_CBC_SHA384
                      Y9                 ECDHE_RSA_AES_128_CBC_SHA256  
                      YA                 ECDHE_RSA_AES_256_CBC_SHA384  
                      YB                 ECDHE_ECDSA_AES_128_GCM_SHA256
                      YC                 ECDHE_ECDSA_AES_256_GCM_SHA384
                      YD                 ECDHE_RSA_AES_128_GCM_SHA256
                      YE                 ECDHE_RSA_AES_256_GCM_SHA384
    
    x) If needed, execute the "-eligibleDefaultProtocols" option against the SSLCONFIG Advanced Analysis Command to set up the eligible default SSL/TLS protocols. These protocols are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a protocol to use.
    • i.e.
       -eligibleDefaultProtocols:04,08,10
      
      Executing the above option will enable the TLSv1.0, TLSv1.1, and TLSv1.2 protocols to be used.
    
    xi) If needed, execute the "-eligibleDefaultCipherSuites" option against the SSLCONFIG Advanced Analysis Command to set up the eligible default SSL/TLS cipher suites. These cipher suites are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a cipher suite to use.
    
    
    • -eligibleDefaultCipherSuites:2F,35,3C,3D,9C,9D,Y7,Y8,Y9,YA,YB,YC,YD,YE
      
      Executing the above option will set the
      RSA_AES_128_CBC_SHA
      RSA_AES_256_CBC_SHA
      RSA_AES_128_CBC_SHA256
      RSA_AES_256_CBC_SHA256
      RSA_AES_128_GCM_SHA256
      RSA_AES_256_GCM_SHA384
      ECDHE_ECDSA_AES_128_CBC_SHA256
      ECDHE_ECDSA_AES_256_CBC_SHA384
      ECDHE_RSA_AES_128_CBC_SHA256
      ECDHE_RSA_AES_256_CBC_SHA384
      ECDHE_ECDSA_AES_128_GCM_SHA256
      ECDHE_ECDSA_AES_256_GCM_SHA384
      ECDHE_RSA_AES_128_GCM_SHA256
      ECDHE_RSA_AES_256_GCM_SHA384
      cipher suites to be used as the default.
    
    xii) Execute the "-display" option to confirm the correct changes were made.
    xiii) Press F3 several times and then press ENTER to exit the System Service Tools (SST).
    xiv) You have now successfully changed the supported and default System SSL/TLS protocols and cipher suites definition for your IBM i server.

Please refer to the IBM i 7.3 System SSL/TLS System Level Settings Documentation document for more information on the IBM i 7.3 System SSL/TLS protocols, Shipped SSL/TLS Supported protocols, Shipped SSL/TLS Default protocols, SSL/TLS cipher suites, Shipped SSL/TLS Supported cipher specification list, and Shipped SSL/TLS Default cipher specification list.

Please refer to the IBM i 7.3 SSL/TLS Security Reference PDF for the complete SSL/TLS reference guide for IBM i 7.3 OS.

NOTE:  TLSv1.3 has been added to IBM i 7.3 with Technology Refresh 8 (which means TR8 is required) as well as the following PTF Group levels and individual PTFs:

The enhancements can be obtained by applying the following:

• SF99867: 730 TCP/IP PTF Group Level: 5
• SF99722: 730 IBM HTTP Server for i PTF Group Level: 24
  For GUI System Value QSSLPCL and QSSLCSL support, not for HTTP Server use of TLS 1.3

• SF99725: 730 Java PTF Group Level: 18
  Plus these 4 Java PTFs:
  SI72654 and SI72653 - JVA-RUN JDK 80-64 Native JSSE TLSv1.3
  SI72652 and SI72651 - JVA-RUN JDK 70-64 Native JSSE TLSv1.2 ChaCha20Poly1305

NOTE: When the following PTFs are applied, applications coded to use the System SSL/TLS default values will no longer negotiate the use of Triple DES (3DES) cipher suites with peers. For more information, please refer to the following IBM Technical Document.

Security Bulletin: IBM i is affected by several vulnerabilities (CVE-2016-2183 and CVE-2016-6329)

IBM i 7.3 = 5770SS1-SI62586, 5733SC1-SI62622 & 5770999-MF62780


Process to change your SSL/TLS protocols and cipher suites at IBM i 7.3.0.

When configuring your IBM i System SSL/TLS protocols and cipher suites, it is not always required to change your existing configuration. In some cases, only your SSL/TLS protocol configuration needs to be changed. In reverse, some cases will only require you to change your SSL/TLS cipher suite configuration. IBM recommends you carefully consider your SSL/TLS protocol and cipher suite requirements before making any changes.

1) If needed, update your QSSLPCL IBM i System Value to set up your System SSL/TLS supported protocols.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLPCL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLPCL and press ENTER. Otherwise, continue on to step 2.
iv) Specify the SSL/TLS Protocol Value(s) to modify your IBM i System SSL/TLS Protocol list and then press ENTER.

- *OPSYS =*TLSV1.3,*TLSV1.2, *TLSV1.1, *TLSV1. This value cannot be combined with any other value. Please refer to the IBM i 7.3 System SSL/TLS System Level Settings Documentation document for more information.
-*TLSV1.3 = Transport Layer Security v1.3
-*TLSV1.2 = Transport Layer Security v1.2
-*TLSV1.1 = Transport Layer Security v1.1
- *TLSV1 = Transport Layer Security v1.0

i.e.
CHGSYSVAL SYSVAL(QSSLPCL) VALUE(*OPSYS) - This will set the System SSL/TLS Supported Protocol List to *TLSV1.2, *TLSV1.1 and *TLSV1.

CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1.3 *TLSV1.2') - This will set the System SSL/TLS Supported Protocol List to only support the TLSv 1.3 and TLSv1.2 protocols.

2) If needed, update your QSSLCSLCTL and QSSLCSL IBM i System Values to set up your System SSL/TLS supported cipher suites.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLCSLCTL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLCSLCTL and press ENTER. Otherwise, continue on to step 3.
iv) Specify either *OPSYS or *USRDFN to define how you want your System SSL/TLS cipher suites supported list managed on the server and then press ENTER.

- *OPSYS = Operating System determines the supported cipher suites. Please refer to the IBM i 7.3 System SSL/TLS System Level Settings Documentation document for more information.
- *USRDFN = The user will define the cipher suite list via the QSSLCSL system value.

v) Enter option 2 next to QSSLCSL to modify the System SSL/TLS cipher suite list and then press ENTER. This step (as well as step vi) are only allowed if QSSLCSLCTL is set to *USRDFN.
vi) Specify the SSL/TLS cipher suites you want System SSL/TLS to support in the order of how you want them prioritized. The list of supported SSL/TLS cipher suites that can be specified here can be found here, IBM i 7.3 System SSL/TLS System Level Settings Documentation under "cipher suite configuration". Press ENTER once you are done to confirm your changes.

3) If needed, update your Digital Certificate Manager (DCM) applications to support the required SSL/TLS protocols and cipher suites.

NOTE: IBM HTTP Server applications listed in DCM cannot be edited. Please refer to the mod_ssl HTTP directives if you want to customize your IBM HTTP Server's SSL/TLS configuration.

i) Open a web browser to the URL where <server> is your IBM i server's IP address or TCP/IP host name.
http://<server>:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0
ii) Sign in when prompted with an IBM i user profile with *ALLOBJ and *IOSYSCFG special authorities.
iii) Click the "Select a Certificate Store" button on the left, vertical menu bar.
iv) Select the "*SYSTEM" store and press the "Continue" button.
NOTE: If you do not see the *SYSTEM store, please refer to the following URL: http://www-01.ibm.com/support/docview.wss?uid=nas8N1010320
v) Enter the *SYSTEM certificate store password and press the "Continue" button. You can click the "Reset Password" button to reset your password if you cannot remember it.
vi) Expand the "Fast Path" section in the left, vertical menu bar.
vii) Click the "Work with server applications" OR "Work with client applications" link depending on whether you want to manage your server or client applications.
viii) Select the application from the list and click the "Work with Application" button at the bottom of the list of applications.
ix) To customize the SSL/TLS protocol configuration for the specific application, change the "SSL protocols" section from *PGM to "Define protocols supported" and then checkmark the specific SSL Protocols you would like the application to support.
x) To customize the SSL/TLS cipher suite configuration for the specific application, change the "SSL cipher specification option" section from *PGM to "Define cipher specification list" and then set up the order of the cipher suites under the "Order" column. To disable a cipher suite, change the value to "Disable" under the "Order" column next to the cipher suite you want to disable.
xi) Click the "Apply" button to implement the changes to the application.

NOTE: The changes to the application definition will not be implemented until the application type is restarted.

xii) Repeat steps vii) through x) to modify additional application definitions.

4) If needed, update your Eligible Default protocols or Eligible Default cipher suites using the SSLCONFIG System Service Tools (SST) Advanced Analysis Command.

NOTE: The eligible default protocols and cipher suites are only used by applications when specific protocols and cipher suites are NOT specified by the application. The default protocols and cipher suites on a system are the intersection of the enabled protocols and cipher suites from QSSLPCL, QSSLCSLCTL, QSSLCSL and the eligible default protocols and cipher suites. The eligible default protocol and cipher suite list are configured using SSLCONFIG. SSLCONFIG is a System Service Tools (SST) Advanced Analysis Command.

To determine the current value of the eligible default protocol and cipher suite list as well as the default protocol and cipher suite list on the system, use SSLCONFIG option “–display”.

i) On the command line, type STRSST.
ii) Type your service tools user name and password.
iii) Select option 1 (Start a service tool).
iv) Select option 4 (Display/Alter/Dump).
v) Select option 1 (Display/Alter storage).
vi) Select option 2 (Licensed Internal Code (LIC) data).
vii) Select option 14 (Advanced analysis).
viii) Select option 1 (SSLCONFIG).
ix) Enter -h and press ENTER to review the "-display", "-eligibleDefaultProtocols", and "-eligibleDefaultCipherSuites" SSLCONFIG options and their values.

-display                                      
        Display current configuration settings.

-eligibleDefaultProtocols:<ProtocolNumber>[,<ProtocolNumber>...]    
        Set the System SSL eligible default protocol list.          
        This option takes a comma-separated list of numbers        
        to determine the System SSL eligible default protocol list.
        This list is used along with QSSLPCL to generate the default
        protocol list used by System SSL.      
                   
        ProtocolNumber             ProtocolName                    
        -----------------          ---------------
                02                 SSLv3
                04                 TLSv1.0                          
                08                 TLSv1.1                          
                10                 TLSv1.2
                20                 TLSv1.3

-eligibleDefaultCipherSuites:<cipherSuiteNumber>[,<cipherSuiteNumber>...]
        Set the System SSL eligible default cipher suite list.
        This option takes a comma-separated list of numbers
        to determine the eligible default cipher suites.  This list
        is used along with QSSLCSL to generate the default cipher
        suite list used by System SSL.

        CipherSuiteNumber          CipherSuiteName
        -----------------          ---------------
                05                 RSA_RC4_128_SHA
                0A                 RSA_3DES_EDE_CBC_SHA
                2F                 RSA_AES_128_CBC_SHA
                35                 RSA_AES_256_CBC_SHA
                3C                 RSA_AES_128_CBC_SHA256        
                3D                 RSA_AES_256_CBC_SHA256        
                9C                 RSA_AES_128_GCM_SHA256        
                9D                 RSA_AES_256_GCM_SHA384        
                Y2                 ECDHE_ECDSA_RC4_128_SHA      
                Y3                 ECDHE_ECDSA_3DES_EDE_CBC_SHA  
                Y5                 ECDHE_RSA_RC4_128_SHA        
                Y6                 ECDHE_RSA_3DES_EDE_CBC_SHA    
                Y7                 ECDHE_ECDSA_AES_128_CBC_SHA256
                Y8                 ECDHE_ECDSA_AES_256_CBC_SHA384
                Y9                 ECDHE_RSA_AES_128_CBC_SHA256  
                YA                 ECDHE_RSA_AES_256_CBC_SHA384  
                YB                 ECDHE_ECDSA_AES_128_GCM_SHA256
                YC                 ECDHE_ECDSA_AES_256_GCM_SHA384
                YD                 ECDHE_RSA_AES_128_GCM_SHA256
                YE                 ECDHE_RSA_AES_256_GCM_SHA384
                YF                 AES_128_GCM_SHA256
                YG                 AES_256_GCM_SHA384
                YH                 CHACHA20_POLY1305_SHA256
                YI                 ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
                YJ                 ECDHE_RSA_CHACHA20_POLY1305_SHA256

x) If needed, execute the "-eligibleDefaultProtocols" option against the SSLCONFIG Advanced Analysis Command to set up the eligible default SSL/TLS protocols. These protocols are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a protocol to use.

i.e.
 -eligibleDefaultProtocols:04,08,10,20

Executing the above option will enable the TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3 protocols to be used.

xi) If needed, execute the "-eligibleDefaultCipherSuites" option against the SSLCONFIG Advanced Analysis Command to set up the eligible default SSL/TLS cipher suites. These cipher suites are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a cipher suite to use.

-eligibleDefaultCipherSuites:9C,9D,Y7,Y8,Y9,YA,YB,YC,YD,YE,YF,YG,YH,YI,YJ

Executing the above option will set the
RSA_AES_128_GCM_SHA256
RSA_AES_256_GCM_SHA384
ECDHE_ECDSA_AES_128_CBC_SHA256
ECDHE_ECDSA_AES_256_CBC_SHA384
ECDHE_RSA_AES_128_CBC_SHA256
ECDHE_RSA_AES_256_CBC_SHA384
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
CHACHA20_POLY1305_SHA256
AES_256_GCM_SHA384
AES_128_GCM_SHA256
cipher suites to be used as the default.

xii) Execute the "-display" option to confirm the correct changes were made.
xiii) Press F3 several times and then press ENTER to exit the System Service Tools (SST).
xiv) You have now successfully changed the supported and default System SSL/TLS protocols and cipher suites definition for your IBM i server.

Please refer to the IBM i 7.4 System TLS System Level Settings Documentation document for more information on the IBM i 7.4 System TLS protocols, Shipped TLS Supported protocols, Shipped TLS Default protocols, TLS cipher suites, Shipped TLS Supported cipher specification list, and Shipped TLS Default cipher specification list.

NOTE:  Apply SI71547, SI71373, SI71363, SI71361 and MF66742 and all requisites to add support for the *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256 & *ECDHE_RSA_CHACHA20_POLY1305_SHA256 cipher suites.  Some requisite PTFs are delayed apply.  Refer to the IBM i System TLS Enhancements to the TLSv1.3 and TLSv1.2 Protocols document for more information.

Please refer to the IBM i 7.4 TLS Security Reference PDF for the complete TLS reference guide for IBM i 7.4 OS.


Process to change your TLS protocols and cipher suites at IBM i 7.4.

When configuring your IBM i System TLS protocols and cipher suites, it is not always required to change your existing configuration. In some cases, only your TLS protocol configuration needs to be changed. In reverse, some cases will only require you to change your TLS cipher suite configuration. IBM recommends you carefully consider your TLS protocol and cipher suite requirements before making any changes.

1) If needed, update your QSSLPCL IBM i System Value to set up your System TLS supported protocols.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLPCL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLPCL and press ENTER. Otherwise, continue on to step 2.
iv) Specify the TLS Protocol Value(s) to modify your IBM i System TLS Protocol list and then press ENTER.

- *OPSYS =*TLSV1.3, *TLSV1.2. This value cannot be combined with any other value. Please refer to the IBM i 7.4 System TLS System Level Settings Documentation document for more information.
-*TLSV1.3 = Transport Layer Security v1.3
-*TLSV1.2 = Transport Layer Security v1.2
-*TLSV1.1 = Transport Layer Security v1.1
-*TLSV1 = Transport Layer Security v1.0

i.e.
CHGSYSVAL SYSVAL(QSSLPCL) VALUE(*OPSYS) - This will set the System TLS Supported Protocol List to *TLSV1.3 and *TLSV1.2.

CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1.3 *TLSV1.2') - This will set the System TLS Supported Protocol List to only support the TLSv1.3 and TLSv1.2 protocols.

2) If needed, update your QSSLCSLCTL and QSSLCSL IBM i System Values to set up your System TLS supported cipher suites.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLCSLCTL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLCSLCTL and press ENTER. Otherwise, continue on to step 3.
iv) Specify either *OPSYS or *USRDFN to define how you want your System TLS cipher suites supported list managed on the server and then press ENTER.

- *OPSYS = Operating System determines the supported cipher suites. Please refer to the IBM i 7.4 System TLS System Level Settings Documentation document for more information.
- *USRDFN = The user will define the cipher suite list via the QSSLCSL system value.

v) Enter option 2 next to QSSLCSL to modify the System TLS cipher suite list and then press ENTER. This step (as well as step vi) are only allowed if QSSLCSLCTL is set to *USRDFN.
vi) Specify the TLS cipher suites you want System TLS to support in the order of how you want them prioritized. The list of supported TLS cipher suites that can be specified here can be found here, IBM i 7.4 System TLS System Level Settings Documentation under "cipher suite configuration". Press ENTER once you are done to confirm your changes.

3) If needed, update your Digital Certificate Manager (DCM) applications to support the required TLS protocols and cipher suites.

NOTE: IBM HTTP Server applications listed in DCM cannot be edited. Please refer to the mod_ssl HTTP directives if you want to customize your IBM HTTP Server's TLS configuration.

i) Open a web browser to the URL where <server> is your IBM i server's IP address or TCP/IP host name.
http://<server>:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0
ii) Sign in when prompted with an IBM i user profile with *ALLOBJ and *IOSYSCFG special authorities.
iii) Click the "Select a Certificate Store" button on the left, vertical menu bar.
iv) Select the "*SYSTEM" store and press the "Continue" button.
NOTE: If you do not see the *SYSTEM store, please refer to the following URL: http://www-01.ibm.com/support/docview.wss?uid=nas8N1010320
v) Enter the *SYSTEM certificate store password and press the "Continue" button. You can click the "Reset Password" button to reset your password if you cannot remember it.
vi) Expand the "Fast Path" section in the left, vertical menu bar.
vii) Click the "Work with server applications" OR "Work with client applications" link depending on whether you want to manage your server or client applications.
viii) Select the application from the list and click the "Work with Application" button at the bottom of the list of applications.
ix) To customize the TLS protocol configuration for the specific application, change the "TLS protocols" section from *PGM to "Define protocols supported" and then checkmark the specific SSL Protocols you would like the application to support.
x) To customize the TLS cipher suite configuration for the specific application, change the "TLS cipher specification option" section from *PGM to "Define cipher specification list" and then set up the order of the cipher suites under the "Order" column. To disable a cipher suite, change the value to "Disable" under the "Order" column next to the cipher suite you want to disable.
xi) Click the "Apply" button to implement the changes to the application.

NOTE: The changes to the application definition will not be implemented until the application type is restarted.

xii) Repeat steps vii) through x) to modify additional application definitions.

4) If needed, update your Eligible Default Protocols or Eligible Default Cipher Suites using the TLSCONFIG System Service Tools (SST) Advanced Analysis Command.

NOTE: The eligible default protocols and cipher suites are only used by applications when specific protocols and cipher suites are NOT specified by the application. The default protocols and cipher suites on a system are the intersection of the enabled protocols and cipher suites from QSSLPCL, QSSLCSLCTL, QSSLCSL and the eligible default protocols and cipher suites. The eligible default protocol and cipher suite list are configured using TLSCONFIG. TLSCONFIG is a System Service Tools (SST) Advanced Analysis Command.

To determine the current value of the eligible default protocol and cipher suite list as well as the default protocol and cipher suite list on the system, use TLSCONFIG option “–display”.

i) On the command line, type STRSST.
ii) Type your service tools user name and password.
iii) Select option 1 (Start a service tool).
iv) Select option 4 (Display/Alter/Dump).
v) Select option 1 (Display/Alter storage).
vi) Select option 2 (Licensed Internal Code (LIC) data).
vii) Select option 14 (Advanced analysis).
viii) Select option 1 (TLSCONFIG).
ix) Enter -h and press ENTER to review the "-display", "-eligibleDefaultProtocols", and "-eligibleDefaultCipherSuites" TLSCONFIG options and their values.

-display                                      
        Display current configuration settings.

-eligibleDefaultProtocols:<ProtocolNumber>[,<ProtocolNumber>...]    
        Set the System TLS eligible default protocol list.          
        This option takes a comma-separated list of numbers        
        to determine the System TLS eligible default protocol list.
        This list is used along with QSSLPCL to generate the default
        protocol list used by System TLS.      
                   
        ProtocolNumber             ProtocolName                    
        -----------------          ---------------
                02                 SSLv3
                04                 TLSv1.0                          
                08                 TLSv1.1                          
                10                 TLSv1.2
                20                 TLSv1.3

-eligibleDefaultCipherSuites:<cipherSuiteNumber>[,<cipherSuiteNumber>...]
        Set the System TLS eligible default cipher suite list.
        This option takes a comma-separated list of numbers
        to determine the eligible default cipher suites.  This list
        is used along with QSSLCSL to generate the default cipher
        suite list used by System TLS.

        CipherSuiteNumber          CipherSuiteName
        -----------------          ---------------
                05                 RSA_RC4_128_SHA
                0A                 RSA_3DES_EDE_CBC_SHA
                2F                 RSA_AES_128_CBC_SHA
                35                 RSA_AES_256_CBC_SHA
                3C                 RSA_AES_128_CBC_SHA256        
                3D                 RSA_AES_256_CBC_SHA256        
                9C                 RSA_AES_128_GCM_SHA256        
                9D                 RSA_AES_256_GCM_SHA384        
                Y2                 ECDHE_ECDSA_RC4_128_SHA      
                Y3                 ECDHE_ECDSA_3DES_EDE_CBC_SHA  
                Y5                 ECDHE_RSA_RC4_128_SHA        
                Y6                 ECDHE_RSA_3DES_EDE_CBC_SHA    
                Y7                 ECDHE_ECDSA_AES_128_CBC_SHA256
                Y8                 ECDHE_ECDSA_AES_256_CBC_SHA384
                Y9                 ECDHE_RSA_AES_128_CBC_SHA256  
                YA                 ECDHE_RSA_AES_256_CBC_SHA384  
                YB                 ECDHE_ECDSA_AES_128_GCM_SHA256
                YC                 ECDHE_ECDSA_AES_256_GCM_SHA384
                YD                 ECDHE_RSA_AES_128_GCM_SHA256
                YE                 ECDHE_RSA_AES_256_GCM_SHA384
                YF                 AES_128_GCM_SHA256
                YG                 AES_256_GCM_SHA384
                YH                 CHACHA20_POLY1305_SHA256
                YI                 ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
                YJ                 ECDHE_RSA_CHACHA20_POLY1305_SHA256

x) If needed, execute the "-eligibleDefaultProtocols" option against the TLSCONFIG Advanced Analysis Command to set up the eligible default TLS protocols. These protocols are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a protocol to use.

i.e.
 -eligibleDefaultProtocols:10,20

Executing the above option will enable the TLSv1.3 and TLSv1.2 protocols to be used.

xi) If needed, execute the "-eligibleDefaultCipherSuites" option against the TLSCONFIG Advanced Analysis Command to set up the eligible default TLS cipher suites. These cipher suites are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a cipher suite to use.

-eligibleDefaultCipherSuites:YI,YJ,YH,YG,YF,YC,YB,YE,YD

NOTE:  Apply SI71547, SI71373, SI71363, SI71361 and MF66742 and all requisites to add support for the *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256 & *ECDHE_RSA_CHACHA20_POLY1305_SHA256 cipher suites.  Some requisite PTFs are delayed apply.  Refer to the IBM i System TLS Enhancements to the TLSv1.3 and TLSv1.2 Protocols document for more information.

Executing the above option will set the following cipher suites to be used as the default.
ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
ECDHE_RSA_CHACHA20_POLY1305_SHA256
CHACHA20_POLY1305_SHA256
AES_256_GCM_SHA384
AES_128_GCM_SHA256
ECDHE_ECDSA_AES_256_GCM_SHA384
ECDHE_ECDSA_AES_128_GCM_SHA256
ECDHE_RSA_AES_256_GCM_SHA384
ECDHE_RSA_AES_128_GCM_SHA256

xii) If needed, execute the "-defaultSignatureAlgorithmList" option against the TLSCONFIG Advanced Analysis Command. Applications can negotiate secure sessions only with certificates that use the signature algorithms that are listed for TLSCONFIG option supportedSignatureAlgorithmCertificateList.

To determine the current value of the enabled signature algorithm certificate list on the system, use TLSCONFIG option display or the Retrieve TLS Attributes (QsoRtvTLSA) API. If the enabled signature algorithm certificate list must be changed on the system, use TLSCONFIG option supportedSignatureAlgorithmCertificateList to change the value. TLSCONFIG option h displays the help text that describes how to set the signature algorithm certificate list. Only signature algorithm values that are listed in the help text can be added to the list.

Example of setting SHA2 signature algorithms as the supported certificate signature algorithms on the system:
TLSCONFIG -supportedSignatureAlgorithmCertificateList:36,35,34,16,15,14

xiii) Execute the "-display" option to confirm the correct changes were made.
xiv) Press F3 several times and then press ENTER to exit the System Service Tools (SST).
xv) You have now successfully changed the supported and default System TLS protocols and cipher suites definition for your IBM i server.

Please refer to the IBM i 7.5 System TLS System Level Settings Documentation document for more information on the IBM i 7.5 System TLS protocols, Shipped TLS Supported protocols, Shipped TLS Default protocols, TLS cipher suites, Shipped TLS Supported cipher specification list, and Shipped TLS Default cipher specification list.

Please refer to the IBM i 7.5 TLS Security Reference PDF for the complete TLS reference guide for IBM i 7.5 OS.

Process to change your TLS protocols and cipher suites at IBM i 7.5.

When configuring your IBM i System TLS protocols and cipher suites, it is not always required to change your existing configuration. In some cases, only your TLS protocol configuration needs to be changed. In reverse, some cases will only require you to change your TLS cipher suite configuration. IBM recommends you carefully consider your TLS protocol and cipher suite requirements before making any changes.

1) If needed, update your QSSLPCL IBM i System Value to set up your System TLS supported protocols.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLPCL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLPCL and press ENTER. Otherwise, continue on to step 2.
iv) Specify the TLS Protocol Value(s) to modify your IBM i System TLS Protocol list and then press ENTER.

- *OPSYS =*TLSV1.3, *TLSV1.2. This value cannot be combined with any other value. Please refer to the IBM i 7.5 System TLS System Level Settings Documentation document for more information.
-*TLSV1.3 = Transport Layer Security v1.3
-*TLSV1.2 = Transport Layer Security v1.2
-*TLSV1.1 = Transport Layer Security v1.1
-*TLSV1 = Transport Layer Security v1.0

i.e.
CHGSYSVAL SYSVAL(QSSLPCL) VALUE(*OPSYS) - This will set the System TLS Supported Protocol List to *TLSV1.3 and *TLSV1.2.

CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1.3 *TLSV1.2') - This will set the System TLS Supported Protocol List to only support the TLSv1.3 and TLSv1.2 protocols.

2) If needed, update your QSSLCSLCTL and QSSLCSL IBM i System Values to set up your System TLS supported cipher suites.

i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
ii) Enter option 5 next to QSSLCSLCTL and press ENTER.
iii) If the current value displayed is not what your environment requires, enter option 2 next to QSSLCSLCTL and press ENTER. Otherwise, continue on to step 3.
iv) Specify either *OPSYS or *USRDFN to define how you want your System TLS cipher suites supported list managed on the server and then press ENTER.

- *OPSYS = Operating System determines the supported cipher suites. Please refer to the IBM i 7.5 System TLS System Level Settings Documentation document for more information.
- *USRDFN = The user will define the cipher suite list via the QSSLCSL system value.

v) Enter option 2 next to QSSLCSL to modify the System TLS cipher suite list and then press ENTER. This step (as well as step vi) are only allowed if QSSLCSLCTL is set to *USRDFN.
vi) Specify the TLS cipher suites you want System TLS to support in the order of how you want them prioritized. The list of supported TLS cipher suites that can be specified here can be found here, IBM i 7.5 System TLS System Level Settings Documentation under "cipher suite configuration". Press ENTER once you are done to confirm your changes.

3) If needed, update your Digital Certificate Manager (DCM) applications to support the required TLS protocols and cipher suites.

NOTE: IBM HTTP Server applications listed in DCM cannot be edited. Please refer to the mod_ssl HTTP directives if you want to customize your IBM HTTP Server's TLS configuration.

i) Open a web browser to the URL where <server> is your IBM i server's IP address or TCP/IP host name.
http://<server>:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0
ii) Sign in when prompted with an IBM i user profile with *ALLOBJ and *IOSYSCFG special authorities.
iii) Click the "Select a Certificate Store" button on the left, vertical menu bar.
iv) Select the "*SYSTEM" store and press the "Continue" button.
NOTE: If you do not see the *SYSTEM store, please refer to the following URL: http://www-01.ibm.com/support/docview.wss?uid=nas8N1010320
v) Enter the *SYSTEM certificate store password and press the "Continue" button. You can click the "Reset Password" button to reset your password if you cannot remember it.
vi) Expand the "Fast Path" section in the left, vertical menu bar.
vii) Click the "Work with server applications" OR "Work with client applications" link depending on whether you want to manage your server or client applications.
viii) Select the application from the list and click the "Work with Application" button at the bottom of the list of applications.
ix) To customize the TLS protocol configuration for the specific application, change the "TLS protocols" section from *PGM to "Define protocols supported" and then checkmark the specific SSL Protocols you would like the application to support.
x) To customize the TLS cipher suite configuration for the specific application, change the "TLS cipher specification option" section from *PGM to "Define cipher specification list" and then set up the order of the cipher suites under the "Order" column. To disable a cipher suite, change the value to "Disable" under the "Order" column next to the cipher suite you want to disable.
xi) Click the "Apply" button to implement the changes to the application.

NOTE: The changes to the application definition will not be implemented until the application type is restarted.

xii) Repeat steps vii) through x) to modify additional application definitions.

4) If needed, update your Eligible Default protocols or Eligible Default cipher suites using the TLSCONFIG System Service Tools (SST) Advanced Analysis Command.

NOTE: The eligible default protocols and cipher suites are only used by applications when specific protocols and cipher suites are NOT specified by the application. The default protocols and cipher suites on a system are the intersection of the enabled protocols and cipher suites from QSSLPCL, QSSLCSLCTL, QSSLCSL and the eligible default protocols and cipher suites. The eligible default protocol and cipher suite list are configured using TLSCONFIG. TLSCONFIG is a System Service Tools (SST) Advanced Analysis Command.

To determine the current value of the eligible default protocol and cipher suite list as well as the default protocol and cipher suite list on the system, use TLSCONFIG option “–display”.

i) On the command line, type STRSST.
ii) Type your service tools user name and password.
iii) Select option 1 (Start a service tool).
iv) Select option 4 (Display/Alter/Dump).
v) Select option 1 (Display/Alter storage).
vi) Select option 2 (Licensed Internal Code (LIC) data).
vii) Select option 14 (Advanced analysis).
viii) Select option 1 (TLSCONFIG).
ix) Enter -h and press ENTER to review the "-display", "-eligibleDefaultProtocols", and "-eligibleDefaultCipherSuites" TLSCONFIG options and their values.

-display                                      
        Display current configuration settings.

-eligibleDefaultProtocols:<ProtocolNumber>[,<ProtocolNumber>...]    
        Set the System TLS eligible default protocol list.          
        This option takes a comma-separated list of numbers        
        to determine the System TLS eligible default protocol list.
        This list is used along with QSSLPCL to generate the default
        protocol list used by System TLS.      
                   
        ProtocolNumber             ProtocolName                    
        -----------------          ---------------
                02                 SSLv3
                04                 TLSv1.0                          
                08                 TLSv1.1                          
                10                 TLSv1.2
                20                 TLSv1.3

-eligibleDefaultCipherSuites:<cipherSuiteNumber>[,<cipherSuiteNumber>...]
        Set the System TLS eligible default cipher suite list.
        This option takes a comma-separated list of numbers
        to determine the eligible default cipher suites.  This list
        is used along with QSSLCSL to generate the default cipher
        suite list used by System TLS.

        CipherSuiteNumber          CipherSuiteName
        -----------------          ---------------
                05                 RSA_RC4_128_SHA
                0A                 RSA_3DES_EDE_CBC_SHA
                2F                 RSA_AES_128_CBC_SHA
                35                 RSA_AES_256_CBC_SHA
                3C                 RSA_AES_128_CBC_SHA256        
                3D                 RSA_AES_256_CBC_SHA256        
                9C                 RSA_AES_128_GCM_SHA256        
                9D                 RSA_AES_256_GCM_SHA384        
                Y2                 ECDHE_ECDSA_RC4_128_SHA      
                Y3                 ECDHE_ECDSA_3DES_EDE_CBC_SHA  
                Y5                 ECDHE_RSA_RC4_128_SHA        
                Y6                 ECDHE_RSA_3DES_EDE_CBC_SHA    
                Y7                 ECDHE_ECDSA_AES_128_CBC_SHA256
                Y8                 ECDHE_ECDSA_AES_256_CBC_SHA384
                Y9                 ECDHE_RSA_AES_128_CBC_SHA256  
                YA                 ECDHE_RSA_AES_256_CBC_SHA384  
                YB                 ECDHE_ECDSA_AES_128_GCM_SHA256
                YC                 ECDHE_ECDSA_AES_256_GCM_SHA384
                YD                 ECDHE_RSA_AES_128_GCM_SHA256
                YE                 ECDHE_RSA_AES_256_GCM_SHA384
                YF                 AES_128_GCM_SHA256
                YG                 AES_256_GCM_SHA384
                YH                 CHACHA20_POLY1305_SHA256
                YI                 ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
                YJ                 ECDHE_RSA_CHACHA20_POLY1305_SHA256

x) If needed, execute the "-eligibleDefaultProtocols" option against the TLSCONFIG Advanced Analysis Command to set up the eligible default TLS protocols. These protocols are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a protocol to use.

i.e.
 -eligibleDefaultProtocols:10,20

Executing the above option will enable the TLSv1.3 and TLSv1.2 protocols to be used.

xi) If needed, execute the "-eligibleDefaultCipherSuites" option against the TLSCONFIG Advanced Analysis Command to set up the eligible default TLS cipher suites. These cipher suites are eligible to be used by applications that leverage the GSKit or SSL_ APIs and do not programmatically specify a cipher suite to use.

-eligibleDefaultCipherSuites:YI,YJ,YH,YG,YF,YC,YB,YE,YD

Executing the above option will set the following cipher suites to be used as the default.
ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
ECDHE_RSA_CHACHA20_POLY1305_SHA256
CHACHA20_POLY1305_SHA256
AES_256_GCM_SHA384
AES_128_GCM_SHA256
ECDHE_ECDSA_AES_256_GCM_SHA384
ECDHE_ECDSA_AES_128_GCM_SHA256
ECDHE_RSA_AES_256_GCM_SHA384
ECDHE_RSA_AES_128_GCM_SHA256

xii) If needed, execute the "-defaultSignatureAlgorithmList" option against the TLSCONFIG Advanced Analysis Command. Applications can negotiate secure sessions only with certificates that use the signature algorithms that are listed for TLSCONFIG option supportedSignatureAlgorithmCertificateList.

To determine the current value of the enabled signature algorithm certificate list on the system, use TLSCONFIG option display or the Retrieve TLS Attributes (QsoRtvTLSA) API. If the enabled signature algorithm certificate list must be changed on the system, use TLSCONFIG option supportedSignatureAlgorithmCertificateList to change the value. TLSCONFIG option h displays the help text that describes how to set the signature algorithm certificate list. Only signature algorithm values that are listed in the help text can be added to the list.

Example of setting SHA2 signature algorithms as the supported certificate signature algorithms on the system:
TLSCONFIG -supportedSignatureAlgorithmCertificateList:36,35,34,16,15,14

xiii) Execute the "-display" option to confirm the correct changes were made.
xiv) Press F3 several times and then press ENTER to exit the System Service Tools (SST).
xv) You have now successfully changed the supported and default System TLS protocols and cipher suites definition for your IBM i server.