IBM Support

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

Question & Answer


Question

How do you configure the System SSL/TLS protocols and cipher suites on the IBM i OS?

Answer


 
The IBM i System Secure Sockets Layer (SSL)/Transport Layer Security (TLS) protocols and ciphers suites are managed through the interconnect of the QSSLPCL, QSSLCSLCTL, and QSSLCSL system values, Digital Certificate Manager application definitions, and the SSLCONFIG IBM i System Service Tools (SST) Advanced Analysis (AA) Command. 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.

IBM strongly recommends that you always run your IBM i server with the network protocols and cipher suites specified below disabled. NOTE: Configuring your IBM i server to allow the use of weak protocols and weak cipher suites will result 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 NETWORK PROTOCOL AND/OR CIPHER SUITES.

Weak Protocols (as of April 2019):
Transport Layer Security version 1.1 (TLSv1.1)
Transport Layer Security version 1.0 (TLSv1.0)
Secure Sockets Layer version 2.0 (SSLv2)
Secure Sockets Layer version 3.0 (SSLv3)

Weak Cipher Suites (as of April 2019):
*RSA_RC4_128_SHA
*RSA_RC4_128_MD5
*RSA_NULL_MD5
*RSA_NULL_SHA
*RSA_NULL_SHA256
*RSA_DES_CBC_SHA
*RSA_EXPORT_RC4_40_MD5
*RSA_EXPORT_RC2_CBC_40_MD5
*RSA_RC2_CBC_128_MD5
*RSA_DES_CBC_MD5
*RSA_3DES_EDE_CBC_MD5
*RSA_3DES_EDE_CBC_SHA
*ECDHE_ECDSA_NULL_SHA
*ECDHE_ECDSA_RC4_128_SHA
*ECDHE_RSA_NULL_SHA
*ECDHE_RSA_RC4_128_SHA
*ECDHE_RSA_3DES_EDE_CBC_SHA
*ECDHE_ECDSA_3DES_EDE_CBC_SHA

-----------------------------------------------------------------------------

Enabled Protocols

  • The QSSLPCL system value setting identifies the specific protocols that are enabled on the system. Applications can negotiate secure sessions with only the protocols that are listed in QSSLPCL. For example, to restrict the System SSL/TLS implementation to use only TLSv1.3 and TLSv1.2 and not allow any of the older protocol versions, set QSSLPCL to contain only *TLSV1.3 & *TLSV1.2.

    The QSSLPCL special value *OPSYS allows the operating system to change the protocols that are enabled on the system on a release boundary. The value of QSSLPCL remains the same when the system upgrades to a newer operating system release. If the value of QSSLPCL is not *OPSYS, then the administrator must manually add in newer protocol versions to QSSLPCL after the system moves to a new release.

     
    Table 1.
    IBM i Release QSSLPCL *OPSYS definition
    7.4 *TLSV1.3 *TLSV1.2
    7.3 *TLSV1.3 *TLSV1.2 *TLSV1.1 *TLSV1
    7.2 *TLSV1.2 *TLSV1.1 *TLSV1
    7.1 *TLSV1 *SSLV3
    6.1 *TLSV1 *SSLV3

