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
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", 
"oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token", 
"clientId": "9a919tf53ccf42d9b0c756312846ec98", 
"clientSecretPassword": "*******", 
"username": "testuser", 
"password": "*******" } ]
host Hostname or IP address of the EKMF Web server. ekmf_server_hostname
port Port number to access the EKMF Web server. 443
oidcUrl URL of the OIDC server for authenticating to the EKMF Web server. https://oidc-server/oidc/endpoint/EkmfOpenIdConnect/token
clientId Client ID. You can get this parameter value from the EKMF Web configuration. client1
clientSecretPassword Password associated with the client ID. You can get this parameter value from the EKMF Web configuration. client1_password
username Username of the EKMF Web server. You can get this parameter value from the EKMF Web configuration. user1
password Password associated with the username of the EKMF Web server. You can get this parameter value from the EKMF Web configuration. user1_password

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: In an OIDC authentication setup, ensure that the mtls parameter is set to false. Also, ensure that the master key alias is correct as 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": "TEMPGKLM",
        "mtls": "false",
        "masterkeyAlias": "MKEY123",
        "hosts": [
            {
                "host": "ekmf1.mycompany.com",
                "port": "443",
                "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
                "clientId": "9a919tf53ccf42d9b0c756312846ec98",
                "clientSecretPassword": "*******",
                "username": "testuser",
                "password": "*******"
            }
        ]
    }
    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": "TEMPGKLM",
        "mtls": "false",
        "masterkeyAlias": "MKEY123",
        "hosts": [
            {
                "host": "ekmf1.mycompany.com",
                "port": "443",
                "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
                "clientId": "9a919tf53ccf42d9b0c756312846ec98",
                "clientSecretPassword": "*******",
                "username": "testuser",
                "password": "*******"
            }
            {
                "host": "ekmf2.mycompany.com",
                "port": "443",
                "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
                "clientId": "9a919tf53ccf42d9b0c756312846ec98",
                "clientSecretPassword": "*******",
                "username": "testuser",
                "password": "*******"
            }
        ],
        "hostPreferenceSequence": [ 
                "ekmf1.mycompany.com", 
                "ekmf2.mycompany.com" 
         ]
    }
  5. To view the configured EKMF Web details, run the Get EKMF Web Configuration Settings REST Service.
    GET https://host:9443/SKLM/rest/v1/ckms/masterKey/EKMFWeb/config

What to do next

Complete steps 3 and 4:

Step 3: Import the EKMF Web certificate and OIDC server certificate. When you import the EKMF Web certificate, for the Trust this certificate for field, choose EKMF Web. Similarly, for the OIDC certificate choose OIDC. For instructions, see Importing a system peripheral certificate.

Step 4: Set up the master key in EKMF Web. For instructions, see Setting up the master key in EKMF Web.