Before you can configure WebSphere Application Server to support hardware cryptography, you must complete the following steps to set up the Linux for System z hardware. Unless otherwise indicated, the steps in this document are identical for both the SUSE Linux Enterprise Server and Red Hat Enterprise Linux operating systems.

Install the OpenCryptoki, and libica software files. These software files are provided by the software vendor for your Linux operating system. Generally, these files are part of the Linux installation image.

Enter the following command to load the z90crypt device driver and then verify that it is running:

# rcz90crypt start

# modprobe z90crypt

The command results in the following message:

Loading z90crypt module done

Enter the following command to verify that the z90crypt daemon is running:

# rcz90crypt status

The command results in the following message: Checking for module z90crypt: running

Enter the following command to verify that the device driver has loaded and a hardware cryptography card is available:

In the previous results, the total device count is 1. This value indicates that the cryptographic device is available. Also, the previous results show that the CEX2A count field value is 1. This value indicates that the Cryptographic Express 2 Feature is in the accelerator mode.

Enter the following command to start the pkcsslotd daemon:

# rcpkcsslotd start

The command results in a response that is similar to the following message:

Starting pkcsslotd daemon:usermod: `root' is primary group name.

# /etc/init.d/pkcsslotd start

The command results in a response that is similar to the following message:# [ OK ]

Enter the following command to verify that the pkcsslotd daemon is running:

# rcpkcsslotd status

The command results in the following message:

Checking for service pkcsslotd: running

# /etc/init.d/pkcsslotd status

The command results in a response that is similar to the following message:

In the previous results, the total device count value is 1. This value indicates that the cryptographic device is available. Also, the previous results show that the CEX2C count field value is 1. This value indicates that the Cryptographic Express 2 is in the coprocessor mode.

Note: For the Crypto Express 2 card to successfully process cryptographic operations, the certificate must have a Public Key Modulus value that is greater than the signature value. For more information, see Appendix A: Displaying the public key modulus and signature files of a certificate. If the Public Key Modulus value is not greater, the Crypto Express 2 card in the coprocessor mode rejects the cryptographic operation. In some instances, the cryptographic device is disabled, which results in subsequent cryptographic operations being completed by the software. On the SUSE Linux Enterprise Server Version 10 SP 3 operating system, the following message is displayed in the /var/log/messages file:

To re-enable the device, use the vi editor to modify the /proc/driver/z90crypt file and change the d in boldface type within the previous example to e. After making the change and saving the file, the cryptographic device is re-enabled.

Verify whether the PKCS#11 cryptographic token is initialized. You must initialize the token before using it. To check the status of the PKCS#11 cryptographic token, enter the following command:

In the previous example, the label value is set to the default IBM ICA PKCS #11 value. You need to change this value. Also, the SO pin and the USER pin values are not set. Thus, this token is not initialized. If the token is initialized, there is a label value and the Flags value confirms that initialization is complete. For example:

When the CPACF feature is active on the machine, the command displays a yes response for all of the operations on a z10 machine. Machines that are prior to z10 display a yes response for the operations that are supported by that machine type.

After you configure the Linux for System z hardware for cryptography, you must configure WebSphere Application Server. Ensure that you are using WebSphere Application Server Version 7.0.0.7 with the Java™ SDK cumulative fix before completing the following steps:

Backup your WebSphere Application Server configuration and the original files in the /opt/IBM/WebSphere/AppServer/java directory to be able to restore the original configuration later.

Download the unlimited jurisdiction policy files and install them in the following directory location:/opt/IBM/WebSphere/AppServer/java/jre/lib/security Complete the following steps to obtain these policy files from the IBM developerWorks Web site:

Add the com.ibm.ws.security.ltpa.forceSoftwareJCEProviderForLTPA custom property with a true value for the deployment manager, the node agent, and each application server. For more information on this custom property, read the Java™ virtual machine custom properties topic in the Version 7.0 Information Center.

The following table shows the paths to follow through the administrative console to set the custom property.

Change the Secure Sockets Layer (SSL) cell settings to use a higher-strength cipher such as DES, 3DES, or AES128. For example, change the settings to use the SSL_RSA_WITH_3DES_EDE_CBC_SHA 3DES cipher group. Complete the following steps in the administrative console to make these changes:

Verify that the SSL_RSA_WITH_3DES_EDE_CBC_SHA cipher is listed in the Selected ciphers list.

Click OK and save the changes directly to the master configuration.

Optional: If the application server is running under a functional ID, modify the PKCS11 group to include the user. For example, if the application server is running under the wasadmin functional ID, run the following command:

usermod -G pkcs11 wasadmin

This command adds the wasadmin user to the pkcs11 group.

Restart WebSphere Application Server.

Request an application, for example, snoop, and verify that the counters increase when cryptography is used. To verify, run the following command before requesting the snoop application:# cat /proc/driver/z90crypt The command results in a response that is similar to the following information:

After you configure WebSphere Application Server to enable hardware cryptography, configure the IBM HTTP Server. Complete the following steps:

Obtain a personal certificate from a recognized certificate authority. For more information, read about creating a certificate authority request in the Version 7.0 Information Center. For testing purposes, these steps use a self-signed certificate.

Under the /opt/IBM/HTTPServer/java/jre/lib/ext/ directory, remove the gskikm.jar file.

IMPORTANT: Do not perform this step if you are using IBM HTTP Server Version 8.0 or higher.

Click OK. The cryptographic token information, which was configured with the "Set up the Linux for System z hardware" steps, shows in the Open Cryptographic Token window. You must enter the Cryptographic Token Password. This value is the User Pin value that you previously set in the "Set up the Linux for System z hardware" steps.

Clear the Open existing secondary key database check box.

Click OK. A window opens with the key database information.

Click Create > New Self-Signed Certificate.

Enter a value in the Key Label, Version, and Key Size fields. Also, optionally, enter a value for the other fields on the Create New Self-Signed Certificate panel.

Click OK. The new self-signed certificate is displayed in the list of available personal certificates.Note: Use a self-signed certificate for testing purposes only. For production, obtain a certificate from a known certificate authority. The Key database content lists the name of the certificate. This value is also used in the httpd.conf file for a subsequent step.

Modify the PKCS11 group to contain the "nobody" user. For this example, the "nobody" user is running the IBM HTTP Server.Enter the following commands to modify the group:

Extract the certificate and public key to a file in the Privacy Enhanced Mail (PEM) format. To extract the certificate and the public key, you can use the iKeyman Extract function. The contents of the file will look similar to the following example: