Master Key REST Service

Use Master Key REST Service to create an IBM Security Guardium Key Lifecycle Manager master key of the length that you specify for encryption of keys. If a key exists in the keystore, then the new master key that is created by using this REST service replaces it. You can also use this REST service to move the master key from a Java™ keystore to HSM (Hardware Security Module) or EKMF (Enterprise Key Management Foundation) and vice versa.

After you create the first server certificate or key, an AES 256-bit master key is generated in the IBM Security Guardium Key Lifecycle Manager server. When you use the Master Key REST Service, a new master key is created. All the cryptographic data that was encrypted with the earlier master key is re-encrypted with the new master key.

When you use this REST service to move the master key from one keystore (source) to another (destination), IBM Security Guardium Key Lifecycle Manager automatically uses the master key from the destination keystore for encryption. When you move the master key from the Java keystore to HSM or EKMF, the Java keystore is deleted. However, when you move the master key from HSM or EKMF to the Java keystore, the master key in HSM or EKMF is not deleted.

You can rerun the Master Key REST Service if a run of this REST service fails.

Note: If the IBM Security Guardium Key Lifecycle Manager server is part of a Multi-Master cluster, you can replace or move the master key from the primary master server only.

Before you begin

Before you move the master key from the Java keystore to HSM or EKMF, configure the required parameters in the IBM Security Guardium Key Lifecycle Manager configuration file. You can use the Update Config Property REST Service.

By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify this default port.

Request

Request Parameters
Parameter Description
host Specify the IP address or hostname of the IBM Security Guardium Key Lifecycle Manager server.
port Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests.
Request Headers
Header name Value
Content-Type application/json
Accept application/json
Authorization SKLMAuth userAuthId=<authIdValue>
Accept-Language Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de.
Request Body

JSON object with the following specification:

JSON property name Description
masterKeySize Specify length of the IBM Security Guardium Key Lifecycle Manager master key in bits. You can specify 128 or 256.
source Optional. Specify the source keystore from where you want to move the master key. The valid values are:
  • Keystore
  • HSM
  • EKMF Web

The values are case-insensitive.

destination Optional. Specify the destination keystore to which you want to move the master key. The valid values are:
  • Keystore
  • HSM
  • EKMF Web

The values are case-insensitive.

Response

Response Headers
Header name Value and description
Status Code
200 OK
The request was successful. The response body contains the requested representation.
400 Bad Request
The authentication information was not provided in the correct format.
401 Unauthorized
The authentication credentials were missing or incorrect.
404 Not Found Error
The processing of the request fails.
500 Internal Server Error
The processing of the request fails because of an unexpected condition on the server.
Content-Type application/json
Content-Language Locale for the response message.
Response Body

JSON object with the following specification:

JSON property name Description
code Returns the success or error message code.
message Returns the message that describes the success or error code.

Examples

Service request to create a new master key with 256-bit length
POST https://localhost:port/SKLM/rest/v1/ckms/masterKey
{"masterKeySize":"256"}
Success response
Status Code: 200 OK
{"code":"CTGKM3350I", “message”:”Successfully refreshed Master Key.”}
Error response
Status Code: 400 Bad Request
Content-Language: en
{"code": "CTGKM6002E", "message" : "CTGKM6002E Bad Request: Invalid user
authentication ID or invalid request format."}
Service request to move the master key from the Java keystore to HSM
POST https://localhost:<port>/SKLM/rest/v1/ckms/masterKey
{"masterKeySize":"256",”source”:”keystore”,”destination”:”HSM”}
Success response
Status Code: 200 OK
{"code":"CTGKM3349I", “message”:”Successfully completed movement of Master Key from keystore to HSM.”}
Error response
Status Code: 400 Bad Request
Content-Language: en
{"code": "CTGKM6002E", "message" : "CTGKM6002E Bad Request: Invalid user
authentication ID or invalid request format."}