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.
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.
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
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. |
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. |
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:
The values are case-insensitive. |
destination | Optional. Specify the destination keystore to which you want to move the
master key. The valid values are:
The values are case-insensitive. |
Response
Header name | Value and description |
---|---|
Status Code |
|
Content-Type | application/json |
Content-Language | Locale for the response message. |
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"}
- 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”}