(zos)

Configure the root certificate keyring

WebSphere Application Server provides the function to allow a WAS administrator to perform certificate management operations on System Authorization Facility (SAF) keyrings by utilizing the (Open Cryptographic Services Facility) OCSF Data library functions for SAF keyrings. This task configures the root certificate keyring.

We must enable support for writable keyrings using the profile management tool prior to generating the application server profiles. Writable keyring support is only configurable when running z/OS Release 1.9 or at z/OS Release 1.8 with APAR OA22287 - resource access control facility (RACF ) (or the APAR for the equivalent security product) and APAR OA22295 - SAF.

The root certificate authority (CA) certificate is used to sign other certificates for WebSphere Application Server. By default, during profile management, the default root keying (NodeDefaultRootStore or DmgrDefaultRootStore for a deployment manager), and the root CA certificate, are automatically configured. Alternatively, if migrating from a pervious WebSphere Application Server installation, we can set up the root keyring for a keystore object using the following steps.

1. Create a keyring for the control region RACF ID for the sever. For example, if the server is running with a RACF user ID called CRRACFID, issue the following command:
   RACDCERT ADDRING(keyring_name.Root) ID(CRRACFID)

   CRRACFID is the RACF ID for the application server control region. keyring_name is the name of the z/OS keyring used by the servers in the cell.

2. To create chained certificates with the root CA certificate, the keyring created in the step (1) must include the public/private key CA certificate generated for the WAS installation. To connect the certificate, you must complete the following step:

   Determine the label name of the root CA certificate for the installation and issue the following command:

   RACDCERT ID(CRRACFID) CONNECT (RING(keyring_name.Root) LABEL('rootcalabel') CERTAUTH USAGE(PERSONAL))

   CRRACFID is the RACF ID for the application server control region. keyring_name is the name of the z/OS keyring used by the servers in the cell. rootcalabel is the root CA certificate

3. Modify NodeDefaultRootStore (DmgrDefaultRootStore for deployment manager) to point to the keyring created in step (1).

   1. Click Security > SSL certificate and key management > Key stores and certificates

   2. Select Root Certificates Keystore under Keystore usages

   3. Select NodeDefaultRootStore ( or DmgrDefaultRootStore for deployment manager).

   4. Under General Properties

      1. Modify the Path
         safkeyring://CRRACFID/keyring_name.Root

         CRRACFID is the RACF ID for the application server control region. keyring_name is the name of the z/OS keyring used by the servers in the cell.

      2. Change the type to JCERACFKS

      3. Enter the password, password.

   5. Click Apply.

Results

After completing these steps, a new z/OS keyring is created containing the root CA certificate attached with the personal usage.

What to do next

Verify that the keystore was modified successfully.

1. Under Additional Properties, on the keystore collection panel, click Personal Certificates.

2. Verify that the certificate appears in the list.

Known error conditions

• When attempting to create a new keyring the follow error message can occur:

  R_datalib (IRRSDL00) error: One or more updates could not be completed.
  Requested Function_code not defined.
  Function code: (7) Return Codes: (8, 8, 20)

  This message indicates that you attempted to create a new keyring and did not have native writable support installed. We must be running at z/OS release 1.9 or 1.8 with APAR's OA22287 and OA22295.

• The following message can occur when attempting to perform write operations on a SAF keyring, operations such as, creating or deleting a certificate:
  Error Message: An error occurred creating the key store: R_datalib (IRRSDL00) error: One or more updates could not be completed. Not RACF authorized to use the requested service. Function code: (7) Return Codes: (8, 8, 8)

  This message is received if we have not defined the correct RACF authority. See the document Define RACF authority for Clients and Servers in the z/OS internet library http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/.

• The following message can occur when performing write operations if the underlying keyring does not exist in RACF.
  R_datalib (IRRSDL00) error: profile for ring not found (8, 8, 84)

  Ensure the keyring exists in RACF prior to performing certificate management write operations.

Related tasks

Create writable SAF keyrings

Enable writable SAF keyrings

Use writable SAF keyrings