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.
Important: To
use iKeyman for key management with a cryptographic token device, you must
edit the
app_server_root/java/jre/lib/security/java.security file.
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 cryptography support. For more information
on the IBMPKCS11Impl provider, see the DeveloperWorks Security Information Web site. On this
Web site, select the appropriate Java 2 Platform, Standard Edition (J2SE)
version and read the IBMPKCS11Impl documentation. The documentation is not
available for J2SE 1.4.2 for Intel 32-bit Debug Platforms and z/OS64 and AMD
64.
Note: To
use cryptographic token devices in the Solaris Operating Environment, you
must edit the
app_server_root/java/jre/lib/security/java.security file.
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 Secure Sockets Layer (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 properties, using a number sign (# )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 that 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. 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.
- Specify http://server_hostname:port_number/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 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.
- 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 displays on the Secure Sockets Layer (SSL) configuration repertoires
panel. To access the panel, click Security > SSL.
- Select the Cryptographic token check box and click OK.
The Cryptographic token - General Properties panel is displayed.
-
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 that 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 action returns you to the SSL configuration
repertoires - General Properties panel for this alias.
- Optional:
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.
- Add a property value with the slot number; for example: 0.
- Click OK to exit the Custom Properties panel and return to the
SSL configuration repertoires - General Properties panel.
- Optional:
To configure the selection of a specific inbound certificate alias (the
alias selected for server transports) within the configured slot:
- Click Custom Properties from the SSL configuration
repertoires - General Properties panel.
- Add a new property name, com.ibm.ssl.keyStoreServerAlias.
- Add a property value that is equal to the certificate alias name as it
displays when viewing the slot through iKeyMan.
Note: If a colon(:)
exists, the certificate alias name is only what is displayed after the colon.
- Click OK to exit the Custom Properties panel and return to the
SSL configuration repertoires - General Properties panel.
- Optional:
To configure the selection of a specific outbound certificate alias,
the alias selected for client transports, within the configured slot:
- Click Custom Properties from the SSL configuration
repertoires - General Properties panel.
- Add a new property name, com.ibm.ssl.keyStoreClientAlias.
- Add a property value that is equal to the certificate alias name as it
displays when viewing the slot through iKeyMan.
Note: If a colon(:) exists,
the certificate alias name is only what is displayed after the colon.
- Click OK to exit the Custom Properties panel and return to the
SSL configuration repertoires - General Properties panel.
- 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.
- 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.
- 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 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.
- 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.
- 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.
- 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.
- 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.