com.ibm.websphere.crypto

Class KeySetHelper

java.lang.Object

com.ibm.websphere.crypto.KeySetHelper

public class KeySetHelper
extends java.lang.Object

This class provides function to return all keys or the latest keys from KeySetGroups managed in the configuration. Getting the latest keys is typically used for primary encryption/decription. Getting all the keys is typically used for secondary decryption/validation for cipher text which has been persisted for a while or which might linger in the runtime after a key change.

Since:

WAS 6.1

Version:

1.0

Constructor Summary

Constructors

Constructor and Description
KeySetHelper()

Method Summary

Methods

Modifier and Type	Method and Description
java.util.Map	getAllKeysForKeySet(java.lang.String keySetName) This method returns a Map containing all of the Keys for a specific KeySet in the configuration.
java.util.Map	getAllKeysForKeySetGroup(java.lang.String keySetGroupName) A KeySetGroup contains one or more KeySets.
static KeySetHelper	getInstance() This method returns an instance of the KeySetHelper class.
java.lang.Object	getLatestKeyForKeySet(java.lang.String keySetName) Returns the latest key for a specified KeySet.
java.util.Map	getLatestKeysForKeySetGroup(java.lang.String keySetGroupName) This method returns a Map containing the latest Keys for each KeySet specified for the KeySetGroup.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeySetHelper

public KeySetHelper()

Method Detail

getInstance

public static KeySetHelper getInstance()

This method returns an instance of the KeySetHelper class. This is the proper way to get a reference of this API class.

Returns:

KeySetHelper

getAllKeysForKeySetGroup

public java.util.Map getAllKeysForKeySetGroup(java.lang.String keySetGroupName)
                                       throws KeyException,
                                              java.lang.SecurityException

A KeySetGroup contains one or more KeySets. Each KeySet references keys in a KeyStore. The keys can either be auto-generated or they can be references of existing keys. This API returns the keys which are referenced by KeySets belonging to this KeySetGroup.

The keys returned are either java.security.Key references (which this API does not have any knowledge of the key type, algorithm, size, etc.) or it is a com.ibm.websphere.crypto.KeyPair which either references a java.security.cert.Certificate[] and java.security.PrivateKey OR a java.security.PublicKey and java.security.PrivateKey. The latter is done in cases where just a KeyPair is available without a certificate. This changes the way the key can be stored in the KeyStore.

This method returns a Map containing the versions (KeyReferences) of KeySets for the specified KeySetGroup name. The order should be first -> last (i.e., array element 0 is the oldest). If you need these in decending order, you can get the Set.toArray() and do a for loop starting from element array.length-1 to array.0.

Example of all keys in map sorted by version for CellLTPAKeySetGroup:

{ version_2={ LTPASecret_2=javax.crypto.spec.SecretKeySpec@16833, LTPAKeyPair_2=com.ibm.websphere.crypto.KeyPair@5e225e22}, version_3={ LTPASecret_3=javax.crypto.spec.SecretKeySpec@fffe8b59, LTPAKeyPair_3=com.ibm.websphere.crypto.KeyPair@1cec1cec}, version_4={ LTPAKeyPair_4=com.ibm.websphere.crypto.KeyPair@5bd45bd4, LTPASecret_4=javax.crypto.spec.SecretKeySpec@1781d} }

When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getKeySetGroups" to be granted for access to keys in any KeySetGroup. Otherwise, the permission WebSphereRuntimePermission "getKeySetGroups." can be granted for finer grained control.

Parameters:

String - keySetGroupName - the name of the KeySetGroup where keys are located.

Returns:

java.util.Map - a map containing the keys

Throws:

KeyException

java.lang.SecurityException

getLatestKeysForKeySetGroup

public java.util.Map getLatestKeysForKeySetGroup(java.lang.String keySetGroupName)
                                          throws KeyException,
                                                 java.lang.SecurityException

This method returns a Map containing the latest Keys for each KeySet specified for the KeySetGroup. The key from each KeySet with the highest version number will be returned.

Example of latest keys (in this case KeyReference version="4") returned for KeySetGroup "CellLTPAKeySetGroup":

{ LTPAKeyPair_4=com.ibm.websphere.crypto.KeyPair@5bd45bd4, LTPASecret_4=javax.crypto.spec.SecretKeySpec@1781d }

When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getKeySetGroups" to be granted for access to keys in any KeySetGroup. Otherwise, the permission WebSphereRuntimePermission "getKeySetGroups." can be granted for finer grained control.

Parameters:

String - keySetGroupName - the name of the KeySetGroup

Returns:

java.util.Map - a Map containing the latest keys.

Throws:

KeyException

java.lang.SecurityException

getAllKeysForKeySet

public java.util.Map getAllKeysForKeySet(java.lang.String keySetName)
                                  throws KeyException

This method returns a Map containing all of the Keys for a specific KeySet in the configuration. The parameter is the KeySet name. Keys for each KeyReference will be returned in the Map.

Example of all keys from KeySet name "CellLTPASecret":

{ LTPASecret_2=javax.crypto.spec.SecretKeySpec@16833, LTPASecret_3=javax.crypto.spec.SecretKeySpec@fffe8b59, LTPASecret_4=javax.crypto.spec.SecretKeySpec@1781d }

Example of all keys from KeySet name "CellLTPAKeyPair":

{ LTPAKeyPair_4=com.ibm.websphere.crypto.KeyPair@5bd45bd4, LTPAKeyPair_2=com.ibm.websphere.crypto.KeyPair@5e225e22, LTPAKeyPair_3=com.ibm.websphere.crypto.KeyPair@1cec1cec }

When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getKeySets" to be granted for access to keys in any KeySet. Otherwise, the permission WebSphereRuntimePermission "getKeySets." can be granted for finer grained control.

Parameters:

String - keySetName - the name of the KeySet.

Returns:

java.util.Map - a Map containing all keys for the specified KeySet.

Throws:

KeyException

getLatestKeyForKeySet

public java.lang.Object getLatestKeyForKeySet(java.lang.String keySetName)
                                       throws KeyException

Returns the latest key for a specified KeySet. The value is an Object containing either a java.security.Key instance or com.ibm.websphere. crytpo.KeyPair instance depending upon the KeySet type. A KeySet can either generate com.ibm.websphere.crypto.KeyPair (containing either java.security.cert.Certificate[] and java.security.PrivateKey OR java.security.PublicKey and java.security.PrivateKey. The object returned needs to be casted to the correct Object type based on knowledge of the KeySets key format. Both the caller of this API and the administrator configuring the KeySet should have knowledge of the key type.

Example of latest key from KeySet name "CellLTPASecret":

javax.crypto.spec.SecretKeySpec@1781d

Example of latest key from KeySet name "CellLTPAKeyPair":

com.ibm.websphere.crypto.KeyPair@5bd45bd4

When Java 2 Security is enabled, access to call this method requires WebSphereRuntimePermission "getKeySets" to be granted for access to keys in any KeySet. Otherwise, the permission WebSphereRuntimePermission "getKeySets." can be granted for finer grained control.

Parameters:

String - keySetName - the name of the KeySet.

Throws:

KeyException