Converting XCOM OpenSSL configuration files to System SSL

Products

• XCOM Data Transport - z/OS
• XCOM Data Transport

Issue/Introduction

With the removal of OpenSSL from XCOM Data Transport for z/OS, it is necessary to create or migrate your OpenSSL configuration files for use with System SSL. See the announcement here- XCOM Data Transport for z/OS Risk Mitigation through Stronger Encryption Security.

The parameters are different, and some are used differently than for OpenSSL.

Resolution

Perform the following steps to convert your OpenSSL environment to System SSL.

1. Copy your current OpenSSL configuration file to a different name or use the "SYSconfigssl.cnf" created during XCOM Data Transport for z/OS 12.0 installation.
   
   
2. Edit the new configuration file and use the reference configuration section conversion chart below as a guide for converting and selecting the appropriate System SSL parameter equivalents.
   
   
3. During the initial installation of XCOM Data Transport for z/OS, sample certificates were created and a sample System SSL keystore database (.kdb) was created as "sysssl/database/xcomcert.kdb" in your selected USS installation directory. This sample .kdb is referenced by the sample System SSL configuration file "SYSconfigssl.cnf" referenced above.
   
   
4. If your OpenSSL environment uses keyrings, copy the keyring definition to the KEYRING_FILE section parameters "INITIATE_SIDE" and "RECEIVE_SIDE" as appropriate.
   
   
5. Keep the LABLCERT section values the same, unless you intend to use different certificates.
   
   
6. If you were using certificate files other than the samples created during XCOM installation, under OpenSSL, you must migrate those certificates into a System SSL keystore database (.kdb file). XCOM provides a "makesysssl" script to migrate certificates in PKCS#12 format into a .kdb. You can copy that script and modify it to suit your purposes for the migration of your own certificates into a .kdb for use by System SSL. For more information on running this script consult the "Administrating / Implement System SSL / Prepare the CA, Client, and Server Certificates" section of the XCOM Data Transport for z/OS 12.0 documentation.
   
   
7. For the initial conversion, you most likely can keep your existing SSL_METHOD, FIPS, CIPHER, VERIFY_CERTIFICATE, VERIFY_MACHINE, and HOST_NAME values as they were for OpenSSL
   
   
8. XCOM System SSL will ignore any sections in the new configuration file which are listed as "Not used" or "Not supported" in the chart below. The following is a list of OpenSSL section names and their usage or equivalent parameters in a System SSL configuration file:

 

   Open SSL Section Name    System SSL Section Name     System SSL Usage

   ---------------------    -----------------------     -------------------------------------------------------------

   KEYRING                    KEYRING_FILE               Either the userid/keyring or the keyring database (.kdb) name

   KEYRING_FILE               KEYRING_FILE               Either the userid/keyring or the keyring database (.kdb) name

   KEYRING_PW                 KEYRING_PW                 Optional password for the keyring database (.kdb)

   LABLCERT                   LABLCERT                   Label identifier of the certificate to be used

   FIPS                       FIPS                       FIPS mode selection (YES | NO)

   SSL_METHOD                 SSL_METHOD                 Minimum SSL/TLS level (SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2)

   CIPHER                     CIPHER                     Cipher families to be used (unchanged from Open SSL)

   VERIFY_CERTIFICATE         VERIFY_CERTIFICATE         (YES | NO)

   VERIFY_MACHINE             VERIFY_MACHINE             (YES | NO) - consult XCOM documentation for other options

   HOST_NAME                  HOST_NAME                  Host names for validation (domain format, generics supported)

   SERIAL_NUMBER              SERIAL_NUMBER              (Not used)

   NAME                       NAME                       (Not used)

   TITLE                      TITLE                      (Not used)

   DESCRIPTION                DESCRIPTION                (Not used)

   EMAIL                      EMAIL                      (Not used)

   ORGANIZATIONAL_UNIT_NAME   ORGANIZATIONAL_UNIT_NAME   (Not used)

   ORGANIZATION_NAME          ORGANIZATION_NAME          (Not used)

   LOCALITY_NAME              LOCALITY_NAME              (Not used)

   STATE_OR_PROVINCE_NAME     STATE_OR_PROVINCE_NAME     (Not used)

   COUNTRY_NAME               COUNTRY_NAME               (Not used)

   ICSF                       N/A                        (Not supported)

   CA                         N/A                        (Not supported)

   CA_DIRECTORY               N/A                        (Not supported)

   CERTIFICATE                N/A                        (Not supported)

   PRIVATEKEY                 N/A                        (Not supported)

   RSAKEY                     N/A                        (Not supported)

   DH                         N/A                        (Not supported)

   RANDOM                     N/A                        (Not supported)

   PASSWORD                   N/A                        (Not supported)

   SSL_OPTION                 N/A                        (Not supported)

   VERIFY_DEPTH               N/A                        (Not supported)

Additional Information

For further information relating to configuring System SSL in XCOM, consult the XCOM™ Data Transport® for z/OS 12.0 documentation section Configure the System SSL Configuration File.
NOTE: SSL_METHOD is not specifically documented but can still be added if required and set to one of the above values. By default SSL_METHOD values for INITIATE_SIDE and RECEIVE_SIDE are set to ALL to enable all protocols supported by System SSL and the one to be used is then negotiated.

Moving to AT-TLS is an XCOM for z/OS best practice. See XCOM™ Data Transport® for z/OS 12.0 documentation section AT-TLS Support.