Master Key REST Service

Use Master Key REST Service to create an IBM Security 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 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 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 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 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, IBM Security Key Lifecycle Manager server listens to non-secure port 80 (HTTP) and secure port 443 (HTTPS) for communication. During IBM Security Key Lifecycle Manager installation, you can modify these default ports. If you are using the default port for HTTP or HTTPS, the port is an optional part of the URL.

Request

Request Parameters

Parameter	Description
host	Specify the IP address or host name of the IBM Security Key Lifecycle Manager server.
port	Specify the port number on which the IBM Security 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 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 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. 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."}