TLS: Creating a RACF key ring for the Data Streamer

To configure TLS connections between the Data Streamer and its subscribers, you need to create a RACF® key ring for the Data Streamer.

Before you begin

You must have the access to run the RACDCERT commands to create the RACF key ring and certificates. For more information about the RACDCERT commands and the authorizations that are required, see RACDCERT (Manage RACF digital certificates) in the z/OS® Security Server RACF Command Language Reference.

About this task

In the following examples, HBOLGF is the user ID that is assigned to the Data Streamer started task. If you use a different user ID, change it to a different value.

Procedure

Obtain a server certificate for the Data Streamer.
This step is required only when any of the subscribers requires TLS client authentication that is sometimes referred to as mutual TLS authentication. If you already have a server certificate such as a SITE certificate, skip this step.
If none is available, you can complete one of the following steps to obtain an external CA signed certificate or a locally signed certificate for the Data Streamer depending on your site policy. It is recommended to use a CA-signed certificate for the communication between z/OS and distributed systems.
Option 1: obtain a server certificate signed by an external CA.
Generate a self-signed certificate for the Data Streamer.
RACDCERT ID(HBOLGF) GENCERT SUBJECTSDN(CN('yourhost.yourcompany.com') OU('xxxx') O('yyyy') C('US')) ALTNAME(DOMAIN('yourhost.yourcompany.com')) RSA SIZE(2048) KEYUSAGE(HANDSHAKE) NOTAFTER(DATE(2030-12-31)) WITHLABEL('cdpDSCert')

yourhost.yourcompany.com

Specify a fully qualified host name of the z/OS where the Data Streamer runs.

OU('xxxx') O('yyyy') C('US'))

Specify your organizational unit name, organization name, and country.

NOTAFTER(DATE(2030-12-31))

Specify the expiry date that you need. The expiry date might be overridden when the certificate is issued by the external CA.

Note: If you want to use a CCA cryptographic coprocessor to generate the key pair, you can specify the PKDS parameter to RSA.

Run the following command to create a certificate request based on the certificate that you create in step a.
RACDCERT ID(HBOLGF) GENREQ(LABEL('cdpDSCert')) DSN('USER1.CDP.CRTREQ')
After you run the command, a certificate request is created and placed in the data set USER1.CDP.CRTREQ.

Send the certificate request to the certificate authority. The certificate request is in base64-encoded text. Typically, you can cut and paste the request into an email and send it to the certificate authority.
The certificate authority validates the certificate. If the certificate is approved by the certificate authority, it is signed by the certificate authority, and returned to the requester.

Put the returned certificate into a data set, for example, USER1.CDP.CRT. The returned certificate is usually in base64-encoded text. You can cut and paste the text into a data set, or use FTP or other methods to send the certificate to a data set.

Replace the self-signed certificate with the certificate that is signed by the certificate authority.
RACDCERT ID(HBOLGF) ADD('USER1.CDP.CRT') WITHLABEL('cdpDSCert') SETROPTS RACLIST(DIGTCERT) REFRESH RACDCERT ID(HBOLGF) LIST (LABEL('cdpDSCert'))
Note: The certificate is replaced only if the user ID that is specified in the RACDCERT ADD command matches the user ID that is specified when you create the certificate.
Option 2: obtain a locally signed server certificate.
Generate a self-signed certificate to represent the local certificate authority. This certificate is used as the CA certificate. If you already have a certificate, skip this step.
RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('Root CA for CDP') OU('xxxx') O('yyyy') C('US')) RSA SIZE(2048) NOTAFTER(DATE(2030-12-31)) WITHLABEL('cdpCA') SETROPTS RACLIST(DIGTCERT) REFRESH RACDCERT CERTAUTH LIST (LABEL('cdpCA'))

OU('xxxx') O('yyyy') C('US'))

Specify your organizational unit name, organization name, and country.

NOTAFTER(DATE(2030-12-31))

Specify the expiry date that you need.

Create a personal certificate that is signed by the CA certificate that you create in step a for the Data Streamer.
RACDCERT ID(HBOLGF) GENCERT SUBJECTSDN(CN('yourhost.yourcompany.com') OU('xxxx') O('yyyy') C('US')) ALTNAME(DOMAIN('yourhost.yourcompany.com')) RSA SIZE(2048) KEYUSAGE(HANDSHAKE) NOTAFTER(DATE(2030-12-31)) WITHLABEL('cdpDSCert') SIGNWITH(CERTAUTH LABEL('cdpCA')) SETROPTS RACLIST(DIGTCERT) REFRESH RACDCERT ID(HBOLGF) LIST (LABEL('cdpDSCert'))

yourhost.yourcompany.com

Specify a fully qualified host name of the z/OS where the Data Streamer runs.

OU('xxxx') O('yyyy') C('US'))

Specify your organizational unit name, organization name, and country.

NOTAFTER(DATE(2030-12-31))

Specify the expiry date that you need.

Note: If you want to use a CCA cryptographic coprocessor to generate the key pair, you can specify the PKDS parameter to RSA.

