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) 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, the Java keystore is deleted. However, when you move the master key from HSM to the Java keystore, the master key in HSM 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, configure the pkcs11.pin, pkcs11.config in the IBM Security Guardium Key Lifecycle Manager configuration file. You can use the Update Config Property REST Service or the tklmConfigUpdateEntry CLI command.

Operation: POST
URL: https://<host>:<port>/SKLM/rest/v1/ckms/masterKey

By default, Guardium Key Lifecycle Manager server listens to non-secure port 9080 (HTTP) and secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify these default ports.

Note: The non-secure port 9080 is not applicable when IBM Security Guardium Key Lifecycle Manager is deployed in a containerized environment.

Request

Request Parameters

Parameter	Description
host	Specify the IP address or host name 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 or HSM. 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 or HSM. 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-bits length

POST https://localhost:<port>/SKLM/rest/v1/ckms/masterKey
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
Accept-Language: en
{"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
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
Accept-Language: en
{"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."}