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 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
driveThe 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 driveThe 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 driveThis 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 driveFor 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 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 "}}