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
- 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.
- 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
- Modify NodeDefaultRootStore (DmgrDefaultRootStore for
deployment manager) to point to the keyring created in step (1).
- Click Security > SSL certificate and key management > Key
stores and certificates
- Select Root Certificates Keystore under Keystore usages
- Select NodeDefaultRootStore ( or DmgrDefaultRootStore for
deployment manager).
- Under General Properties
- 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.
- Change the type to JCERACFKS
- Enter the password, password.
- 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.
- Under Additional Properties, on the keystore collection panel, click Personal
Certificates.
- 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 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.