Certificate List REST Service

Use the Certificate List REST Service to return certificate information, which is based on the criteria such as a specific state.

Certificate List 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 certificates:
https://host:port/SKLM/rest/v1/certificates
Note: Returns the first 2000 records.
To retrieve a specific list:
https://host:port/SKLM/rest/v1/certificates?uuid=<uuid>&alias=<alias>&attributes=<attributes>&usage=<usage>
Note: Returns the first 2000 records.
To retrieve a specific list with pagination:
https://host:port/SKLM/rest/v1/certificates?uuid=<uuid>&alias=<alias>>&attributes=<state value, trusted 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 host name 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.
uuid Specify the unique ID of the certificate. For example: CERTIFICATE-b4c70958-446d-42c4-ae3b-8c9e0f44c0fa
alias Specify the alias name for the certificate.
attributes Specify the attributes to search. Only the state and trusted attributes are supported. You can specify only one state.
state
You can specify the following values:
pending
A certificate request entry is pending the return of a certificate that is approved and certified by a certificate authority.
pre-active
The object exists. It is not yet usable for any cryptographic purpose. An example is a migrated certificate with a future use time stamp.
active
The 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 suspect. A compromised object never returns to an uncompromised state. It 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
Do not use the object 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. However, the compromised status of the object can be retained for audit or security purposes.
destroyed-compromised
Object is no longer usable for any purpose. However, the compromised status of the object can be retained for audit or security purposes.
trusted
Values for this attribute can be y, n, or no value.

Set the value to y to list only trusted certificates. Set the value to n to list only the untrusted certificates. Not setting a value lists both trusted and untrusted certificates.

usage Specify the target application usage with the following values:
3592
Specifies the 3592 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.
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
TLSCLIENT
Specifies a client-side certificate that is used in secure communication by using Secure Socket Layer protocol to authenticate the client device.
TLSSERVER
Specifies a server-side certificate that is used in secure communication by using Secure Socket Layer protocol.
SYSLOG
Syslog server-side certificate that is used in secure communication by using Secure Socket Layer protocol to authenticate the syslog server.
userdevicegroup
Specifies a user-defined group that is based on a supported device family.
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 (offset).
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.

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 a unique ID for the certificate.
alias Returns an alias name for the certificate.
information Returns important information about the certificate.
key store name Returns the keystore name that contains the certificate.
key store uuid Returns the keystore unique ID that contains the certificate.
owner Returns the certificate owner name.
key state Indicates the certificate status, such as ACTIVE.
issuer name Returns the distinguished name of the certificate issuer. The property value is from the Issuer field of the certificate.
subject name Returns the certificate subject name. The X.509 certificates contain the subject distinguished name. The property value is from the Subject field of the certificate.
activation date Returns the certificate activation date.
archive date Returns the certificate archived date.
compromise date Returns the date on which the certificate is compromised.
creation date Returns the certificate creation date.
expiration date Returns the certificate expiration date.
destroy date Returns the date on which the certificate is destroyed.
trusted Indicates whether the certificate is trusted.
has private key Indicates whether the certificate has a private key.
serial number Returns the certificate serial number.
hash value Returns the hash value of the certificate.
usage Returns the target application usage, such as TLSSERVER.
Certificate Type Returns the certificate type such as X.509 or PGP.
Certificate Subject Alternate Name Indicates the alternative name for the certificate owner.
Cryptographic Algorithm Represents the cryptographic algorithm that is used by the certificate such as RSA, DSA, DES, 3DES, or AES.
Cryptographic Length Returns the length of the clear-text cryptographic object in bits.
Cryptographic Usage Mask Represents the cryptographic usage of a key. For example, Encrypt, Decrypt, or Export.
Operation Policy Name Indicates the 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. For example, compromised, expired, or no longer used.
Name Returns the name to identify and locate the cryptographic object.
Cryptographic Parameters Returns the cryptographic parameters for cryptographic operations.
Object Group Returns the group name that contains the cryptographic objects.
Link Identifies the target managed cryptographic object by its unique identifier. For certificate objects, the parent certificate for a certificate in a certificate chain.
Digest Contains the digest value of the key or secret data, such as digest of the key material or digest of the certificate value.
Application Specific Information Stores information specific to the application by using 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 certificate information
GET https://host:port/SKLM/rest/v1/certificates?offset=1&count=10 
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
Success response
Status Code : 200 OK
Content-Language: en
[
  {
    "uuid": "CERTIFICATE-c4d35809-b4c2-40af-90db-f291c251f96e",
    "alias": "sslselfcert ",
    "information": null,
    "key store name": "defaultKeyStore ",
    "key store uuid": "KEYSTORE-f1e85369-1e8f-481b-b6ec-10ce59198e89 ",
    "owner": null,
    "key state": "ACTIVE",
    "issuer name": "CN=TLSSelfCert, OU=Security Systems, O=ibm, L=Bangalore,
     ST=Karnataka, C=In",
    "subject name": "CN=TLSSelfCert, OU=Security Systems, O=ibm, L=Bangalore
     , ST=Karnataka, C=In",
    "activation date": "1/8/13 11:13:35 PM India Standard Time",
    "archive date": "null",
    "compromise date": "null",
    "creation date": "1/8/13 11:13:37 PM India Standard Time",
    "expiration date": "1/8/16 11:13:35 PM India Standard Time",
    "destroy date": "null",
    "trusted": "1",
    "has private key": "TRUE ",
    "serial number": "34348697221015",
    "hash value": "0000: fb b5 00 e1 a2 d4 58 45  2d 68 e6 81 c2 43 c4 7b  
     ......XE.h...C..0010: 10 75 44 dd bc 2d 5f e4  42 18 a2 27 0f b0 8f 77 
     .uD.....B......w",
    "usage": "TLSSERVER",
    "Certificate Type": null,
    "Certificate Subject Alternate Name": null,
    "Cryptographic Algorithm": null,
    "Cryptographic Length": null,
    "Cryptographic Usage Mask": null,
    "Operation Policy Name": null,
    "Contact Information": null,
    "Revocation Reason": null,
    "Name": null,
    "Cryptographic Parameters": null,
    "Object Group": null,
    "Link": null,
    "Digest": null,
    "Application Specific Information": null,
    "Custom Attributes": null,
    "Type": "CERTIFICATE",
    "Last Changed Date": "1/8/13 11:13:37 PM India Standard Time",
    "Compromise Occurence Date": null,
    "Lease Time": null
  }
]
Service request with invalid device group
GET https://host:port/SKLM/rest/v1/certificates?alias=cert_test&usage=LTO 
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": "CTGKM1147E",
  "message": "CTGKM1147E The device group \"  LTO  \" does not support certificates."
}