Key locator

A key locator (com.ibm.wsspi.wssecurity.config.KeyLocator) is an abstraction of the mechanism that retrieves the key for digital signature and encryption.

There is an important distinction between V5.x and Version 6.0.x applications. The information in this article supports Version 5.x applications only that are used with WAS V6.0.x and later. The information does not apply to V 6.0.x applications.

Use any of the following infrastructure from which to retrieve the keys depending upon the implementation:

• Java keystore file

• Database
• LTPA server

Key locators search the key using some type of a clue.

The following types of clues are supported:

• A string label of the key, which is explicitly passed through the API. The relationships between each key and its name (string label) is maintained inside the key locator.

• The execution context of the key locator; explicit information is not passed to the key locator. A key locator determines the appropriate key according to the execution context.

Current versions of key locators do not support the retrieval of verification keys because current WS-Security implementations do not support the secret key-based signature. Because the key locators support the public key-based signature only, the key for verification is embedded in the X.509 certificate as a <BinarySecurityToken> element in the incoming message.

For example, key locators can obtain the identity of the caller from the context and can retrieve the public key of the caller for response encryption.

 

Usage scenarios

This section describes the usage scenarios for key locators.

Signing

The name of the signing key is specified in the WS-Security configuration. This value is passed to the key locator and the actual key is returned. The corresponding X.509 certificate also can be returned.

 

Verification

As described previously, key locators are not used in signature verification.

Encryption

The name of the encryption key is specified in the WS-Security configuration. This value is passed to the key locator and the actual key is returned.

Decryption

The WS-Security spec recommends using the key identifier instead of the key name. However, while the algorithm for computing the identifier for the public keys is defined in IETF RFC 3280, there is no agreed upon algorithm for the secret keys. Therefore, the current implementation of WS-Security uses the identifier only when public key-based encryption is performed. Otherwise, the ordinal key name is used.

When you use public key-based encryption, the value of the key identifier is embedded in the incoming encrypted message. Then, the WS-Security implementation searches for all the keys managed by the key locator and decrypts the message using the key whose identifier value matches the one in the message.

When you use secret key-based encryption, the value of the key name is embedded in the incoming encrypted message. The WS-Security implementation asks the key locator for the key with the name that matches the name in the message and decrypts the message using the key.

---

 

Related concepts

Binary security token

 

Related tasks

Secure Web services for V5.x applications using XML digital signature