Get Master Key Status for Device Groups REST Service

Use Get Master Key Status for Device Groups REST Service to obtain details of the master key status for all the device groups or for a specific device group.

Operation
GET
URL
To retrieve the master key status for all device groups
https://host:port/SKLM/rest/v1/ckms/deviceGroupMasterKey
To retrieve the master key status for a specific device group
https://host:port/SKLM/rest/v1/ckms/deviceGroupMasterKey/{deviceGroupName}

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 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.
deviceGroupName Optional. Specify the name of the device group for which you want to retrieve the master key status details. If you do not specify this parameter, master key status for all the device groups are returned. Some examples of device groups are 3592, LTO, DS8000®, and GPFS.
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.

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.
Success response body when the request is to retrieve the master key status for all device groups

JSON object with the following specification:

JSON property name Description
code Returns 0 when the request is successful. Otherwise, returns 1.
status For every device group, returns values for the following properties:
  • device: Returns the device group name.
  • status: If the master key is enabled for the device group, returns true. Else, returns false.
  • creation_date: If the master key is enabled for the device group, returns the date when the master key was created. Else, this property is not returned.
  • next_rotation_date: Returns the date when the master key is to be refreshed. This property is returned only if the key rotation value is specified in the Enable or Disable Master Key for Device Group REST Service.
  • keysize: If the master key is enabled for the device group, returns the size of the master key. Else, this property is not returned.
  • algorithm: If the master key is enabled for the device group, returns the algorithm for the master key. Else, this property is not returned.
Success response body when the request is to retrieve the master key status for a specific device group

JSON object with the following specification:

JSON property name Description
code Returns 0 when the request is successful. Otherwise, returns 1.
creation_date Returns the date of the master key creation.
next_rotation_date Returns the date when the master key is to be refreshed. This property is returned only if the key rotation value is specified in the Enable or Disable Master Key for Device Group REST Service.
keysize Returns the size of the master key.
algorithm Returns the algorithm for the master key. The value can be AES.
status Returns true when the master key is enabled for the device group. Otherwise, returns false.
Error Response Body

JSON object with the following specification.

JSON property name Description
code Returns the application error code.
message Returns a message that describes the error.

Examples

Service request to get master key details for all device groups
GET https://localhost:port/SKLM/rest/v1/ckms/deviceGroupMasterKey
Content-Type: application/json
Accept : application/json
Authorization: SKLMAuth userAuthId=4259b494-9cb2-4414-87b4-9a17b9f916c7
Accept-Language : en
Success response
{"code":"0","status":[{"device":"3592","status":"false"},
{"device":"LTO","status":"false"},{"device":"DS8000","status":"false"},
{"device":"DS5000","status":"false"},{"device":"GENERIC","status":"false"},
{"device":"BRCD_ENCRYPTOR","status":"false"},{"device":"ONESECURE","status":"false"},
{"device":"ETERNUS_DX","status":"false"},{"device":"IBM_SYSTEM_X_SED","status":"false"},
{"device":"XIV","status":"false"},
{"keysize":"256","creation_date":"2018-12-07 13:41:21","device":"GPFS","status":"true","algorithm":"AES"},
{"device":"PEER_TO_PEER","status":"false"},{"device":"DS8000_TCT","status":"false"}]}
Service request to get master key details for a specific device group
GET https://localhost:port/SKLM/rest/v1/ckms/deviceGroupMasterKey/LTO
Content-Type: application/json
Accept : application/json
Authorization: SKLMAuth userAuthId=4259b494-9cb2-4414-87b4-9a17b9f916c7
Accept-Language : en
Success response
{"code":"0","status":"true","creation_date":"2018-12-11 04:44:15",
"next_rotation_date":"2018-12-21 04:44:15","keysize":"256","algorithm":"AES"}
Error response
{"code":"CTGKM0830E","message":"Device group is not valid: saan"}