Integrated Cryptographic Service Facility (ICSF) is the
software on a z/OS system that serves as an interface with the hardware
where keys can be stored. IBMJCECCARACFKS keystores handle certificates
and keys managed in Resource Access Control Facility (RACF). The certificates
are stored in RACF, but you can store keys in ICSF or RACF. The IBMJCECCARACFKS
keystore will achieve hardware crypto exploitation, such as encryption,
decryption and signing, regardless if the keys are in stored in RACF
or in ICSF.
Before you begin
Before starting this task, you should become familiar with
the content of the topic Hardware cryptographic device support
for Web Services Security.
You must also:
- Ensure the necessary setup for placing your certificates in RACF
have been completed. Refer to the z/OS Information Center for the
version of z/OS that is running on your system, for information on
how to place your certificates in RACF
- Know the CSFSERV access permissions required for the ICSF Services
that the IBMJCECCA provider uses. Refer to the document Standard Edition,
Hardware Cryptography IBMJCECCA Overview for information about these
access permissions. This document is located at http://www.ibm.com/systems/z/os/zos/tools/java/products/j6jcecca.html
- Ensure that ICSF is running.
Note: The JCECCARACFKS keystore type, is only available
on the z/OS platform.
About this task
The JCECCAKS keystore is used for keys that you manage
and store directly in ICSF and requires that you include the IBMJCECCA
provider in the provider list specified in the java.security file.
The
JCECCARACFKS keystore is used for certificates and keys that you manage
in RACF. You store the certificates in RACF, and you can store the
keys in either RACF or ICSF. Using the JCECCARACFKS keystore type
requires that you include the IBMJCECCA provider in the provider list
specified in the java.security file. For JDK
5.0, you can achieve hardware crypto exploitation for performance
benefit even when your keys are not stored in the hardware.
The
JCERACFKS keystore is used with the IBMJCE provider or the IBMJCECCA
provider. You can use the JCERACFKS keystore for certificates and
keys that are managed and stored by RACF. You can achieve hardware
crypto exploitation for performance benefit, when using the IBMJCECCA
provider. The URI path reference for the JCERACFKS keystore is in
the form of safkeyring:///your_keyring_name.
Note: If
the key is going to be stored in the hardware, generating new keys
in RACF requires using the ICSF option.
Procedure
- Start the required ICSF services. Refer to
JAVA and ICSF documentation for more information.
- In the java.security file that is
located under $JAVA_HOME/lib/security, Uncomment
the following IBMJCECCA provider to the top of the provider list:
security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
Avoid trouble: $JAVA_HOME will be
WAS_HOME/AppServer/java64
when running in 64 bit mode, and $JAVA_HOME will be
WAS_HOME/AppServer/java
when running in 31 bit mode.
gotcha
- Renumber the remaining providers in the provider list.
- Navigate to Security > SSL certificate and key management
> Key stores and certificates.
- Click New to create a new a new keystore.
- Add the directory path to the keystore. The
URI must contain safkeyringhw instead of safkeyring, for example, safkeyringhw:///your_keyring_name.
- Select JCECCARACFKS for the Type and complete the
rest of the fields as appropriate.
If the token login
is required, type the keystore password in
the Password field.
To be compatible
with the JCE keystore in requiring a password, the JCERACFKS password
is password. Security for this keystore is
not really protected using a password as other keystore types, but
rather it is based on the identity of the executing thread for protection
with RACF. This password is for the keystore file that you specified
in the Path field.
Operations that use keys on the token require
a secure login. This field is optional if the keystore is used as
a cryptographic accelerator. In this case, you need to select the Enable
cryptographic operations on hardware device option.
- Click OK, then click Save to apply these
changes to the master configuration.
You might need
to restart the servers before these changes take affect.
Results
A keystore is now available to configure SSL connections.
What to do next
You can continue securing communication between the client
and server using this keystore file when setting up an SSL configuration.