Default Protocols

  • When an application does not specify the protocols to enable, the System SSL/TLS default protocols are used. Applications use this design to pick up new TLS support without requiring application code changes. The default protocol setting has no meaning for applications that explicitly specify the protocols to enable for the application.

    The default protocols on a system are the intersection of the enabled protocols from QSSLPCL and the eligible default protocols. The eligible default protocol list is configured by using SSLCONFIG/TLSCONFIG option eligibleDefaultProtocols.

    To determine the current value of the eligible default protocol list and the default protocol list on the system, use SSLCONFIG/TLSCONFIG option –display.

    An administrator should consider changing the default protocol settings only when no other configuration setting allows an application to interoperate with peers successfully. It is preferred to enable an older protocol 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 protocol version 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 protocol from the default protocol 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 protocol 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 protocols must be changed on the system, use SSLCONFIG/TLSCONFIG option eligibleDefaultProtocols to change the value. SSLCONFIG/TLSCONFIG option -h displays the help panel that describes how to set the protocol list. Only protocol versions that are listed in the help text can be added to the list.

    Note: The SSLCONFIG/TLSCONFIG eligibleDefaultProtocols setting is reset by installing the Licensed Internal Code (LIC).

    Example of setting TLSv1.3 and TLSv1.2 to be the only default protocols on the system:
    SSLCONFIG -eligibleDefaultProtocols:10,20

    Example of setting TLSv1.3 to be the only default protocol on the system (IBM i 7.3 and 7.4 only):
    TLSCONFIG -eligibleDefaultProtocols:20
     
    Table 2.
    IBM i Release Eligible Default Protocol list with latest Security Group PTF
    7.4 *TLSV1.3 *TLSV1.2
    7.3 *TLSV1.3 *TLSV1.2 *TLSV1.1 *TLSV1
    7.2 *TLSV1.2 *TLSV1.1 *TLSV1
    7.1 *TLSV1
    6.1 *TLSV1

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. The QSSLCSL system value setting identifies the specific cipher suites that are enabled on the system. 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.

    For example, to restrict the System SSL/TLS implementation to use only Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) and not allow the RSA key exchange:

     
    1. Change QSSLCSLCTL system value to special value *USRDFN to allow the QSSLCSL system value to be edited.
    2. Remove all cipher suites from QSSLCSL that do not contain the ECDHE keyword.

    The QSSLCSLCTL system value special value *OPSYS allows the operating system to change the cipher suites that are enabled on the system on a release boundary. 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 SSL/TLS protocol required by the cipher suite is not set in QSSLPCL.


Default Cipher Suites

  • When an application does not specify the cipher suites to enable, the ordered System SSL/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 SSLCONFIG/TLSCONFIG option eligibleDefaultCipherSuites. 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 SSLCONFIG/TLSCONFIG option –display.

    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 SSLCONFIG/TLSCONFIG option eligibleDefaultCipherSuites to change the value. SSLCONFIG/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 SSLCONFIG/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:
    SSLCONFIG -eligibleDefaultCipherSuites:YE,YD,YC,YB,YA,Y9,Y8,Y7,Y6,Y3

    Example of setting only ECDHE and GCM cipher suites as the default on the system (IBM i 7.3 and 7.4 only):
    TLSCONFIG -eligibleDefaultCipherSuites:YI,YH,YG,YF,YC,YB,YE,YD
 

IBM i 6.1 OS


Please refer to the IBM i 6.1 System SSL Properties Information Center document for more information on the IBM i 6.1 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: TLSv1.2 and TLSv1.1 TLS protocols are NOT supported at IBM i 6.1.x OS. You will need to upgrade your OS VRM to 7.1 or later in order to support these TLS protocols.

NOTE: The process of changing the eligible and default IBM i System SSL/TLS protocols and cipher suites has changed with the following PTFs. You can execute the command DSPPTF to determine your IBM i OS Version, Release, and Modification Level.

IBM i 6.1.0 = 5761SS1-SI57357 & 5761999-MF60429
IBM i 6.1.1 = 5761SS1-SI57357 & 5761999-MF60431

If you do not have the above PTFs applied to your IBM i OS, please skip step 3 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 6.1.0 = 5761SS1-SI62465 & 5761999-MF62786
IBM i 6.1.1 = 5761SS1-SI62465 & 5761999-MF62785


Process to change your SSL/TLS Protocols and Cipher Suites at IBM i 6.1.x.

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, *SSLV3. This value cannot be combined with any other value. Please refer to the IBM i 6.1 System SSL Properties Information Center document for more information.
        - *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 and *SSLV3.

        CHGSYSVAL SYSVAL(QSSLPCL) VALUE(*TLSV1) - This will set the System SSL/TLS Supported Protocol List to only support the TLSv1.0 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 6.1 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 in the IBM i 6.1 System SSL Properties Information Center under "SSL Cipher Suites". Press ENTER once you are done to confirm your changes.

    3) If needed, update your Eligible Default Protocols and/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 is 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

        -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
                -----------------          ---------------
                        04                 RSA_RC4_128_MD5
                        05                 RSA_RC4_128_SHA
                        0A                 RSA_3DES_EDE_CBC_SHA
                        2F                 RSA_AES_128_CBC_SHA
                        35                 RSA_AES_256_CBC_SHA

      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 utilize the GSKit and/or SSL_ APIs and do not programmatically specify a protocol to use.

      • i.e.
         -eligibleDefaultProtocols:04

        Executing the above option will only enable the TLSv1.0 protocol 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 utilize the GSKit and/or SSL_ APIs and do not programmatically specify a cipher suite to use.

      • -eligibleDefaultCipherSuites:2F,35

        Executing the above option will set the
        RSA_AES_128_CBC_SHA
        RSA_AES_256_CBC_SHA
        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.

