Key Attribute Update REST Service

Use Key Attribute Update REST Service to update the key metadata that are Key Management Interoperability Protocol attributes in the database.

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

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:

JSON property name	Description
attrName	Required. Specify the name that you can use to identify or locate the attribute pair as an object. Note: Do not use an asterisk (`*`) or question mark (`?`) as a character in a Key Management Interoperability Protocol attribute. These wildcard characters are reserved for future use. You can specify the following attributes: applicationSpecificInformation Specifies application namespace information as a Key Management Interoperability Protocol attribute. contactInformation Specifies contact information as a Key Management Interoperability Protocol attribute. cryptoParams cryptoparameter1, cryptoparameterN Specifies the cryptographic parameters that you use for cryptographic operations by using the object. This attribute is a Key Management Interoperability Protocol attribute. customAttribute Specifies a custom attribute in string format as a Key Management Interoperability Protocol attribute. Client-specific attributes must start with the characters "x-" (x hyphen) and server-specific attributes must start with "y-" (y hyphen). link Specifies the link from one managed cryptographic object to another, closely related target managed cryptographic object. This attribute is a Key Management Interoperability Protocol attribute. name Specifies the name that you use to identify or locate the object. This attribute is a Key Management Interoperability Protocol attribute. objectGroup Specifies one or more object group names of which this object might be part. This attribute is a Key Management Interoperability Protocol attribute. processStartDate Specifies the date in yyyy-MM-dd format on which a symmetric key object can be used for process purposes. You cannot change the value after the date occurs. If you specify a date earlier than the current date, the value is set to the current date. This attribute is a Key Management Interoperability Protocol attribute. protectStopDate Specifies the date in yyyy-MM-dd format on which an object cannot be used for process purposes. You cannot change the value after the date occurs. If you specify a date earlier than the current date, the value is set to the current date. This attribute is a Key Management Interoperability Protocol attribute. usageLimits Specifies either total bytes (BYTE) or total objects (OBJECT) as a Key Management Interoperability Protocol attribute. You cannot modify this value once this object is used. For example, GetUsageAllocation calls this object.
attrValue	Conditional. Specify one or more of these key value pairs to add or update: applicationSpecificInformation applicationIDstring Specifies application namespace information as the value of applicationIDstring. NAMESPACE Application namespace. INFO Application namespace information. contactInformation contactstring Specifies contact information as the value of contactstring. This attribute is a Key Management Interoperability Protocol attribute. VALUE Contact information.
	cryptoParams cryptoparameter1, cryptoparameterN Specifies the cryptographic parameters that you use for cryptographic operations by using the object. This attribute is a Key Management Interoperability Protocol attribute. MODE CBC, ECB, PCBC, CFB, OFB, CTR, CMAC, CCM, GCM, CBC_MAC, XTS, AES_KEY_WRAP_PADDING, X9_102_AESKW, X9_102_TDKW, X9_102_AKW1, X 9_102_AKW2 PAD NONE, OAEP, PKCS5, SSL3, ZEROS, ANSI_X9_23, ISO_10126, PKCS1_ V1_5, X9_31, PSS HASH MD2, MD4, MD5, SHA1, SHA224, SHA256, SHA384, SHA512 ROLE BDK, CVK, DEK, MKAC, MKSMC, MKSMI, MKDAC, MKDN, MKCP, MKOTH, KEK, MAC1660 9, MAC97971, MAC97972, MAC97973, MAC97974, MAC97975, ZPK, PVKIBM, PVKPVV, PVKOTH
	customAttribute customstring Specifies for the value of customstring a custom attribute in string format as a Key Management Interoperability Protocol attribute. Client-specific attributes must start with the characters "x-" (x hyphen) and server-specific attributes must start with "y-" (y hyphen). NAME Client or server attribute name. VALUE Value of the attribute name.
	link objectname, objectnametarget Specifies the link from one managed cryptographic object to another, closely related target managed cryptographic object. This attribute is a Key Management Interoperability Protocol attribute. TYPE KEY, PRIVATE_KEY, PUBLIC_KEY, DERIVATION_BASE_OBJECT, DERIVED_KEY, REPLACEMENT_OBJECT, REPLACED_OBJECT LINKED_OBJECT_ID Specify the target uuid of the linked object.
	name Specifies the name that you to identify or locate the object. This attribute is a Key Management Interoperability Protocol attribute. TYPE TEXT, URI VALUE Name, or URI identifying the object.
	objectGroup objectgroupname1, objectgroupnameN Specifies for objectgroupname1, objectgroupnameN the values of one or more object group names of which this object might be part. This attribute is a Key Management Interoperability Protocol attribute. VALUE Object group name.
	processStartDate VALUE Date in yyyy-MM-dd format.
	protectStopDate VALUE Date in yyyy-MM-dd format.
	usageLimits TYPE OBJECT, BYTE TOTAL Total number of objects or bytes.
index	Conditional. Specify the index to update or delete an attribute value.
operation	Required. Specify one of these valid operations to run on an attribute value: `add`, `update`, or `delete`
uuid	Required. Specify the universal unique identifier of the key.

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 the code that is specified by the status property.
status	Returns the status to indicate whether the key attribute update task is successful.

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 add an attribute to a key

PUT https://localhost:<port>/SKLM/rest/v1/keyAttributes
{"uuid":"KEY-d3ee4491-f96e-495d-bb37-fc03748924ba","operation":
"add","attrName":"cryptoParams","attrValue":"MODE CBC, PAD NONE,HASH 
SHA256,ROLE BDK"}

Success response

Status Code : 200 OK
{"code": "0","status": "Succeeded"}

Service request to add an attribute for a key name

PUT https://localhost:port/SKLM/rest/v1/keyAttributes
{"uuid":"KEY-d3ee4491-f96e-495d-bb37-fc03748924ba","operation":
"add","attrName":"name","attrValue":"TYPE TEXT,VALUE key name for xyz"

Success response

Status Code : 200 OK
{"code": "0","status": "Succeeded"}

Service request to update an attribute

PUT https://localhost:port/SKLM/rest/v1/keyAttributes
{"uuid":"KEY-d3ee4491-f96e-495d-bb37-fc03748924ba","operation":"update",
"index":"0","attrName":"name","attrValue":"TYPE TEXT,VALUE updated key 
name for xyz"}

Success response

Status Code : 200 OK
{"code": "0","status": "Succeeded"}

Service request to delete an attribute

PUT https://localhost:<port>/SKLM/rest/v1/keyAttributes
Content-Type: application/json
Accept : application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"uuid":"KEY-d3ee4491-f96e-495d-bb37-fc03748924ba","operation":"delete",
"index":"0","attrName":"name"}

Success response

Status Code : 200 OK
{"code": "0","status": "Succeeded"}

Service request to update an attribute when an invalid parameter is specified

PUT https://localhost:<port>/SKLM/rest/v1/keyAttributes
Content-Type: application/json
Accept : application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"UUID":"KEY-d3ee4491-f96e-495d-bb37-fc03748924ba","operation":
"add","attrName":"cryptoParams","attrValue":"MODE CBC, PAD NONE,HASH 
SHA256,ROLE BDK"}

Error response

Status Code : 400 Bad Request
{"code":"CTGKM0630E","message":"CTGKM0630E Validation error:
 \"Invalid name \" for parameter \"UUID\"."}