Creating a TLS cipher suite specification file

You can create a TLS cipher suite specification file to specify a list of cipher suites to be used by TLS. If TLS is used for TCP/IP connections, you can specify the name of cipher suite specification file in the CIPHERS attribute for resources that define TCP/IP connections.

6.1 6.2 You must have a cipher specification file named defaultciphers.xml if you have the feature toggle com.ibm.cics.web.defaultciperfile=true set up. CICS will use this file to provide a default set of ciphers when an alternative file has not been specified for a secure TCP/IP connection.

6.3 beta You must have a cipher specification file named defaultciphers.xml. CICS will load this file at startup if the KEYRING SIT parameter specifies a keyring name. This enables you to use CICS ‑managed TLS connections. CICS will use this file to provide a default set of ciphers when an alternative file has not been specified for a secure TCP/IP connection. CICS will attempt to load this file from the usshome/security/ciphers directory if it cannot be found in the ussconfig/security/ciphers directory.

Procedure

Create a TLS cipher suite specification file either by editing a sample specification file or by creating your own one:
- To modify a sample TLS cipher suite specification file, copy one of the sample files located in the usshome/security/ciphers directory to the ussconfig/security/ciphers directory, where
  
  usshome
  
  is the value of the SIT parameter USSHOME.
  
  ussconfig
  
  is the value of the SIT parameter USSCONFIG.
  
  Note: The TLS cipher suite specification file must be in the ussconfig/security/ciphers directory.
- To create your own TLS cipher suite specification file, create an XML file in the ussconfig/security/ciphers directory and ensure the file follows these rules:
  - The file name is up to 28 characters in length, including the .xml extension.
  - The file name is case-sensitive. It must be a valid name for a UNIX file and contain only the following characters: A-Z a-z 0-9 # - . @ _
  - The file must use the EBCDIC 037 encoding.
Specify your list of cipher suites in the specification file.
The order of the cipher suites is important. If CICS is acting as a server, then the first valid cipher suite in the list which is also supported by the client will be selected. If CICS is acting as a client, then the order of the client list of cipher suites is usually used to locate a matching cipher suite with the server. Ensure that the cipher suite specification file contains only cipher suites that meet security standards of your organization. You can include any cipher suites that are supported by z/OS.
The format of the cipher suite specification file is a single <cipher_list> element containing one or more <cipher> elements that specify a 4-digit cipher suite code.
The following example cipher specification file contains two ciphers, C030 followed by C02C.
```
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<cipher_list xmlns="http://www.ibm.com/software/htp/cics/ciphers">       
    <cipher number="C030">
       
    </cipher>
    <cipher number="C02C">
       
    </cipher>
<cipher_list>
```
Note: CICS uses only 4-digit cipher suite code. CICS does not use the full cipher suite name. The names have been included in the example as comments for better understanding of each cipher suite code represents.
For the file to be effective in a TLS connection, ensure that the CICS region has permission to access z/OS UNIX, and that the region has read and execute access to the directory that contains the specification file, and read access to the file itself.

Results

You have created a cipher suite specification file. A TLS cipher suite file can be used by multiple resources. The first time when a resource that uses a specification file is installed, the file is read from zFS and parsed. Any errors are flagged during this parse. If the file is valid, the resource is installed and the cipher information is stored in a new control block that is associated with the file. When subsequent resources that use the same cipher file are installed, cached information in the control block is used.

What to do next

If you want to update the list of cipher suites in a cipher suite specification file, you can edit the file directly, but you must restart CICS for the updated list to take effect. The file is reread for any type of start, whether the START system initialization parameter is set to INITIAL, COLD, or AUTO.

If you want to use your own named file instead of defaultciphers.xml, you can create a link on the file system to avoid maintaining two identical files.

From the ussconfig/security/ciphers directory, enter the following command by replacing myciphers.xml with the name of your cipher specification file:

ln -s myciphers.xml defaultciphers.xml

Note: The ln command will fail if defaultciphers.xml already exists in the ussconfig/security/ciphers directory.

You can now access your file using its original name and defaultciphers.xml.

To share a single cipher specification file between multiple CICS regions that have their own USSCONFIG directories, follow a similar procedure:

Create a single shared directory and give read access to all the required CICS regions.
Create a cipher specification file (myciphers.xml) within the shared directory. Give read access to all the required CICS regions.
From the ussconfig/security/ciphers directory of each CICS region that needs to use the shared file, issue the following commands:
```
ln -s /path/to/shared/directory/myciphers.xml myciphers.xml
ln -s /path/to/shared/directory/myciphers.xml defaultciphers.xml
```

You can now access the single shared cipher specification file from all CICS regions either by using its original name or defaultciphers.xml. This allows you to update only a single file whenever the set of ciphers used by CICS needs to be changed.