[z/OS]

Configuring the root certificate keyring

WebSphere® Application Server provides the function to allow a WebSphere Application Server 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.

Before you begin

You 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 your equivalent security product) and APAR OA22295 – SAF.

About this task

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, you can set up the root keyring for a keystore object using the following steps.

Procedure

  1. Create a keyring for the control region RACF ID for your sever. For example, if your 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 that is 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 your WebSphere Application Server installation. To connect the certificate, you must complete the following step:

    Determine the label name of the root CA certificate for your 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 that is 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 that is 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 that contains 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. You 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 you have not defined the correct RACF authority. See the document Defining RACF authority for Clients and Servers in the z/OS Internet Library.
  • 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.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: March 5, 2017 17:29
File name: tsec_7configureSAF_keyring.html