IBM i 7.1 OS


Please refer to the IBM i 7.1 System SSL Properties Information Center document for more information on the IBM i 7.1 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: Support for the TLSv1.2 and TLSv1.1 TLS protocols began in IBM i Technology Refresh Level 6. You will need to ensure you have PTF 5770999-MF99006 or newer permanently applied before you can utilize the *TLSV1.2 and *TLSV1.1 values in the QSSLPCL system value and support the associated TLSv1.2 and TLSv1.1 SSL Cipher Suites.

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.1 = 5770SS1-SI57332 & 5770999-MF60430

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.1 = 5770SS1-SI62463, 5733SC1-SI62623, & 5770999-MF62779


Process to change your SSL/TLS Protocols and Cipher Suites at IBM i 7.1.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, *SSLV3. This value cannot be combined with any other value. Please refer to the IBM i 7.1 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 and *SSLV3.

        CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1.2 *TLSV1.1 *TLSV1') - This will set the System SSL/TLS Supported Protocol List to support the TLSv1.2, TLSv1.1, and TLSv1.0 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.1 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 Cipher Suites that can be specified here can be found here, IBM i 7.1 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 on the "Select a Certificate Store" button on the left-hand, 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 on the "Reset Password" button to reset your password if you cannot remember it.
      vi) Expand the "Fast Path" section in the left-hand, vertical menu bar.
      vii) Click on 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 on 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 check mark 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 on 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 and/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 is 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
                -----------------          ---------------
                        04                 RSA_RC4_128_MD5
                        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

      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 utilize the GSKit and/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 utilize the GSKit and/or SSL_ APIs and do not programmatically specify a cipher suite to use.

      • -eligibleDefaultCipherSuites:2F,35,3C,3D

        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
        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.

IBM i 7.2 OS


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 on the "Select a Certificate Store" button on the left-hand, 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 on the "Reset Password" button to reset your password if you cannot remember it.
      vi) Expand the "Fast Path" section in the left-hand, vertical menu bar.
      vii) Click on 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 on 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 check mark 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 on 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 and/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 is 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 utilize the GSKit and/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 utilize the GSKit and/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.

IBM i 7.3 OS


Please refer to the IBM i 7.3 System SSL/TLS System Level Settings Knowledge Center 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 Knowledge Center 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 Knowledge 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.3 System SSL/TLS System Level Settings Knowledge Center 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 on the "Select a Certificate Store" button on the left-hand, 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 on the "Reset Password" button to reset your password if you cannot remember it.
vi) Expand the "Fast Path" section in the left-hand, vertical menu bar.
vii) Click on 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 on 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 check mark 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 on 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 and/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 is 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 utilize the GSKit and/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 utilize the GSKit and/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,YF,YG,YH,YI,YJ

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
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.

IBM i 7.4 OS


Please refer to the IBM i 7.4 System TLS System Level Settings Knowledge Center document for more information on the IBM i 7.4 System TLS Protocols, Shipped TLS Supported Protocols, Shipped LS Default Protocols, LS 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 Knowledge Center 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 Knowledge 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 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 Knowledge Center 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 on the "Select a Certificate Store" button on the left-hand, 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 on the "Reset Password" button to reset your password if you cannot remember it.
vi) Expand the "Fast Path" section in the left-hand, vertical menu bar.
vii) Click on 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 on 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 check mark 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 on 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 and/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 is 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 utilize the GSKit and/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 utilize the GSKit and/or SSL_ APIs and do not programmatically specify a cipher suite to use.

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

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


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

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.

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Component":"Operating System","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.4;7.3;7.2;7.1;6.1","Edition":"","Line of Business":{"code":"LOB08","label":"Cognitive Systems"}}]

Document Information

Modified date:
31 January 2021

UID

nas8N1020876