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. Starting in JDK 5.0, 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
Note: The JCECCARACFKS keystore type, is only available
on the z/OS platform.
About this task
The IBMJCECCA provider replaces
the IBMJCE4758 provider that is deprecated beginning with JDK 5.0.
The JCE4758KS keystore and the JCE4758RACFKS keystore are also deprecated
beginning with JDK 5.0. The JCECCAKS keystore replaces the JCE4758KS
keystore and the JCECCARACFKS keystore replaces the JCE4758RACFKS
keystore.
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. New for JDK 5.0, 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
- Make a backup copy of the original restricted local_policy.jar and US_export_policy.jar files.
- Obtain the Java unrestricted policy jars from the IBM developer kit: Security information Web
site and place them on the WebSphere Application Server for z/OS system.
Important: Your country of origin
might have restrictions on the import, possession, use, or re-export
to another country, of encryption software. Before downloading or
using the unrestricted policy files, you must check the laws of your
country, its regulations, and its policies concerning the import,
possession, use, and re-export of encryption software, to determine
if it is permitted.
Complete the following steps:
- Click J2SE 5.0.
- Scroll down the page then click IBM SDK Policy files.
- Click Sign in and provide your IBM.com ID and password.
- Select Unrestricted JCE Policy files
for SDK for all newer versions: Version 1.4.2 + and click Continue.
- View the license, select I agree, and click I confirm to continue.
- Click Download now.
- Download the unrestricted local_policy.jar and US_export_policy.jar files to your WebSphere
Application Server for z/OS system and place them in the WAS_HOME/AppServer/java/lib/security directory.
- Use the chmod 644 command to change the file permissions
so that the control and servant region address spaces can access the
Java archive (JAR) files. For example:
chmod 644 local_policy.jar
chmod 644 US_export_policy.jar
- 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
- 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.
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.