Defining EKMF Web configuration properties in IBM Security Guardium Key Lifecycle Manager

Define the EKMF Web configuration properties in IBM® Security Guardium® Key Lifecycle Manager by using the REST interface.

About this task

To configure EKMF Web, you must define the following parameters in the IBM Security Guardium Key Lifecycle Manager:
Table 1. EKMF Web parameters
Parameter Description Sample value
templateName Name of the key template that you created in EKMF Web. TEMPGKLM
mTLS Set this property to true for mTLS communication between EKMF Web and IBM Security Guardium Key Lifecycle Manager. Possible values are true or false. For mTLS authentication, set it to true.
masterKeyAlias Specify a custom alias for the master key.

If no value is specified, by default the master key is created with an alias in the format KLMnKEY. Where, n is a number that automatically increments with every IBM Security Guardium Key Lifecycle Manager server that is configured with an EKMF Web host. For example, KLM1KEY, KLM2KEY.

The master key alias that you specify must contain only alphabets in uppercase and numbers and must be 7 characters long. For example, ALIAS123.
Note: Ensure that the master key is correct because after the master key alias is configured, it cannot be changed directly. If you want to change the master key alias, first migrate the master key store from EKMF Web to JCEKS and then reconfigure EKMF Web with the desired master key alias.
MKEY123
hostPreferenceSequence Specifies the preference order in which IBM Security Guardium Key Lifecycle Manager connects to the configured EKMF Web hosts.
hostPreferenceSequence": [ "ekmf1.mycompany.com", "ekmf2.mycompany.com" ] 
hosts List of hosts and their details.
"hosts": [ {"host": "ekmf1.mycompany.com", "port": "443"} ]
host Hostname or IP address of the EKMF Web server. ekmf_server_hostname
port Port number to access the EKMF Web server. 443

Procedure

  1. Open the Swagger UI. For more information, see Using Swagger UI.
  2. Authenticate and authorize to access the REST APIs. For more information, see Authentication process for REST services.
  3. Go to the Master key management section.
  4. Run the Update EKMF Web Configuration Settings REST Service to define the EKMF Web parameters in IBM Security Guardium Key Lifecycle Manager. To specify a custom master key alias, use the masterkeyAlias parameter.
    Note: Ensure that the master key alias is correct because it cannot be changed directly after it is configured. If you want to change the master key alias, first migrate the master key from EKMF Web to JCEKS, and then reconfigure EKMF Web with the desired master key alias.
    Configuring a single EKMF Web host
    POST SKLM/rest/v1/ckms/masterKey/EKMFWeb/config
    {
        "templateName": "TMPLGKLM",
        "mtls": "true",
        "masterkeyAlias": "MKEY123",
        "hosts": [
            {
                "host": "gklm.mycompany.com",
                "port": "443"
            }
        ]
    }
    Configuring multiple EKMF Web hosts
    To configure multiple EKMF Web hosts, specify the EKMF Web hosts and their details in the hosts parameter in comma-separated format.
    POST SKLM/rest/v1/ckms/masterKey/EKMFWeb/config
    {
      "templateName": "ARV4GKLM",
        "mtls": "true",
        "masterkeyAlias": "MKEY123",
        "hosts": [
             {
                "host": "ekmfweb_hostname1",
                "port": "19443"
            },
           {
               "host": "ekmfweb_hostname2",
                "port": "19443"
            }
       ],
       "hostPreferenceSequence": [
            "ekmf_hostname1",
            "ekmf_hostname2"
        ]
    }
  5. To view the configured EKMF Web details, run the Get EKMF Web Configuration Settings REST Service.
    GET https://host:port/SKLM/rest/v1/ckms/masterKey/EKMFWeb/config

What to do next

Set up the mTLS authentication between EKMF Web and IBM Security Guardium Key Lifecycle Manager. For instructions, see Setting up mTLS authentication.