Configuring TLS Using a RACF Keyring - 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

The steps that follow are for generating certificates in a RACF key ring and configuring the Ironstream agent to use the RACF key ring for the certificate information. For more information about the commands used in this appendix, consult the IBM documentation.

Note: The certificate must be the default certificate.

Create a Self-Signed Certificate Authority

If you are not using an existing certificate authority, you can create a self-signed certificate authority using RACF with this RACF command:

RACDCERT GENCERT CERTAUTH SUBJECTSDN (CN('<subject’s common name>')) KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN) WITHLABEL('<certificate

authority label>') SIZE(2048)

where:

Command

Description

<subject’s common name>

The common name of your subject.

<certificate authority label>

The label to apply to this new certificate, which must be unique to the user ID with which the certificate is associated.

Create a Key Ring

Note: A separate RACF keyring must be created for each LPAR.

  1. Create a key ring for the LPAR by applying this command:

RACDCERT ADDRING(<name of the new key ring> ID(<userID>)

where:

Command

Description

<name of the new key ring>

The name of the key ring that you require. For easy identification it is best to use a descriptive name that includes the LPAR

name.

<userID>

The user ID of the key ring owner. This must be the userid that is assigned to the Ironstream agent.

  1. Connect the certificate authority to the key ring by applying this command:

RACDCERT CONNECT (CERTAUTH LABEL('<label name>')

RING(<key ring name>) USAGE(CERTAUTH)) ID(<userID>)

where:

Command

Description

<label name>

The label of the certificate that is being connected to the key ring. This will either be the label applied to the self-signed certificate authority or the label of an

existing certificate authority.

<key ring name>

The name of the key ring to which the certificate authority is being connected.

<userID>

The user ID of the key ring owner. This must be the userid that is assigned to the Ironstream agent.

  1. Generate the mainframe server certificate and key by applying this command:

RACDCERT GENCERT ID(<userID>) SUBJECTSDN(CN('<LPAR FQDN>') OU('<org

unit>') O('<org>') C('<country code>')) SIZE(2048) WITHLABEL('<server certificate label>') KEYUSAGE(HANDSHAKE SIGNWITH(CERTAUTH

LABEL('<certificate authority label>')) ALTNAME(IP(<mainframe IP address>) DOMAIN('<LPAR FQDN>'))

where:

Command

Description

<userID>

The userID of the certificate owner. This

must be the userID that is assigned to the Ironstream agent.

<LPAR FQDN>

The CN parameter and the DOMAIN parameter, with the fully qualified domain

name of the LPAR.

<org unit>

Your organization’s unit.

<org>

Your organization’s name.

<country code>

The two-character country code of your organization.

<server certificate label>

The label for this certificate. For easy identification, it is best to use a descriptive

name that includes the LPAR name.

<certificate authority label>

The label assigned to the certificate authority with a private key that will be used to sign the certificate. This is the

certificate authority connected in step 2.

(<mainframe IP address>

The fully qualified numeric IP address of the mainframe.

  1. Generate the client certificate and key by applying this command:

RACDCERT GENCERT ID(<userID>) SUBJECTSDN(CN('<proxy FQDN>')

OU('<org unit>') O('<org>') C('<country code>')) SIZE(2048) WITHLABEL('<client certificate label>') KEYUSAGE(HANDSHAKE) SIGNWITH(CERTAUTH LABEL('<certificate authority label>')) ALTNAME(IP(<proxy IP address>) DOMAIN('<proxy FQDN>'))

where:

Command

Description

<userID>

The userID of the certificate owner. This must be the userID that is assigned to the Ironstream agent.

<proxy FQDN>

The CN parameter and the DOMAIN parameter, with the fully qualified domain name of the server on which the Ironstream client (proxy server) is installed.

<org unit>

Your organization’s unit.

<org>

Your organization’s name.

<country code>

The two-character country code of your organization.

<client certificate label>

The label for this certificate. For easy identification it is best to use a descriptive

name that includes the LPAR name.

<certificate authority label>

The label assigned to the certificate authority with a private key that will be used to sign the certificate. This is the

certificate authority connected in step 2.

<proxy IP address>

The fully qualified numeric IP address of the server on which the Ironstream client (proxy server) is installed.

  1. Export the client certificate and key by applying this command:

RACDCERT EXPORT (LABEL('<certificate authority label>')) ID(<userID>) DSN(<output data set name>) FORMAT(PKCS12DER)

PASSWORD('<pkcs12 password>')

where:

Command

Description

<certificate authority label>

The label of the certificate that is being exported. This should be the same label that was used in step 4 to generate the client certificate.

<userID>

The userID of the certificate owner. This must be the userID that is assigned to the Ironstream agent.

<output data set name>

The name of the data set that is to contain the certificate.

<pkcs12 password>

The password to use for PKCS #12 package encryption.

  1. Transfer the exported PKCS12 file to the MID or Probe server using binary transfer and enter the name into the mainframe configuration in the web configuration interface.

  2. Connect the mainframe LPAR server certificate to the keyring for this LPAR by applying this command:

RACDCERT CONNECT(ID(<userID>) LABEL('<server certificate label>') RING(<name of the new key ring>) DEFAULT) ID(<userID>)

where:

Command

Description

<userID>

The userID of the certificate owner. This must be the userID that is assigned to the Ironstream agent.

<server certificate label>

The label of the certificate created by step 3.

<name of the new key ring>

The name of the key ring created by step 1.

  1. To activate the changes, execute the RACF command:

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

  1. The RACF keyring name must be specified on the agent’s TCP parameter line. In the KEYF parameter, specify the ID that owns the key ring (<userID>) followed by a “/” and the name of the key ring for the LPAR. For example:

TCP 6106 6107 TLS=Y KEYF=start2/TREX_RING STAF=-

Note: The STAF parameter must contain a “-” to indicate there is no stash file. If the userID owning the keyring is different than the agent started task ID, the agent started task ID must have access to the keyring.