Configuring the z/OSMF server certificate and key ring

If you plan to enable the z/OSMF server for Transport Layer Security (TLS) or Secure Sockets Layer (SSL), you must set up a key ring and certificates. This topic provides the steps for several common scenarios.

This topic describes the following scenarios for server authentication and client authentication:
Additional information is provided in the following topics:

This information assumes the use of RACF®. If you use another external security manager (ESM), contact the vendor for more information.

Note: The z/OSMF sample jobs IZUNUSEC and IZUSEC contain RACF commands for creating a CA and a server certificate. You might find that the commands in IZUNUSEC or IZUSEC are sufficient for your needs. If so, have your security administrator review these sample jobs carefully before you submit them.

1a. Create a server certificate and key ring for the z/OSMF server

In this scenario, you create a new certificate and key ring specifically for use by the z/OSMF server. The certificate and key ring are owned by the z/OSMF server. The certificate is signed by a local certificate authority (CA).

The z/OSMF sample jobs IZUNUSEC and IZUSEC contain RACF commands for creating a key ring and storing the CA and server certificate in the key ring. These constructs are named, as follows:
  • Key ring name is IZUKeyring.IZUDFLT
  • CA name is:
    CN(’z/OSMF CertAuth for Security Domain’)
    OU(’SAF_PREFIX’))
    WITHLABEL(’zOSMFCA’)
To configure a new certificate and key ring, follow these steps:
  1. Create the root CA and the server certificate. In the following example, replace 'HOST NAME' with the local hostname. 
    //* Create the CA certificate for the z/OSMF server                  *
 RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('z/OSMF CertAuth for Security Domain') +
   OU('IZUDFLT')) WITHLABEL('zOSMFCA') TRUST NOTAFTER(DATE(2028/04/12))
 
//* Create the server certificate for the z/OSMF server       */
//* Change HOST NAME in CN field to the real host name.        */
//* Usually the format of the host name is 'XXXX.XXX.XXX.XXX'     */      
RACDCERT ID(IZUSVR) GENCERT SUBJECTSDN(CN('HOST NAME') O('IBM') OU('IZUDFLT')) + 
   Start of changeALTNAME(DOMAIN(‘HOST NAME’)) +End of change
 WITHLABEL('DefaultzOSMFCert.IZUDFLT') SIGNWITH(CERTAUTH LABEL('zOSMFCA')) +
 NOTAFTER(DATE(2021/06/02)) 

 //* RACDCERT ID(IZUSVR) ALTER(LABEL('DefaultzOSMFCert.IZUDFLT')) TRUST  */

    In the example, notice that the RACDCERT ALTER command is commented. This command is not needed if the server certificate validity range falls within the CA certificate validity range.

  2. Create the key ring in your external security manager. For a RACF-protected system, use the following command: 
    RACDCERT ID(IZUSVR) ADDRING(IZUKeyring.IZUDFLT)
  3. Connect the CA certificate and the server certificate to the key ring, as follows: 
    RACDCERT ID(IZUSVR) 
CONNECT(CERTAUTH 
LABEL('zOSMFCA') 
RING(IZUKeyring.IZUDFLT)
)
  4. Verify that the certificates are set up correctly, as follows:
    • Server certificate indicates that it has a private key and is connected as DEFAULT.
    • Both the CA and server certificates have TRUST status and are both connected to the key ring.
  5. Authorize the z/OSMF server to use the key ring and the certificate, as described in Grant the z/OSMF server access to the key ring and the certificate.
  6. Export the CA certificate, as follows: 
    RACDCERT CERTAUTH 
EXPORT(LABEL(‘zOSMFCA’)) 
DSN('TYQTYQ.ZOSMFCA.CRT') 
FORMAT(CERTDER)
  7. Distribute the CA certificate to users. In an installation with many z/OSMF users, you must decide on an appropriate way to distribute the certificate, such as:
    • Sending the certificate to users in an email.
    • Allowing users to download the certificate from the mainframe by FTP.
    • Implementing a method for sending certificates to users automatically.
  8. Start of changeSet up the web browser with the CA certificate. For details, see Import the CA certificate into the client web browser.End of change
  9. Update the KEYRING_NAME parameter in the active IZUPRMxx parmlib member for your system: 
    KEYRING_NAME('IZUKeyring.IZUDFLT')

For related considerations, see Tips for proper set-up.

1b. Share an existing server certificate and key ring with the z/OSMF server

In this scenario, you share an existing certificate and key ring with the z/OSMF server. This procedure is shorter than 1a. Create a server certificate and key ring for the z/OSMF server because the CA certificate and key ring exist already.

Follow these steps:
  1. Authorize the z/OSMF server to use the key ring and the certificate, as described in Grant the z/OSMF server access to the key ring and the certificate.
  2. Export the CA certificate, as follows: 
    RACDCERT CERTAUTH 
