Configure a key locator

The purpose of key locators is to find keys or certificates. The method used to find keys or certificates depends upon the key locator implementation. WebSphere Application Server - Express provides the following default implementations:

• KeyStoreKeyLocator
• WSIdKeyStoreMapKeyLocator
• CertInRequestKeyLocator

Typically, the default implementation that is used for request sending, request receiving, and response receiving is the KeyStoreKeyLocator implementation. The implementation for response sender, however, is usually different because of the need to determine what key to use so that the client understands the response. The server communicates with many clients that might have different keys. Therefore, for the proper response, the response sender typically uses a special key locator implementation. The two key locator implementations that handle this problem for the response sending logic are as follows:

• WSIdKeyStoreMapKeyLocator
• CertInRequestKeyLocator

The WSIdKeyStoreMapKeyLocator implementation checks the client credentials to determine which key is mapped and then uses that key for the response. The CertInRequestKeyLocator implementation uses the certificate that signed the received request to encrypt the response.

You can choose which implementation to use for your environment or you can write your own. Custom key locators must implement the com.ibm.wsspi.wssecurity.config.KeyLocator interface. With this implementation, you can locate keys from any data source you choose.

This topic focuses on configuring a key locator. See the following topics for more information:

• Key locators
• Key locator default implementation
• Develop a key locator

For more information about creating a key store, see Use Java keystore files in the Security topic.

You can configure key locators with the WebSphere Development Studio Client for iSeries or the WebSphere administrative console. See these topics for more information:

• Configure a key locator in the WebSphere Development Studio Client for iSeries
• Configure a key locator in the WebSphere administrative console
• Configure default key locators at the server level in the administrative console

Configure a key locator in the WebSphere Development Studio Client for iSeries

1. Open your deployment descriptor file in the WebSphere Development Studio Client for iSeries:

   • For a Web service application, open webservices.xml in the Web Services Editor.
   • For a Web service client, open webservicesclient.xml in the Web Services Client Editor.

   For more information, see Configure your Web services application.

2. Click the Port Binding tab in the Web Services Client Editor or the Binding Configurations tab in the Web Services Editor.

3. Expand one of the Binding Configuration sections. For example, expand Security Request Sender Binding Configuration section.

4. Expand the Key Locators section.

5. Click Add to create a new key locator, or click Edit to edit an existing one.

6. Enter a key locator name. The name entered for the key locator name is used to refer to the key locator from the Encryption information and Signing Information sections.

7. Enter a key locator class.The key locator class is the implementation of the KeyLocator interface. When using default implementations, select a class from the menu.

8. Determine whether to click Use key store. The default implementations all use key stores. Select this option when you use the default implementations. Specify the following information:

   1. Enter a key store storepass. The key store storepass is the password to access the key store.

   2. Enter a key store path. The key store path is the location on the file system where the key store resides. Make sure that the location can be found wherever you deploy the application.

   3. Enter a key store type.The valid types to enter are JKS and JCEKS. JKS is used when you are not using Java Cryptography Extensions (JCE). JCEKS is used when you are using JCE. Although the JCEKS type is more secure, it may decrease performance.

   4. Click Add to create an entry for a Key in the key store. Specify the following information:
      1. Enter a key alias. The key alias is a reference to this particular key from the Signing Information section.
      2. Enter a keypass. The keypass is the password that is associated with the certificate when it is created.
      3. Enter a key name. The key name refers to the alias of the certificate as found in the key store.

9. Click Add to create a custom property. The property can be used by custom implementations of KeyLocator. For example, you can use properties with the WSIdKeyStoreMapKeyLocator default implementation. The KeyLocator has the following property names:

   • id_, which maps to a credential user ID
   • mappedName_, which maps to the key alias to use for this user name
   • default, which maps to a Key alias to use when a credential does not have an associated id_ entry

   A typical set of properties for this key locator could be id_1=user1, mappedName_1=key1, id_2=user2, mappedName_2=key2, default=key3. If user1 or user2 authenticates, then the associated key1 or key2 is used, respectively. However, if none of the user properties authenticate or the user is not user1 or user2, then key3 is used.

   1. Enter a Name.The name entered is the property name.
   2. Enter a Value. This value entered is the property value.

10. Save the file.

11. Repeat the process until you have configured the necessary key locators for your applications.

Configure a key locator in the WebSphere administrative console

You can configure binding information in the administrative console, but for extensions, you must use the WebSphere Development Studio Client for iSeries.

Perform the following steps in the administrative console to configure a key locator for a specific application:

1. Click Applications --> Enterprise Applications --> application_name, where application_name is the name of your application. Under Related Items, click Web Modules.

2. Click the name of the module you are securing.

3. Under Additional Properties, click either Web Services: Client Security Bindings or Web Services: Server Security Bindings depending on whether you are adding the key locator to the client security bindings or the server security bindings.

   If you do not see any entries, return to the WebSphere Development Studio Client for iSeries and configure the security extensions.

4. Complete either of the following steps:

   • If you are editing your client security bindings, click Edit for either the Request Sender Binding or Response Receiver Binding.
   • If you are editing your server security bindings, click Edit for either the Request Receiver Binding or Response Sender Binding.

5. Click Key Locators. The same information that was used to configure a key locator with the WebSphere Development Studio Client for iSeries applies at this point in the steps. See step 5 in Configure a key locator in the WebSphere Development Studio Client for iSeries.

Configure default key locators at the server level in the administrative console

A key locator typically locates a key store in the file system. The location of key stores can vary from machine to machine so it is often helpful to configure a default key locator for a specific machine and reference it from within the encryption or signing information. This information is found within the binding configurations of any application installed on that machine. This suggestion enables you to define a single key locator for all applications that need to use the same keys.

Perform the following steps in the WebSphere administrative console to configure default key locators at the server level:

1. Click Servers --> Application Servers --> server_name, where server_name is the name of your application server.

2. Under Additional Properties, click Web Services: Default bindings for Web Services Security.

3. Click Key Locators. The same information that was used to configure a key locator using the WebSphere Development Studio Client for iSeries applies at this point in the steps. See step 5 in Configure a key locator in the WebSphere Development Studio Client for iSeries.