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