EXPORT(LABEL(‘<label of the existing CA>’)) 
DSN('TYQTYQ.SOMECA.CRT') 
FORMAT(CERTDER)
  3. Distribute the CA certificate to users. In an installation with many z/OSMF users, you must decide on an appropriate way to distribute the certificate, such as:
    • Sending the certificate to users in an email.
    • Allowing users to download the certificate from the mainframe by FTP.
    • Implementing a method for sending certificates to users automatically.
  4. Start of changeSet up the web browser with the CA certificate. For details, see Import the CA certificate into the client web browser.End of change
  5. Update the KEYRING_NAME parameter in the active IZUPRMxx parmlib member for your system: 
    KEYRING_NAME('keyring.name')
  6. Grant the z/OSMF started task user ID access to the key ring and the certificate, as described in Grant the z/OSMF server access to the key ring and the certificate.
  7. Update the parameter KEYRING_NAME in the IZUPRMxx parmlib member:
    KEYRING_NAME('RING01’)
  8. Because the owner is not the z/OSMF started task user ID, you must create an override file that is named local_override.cfg in the user configuration directory, which is /global/zosmf/configuration/, by default. In the override file, add the following option, which indicates that the certificate and key ring are owned by BBGSRV, which is the WebSphere Liberty server user ID: 
    KEYRING_OWNER_USERID=BBGSRV

For related considerations, see Tips for proper set-up.

2a. Use client and server certificates from the same CA

In this scenario, you use client and server certificates that were generated by the same CA to enable client authentication with the z/OSMF server. This procedure assumes that you completed the steps in 1a. Create a server certificate and key ring for the z/OSMF server.

Follow these steps:
  1. Generate a client certificate from the same root CA. For example, assume that you want to create a client certificate with the label Certificate for user DEBUG41. This label is signed by the internal certificate authority (CA), which uses the label zOSMFCA. This certificate is created under the user ID DEBUG41.
    To create the client certificate signed by the internal CA, enter the following RACF command: 
    RACDCERT ID(DEBUG41) GENCERT SUBJECTSDN(CN('User DEBUG41') 
O('Your Company') OU('Org A') C('US')) WITHLABEL('Certificate for DEBUG41') 
SIGNWITH(CERTAUTH LABEL('zOSMFCA'))
    Where the distinguished name consists of the following properties:
    Common name (Domain Name)
    User DEBUG41
    Organization name
    Your Company
    Optional organizational unit
    Org A
    Country code
    US
    User ID under which the client certificate is to be added.
    DEBUG41
    Label of the client certificate
    Certificate for DEBUG41
    Label of the CA certificate that is used to sign the client certificate.
    zOSMFCA

    The client certificate is created with status TRUST, which indicates that the client certificate can be used to authenticate the user ID DEBUG41.

  2. Export the client certificate and provide it to the client, as described in the following example:
    1. To export the client certificate to a z/OS® data set, enter the RACDCERT command, as shown in the following example: 
      RACDCERT ID(DEBUG41) EXPORT(LABEL('Certificate for DEBUG41'))
DSN('TYQTYQ.CLIENTCR.DEBUG41.P12') FORMAT(PKCS12DER) PASSWORD('Test1234')
      Where:
      • DEBUG41 is the user ID associated with the client certificate to be exported.
      • Certificate for DEBUG41 is the label of the client certificate.
      • TYQTYQ.CLIENTCR.DEBUG41.P12 is the data set that will contain the client certificate.
      • PKCS12DER indicates that the client certificate and private key are DER encoded when saved to the data set.
      • Test1234 is the password that is associated with the encrypted certificate. You are required to provide this password when you import the client certificate into the browser. The password is case-sensitive.
    2. FTP the client certificate to the client's workstation. For details, see Transfer the client certificate from z/OS to the client workstation.
    3. Import the client certificate into the user's web browser. For details, see Import the client certificate into the client web browser.
  3. Export the CA certificate and provide it to the client if you have not already done so, as described in 1a. Create a server certificate and key ring for the z/OSMF server.

2b. Use a client certificate from a different CA

In this scenario, you use a client certificate that is generated by a different CA than was used for the server certificate. This procedure assumes that you completed the steps in 1a. Create a server certificate and key ring for the z/OSMF server.

Follow these steps:
  1. Obtain the client certificate from an external CA.
  2. Add the external root CA to RACF and connect it to the server key ring. In the following example, the label zOSMFEXTCA is assigned to the external CA.
    RACDCERT CERTAUTH 
ADD('TYQTYQ.ZOSMF.EXTCA.CRT')
WITHLABEL(‘zOSMFEXTCA’)

RACDCERT ID(IZUSVR) 
CONNECT(CERTAUTH LABEL('zOSMFEXTCA') 
RING(IZUKeyring.IZUDFLT)
)
  3. Place the client certificate and CA certificate in the web browser, as described in 2a. Use client and server certificates from the same CA.

Transfer the client certificate from z/OS to the client workstation

In the following example, the FTP command is used to transfer the PKCS12 data set that contains the signed client certificate to the client's workstation.

From the client workstation, do the following:
  1. Enter the FTP command and the hostname or IP address of the server, for example, ftp hostname.com.
  2. When prompted, enter your user ID and password.
  3. Enter bin to transfer the file in binary format.
  4. Transfer the file to the workstation by entering get 'TYQTYQ.CLIENTCR.DEBUG41.P12' debug41.p12
  5. Enter quit to exit.

Import the client certificate into the client web browser

In the following example, the PKCS12 file is imported into the Mozilla Firefox browser.

From the client workstation, do the following:
  1. Start the Firefox browser.
  2. Access the Certificate Manager by selecting Tools > Options > Privacy & Security > View Certificates.
  3. Under Certificate Manager, click Your Certificates.
  4. To import the certificate, click Import.
  5. Locate your PKCS12 certificate file and select it.
  6. Click Open and enter the case-sensitive password to be used for protecting the file.
  7. Click OK. The following message is displayed: "Successfully restored your security certificate(s) and private key(s)."
  8. Click OK. Verify that the certificate label is shown in the window These are Your Certificates.
  9. To make these changes effective, restart the browser.
Tip: For the Microsoft Edge browser, you can double-click the PKCS12 certificate file to import it.
Start of change

Import the CA certificate into the client web browser

In the following example, the CA certificate file is imported into the Mozilla Firefox browser.

From the client workstation, do the following:
  1. Start the Firefox browser.
  2. Access the Certificate Manager by selecting Tools > Options > Privacy & Security > View Certificates.
  3. Under Certificate Manager, click Authorities.
  4. To import the certificate, click Import.
  5. Locate the CA certificate file and select it.
  6. Click Open.
  7. Select Trust this CA to identify websites and click OK.
  8. To make these changes effective, restart the browser.
End of change

Grant the z/OSMF server access to the key ring and the certificate

You can use the RDATALIB class to grant the z/OSMF server access to the key ring, certificate, and private key, as described in the procedure that follows.
Before you begin:
  1. The RDATALIB class is case-insensitive.
  2. The RACF commands in this procedure are provided in the sample job IZUSKSEC.
Follow these steps:
  1. Define the RDATALIB class, as follows:
    RDEFINE RDATALIB <keyRingOwner>.<keyRingName>.LST UACC(NONE)

    Substitute the keyRingOwner and keyRingName with the actual key ring owner and key ring name.

    1. If the owner of the server certificate is the same as your z/OSMF started task ID (IZUSVR), enter the following command: 
      PERMIT <keyRingOwner>.<keyRingName>.LST CLASS(RDATALIB) ID(IZUSVR) ACCESS(READ)
    2. If the owner of the server certificate is not the same as your z/OSMF started task ID (IZUSVR), enter the following command:
      PERMIT <keyRingOwner>.<keyRingName>.LST CLASS(RDATALIB) ID(IZUSVR) ACCESS(UPDATE)
    3. If the owner of the server certificate is SITE, enter the following command:
      PERMIT <keyRingOwner>.<keyRingName>.LST CLASS(RDATALIB) ID(IZUSVR) ACCESS(CONTROL)
  2. If the RDATALIB class is not already active, activate it and RACLIST it, as follows:
    SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)
  3. If the RDATALIB class is already active and RACLISTed, refresh it, as follows:
    SETROPTS RACLIST(RDATALIB) REFRESH

