Configure to use cryptographic tokens

Configure to use cryptographic tokens

+
Search Tips | Advanced Search

One can configure cryptographic token support in both client and server configurations. To configure a Java client application, use...
install_root/profiles/profile/properties/sas.client.props

To configure WebSphere Application Server, start the administrative console by specifying the following URL:
http://server_hostname:9060/ibm/console

Before you begin

To understand how to make WAS (both the run time and the key management utility) work correctly with any cryptographic token device, become familiar with the Java Secure Socket Extension (JSSE) documentation available in the http://www.ibm.com/developerworks/java/jdk/security/142/jsse2docs.zip. and http://www.ibm.com/developerworks/java/jdk/security/142/ikmuserguide.pdf files.
Follow the documentation that accompanies your device to install your cryptographic device. Installation instructions for IBM cryptographic hardware devices can be found in the Administration section of Security: Resources for learning.
Note: We cannot use cryptographic token devices when you enable the FIPS option on the Global security administrative console panel.
Important: To use iKeyMan for key management with a cryptographic token device, edit the file...
${WAS_INSTALL_ROOT}/java/jre/lib/security/java.security

Uncomment the line containing...
com.ibm.crypto.pkcs11.provider.IBMPKCS11

WebSphere Application Server runtime uses the IBMPKCS11Impl provider instead of the IBMPKCS11 provider for hardware crypto support. See http://www.ibm.com/developerworks/java/jdk/security/142/pkcs11implDocs.zip for more information. Refer to the "IBM Java PKCS 11 Implementation Provider.htm" document located in this zip file.
Note: To use cryptographic token devices in the Solaris Operating Environment, edit the file...
${WAS_INSTALL_ROOT}/java/jre/lib/security/java.security

Uncomment the line containing...
com.ibm.crypto.pkcs11.provider.IBMPKCS11

By default, the line is commented out because the algorithm MD4 is not present in the IBMPKCS11 provider.

Procedure

