Defining your TLS environment

Before you begin

Consider the following information before defining your TLS environment:

• Familiarize yourself with the UIMSSL-configuration-member.
• No changes are necessary to your existing configuration unless you want to tailor your use of TLS. Your current TLS configuration will continue to function as it does now. 
• To implement TLS support, you must provide a Server certificate, all intermediate Certificate Authority (CA) certificates, and a private key.
  • The private key can be managed in the PKDS of ICSF (SSL_PRIVATE_KEY element ICSF attribute) or imbedded in the server certificate (SSL_CERTIFICATE element R_DATALIB attribute, no SSL_PRIVATE_KEY element is required).
  • The certificate can be in a data set (SSL_CERTIFICATE DSN attribute) or a Key Ring within the RACF/ACF2 security repository (SSL_CERTIFICATE element R_DATALIB attribute).

• ICSF is configured with a cryptographic coprocessor to support the RSA Public Key Infrastructure Algorithm.

To define your TLS environment

1. Ensure that UIM is installed and that the encryption level is set to the correct level.

   • If UIM is not installed, install a product that uses UIM. During product configuration, set the UIM server encryption level to SSL-IF or SSL-REQUIRED.
   • If UIM is already installed, access the UIM Startup Configuration Member and set the encryption level to SSL-IF or SSL-REQUIRED.
     <BMC_PARM ID="encryptionLevel" value="SSL-value"

   Specifying SSL-IF or SSL-REQUIRED activates UIMSSL. For more information about encryption levels, see Using-encryption-for-the-UIM-server.
   
   

2. Open the UIMSSL file (located in the UIM UBMCCNFG library) for editing.

   Important

   If you do not have a UIMSSL file, create one in the UIM UBMCCNFG library by copying the sample UIMSSL file from the BMCSAMP library.

3. Remove all of the comment tags around the XML statements that you want to use.
   By default, all of the statements are commented out, and all options are enabled. Comments are designated by the comment tags (<!-- and -->). To uncomment a statement, remove the comment tags or move the statement outside the comment tags.
   
   
4. In the UIMSSL file, indicate the TLS versions, encryption hash algorithms, encryption cipher algorithms, and encryption cipher suites to allow in your environment.
   In each section, specify Yes to allow the selection or No to disallow the selection.
   
   

5. In the UIMSSL file, use SSL_STORE statements to specify the name and location of your TLS certificate and private key.

   Important

   If the specified LOCATION parameter value is set as R_DATALIB and the SSL_PRIVATE_Key value is embedded, only the SSL_CERTIFICATE statement is required, therefore omit SSL_PRIVATE_KEY. If the certificate contains an embedded private Key, the SSL_PRIVATE_KEY specification is ignored.

   The syntax of the SSL_STORE statement is:

   <SSL_STORE [HOST="hostName"] [JOBNAME="addressSpaceName"]>
        <SSL_CERTIFICATE 
        LOCATION="certificateLocation"
           >certificateName</SSL_CERTIFICATE>
        <SSL_PRIVATE_KEY 
        LOCATION="privateKeyLocation"
           >privateKeyName</SSL_PRIVATE_KEY>
   </SSL_STORE>

   
   

   You can specify:

   • One certificate or private key combination for all systems
   • Different certificate or private key combinations for different systems and address spaces by using the filtering attributes (HOST and JOBNAME)
   • As many SSL_STORE statements as you want

   The following table explains the variables in the SSL_STORE statement:

   Parameter	Variable	Description
   HOST	hostName	Name of a system to which this SSL_STORE statement applies The HOST parameter is optional. If you omit it, the statement applies to all systems.
   JOBNAME	addressSpaceName	Name of an address space to which this SSL_STORE statement applies The JOBNAME parameter is optional. If you omit it, the statement applies to all address spaces. Use with or without HOST. If used with HOST, applies only to the named address space on the named system.
   SSL_CERTIFICATE	certificateLocation	Name of the storage medium for the certificate Valid medium types are: DSN—Sequential data set R_DATA—SAF access to Security System (RACF or ACF2) database
   SSL_CERTIFICATE	certificateName	Name (DSN or Security System Database label name) of the certificate
   SSL_PRIVATE_KEY	privateKeyLocation	Name of the storage medium for the private key Valid medium types are: ICSF—ICSF key data set R_DATALIB—SAF access to Security System (RACF or ACF2) database Important If the specified LOCATION parameter value is set as R_DATALIB and the SSL_PRIVATE_Key value is embedded, only the SSL_CERTIFICATE statement is required, therefore omit SSL_PRIVATE_KEY. If the certificate contains an embedded private Key, the SSL_PRIVATE_KEY specification is ignored.
   SSL_PRIVATE_KEY	privateKeyName	Name (DSN or Security System Database label name) of the private key

   UIM evaluates the SSL_STORE statements in the order in which they appear in the UIMSSL file. The last statement encountered that evaluates as true identifies the certificate and private key to use.

   Tip

   For an overview of the Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates and instructions for creating them, see Creating SSL/TLS certificates for use with UIM or MVE. 

6. Save and close the UIMSSL file.