List Key REST Service

Use List Key REST Service to list a key or keys in the keystore that is based on specified criteria, such as an active state.

List Key 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 keys:: https://host:port/SKLM/rest/v1/keys
Note: Returns the first 2000 records.
To retrieve a specific list:: https://host:port/SKLM/rest/v1/keys?uuid=<uuid>&alias=<alias>&usage=<usage>&attributes=<state value>
Note: Returns the first 2000 records.
To retrieve a specific list with pagination:: https://host:port/SKLM/rest/v1/keys?uuid=<uuid>&alias=<alias>&attributes=<state value>&usage=<usage>&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 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`.

Query parameters

Parameter name	Description
uuid	Specify the unique ID of the key.
alias	Specify the unique alias name for the key.
usage	Specify the device group that contains the key. You can specify the following values: `LTO` `3592` `DS5000` `DS8000` `BRCD_ENCRYPTOR` `ONESECURE` `GENERIC` `ETERNUS_DX` `XIV` `GPFS` `PEER_TO_PEER` `DS8000_TCT` `userdevicegroup` `TLSSERVER` `TLSCLIENT`
state	Specify the current state of the key. The following values are supported: `pending` A certificate request entry is pending the return of a certificate that is approved and certified by a certificate authority. `pre-active` Object exists but is not yet usable for any cryptographic purpose, such as migrated certificates with a future use time stamp. `active` Object is in operational use for protecting and processing data that might use Process Start Date and Protect Stop Date attributes. For example, protecting includes encryption and signature issue. Processing includes decryption and signature verification. `compromised` The security of the object is suspicious for some reason. A compromised object never returns to an `uncompromised` state, and cannot be used to protect data. Use the object only to process cryptographically protected information in a client that is trusted to handle compromised cryptographic objects. IBM Security Guardium Key Lifecycle Manager retains the state of the object immediately before it was compromised. To process data that was previously protected, the compromised object might continue to be used. `deactivated` Object is not to be used to apply cryptographic protection such as encryption or signing. However, if extraordinary circumstances occur, the object can be used with special permission to process cryptographically protected information. For example, processing includes decryption or verification. `destroyed` Object is no longer usable for any purpose. This status causes the object to be removed from the product. `destroyed-compromised` Object is no longer usable for any purpose. This status causes the object to be removed from the product.
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 that you specify with offset.

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
uuid	Returns the unique ID of the key.
alias	Returns the alias name for the key.
information	Returns the important information about the key.
key algorithm	Represents the algorithm to encrypt the key.
Key length	Returns the length of the key in bits.
Key type	Indicates key type, such as `symmetric`.
key store name	Returns the keystore name that contains the key.
key store uuid	Returns the unique ID of the keystore that contains the key.
owner	Returns the key owner name.
key state	Returns the status of the key, such as `ACTIVE`.
activation date	Returns the key activation date.
archive date	Returns the key archived date.
compromise date	Returns the date on which the key is compromised.
creation date	Returns the key creation date.
expiration date	Returns the key expiration date.
destroy date	Returns the date on which the key is destroyed.
Key group id	Returns the unique ID of the group that contains the key.
hash value	Returns the hash value of the key.
usage	Indicates the usage type of the target application such as `LTO`, `3592`, `DS5000`, `ETERNUS_DX`, `XIV`, `GPFS` or `PEER_TO_PEER`.
Deactivation Date	Identifies the date on which the key is deactivated.
Cryptographic Usage Mask	Indicates the cryptographic usage of a key. For example, `Encrypt`, `Decrypt`, or `Export`.
Operation Policy Name	Identifies operation policy that controls the key management operations on the cryptographic object.
Contact Information	Represents the contact information.
Revocation Reason	Indicates the reason for revoking the managed cryptographic object. For example, `compromised`, `expired`, or `no longer used`
Name	Returns the name that identifies and locates the cryptographic object.
Cryptographic Parameters	Returns the parameters for cryptographic operations.
Object Group	Returns the group that contains the cryptographic object.
Link	Identifies the target managed cryptographic object by its unique identifier.
Digest	Contains the digest value of the key or secret data.
Application Specific Information	Stores information specific to the application that uses managed cryptographic object.
Custom Attributes	Returns the vendor defined custom attributes.
Last Changed Date	Returns the date and time of the last change to the contents or attributes of the specified managed cryptographic object.
Compromise Occurrence Date	Returns the date and time of when the managed cryptographic object was first believed to be compromised.
Lease Time	Defines a time interval for a managed cryptographic object. After the lease time, the client cannot use the object without obtaining another lease.

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 key information

GET https://localhost:port/SKLM/rest/v1/keys?offset=1&count=1 
Content-Type: application/json 
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m

Success response

Status Code: 200 OK
    [
       {
           "uuid": "KEY-d58c43dc-302a-42e0-8c7a-2543a7d19548",
           "information": "",
           "alias": "aaa000000000000000000 ",
           "key algorithm": "AES",
           "key length (in bits)": "256",
           "key type": "SYMMETRIC_KEY",
           "owner": "",
           "key store name": "defaultKeyStore ",
           "key store uuid": "KEYSTORE-edff2086-5eaa-4bf0-b2e8-
             05964ad8eeea ",
           "key state": "ACTIVE",
           "activation date": "12/20/12 1:05:45 PM Central Standard 
             Time",
           "archive date": "null",
           "compromise date": "null",
           "creation date": "12/20/12 1:05:45 PM Central Standard 
             Time",
           "expiration date": "12/15/32 1:05:45 PM Central Standard 
             Time",
           "destroy date": "null",
           "key group ids": "KEYGROUP-b0992af0-ae98-4a89-9c3c-
             dcc30ad6a347 ",
           "hash value": "0000: 02 49 e1 23 4d 66 20 bc ee 33 5d d0 
             e8 ff af de .I..Mf...3...... 0010: 8f 0c ac 28 07 cf 
             a5 99 57 7d 18 1f 51 aa 15 5b ........W...Q... ",
           "usage": "LTO",
           "Cryptographic Usage Mask": "",
           "Usage Limits": "",
           "Operation Policy Name": "",
           "Process Start Date": "",
           "Protect Stop Date": "",
           "Deactivation Date": "12/15/32 1:05:45 PM Central 
             Standard Time",
           "Contact Information": "",
           "Revocation Reason": "",
           "Name": "[[INDEX 0] [TYPE TEXT] [VALUE aaa0000000000000
             00000]]",
           "Cryptographic Parameters": "",
           "Object Group": "",
           "Link": "",
           "Digest": "[[INDEX 0] [HASH SHA256] [VALUE x02,x49,xe1,
             x23,x4d,x66,x20,xbc,xee,x33,x5d,xd0,xe8,xff,xaf,xde,
             x8f,x0c,xac,x28,x07,xcf,xa5,x99,x57,x7d,x18,x1f,x51,
             xaa,x15,x5b]]",
           "Application Specific Information": "",
           "Custom Attributes": "",
           "Last Changed Date": "12/20/12 1:05:45 PM Central 
             Standard Time",
           "Compromise Occurence Date": "",
           "Lease Time": ""
       }
    ]

Error response

Status Code: 400 Bad Request
Content-Language: en

{"code" "CTGKM6002E"
 , "message": "CTGKM6002E Bad Request: Invalid user authentication 
ID or invalid re-quest format."
 }