Device Update REST Service

Use Device Update REST Service to update the attributes of a device in the IBM Security Guardium Key Lifecycle Manager database.

Operation
PUT
URL
https://<host>:<port>/SKLM/rest/v1/devices

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 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.
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:

Property name Description
uuid Required. Specifies the universal unique identifier of the device. For example, DEVICE-74386920-148c-47b2-a1e2-d19194b315cf.
type Specify a unique device group, such as myNewLTO. You can specify any of the following values:
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.
attributes Specify one or more attribute-value pairs. The values are stored in the IBM Security Guardium Key Lifecycle Manager database. You can specify any of the following values:
 
aliasOne
Specifies a default alias for a certificate that is used by a 3592 tape drive or a DS5000 turbo drive. Not used for an LTO tape drive or DS5000 storage server.
  • 3592 tape drive

    The value is optional for a 3592 tape drive. Specifies the primary certificate that the device in the 3592 device family uses if the primary certificate is not available. If this attribute is not specified, the partner default certificate is used. The certificate is specified as a table entry for the device group in the IBM Security Guardium Key Lifecycle Manager database.

  • DS8000 turbo drive

    The value is optional for a DS8000 turbo drive. Matches the label Primary certificate for image in the graphical user interface panels for a DS8000 Turbo drive.

Use Device Group Attribute List REST Service and Device Group Attribute Update REST Service to view and change the value. This value was previously stored in the drive.default.alias1 configuration parameter.
aliasTwo
Used for a 3592 tape drive or a DS8000 turbo drive. Not used for an LTO tape drive or DS5000 storage server.
  • 3592 tape drive

    This attribute specifies a default alternative alias for a 3592 tape drive. This value can be the same, or different from the value that is specified for the primary certificate.

    The value specifies the secondary certificate that the device in the 3592 device family uses if the primary certificate is not available. If this attribute is not specified, the partner default certificate is used. The certificate is specified as a table entry for the device group in the IBM Security Guardium Key Lifecycle Manager database.

  • DS8000 turbo drive

    For a device in the DS8000 device family, the value specifies a secondary certificate that is available for use. For example, you might use this certificate to unlock a DS8000 turbo drive in the case of a deadlock condition.

Use Device Group Attribute List REST Service and Device Group Attribute Update REST Service to view and change the value. This value was previously stored in the drive.default.alias2 configuration parameter.
 
description
Specifies more information that describes the type of device or its purpose.
deviceText
Optional. Specifies the unique text with a minimum length greater than zero bytes and a maximum length of 96 bytes that describes a DS5000 storage server.
serialNumber
For a DS5000 storage server, specifies the serial number of drive. You can change the serial number of a DS5000 storage server to another serial number that is not currently in use.
symAlias
Specifies an alias that is used to identify an existing key group for an LTO tape drive. The attribute is also used for DS5000 storage server to change or associate a new device key container. This value is stored in the IBM Security Guardium Key Lifecycle Manager database.
worldwideName
Specifies the name of a device. This name is a nonsecure address that is used in combination with other device information, such as a serial number, to define devices and device paths. Specify a 16-character hexadecimal value that contains only the characters ABCDEFabcdef1234567890.

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
code Returns an integer value such as 0 or 1 to indicate the device update status.
status Returns the status message to indicate whether the device update task was successful.
0
The device update task succeeded.
1
The device is not updated.
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 update a device
PUT https://localhost:<port>/SKLM/rest/v1/devices
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"uuid":"DEVICE-44b123ad-5ed8-4934-8c84-64cb9e11d990","attributes":
"symAlias LTOKey000001,description myLTOdrive"}
Success response
Status Code: 200 OK
{"code": "0","status": "Succeeded"}
Service request to update a device when attribute value is not specified
PUT https://localhost:<port>/SKLM/rest/v1/devices
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"uuid":"DEVICE-80896a45-8f9e-428d-a3ac-ac9ffcbbfe8b","attributes":
"description "}
Success response
Status Code: 200 OK
{"code":"1","status":"CTGKM0509I No update"}
Error response when uuid is not specified
PUT https://localhost:<port>/SKLM/rest/v1/devices
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"uuid":""}
Error response
Status Code: 400 Bad Request
{"code":"CTGKM0550E","message":"CTGKM0550E Input value cannot be an 
empty string for parameter uuid "}}