Key manager control of X.509 certificate identities
The role of a Java™ Secure Socket Extension (JSSE) key manager is to retrieve the certificate that is used to identify the client or server during a Secure Sockets Layer (SSL) handshake.
- com.ibm.ssl.keyStoreClientAlias
- Defines the alias that is chosen from the keystore for the client side of a connection. This alias must be present in the keystore.
- com.ibm.ssl.keyStoreServerAlias
- Defines the alias that is chosen from the keystore for the server side of a connection. This alias must be present in the keystore.
With WebSphere Application Server, you can configure only one key manager at a time for a given SSL configuration. If you want custom certificate selection logic on the client side, you must write a new custom key manager. The custom key manager could provide function that prompts the user to choose a certificate dynamically. Also, you can implement an extended interface so that a key manager can provide information during connection time. For more information on the extended interface, see the com.ibm.wsspi.ssl.KeyManagerExtendedInfo interface. For more information on custom key manager development, see Creating a custom key manager for SSL.
Default IbmX509 key manager
The default IbmX509 key manager chooses a certificate to serve as the identity for an SSL handshake. The key manager is called to enable client authentication on either side of the SSL handshake; frequently on the server-side, and less frequently on the client side according to client and server requirements. If a keystore is not configured on the client-side and SSL client authentication is enabled, the key manager cannot select a certificate to send to the server. Therefore, the handshake fails.
<keyManagers xmi:id="KeyManager_1" name="IbmX509"
provider="IBMJSSE2" algorithm="IbmX509" keyManagerClass=""
managementScope="ManagementScope_1"/>
You do not specify
the keyManagerClass class because the key manager is provided by the
IBMJSSE2 provider. However, you can specify whether the key manager
is a custom class implementation, in which case you must specify the
keyManager class, or an algorithm name that WebSphere Application
Server can start from the Java security
provider framework.Custom key manager
The following sample code shows the key manager configuration in the security.xml file for a custom class.<keyManagers xmi:id="KeyManager_2" name="CustomKeyManager"
keyManagerClass="com.ibm.ws.ssl.core.CustomKeyManager"
managementScope="ManagementScope_1"/>
The custom class
must implement the javax.net.ssl.X509KeyManager interface and, optionally,
implement the com.ibm.wsspi.ssl.KeyManagerExtendedInfo interface to
retrieve additional WebSphere Application Server
information. This interface replaces the function of the default key
manager because you can configure only one key manager at a time.
Therefore, the custom key manager has sole responsibility for selecting
the alias to use from the configured keystore. The benefit of a custom
key manager is its ability, on the client side, to prompt for an alias.
This process enables the user to decide which certificate to use in
situations where the user knows the client certificate identity. For
more information, see Creating a custom key manager for SSL.