Question & Answer
Question
Answer
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 December 2023):
Transport Layer Security version 1.1 (TLSv1.1)
Secure Sockets Layer version 2.0 (SSLv2)
Secure Sockets Layer version 3.0 (SSLv3)
Weak cipher suites (as of December 2023):
*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 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.5 | *TLSV1.3 *TLSV1.2 |
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
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:
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).
SSLCONFIG -eligibleDefaultProtocols:10
SSLCONFIG -eligibleDefaultProtocols:10,20
Example of setting TLSv1.3 and TLSv1.2 to be the only default protocol on the system (IBM i 7.4 and 7.5 only):
TLSCONFIG -eligibleDefaultProtocols:10,20
Table 2. | |
IBM i Release | Eligible Default Protocol list with latest Security Group PTF |
7.5 | *TLSV1.3 *TLSV1.2 |
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
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:
- Change QSSLCSLCTL system value to special value *USRDFN to allow the QSSLCSL system value to be edited.
- Remove all cipher suites from QSSLCSL that do not contain the ECDHE keyword.
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
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:
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).
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.4 and later):
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.
- - *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.
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. - - *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.
3) 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
-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 leverage the GSKit 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 leverage the GSKit 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. - -display
- i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
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 leverage 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.
- - *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.
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.
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. - - *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.
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
----------------- ---------------
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 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
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. - -display
- i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
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.
- - *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.
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. - - *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.
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. - -display
- i) Execute the CL command WRKSYSVAL QSSL* to work with your QSSL* system values.
IBM i 7.3 OS
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.
IBM i 7.4 OS
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.
IBM i 7.5 OS
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.
Was this topic helpful?
Document Information
Modified date:
06 December 2023
UID
nas8N1020876