Device List REST Service

Use Device List REST Service to list information about all devices of a specific device group, or a device in the IBM Security Guardium Key Lifecycle Manager database.

Device List REST Service supports pagination. The following parameters are used for pagination: offset and count. The offset value specifies the page number from which the records are displayed. The count value specifies the number of records to display on a page, which you specify in the offset value. For example, to retrieve the first 10 records for the list, set offset = 1 and count = 10. To retrieve the next 10 records, set offset = 2 and count = 10. If you do not specify values for pagination parameters, the first 2000 records are returned.
Operation
GET
URL
To retrieve all devices:
https://<host>:<port>/SKLM/rest/v1/devices
Note: Returns the first 2000 records.
To retrieve a specific list:
https://<host>:<port>/SKLM/rest/v1/devices?type=<type>&uuid=<uuid>
Note: Returns the first 2000 records.
To retrieve a specific list with pagination:
https://<host>:<port>/SKLM/rest/v1/devices?type=<type>&uuid=<uuid>&offset=<offset>&count=<count>

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.
Type Specify the device group type. The default is all device groups.
LTO
Specifies the LTO device group.
3592
Specifies the 3592 device group.
DS5000
Specifies the DS5000 device group.
DS8000®
Specifies the DS8000 device group.
BRCD_ENCRYPTOR
Specifies the BRCD_ENCRYPTOR device group that is in the LTO device family.
ONESECURE
Specifies the ONESECURE device group that is in the DS5000 device family.
GENERIC
Specifies a device family that uses the Key Management Interoperability Protocol to interact with IBM Security Guardium Key Lifecycle Manager. The GENERIC device group enables management of KMIP objects.
Do not use the REST interface to add a device to the GENERIC device group, or to change a GENERIC device group attribute.
ETERNUS_DX
Specifies the ETERNUS_DX device group that is in the DS5000 device family.
XIV®
Specifies the XIV device group that is in the DS5000 device family.
userdevicegroup
Specifies a user-defined group that is based on a supported device family.
uuid Specify the unique ID of the device. For example: DEVICE-74386920-148c-47b2-a1e2-d19194b315cf
offset Specify the page number from which the records are displayed based on the value that you specify for count.
count Specify the number of records to display on the specified page (offset). The first 2000 records are returned if you do not specify the value for offset and count.
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

JSON object with the following specification:

JSON property name Description
Description Describes the type of device or its purpose.
Serial Number Returns the serial number as an ASCII string.
Device uuid Returns the unique ID of the device.
Device group Returns the device group type. This property can contain the following device groups:
LTO
Specifies the LTO device group.
3592
Specifies the 3592 device group.
DS5000
Specifies the DS5000 device group.
DS8000
Specifies the DS8000 device group.
BRCD_ENCRYPTOR
Specifies the BRCD_ENCRYPTOR device group that is in the LTO device family.
ONESECURE
Specifies the ONESECURE device group that is in the DS5000 device family.
GENERIC
Specifies a device family that uses KMIP to interact with IBM Security Guardium Key Lifecycle Manager. The GENERIC device group enables management of KMIP objects.

Do not use the REST interface to add a device to the GENERIC device group or to change a GENERIC device group attribute.

ETERNUS_DX
Specifies the ETERNUS_DX device group that is in the DS5000 device family.
XIV
Specifies the XIV device group that is in the DS5000 device family.
userdevicegroup
Specifies a user-defined group that is based on a supported device family.
World wide name Returns the device name, which is a nonsecure address, which is used in combination with other device information, such as a serial number. You can use this name to define devices and device paths.
Sym alias Returns an alias to identify an existing key group for an LTO tape drive. The attribute is also used for the DS5000 storage server to change or associate a new device key container.
Host address Returns the host address for the device.
Key alias 1 Returns the default key alias for a certificate that is used by a 3592 tape drive or a DS8000 Turbo drive. This alias is not used for an LTO tape drive or DS5000 storage server.
Key alias 2 Returns a key alias for a 3592 tape drive or a DS8000 Turbo drive. This alias is not used for an LTO tape drive or DS5000 storage server.
Certificate length Returns the length of the actual certificate that identifies the device.
Device Text Returns a unique text that describes a DS5000 storage server. The text ranges is up to 96 bytes, but it must be greater than 0.
Current Key Returns the current key for the device.
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 list device information
GET https://<host>:<port>/SKLM/rest/v1/devices 
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
Success response
Status Code : 200 OK
Content-Language: en
[
  {
    "Description": "salesDivisionDrive",
    "Serial Number": "FAA49403AQJF",
    "Device uuid": "DEVICE-641b963e-aa61-46f8-a036-12023768427a",
    "Device group": "LTO",
    "World wide name": "ABCDEF1234567890",
    "Sym alias": "satGroup"
  },
  {
    "Description": "salesDivisionDrive",
    "Serial Number": "FAA49403AQJ1",
    "Device uuid": "DEVICE-4c3d0117-79a7-411e-a568-83481adc8332",
    "Device group": "LTO",
    "World wide name": "ABCDEF1234567891",
    "Sym alias": "satGroup"
  },
  {
    "Description": "salesDivisionDrive",
    "Serial Number": "FAA49403AQJ2",
    "Device uuid": "DEVICE-1fe2e310-6c2e-471f-96fd-838f03ac0d5d",
    "Device group": "LTO",
    "World wide name": "ABCDEF1234567892",
    "Sym alias": "satGroup"
  },
  {
    "Description": "salesDivisionDrive",
    "Serial Number": "FAA49403AQJ3",
    "Device uuid": "DEVICE-7890b61a-398c-4e61-afc0-8007a7274bc9",
    "Device group": "LTO",
    "World wide name": "ABCDEF1234567893",
    "Sym alias": "satGroup"
  },
]
Error response
Status Code : 400 Bad Request
Content-Language: en
{"code" "CTGKM6002E"
 , "message": "CTGKM6002E Bad Request: Invalid user authentication ID or 
invalid request format."
 }