Use Key Update REST Service to update
key metadata in the database. For example, you might move an individual
key in one key group to another key group.
- Operation
PUT
- URL
- https://<host>:<port>/SKLM/rest/v1/keys
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
Property name |
Description |
uuid |
Specify the universal unique identifier of the
individual key that you want to update. |
usage |
Optional. Specify a unique device group, such
as LTO . You can specify 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.
- GPFS
- Specifies the IBM Spectrum® Scale (previously known as GPFS) device group.
- PEER_TO_PEER
- Specifies the
PEER_TO_PEER device
group.
- DS8000_TCT
- Specifies the
DS8000_TCT
device group that is in the GPFS device family.
- 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.
- ETERNUS_DX
- Specifies the ETERNUS_DX device group that is in the DS5000 device family.
- XIV
- Specifies the IBM Spectrum Accelerate (previously
known as XIV) device group.
- userdevicegroup
- Specifies a user-defined group that is based on a supported device
family.
|
attributes |
Specify one or more of the following attribute-value
pairs:
- compromised
- Specifies whether the use of a key is compromised. The only value
is y (
compromised ). You cannot change a compromised key
or certificate to an uncompromised state.
- groupName
- Specifies the name of a valid key group. You cannot move the last
key in a default key group to a different group. You can change the
key group name to a key group that is used by a different device
group in the same device family if:
- The key group and its keys are not the default device group.
- The key group and its keys are not attached to a device.
For example, you can change such a group from the myLTO device
group to yourLTO device group in the LTO device
family.
In the DS5000 device family, a key group is generated
for each DS5000 device when the device is created. You cannot create
a DS5000 device with a key group attribute. However, you can create
a new key group and specify the group name of a DS5000 device with
the new key group.
- information informationstring
- Specifies more information about the use of an object.
|
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 |
status |
Returns the status with an appropriate message
that indicates whether the key is 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 the group and key details
PUT https://<host>:<port>/SKLM/rest/v1/keys
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
{"uuid":"KEY-61bd4100-9880-450f-a1a5-7efe19a8d0f5","attributes":"groupName
newGroup1,information movedTonewGroup1"}
- Success response
Status Code : 200 OK
Content-Language: en
{"code":"0","status":"Succeeded"}
- Service request to update the key when uuid parameter
is missing
PUT https://<host>:<port>/SKLM/rest/v1/keys
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
{}
- Error response
Status Code: 400 Bad Request
Content-Language: en
{ "code": "CTGKM0631E", "message": "CTGKM0631E Missing required
parameter " uuid " ."}