Accessing external key manager services

Configure a key manager adapter to access external key manager services.

About this task

A key management service is needed to manage keys for data encryption software. You must create an external key adapter to interact with external key management services.
The key manager adapter must contain a class that implements the following key manager interface:
A constructor that accepts a Properties object
The Properties object contains the BASE_DIR attribute. This attribute is used to locate the file path of the key manager adapter, from the local directory. Use this attribute to access any other data files such as configuration file that is included in the adapter's compressed file.
public Properties createKey(String keyType) throws Exception
This method creates a key of the given key type from external key manager. The method then returns a Properties object containing the following attributes and values:
key
The Base64 encoded key
id
The identifier that is used to reference the key
Note: The value of the keyType attribute depends on the supported encryption specification of the key manager.
Throw an exception when the key type is not supported, or the key creation failed.
public String getKey(String id) throws Exception
This method returns the Base64 encoded key of the matching identifer from target key manager. Throw an exception when it fails to get the key, or if the key does not exist.
public boolean removeKey(String id) throws Exception
This method returns true if the key of matching identifier is successfully removed from target key manager. Throw an exception for errors that occur while a key is being removed from the key manager.
public String resetKey(String id, String keyType) throws Exception
This method returns a newly generated key of the specified key type, of the matching identifier from key manager system.
Note: The value of the keyType attribute depends on the supported encryption specification of the key manager.
Throw an exception if the identifer does not exist, or the key type is not supported, or if the key reset failed.

Procedure

  1. Create a main .jar file that contains a class that implements the key manager adapter interface.
  2. Gather any .jar files that the main .jar file depends upon to run.
    Note: The key manager adapter uses a configuration file to configure itself. The content of the configuration file includes information such as the IP address and port numbers of the target key manager server. You can update the contents of the configuration file before you register the adapter. Updating the configuration file with appropriate data ensures that the adapter works properly on the system.
  3. Create an info.json file.
    The info.json file must contain information about the key manager adapter. The Class attribute with a fully qualified class name as its value is required. The following example illustrates how the class attribute is written.
    {"class":"com.some.company.KeyMgrAdapter"}
  4. Create a compressed file.

    Ensure that the compressed file contains all .jar files, the configuration file, and the info.json file.

What to do next

Register your key manager adapter.
  1. Click System > Key Manager Adapters
  2. Click Register
  3. Type a name for your adapter in the Name field.
  4. Type a description of your adapter in the Description field.
  5. Click Browse to find and select the compressed file you created.

    Selecting your compressed file will prompt the adapter registration.

    Note: If your key manager adapter requires a trust relationship, the certificate exchange between the key manager server and Cloud Pak System Software must be processed manually.

You can also delete a key manager adapter from the list by selecting the key manager adapter and clicking Delete.