Creating an SSL cipher suite specification file

You can create an SSL cipher suite specification file to specify a list of cipher suites to be used by SSL. If SSL 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.

Procedure

  1. Create an SSL cipher suite specification file either by editing a sample specification file or by creating your own one:
    • To modify a sample SSL 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 SSL cipher suite specification file must be in the ussconfig/security/ciphers directory.
    • To create your own SSL cipher suite specification file, create an XML file in the ussconfig/security/ciphers directory and name the file according to the following rules:
      • The file name is up to 28 characters in length, including the .xml extension.
      • The file name must be a valid name for a UNIX file and contain only characters A-Z a-z 0-9 # - . @ _. It is case-sensitive.
  2. Specify your list of cipher suites in the specification file as indicated in Cipher suites and cipher suite specification files.
    If you edit the sample file, you can remove unwanted cipher suites that do not meet your security requirements, or that are not supported by your hardware. You can also add cipher suites, but only those cipher suites that are supported by z/OS®.
  3. For the file to be effective in an SSL 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. An SSL 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.

To update the list of cipher suites for a resource without restarting CICS, you must use a new specification file:
  1. Create a new cipher suite specification file. Ensure that the file name has not been loaded by this CICS system.
  2. Update the existing resource definition to refer to the new file. For example, issue a CREATE TCPIPSERVICE command with CIPHERS(newciphers.xml) specified.
  3. Reinstall the resource definition.