For each subscriber that needs to authenticate the Data Streamer that it connects, you must add the root CA certificate of the Data Streamer server certificate to its truststore. If the root CA certificate is not available on the subscriber side, use the RACF command in the following example to export the certificate to a data set.
RACDCERT CERTAUTH EXPORT(LABEL('cdpCA')) FORMAT(CERTB64) DSN('USER1.DS.ROOTCA.PEM')
Make sure that the correct label that is associated with the CA certificate is specified in the RACF database. The exported certificate file is in base64-encoded text. You can cut and paste the text from the data set to a file on the subscriber side, or use FTP and other methods to send the data set to the subscriber side.
The ways to add the CA root certificate to the truststore of subscribers vary from subscriber to subscriber. For more information, contact the administrator of the subscriber.
Create a RACF key ring for the Data Streamer.
1. Generate a RACF key ring for the Data Streamer.
```
RACDCERT ID(HBOLGF) ADDRING(Keyring.CDPStreamer)
```
2. If a certificate is obtained for the Data Streamer in step 1, connect the certificate and all its CA certificates in the chain to the key ring.
```
RACDCERT ID(HBOLGF) CONNECT (RING(Keyring.CDPStreamer)                 
  CERTAUTH LABEL('cdpCA')                                         
                                                                                                                                          
RACDCERT ID(HBOLGF) CONNECT (RING(Keyring.CDPStreamer)                 
  ID(HBOLGF) LABEL('cdpDSCert')                            
  USAGE(PERSONAL) DEFAULT)                                            
                                                                     
SETROPTS RACLIST(DIGTRING) REFRESH   
RACDCERT ID(HBOLGF) LISTRING(Keyring.CDPStreamer)
```
  CERTAUTH LABEL('cdpCA')
  
  Specify the correct label for the CA certificate. If the Data Streamer server certificate is issued by an intermediate CA, you must connect all the CA certificates in the chain to the key ring.
  
  ID(HBOLGF)
  
  If you use a SITE certificate for the Data Streamer, replace ID(HBOLGF) with SITE.
  
  DEFAULT
  
  The DEFAULT parameter specifies the default certificate for the key ring.
  
  You can use the RACDCERT LISTCHAIN command to check if the certificate chain is complete and if all the certificates in the chain are connected to the key ring. For example,
```
RACDCERT ID(HBOLGF) LISTCHAIN(LABEL('cdpDSCert'))
```
3. For each subscriber that the Data Streamer connects to, its root CA certificate or the subscriber certificate if it is self-signed, must be connected to the key ring. Intermediate CA certificates are not required to connect to the key ring.
  Ensure that the root CA certificate of each subscriber, or the self-signed subscriber certificate be added to the RACF database. Put the certificate into a data set, for example, USER1.LOGSTASH.CA.CRT. If the certificate is in base64-encoded text, you can cut and paste the text into the data set. If the certificate is in DER coded format, you can use FTP or other methods to transfer it to the data set in binary mode. Then run RACF commands to add a root CA certificate to RACF, for example,
```
RACDCERT CERTAUTH TRUST 
  ADD('USER1.LOGSTASH.CA.CRT')  
  WITHLABEL('logstashCA') 

SETROPTS RACLIST(DIGTCERT) REFRESH 
RACDCERT CERTAUTH LIST (LABEL('logstashCA'))
```
  You can then connect the root CA certificate of the subscriber, or the self-signed subscriber certificate, to the RACF key ring. The following is an example of how to use RACF commands to connect a root CA certificate to the key ring.
```
RACDCERT ID(HBOLGF) CONNECT (RING(Keyring.CDPStreamer)                 
  CERTAUTH LABEL('logstashCA'))                                                                                             

SETROPTS RACLIST(DIGTRING) REFRESH   
RACDCERT ID(HBOLGF) LISTRING(Keyring.CDPStreamer)
```
Grant the Data Streamer the access to the key ring and the certificates.
The user ID that is associated with the Data Streamer started task must be granted appropriate access to the certificates and the key ring that you create in steps 1 and 2. The instructions depend on if the RDATALIB or FACILITY class is used in your site to protect the shared key ring and the private key of certificates.
- If you use the RDATALIB class, run the following commands:
```
RDEFINE RDATALIB HBOLGF.Keyring.CDPStreamer.LST UACC(NONE)

PERMIT HBOLGF.Keyring.CDPStreamer.LST CLASS(RDATALIB) ID(HBOLGF) ACCESS(CONTROL)  

SETROPTS RACLIST(RDATALIB) REFRESH
```
  ACCESS(CONTROL)
  Specify the access level based on your need.
  
  READ authority is required if a certificate is not obtained in step 1. In another word, all the subscribers that the Data Streamer connects to don’t require the client authentication of the Data Streamer. Or a personal certificate is obtained for the Data Streamer, and the user ID associated with the Data Streamer is the owner of the certificate.
  
  UPDATE authority is required if a personal certificate is obtained for the Data Streamer, but the owner of the certificate is a different user from the user ID that is associated with the Data Streamer.
  
  CONTROL authority is required, if a SITE certificate is used for the Data Streamer.
- If you use the FACILITY class, run the following commands:
```
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(HBOLGF) ACCESS(READ) 

RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE)                       
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(HBOLGF) ACCESS(CONTROL) 

SETROPTS RACLIST(FACILITY) REFRESH
```
  In the commands, these statements are required only when a SITE certificate is used for the Data Streamer.
```
RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE)                       
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(HBOLGF) ACCESS(CONTROL)
```
  When you use the FACILITY class and a personal certificate is obtained for the Data Streamer, the user ID that is associated with the Data Streamer must be the owner of the certificate.