Served Data List REST Service

Use Served Data List REST Service to query the database and list the served key data. For example, you might list which devices were served a specific key, or list the keys that were served to a specific device.

Served Data 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

Retrieve all the served key data:

https://<host>:<port>/SKLM/rest/v1/servedData

Note: Returns 2000 records.

Retrieve all the served key data when you specify a few parameters:

https://<host>:<port>/SKLM/rest/v1/
servedData?kmipClientCertUUID=<clientCertUUID>&dateBefore=<date>
&dateAfter=<date>

Note: Returns 2000 records.

Retrieve all the served key data when you specify all the parameters:

https://<host>:<port>/SKLM/rest/v1/
servedData?volser=<VolumeSerialNumber>&attributeName=<attrName>
&attributeValue=<attrvalue>&dateBefore=<date>&dateAfter=<date>&usage
=<devicetype>&serialNumber=<deviceSerialNumber>&kmipClientCertUUID
=<clientCertUUID>

Note: Returns 2000 records.

To retrieve a specific list with pagination:

https://<host>:<port>/SKLM/rest/v1/
servedData?volser=<VolumeSerialNumber>&attributeName=<attrName>
&attributeValue=<attrvalue>&dateBefore=<date>&dateAfter=<date>&usage=
<devicetype>&serialNumber=<deviceSerialNumber>&kmipClientCertUUID=
<clientCertUUID>&offset=<offset>&count=<count>

By default, IBM® Security Key Lifecycle Manager server listens to non-secure port 9080 (HTTP) and secure port 9443 (HTTPS) for communication. During IBM Security Key Lifecycle Manager installation, you can modify these default ports.

Request

Request Parameters

Parameter	Description
host	Specify the IP address or host name of the IBM Security Key Lifecycle Manager server.
port	Specify the port number on which the IBM Security 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 Key Lifecycle Manager. For example: `en` or `de`

Query parameters

Parameter name	Description
attributeName	Optional. alias1 Specify a default alias for a certificate that is used by a `3592` tape drive or a `DS8000` Turbo drive. Not used for an `LTO` tape drive or `DS5000` storage server. 3592 tape drive The value is optional for a `3592` tape drive and specifies the primary certificate that the device in the `3592` device family uses. If this attribute is not specified, the partner default certificate is used, as specified by a table entry for the device group in the IBM Security Key Lifecycle Manager database. DS8000 Turbo drive The value is optional for a `DS8000` Turbo drive and 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 obsolete configuration parameter drive.default.alias1. alias2 Used for a `3592` tape drive or a `DS8000` Turbo drive. Not used for an `LTO` tape drive or `DS5000` storage server. 3592 tape drive This 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, as specified by a table entry for the device group in the IBM Security Key Lifecycle Manager database. DS8000 Turbo drive For 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 dead-lock 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 obsolete configuration parameter drive.default.alias2. dki Data key identifier, used only for an `LTO` tape drive.
attributeValue	Optional. Identifies the served data. For example, if `attributeName` is `alias1`, then `attributeValue` might be `cert1`.
dateBefore	Optional. If you specify only this date, list the audits that are made before this date. Hyphens are required in the date value. To list audits that are made between the before and after dates, specify both values. Format for the date is `YYYY-MM-DD`.
dateAfter	Optional. If you specify only this date, list the audits that are made after this date. Hyphens are required in the date value. To list audits that are made between the before and after dates, specify both values. Format for the date is `YYYY-MM-DD`.
usage	Optional. Specify one of the following values: LTO Specifies the `LTO` device family. 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. 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.
volser	Optional. Specify the volume and serial number of a tape cartridge.
kmipClientCertUUID	Optional. Specify UUID of the KMIP client certificate.
serialNumber	Optional. Specify the device serial number.
offset	Optional. Specify the page number from which the records are displayed based on the value that you specify for count.
count	Optional. Specify the number of records to display on the page that you specified with offset. The count must not exceed 2000 records.

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 array that contains JSON objects with the following specification

JSON property name	Description
Device uuid	Returns the universal unique identifier of the device.
Serial Number	Returns the serial number of the device as an ASCII string.
Volume Serial Number	Returns the volume and serial number of the tape cartridge.
World wide name	Returns the name of a device.
Key alias 1	Returns the default key alias.
Key alias 2	Returns the alias of the key served.
TimeStamp	Returns the time stamp when the key was last served.
Data Key Identifier (dki)	Returns the data key identifier.
Attributes	Returns one or more device attributes.
Device Group Name	Returns the device type.
Kmip Client Certificate UUID	Returns the universal unique identifier of KMIP client certificate.

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 served data information

GET https://localhost:<port>/SKLM/rest/v1/servedData?offset=1&count=2
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

[
	{
	 "Device uuid" :   "uuid103",
  "Serial Number":  "null",
	 "Volume Serial Number": "TEST",
	 "World wide name":  "null",
	 "Key alias 1":  "null",
	 "Key alias 2":  "null",
	 "TimeStamp":    "Thursday, January 26, 2016 5:44:19 AM Eastern Daylight
   Time",
   "Data Key Identifier (dki)": "null"
	 "Attributes":  	 "Attributes":   "null",
	 "Device Group Name": "UNSET"
	},
	{
	 "Device uuid" : "uuid101",
   "Serial Number":   "null",
	 "Volume Serial Number":  "null",
	 "World wide name":  "null",
	 "Key alias 1":  "dsk00000000000000000e",
	 "Key alias 2":  "null",
	 "TimeStamp":    "Thursday, January 26, 2016 5:44:19 PM Eastern Daylight
   Time",
   "Data Key Identifier (dki)": "null",
	 "Attributes":   "null",
	 "Device Group Name": "UNSET"
	}
]

Error response

Status Code : 400 Bad Request
Content-Language: en
{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user 
authentication ID or invalid request format."}