Tips for proper set-up

Observe the following considerations:
  • The z/OSMF server certificate that is created by the RACDCERT command does not contain any certificate revocation information. If a web browser attempts to check revocation when it validates the server certificate, it will fail. As an alternative, consider obtaining the server certificate from z/OS PKI Services.
  • The IZUNUSEC and IZUSEC sample jobs provide commands for defining the z/OSMF server certificate and its local signing CERTAUTH certificate (a RACF defined CA). If you prefer, you can use an external CA instead of the local CA. If so, you must connect the external CA (which is used to sign the server certificate) into the key ring instead of the local CA.
  • The certificate must be marked TRUST. A NOTRUST certificate is ignored and is not loaded on server start-up.
  • The z/OSMF server key ring must contain a personal certificate that is owned by a personal ID. By default, the certificate is owned by the z/OSMF server started task user ID, which is IZUSVR. If the z/OSMF server started task user ID does not own the certificate, it must have authority to extract the private key. For more information, see Grant the z/OSMF server access to the key ring and the certificate.
  • If multiple personal certificates exist in the key ring that is owned by the z/OSMF server user ID, the most recently connected certificate is used.
  • The certificate must have the appropriate access to <ringOwner>.<ringName>.LST, as follows:
    • READ access to <ringOwner>.<ringName>.LST, if it is also the certificate owner.
    • UPDATE access to <ringOwner>.<ringName>.LST, if it is not the certificate owner.
    To avoid confusion, disable any certificates in the key ring that are not intended to be used, by doing either of the following actions:
    • Remove the certificates from the key ring.
    • Mark the certificates NOTRUST
  • z/OSMF is based on WebSphere® Liberty, which is in turn based on Java™. You can find more information about key ring and certificate setup in the Java security website: https://public.dhe.ibm.com/software/Java/Java11/IBMJCEHYBRID/HybridRefGuide.html.