Creating and Using a Key Database - ironstream_for_micro_focus_universal_discovery - 7.4

Ironstream for Micro Focus® Universal Discovery for IBM Z® Installation

Product type
Software
Portfolio
Integrate
Product family
Ironstream
Product
Ironstream > Ironstream for Micro Focus® Universal Discovery
Version
7.4
Language
English
Product name
Ironstream for Micro Focus Universal Discovery for IBM Z
Title
Ironstream for Micro Focus® Universal Discovery for IBM Z® Installation
Copyright
2022
First publish date
2007
ft:lastEdition
2023-11-28
ft:lastPublication
2023-11-28T05:42:35.385852

This procedure requires that IBM "Cryptographic Services System SSL" and "Cryptographic Services Security Level 3" packages are installed on the mainframe LPAR.

Step 1 - Creating the key database

From a Unix System Services shell, execute program gskkyman. Select option 1 to create a new database and follow the prompts, selecting whatever options are appropriate for your needs.

In this example, we create a key database named "example" and choose a password and accept the default for password expiration and database record length. Enter "0" for the FIPS mode database option because FIPS mode is not supported on the Proxy server application. This will create an “example” database file in the directory where the gskkyman program was run. The location of this database file will be used in Step 10.

Step 2 – Store the database password

After pressing Enter, you will be taken to the Key Management Menu. Select option 10 to store the key database password in a stash file. The location of the stash file will be used in Step 10.

Step 3 – Creating the certificate authority

After pressing Enter, you will be taken back to the Key Management Menu. Select option 6 to create a self-signed certificate, and then select option 1 on the next menu to create a CA certificate. In this example, the CA certificate will be called "example_ca".

Select the options that are appropriate for your needs in the next menus. For this example, we create a 2048 bit RSA key and use a SHA-256 signature.

Return to the Key Management Menu with option 1. Select the newly created certificate:

Step 4 - Creating the mainframe key and certificate

Select option 10 to create a signed certificate and key. Then from the next menu, select option 2 to create a user or server certificate.

For the mainframe certificate, the Common name must match the fully qualified domain name of the mainframe node (e.g., example.eview-tech.com).

Press Enter to return to the Key and Certificate Menu for the certificate authority.

Step 5 - Creating the client key and certificate

Repeat Step 4 to create a client key and certificate. You must give the new certificate a different label than the mainframe certificate from Step 4, and enter the Proxy server name in the Common name field.

Press Enter to return to the Key and Certificate List.

Step 6 - Set the mainframe key as the default

Select the mainframe certificate from the Key and Certificate List and then choose option 3 to set it as the default key for the key database.

Press Enter to return to the Key and Certificate List.

Step 7 - Exporting the client key

Select the client certificate from the list.

Select option 7 to export the key and certificate, and then select option 3 to export a binary PKCS #12 version 3 key file to the directory where the gskkyman program was run. This option will ask for a password for the PKCS12 file. Retain this password for use in Step 9.

Step 8 - Transfer certificate file to the Proxy server

Transfer the PKCS12 file from step 7 to the Ironstream Proxy server. If using FTP, ensure that binary mode is used.

Step 9 – Set parameters on the Proxy server

Use the Ironstream Configurator web interface to modify these three parameters to enable TLS communication for the defined mainframe node:

Parameter

Description

TLS

This parameter is used to determine whether the communication on the message and command service ports is encrypted using TLS encryption algorithms. Select the checkbox to use TLS.

PKCS #12 FILE

This parameter identifies the location and name of the PKCS12 file that was downloaded in Step 8.

PKCS #12 PASSWORD

Enter the password that was created for the PKCS12 file in Step 7. (The password will be stored in the configuration file

using AES 128-bit encryption.)

Step 10 – Set Agent Configuration to Enable TLS

Additional options are required on the agent task’s "TCP" SYSIN parameter card to enable TLS. In addition to existing parameters available on the TCP card (see "TCP Parameter Card" on page 17), the following parameters must be set to enable TLS communication with the server:

Parameter

Description

TLS

Optional. Set the TLS parameter to "Y" to have the TCP communication with the server use TLS encryption. The default is "N" (No).

You may also set this option to "V" to force the mainframe to check an incoming TLS client certificate's Common Name, validating that it matches the DNS name for the Proxy server that issued the connection request. (This requires that the Proxy server's DNS information is available to the mainframe.)

KEYF

Required if TLS=Y or TLS=V. The certificate key database file (defined in Step 1 above). The owning user ID of the Ironstream task must have read access to this file.

STAF

Required if TLS=Y or TLS=V. The password stash file (defined in Step 2 above). This must be specified when using a certificate key database file. The owning user ID of the Ironstream task must have read access to this file.

This is an example TCP parameter card with TLS enabled:

TCP 6106 6107 TLS=Y KEYF=/u/user1/example STAF=/u/user1/example.sth