Cipher suites and cipher suite specification files

Many different algorithms can be used for encrypting data, and for computing the message authentication code. To allow users to select the level of security that suits their needs, and to enable communication with others who might have different needs, SSL defines cipher suites, or sets of ciphers. You can specify a list of cipher suites to be used during an SSL connection in the SSL cipher suite specification file.

Cipher suites

When an SSL connection is established, during the SSL handshake, the client and server exchange information about which TLS protocols and cipher suites they have in common. They then communicate using the protocol and common cipher suite that offers the highest level of security. If they do not have a protocol or cipher suite in common, then secure communication is not possible and CICS® closes the connection.

The ciphers suites that are available depend on the value of the system initialization parameters MINTLSLEVEL and NISTSP800131A, and on what ciphers are supported by z/OS System SSL. In addition, you can restrict the ciphers that are used by editing the list of cipher suites in the CIPHERS attribute on the appropriate resource definition, or by editing the SSL cipher suite specification file for the resource definition.

You can check which cipher suites are being selected for SSL inbound connections from each CICS region. The performance data field SOCIPHER (320) in the DFHSOCK group shows the code for the cipher suite that was used for each SSL inbound connection. Use this information to identify any cipher suites that are offered by the CICS region but are not being selected for SSL connections. You can also identify any less efficient or less secure cipher suites that are being selected for SSL connections. Then you can decide whether to eliminate such cipher suites.

To specify the level of encryption required:

For inbound HTTP: Use the CIPHERS attribute of the TCPIPSERVICE resource definition.
For outbound HTTP and web service requests: Use the CIPHERS attribute of the URIMAP resource definition.
For inbound IPIC: Use the CIPHERS attribute of the TCPIPSERVICE resource definition.
For outbound IPIC: Use the CIPHERS attribute of the IPCONN resource definition.
For inbound CICSPlex® SM Web User Interface requests: Use the TCPIPSSLCIPHERS Web User Interface server initialization parameter. This value has the same syntax as the CIPHERS attribute of the TCPIPSERVICE resource, but it is limited to a maximum of 22 cipher codes.

The cipher suites that are supported by z/OS® and CICS for each supported security protocol are described in Cipher Suite Definitions in z/OS Cryptographic Services System SSL Programming.

SSL cipher suite specification files

The SSL cipher suite specification file is an XML file that contains a list of cipher suites that can be used in an SSL connection. It uses the EBCDIC 037 encoding.

The name of the file can be up to 28 characters in length including the extension, which must be .xml. The specified value is case-sensitive. It must be a valid name for a UNIX file and can contain only the following characters: A-Z a-z 0-9 # - . @ _

The SSL cipher suite specification file must be in the ussconfig/security/ciphers directory, where ussconfig is the value of the SIT parameter USSCONFIG.

The CICS region must have permission to access z/OS UNIX, and it must have read and execute access to the directory that contains the file, and read access to the file itself.

Sample files are provided in the usshome/security/ciphers directory, where usshome is the value of the SIT parameter USSHOME. A schema file is also supplied, in the usshome/schemas/security directory. The file name is ciphersfile.xsd.

Structure of the SSL cipher suite specification file

Each cipher suite is specified as a number attribute of a cipher element. The cipher number is a four-character code. If you use a two-character code, pad it with leading zeros.

The sample files also contain a comment for each cipher, which contains a text string that describes the cipher suite. However, CICS does not validate this element nor take any action on it.

The following example shows the structure of the cipher file:

<?xml version="1.0"?>
<cipher_list xmlns="http://www.ibm.com/software/htp/cics/ciphers">
    <cipher number="000A">
        <!-- SSL_RSA_WITH_3DES_EDE_CBC_SHA -->
    </cipher>
    <cipher number="000D">
        <!-- SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA -->
    </cipher>
    ...
</cipher_list>