To configure a client to use a cryptographic token, edit the sas.client.props file and set the following properties. Leave the KeyStore File Name, KeyStore File Password, TrustStore File Name, and TrustStore File Password fields in a SSL configuration blank (or comment out the properties com.ibm.ssl.trustStore, com.ibm.ssl.trustStorePassword, com.ibm.ssl.keyStore, and com.ibm.ssl.keyStorePassword, using a # in front of the property name) , if you want to use only cryptographic tokens as your keystore.

com.ibm.ssl.tokenType

Specifies the type of built-in keystore file that is implemented in the cryptographic token. (For example, com.ibm.ssl.tokenType=PKCS\#11). The valid values are: PKCS\#7, PKCS\#11, PKCS\#12, and MSCAPI.

com.ibm.ssl.tokenLibraryFile

Specifies the token file name for PKCS#7 tokens, PKCS#12 tokens, and the library name for PKCS#11, MSCAPI tokens. Make sure the cryptographic token device is installed and functions properly with a cryptographic token created.

com.ibm.ssl.tokenPassword

Specifies the password to unlock the cryptographic token.

Configure your server to use the cryptographic device.
Leave the KeyStore File Name, KeyStore File Password, TrustStore File Name, TrustStore File Password fields in an SSL configuration blank, if you want to use only cryptographic tokens as your keystore. We can modify an existing configuration if you click...
Security | SSL | alias

You must specify an alias and select the Cryptographic token option. The following directions explain how to configure WAS for a new cryptographic device.

Specify http://server_hostname:9060/ibm/console to start the administrative console.
Click...
Security | SSL

...to open the SSL Configuration Repertoires panel.
You must decide if you want to modify existing SSL repertoire entries to convert them to use hardware cryptographic devices, or create new SSL repertoire entries for the new configuration. The former is easiest as this does not require you to change any of the alias references elsewhere in the configuration. Each protocol picks up the new configuration since it's already referencing these existing aliases. The latter is a little more difficult as you might not change every location that needs to be referenced by the new aliases. However, you have more control over which protocols actually use the cryptographic token device. If you want a specific protocol to use the cryptographic token device, it is best to create a new SSL repertoire for the cryptographic token device, then associate the alias of the new SSL repertoire with the SSL configuration of the specific protocol.
Click New JSSE Repertoire to create a new SSL setting alias if you do not want to use the default.
Specify an alias name in the alias field for the new cryptographic device. After you configure the cryptographic device, the alias appears on the SSL configuration repertoires panel. To access the panel, click...
Security | SSL | Cryptographic token check box | OK

This opens the Cryptographic token - General Properties panel.
Complete the information for Token Type to specify the type of built-in keystore file that is implemented in the cryptographic token. The valid values are: PKCS#7, PKCS#11, PKCS#12,or MSCAPI.
Complete the information for Library File to specify the path to the cryptographic device driver. Make sure the cryptographic token device is installed and functions properly with a new cryptographic token.
Complete the information for Password to specify the password for unlocking the cryptographic device.
Click OK. This returns you to the SSL configuration repertoires - General Properties panel for this alias.
Optionally, to configure a specific Token Slot for the cryptographic token device, click Custom Properties from the SSL configuration repertoires - General Properties panel. Add a new property name, com.ibm.ssl.tokenSlot, and a property value with the slot number, for example: 0. Optionally, to configure the selection of a specific inbound certificate alias (the alias selected for server transports) within the configured slot, add a new property name, com.ibm.ssl.keyStoreServerAlias, with a property value equal to the certificate alias name as it appears when viewing the slot through iKeyMan. Optionally, to configure the selection of a specific outbound certificate alias (the alias selected for client transports) within the configured slot, add a new property name, com.ibm.ssl.keyStoreClientAlias, with a property value equal to the certificate alias name as it appears when viewing the slot through iKeyMan, for example. Click OK to exit the Custom Properties panel and return to the SSL configuration repertoires - General Properties panel.
Make sure the SSL configurations when associated with a transport have the appropriate signers added to the truststore or cryptographic token device so that they can contact all servers for which they are configured. For example, any CSIv2 outbound transport should have signers for all CSIv2 inbound transports that they are connecting to. This means that all CSIv2 inbound keystores (or cryptographic token devices) must have the public key of personal certificates extracted, and added as signers to the CSIv2 outbound truststores (or cryptographic token devices).
The following lists the locations of where SSL configuration repertoire aliases are used in the WAS configuration:
For any transports that use the new NIO channel chains, including HTTP and JMS, one can modify the aliases from the following location for each server:

Click...
Server | Application server | servername | Communications | Ports

Locate a transport chain where SSL is enabled and click...
View associated transports | transport_channel_name | Transport Channels | SSL Inbound Channel (SSL_2)

Click...
System administration | Deployment manager | Additional properties | Ports

Locate a transport chain where SSL is enabled and click...
View associated transports | transport_channel_name | Transport Channels SSL Inbound Channel (SSL_2)

Click...
System administration | Node agents | node_agent _name | Additional properties | Ports

Locate a transport chain where SSL is enabled and click...
View associated transports | transport_channel_name | Transport Channels | SSL Inbound Channel (SSL_2)

For the Object Request Broker (ORB) SSL transports, one can modify the SSL configuration repertoire aliases in the following locations. These configurations are for the server-level for WAS and WAS Express and the cell level for WAS Network Deployment.

Click Security | Global security. Under Authentication, click Authentication protocol | CSIv2 Inbound Transport.
Click Security | Global security. Under Authentication, click Authentication protocol | CSIv2 Outbound Transport.
Click Security | Global security. Under Authentication, click Authentication protocol | SAS Inbound Transport.
Click Security | Global security. Under Authentication, click Authentication protocol | SAS Outbound Transport.

For the ORB SSL transports on the server level for WAS Network Deployment, one can modify the SSL configuration repertoire aliases in the following locations:

Click Servers | Application servers | servername. Under Security, click Server security. Under Additional properties, click CSIv2 Inbound Transport.
Click Servers | Application servers | servername. Under Security, click Server security. Under Additional properties, click CSIv2 Outbound Transport.
Click Servers | Application servers | servername. Under Security, click Server security. Under Additional properties, click SAS Inbound Transport.
Click Servers | Application servers | servername. Under Security, click Server security. Under Additional properties, click SAS Outbound Transport.

For the SOAP Java Management Extensions (JMX) administrative transports, one can modify the SSL configurations repertoire aliases by clicking Servers | Application servers | servername.
Under Server infrastructure, click Administration | Administration services. Under Additional properties, click JMX connectors | SOAPConnector. Under Additional properties, click Custom properties. If you want to point the sslConfig property to a new alias, click sslConfig and select an alias in the Value field.
For additional SOAP JMX administrative transports for WAS Network Deployment, one can modify the SSL configuration repertoire aliases in the following locations:

Click System administration | Deployment manager. Under Additional properties, click Administration services. Under Additional properties, click JMX connectors | SOAPConnector. Under Additional properties, click Custom properties. If you want to point the sslConfig property to a new alias, click sslConfig and select an alias in the Value field.
Click System administration | Node agents | node_agent_name. Under Additional properties, Administration services. Under Additional properties, click JMX connectors | SOAPConnector. Under Additional properties, click Custom properties. If you want to point the sslConfig property to a new alias, click sslConfig and select an alias in the Value field.

For the Lightweight Directory Access Protocol (LDAP) SSL transport, one can modify the SSL configuration repertoire aliases by clicking Security | Global security. Under User registries, click LDAP.
Finish configuring the SSL settings for this alias. When using hardware cryptographic tokens, use a JSSE provider of type IBMJSSE2. The IBMPKCS11Impl provider only works with the IBMJSSE2 provider.

Now that you have the aliases configured in the SSL configuration repertoires panel, associate the aliases with each protocol that needs to use them. If you edited existing aliases, you do not need to make any changes since they are already associated with SSL protocols. However, if you created new aliases and want to rearrange this existing alias association, then proceed to the next step.
Repeat steps a. through l. to edit existing or create new SSL configuration repertoires for creating a cryptographic token configuration for use by the IBMJSSE2 provider.
Click OK to complete the editing of the SSL configuration repertoire for this alias.

Result
The WAS configuration is configured to take advantage of a cryptographic token device for cryptographic functions used by SSL This can improve the system performance over software encryption when SSL is used to protect your data that is transferred over the network.

Example

What to do next
If the server configuration has changed, restart the configured server.

See also
Cryptographic token settings

Related Tasks
Manage digital certificates

See Also
Cryptographic token support