Skip to main content

Universal Broker Digital Certificate (RACF) Set-up

Setting up a digital certificate infrastructure in a production environment for the first time requires careful planning by the Security organization and Universal Agent administrator. The instructions provided on this page have been simplified for illustration purposes.

You work with RACF Digital Certificates using the RACF command RACDCERT. RACF profiles control access to the functions provided by RACDCERT.

The user profile with which the following commands are executed require either:

  • SPECIAL attribute
  • Appropriate access to the IRR.DIGTCERT.function profile in the FACILITY class.
    • READ access is required to IRR.DIGTCERT.function to issue RACDCERT commands for the executing user.
    • UPDATE access is required to IRR.DIGTCERT.function to issue RACDCERT commands for other users.
    • CONTROL access is required to IRR.DIGTCERT.function to issue RACDCERT command for SITE or CERTAUTH certificates.
  • Consider managing security to RACF Certificates using the RDATALIB class, as described in the IBM RACF Security Administrator's Guide. It makes sharing specific keyrings among users easier than the IRR.DIGTCERT facility appoach.

The member UNVINDC in the INSTALL library contains the JCL to execute the RACF commands listed in the following steps.

Step 1

Create a Certificate Authority (CA) certificate and private key using the following RACDCERT command:

RACDCERT CERTAUTH GENCERT +
   SUBJECTSDN(CN('Certificate Authority') +
      OU('Security') +
      O('Company Name, Inc.') +
      C('US')) +
   NOTAFTER(DATE(2030-01-01)) +
   KEYUSAGE(HANDSHAKE CERTSIGN) +
   WITHLABEL('Company CA') [SIZE(2048)]

Change the subject and label names to meet local requirements.

It is critical to use the HANDSHAKE and CERTSIGN parameters in the KEYUSAGE option for TLS 1.3 connection support. Doing so will add key usage extension information that TLS 1.3 requires. A listing of the CA certificate must contain the following:

<snip>
509v3 extensions:
    Netscape Comment:
        Generated by the Security Server for z/OS (RACF)
    X509v3 Key Usage: critical
        Digital Signature, Key Encipherment, Certificate Sign, CRL Sign
    X509v3 Basic Constraints: critical
        CA:TRUE
    X509v3 Subject Key Identifier:
      <snip>

The SIZE parameter sets a key length of 2048 bits. This is the default for z/OS 2.5 and later, so the parameter is optional. Do not use a key size less than 2048 bits.

Step 2

Create a certificate for the Universal Broker STC and sign it with the CA certificate created in Step 1 using the following RACDCERT command:

RACDCERT ID(UBRUSR) GENCERT +
   SUBJECTSDN(CN('broker.company.com') +
      OU('Operations') +
      O('Company Name, Inc.') +
      C('US')) +
   KEYUSAGE(HANDSHAKE) +
   WITHLABEL('Broker') +
   SIGNWITH(CERTAUTH LABEL('Company CA')

Change the subject and label names to meet local requirements. The subject's Common Name (CN) value should uniquely identify this instance of the broker in the enterprise.

Step 3

Create a certificate key ring for the user profile UBRUSR with the following RACDCERT command:

RACDCERT ID(UBRUSR) ADDRING(BROKER)

Step 4

Connect the CA certificate and the Universal Broker certificate to the key ring with the following RACDCERT command:

RACDCERT ID(UBRUSR) CONNECT(CERTAUTH LABEL('Company CA') +
   RING(BROKER)
RACDCERT ID(UBRUSR) CONNECT(LABEL('Broker') RING(BROKER) DEFAULT)

Change the labels to match the values used in previous steps.

Step 5

If the resource profile IRR.DIGTCERT.LISTRING in the FACILITY class is not defined, define it with the following RDEFINE command:

RDEFINE FACILITY (IRR.DIGTCERT.LISTRING) UACC(NONE)

Step 6

Permit the Broker user profile UBRUSR READ access to the RACF profile IRR.DIGTCERT.LISTRING in the FACILITY class using the following PERMIT command:

PE IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(UBRUSR) ACCESS(READ)

Step 7

Modify the Universal Broker configuration member UBRCFG00 as follows:

ssl_implementation   system
saf_key_ring        BROKER

Step 8

info

When system SSL is enabled, the Universal Broker will always provide its certificate during the SSL/TLS handshake to the remote Universal Agent manager component (e.g., UCMD, UDM) that initiates the connection. Consequently, the Universal Agent manager component always performs server authentication against that certificate. This means that the CA certificate stored in the key ring must be exported from the key ring, saved to a file on the remote system, and that file must be specified in the Universal Agent manager's configuration via the CA_CERTIFICATES option.

Depending on the peer authentication options used, it may also be necessary to generate a client certificate on the remote system that is signed by the CA stored in the key ring. The file paths to this client certificate and its private key would then be added to the remote manager's configuration via the CERTIFICATE and PRIVATE_KEY options.

To secure connections between a z/OS Universal Agent Server component (i.e., UAGSRV) and a remote OMS Server, the exported CA and trusted client certificates may also need to be added to the Universal Broker's configuration on the OMS Server system.

CA and client certificates can be exported out of the RACF data base into a data set in a PEM (or base64) format with the RACDCERT command. The example below shows how to export the CA out of the key ring.

RACDCERT CERTAUTH EXPORT (LABEL('Company CA')) +
   DSN(TEST.CA.CERT) FORMAT(CERTB64)

Change the label to match the value used in previous steps.

The tsoprefix.TEST.CA.CERT data set contains a PEM formatted certificate. The format is a text format that transfers safely across the network in text mode.

Note that the CA private key is not exported. The CA certificate does not contain any private data.