Configuring to use cryptographic tokens

You can configure cryptographic token support in both client and server configurations. To configure a Java client application, use the sas.client.props configuration file. To configure WebSphere Application Server, start the administrative console by specifying the following URL: http://server_hostname:port_number/ibm/console.

Before you begin

By default, the sas.client.props file is located in the profile_root/properties/ directory of your WebSphere Application Server installation.

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: You cannot use cryptographic token devices when you enable the Federal Information Processing Standard (FIPS) option on the Global security administrative console panel.

Procedure

  1. To configure a client to use a cryptographic token, edit the sas.client.props file and set the following properties. Fill in the KeyStore File Name, KeyStore File Password, TrustStore File Name, and TrustStore File Password fields in the Secure Sockets Layer (SSL) configuration. Leave the com.ibm.ssl.tokenType, com.ibm.ssl.tokenLibraryFile, and com.ibm.ssl.tokenPassword fields blank.
  2. Configure your server to use the cryptographic device.

    Fill in the KeyStore File Name, KeyStore File Password, TrustStore File Name, TrustStore File Password fields in an SSL configuration. You 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 WebSphere Application Server for a new cryptographic device.

    1. Specify http://server_hostname:port_number/ibm/console to start the administrative console.
    2. 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 approach is easiest, this approach does not require you to change any of the alias references elsewhere in the configuration. Each protocol picks up the new configuration because it is 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, 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.
    3. Click New JSSE Repertoire to create a new SSL setting alias if you do not want to use the default.
    4. Specify an alias name in the alias field for the new cryptographic device. After you configure the cryptographic device, the alias displays on the Secure Sockets Layer (SSL) configuration repertoires panel. To access the panel, click Security > SSL.
    5. Select the Cryptographic token check box and click OK. The Cryptographic token - General Properties panel is displayed.
    6. Make sure that 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 the servers for which they are configured. For example, any Common Secure Interoperability Version 2 (CSIv2) outbound transport has signers for all CSIv2 inbound transports that they are connecting to. 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.
    7. The following section lists the locations where SSL configuration repertoire aliases are used in the WebSphere Application Server configuration:
      For any transports that use the new Network Input Output (NIO) channel chains, including HTTP and Java Message Service (JMS), you can modify the aliases from the following location for each server:
      • Click Server > Application server > server_name
      • Under Communications, click Ports.
      • Locate a transport chain where SSL is enabled and click View associated transports > transport_channel_name.
      • Under Transport Channels, click SSL Inbound Channel (SSL_2).
      • Click System administration > Deployment manager.
      • Under Additional properties, click Ports.
      • Locate a transport chain where SSL is enabled and click View associated transports > transport_channel_name.
      • Under Transport Channels, click SSL Inbound Channel (SSL_2).
      • Click System administration > Node agents > node_agent _name.
      • Under Additional properties, click Ports.
      • Locate a transport chain where SSL is enabled and click View associated transports > transport_channel_name.
      • Under Transport Channels, click SSL Inbound Channel (SSL_2).
      For the Object Request Broker (ORB) SSL transports, you can modify the SSL configuration repertoire aliases in the following locations. These configurations are for the server-level for WebSphere Application Server and WebSphere Application Server Express and the cell level for WebSphere Application Server 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 WebSphere Application Server Network Deployment, you can modify the SSL configuration repertoire aliases in the following locations:
      • Click Servers > Application servers > server_name.
      • Under Security, click Server security.
      • Under Additional properties, click CSIv2 Outbound Transport.
      • Click Servers > Application servers > server_name.
      • Under Security, click Server security.
      • Under Additional properties, click SAS Inbound Transport.
      • Click Servers > Application servers > server_name.
      • Under Security, click Server security.
      • Under Additional properties, click SAS Outbound Transport.
      For the SOAP Java Management Extensions (JMX) administrative transports, you can modify the SSL configurations repertoire aliases by clicking Servers > Application servers > server_name.
      1. Under Server infrastructure, click Administration > Administration services.
      2. Under Additional properties, click JMX connectors > SOAPConnector.
      3. Under Additional properties, click Custom properties.
      4. 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 WebSphere Application Server Network Deployment, you 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, you can modify the SSL configuration repertoire aliases by clicking Security > Global security. Under User registries, click LDAP.

    8. Finish configuring the SSL settings for this alias. When using hardware cryptographic tokens, you must use a Java Secure Sockets Extension (JSSE) provider of type IBMJSSE2. The IBMPKCS11Impl provider only works with the IBMJSSE2 provider.
  3. Now that you have the aliases configured in the SSL configuration repertoires panel, you must associate the aliases with each protocol that needs to use them. If you edited existing aliases, you do not need to make any changes because the aliases are already associated with SSL protocols. However, if you created new aliases and want to rearrange this existing alias association, proceed to the next step.
  4. Repeat steps a. through n. to edit existing or create new SSL configuration repertoires for creating a cryptographic token configuration for use by the IBMJSSE2 provider.
  5. Click OK to complete the editing of the SSL configuration repertoire for this alias.

Results

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

Example

WebSphere Application Server uses the cryptographic token as a keystore file for the SSL connection.

What to do next

If the server configuration has changed, restart the configured server.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Aug 29, 2010 8:25:23 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=vela&product=was-nd-zos&topic=tseccrypto
File name: tsec_crypto.html