Device Add REST Service

Use Device Add REST Service to add a device to the IBM Security Guardium Key Lifecycle Manager database. If the device is a DS5000 storage server, this service can optionally create a system-to-device relationship.

Operation
POST
URL
https://<host>:<port>/SKLM/rest/v1/devices

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:

Property name Description
serialNumber Specify the serial number as an ASCII string. The value is case-sensitive. You can use alphanumeric characters and the special characters such as periods, spaces, dashes, semicolons, and underscore. Do not use a space at the beginning or end of a serial number.
LTO tape drives
The serial number must be exactly 10, 12, or 24 characters in length. IBM Security Guardium Key Lifecycle Manager pads a serial number that is 10 characters in length with two leading zeros.
3592 tape drives and DS8000® Turbo drives
The case-sensitive value must be exactly 12 characters in length.
DS5000 storage servers
The serial number can vary 1- 48 characters in length. No padding occurs.
type Specify any of the following device group:
LTO
Specifies the LTO device group.
3592
Specifies the 3592 device group.
DS5000
Specifies the DS5000 device group.
DS8000
Specifies the DS8000 device group.
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.

Do not use the REST interface to add a device to the GENERIC device group, or to change a GENERIC device group attribute.

ETERNUS_DX
Specifies the ETERNUS_DX device group that is in the DS5000 device family.
XIV®
Specifies the XIV device group that is in the DS5000 device family.
userdevicegroup
Specifies a user-defined group that is based on a supported device family.
attributes Optional. Specify one or more attribute-value pairs. Their values are stored in the IBM Security Guardium Key Lifecycle Manager database.
aliasOne
Specifies 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

    Optional for a 3592 tape drive and specifies the primary certificate that the device uses if the secondary 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 Guardium Key Lifecycle Manager database.

  • DS8000 Turbo drive

    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.

 
aliasTwo
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

    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 Guardium 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 deadlock condition.

 
description
Specifies more information that describes the type of device or its purpose.
deviceText
Optional. Specifies the unique text with a minimum length greater than zero bytes and a maximum length of 96 bytes that describes a DS5000 storage server.
driveCert
Specifies the actual certificate that is used to identify the device in base64 encoded format. For current devices, this field is not in use.
keyPrefix
Specifies a key prefix as part of the key name. To add new keys, specify the prefix and number of keys. This value is used only for a device in the DS5000 device family.
machineID
Optional unless you want to add the association of a device to an existing machine identifier in the IBM Security Guardium Key Lifecycle Manager database. Specifies a unique machine ID for a DS5000 storage server, which is a concatenation of the worldwide name and the volume serial number. For example, specify 3042383030303437000000000000.
numberOfKeys
Specifies the number of keys to generate. The keys use the value of the keyPrefix attribute. The maximum number of keys is 12. If this value is not specified, the default value is 12 keys.

This value is used only for a device in the DS5000 device family.

symAlias
Specifies an alias that is used to identify an existing key group for an LTO tape drive.

The value of symAlias is used to specify which symmetric key group is used to obtain a key for a new device media instance. If this attribute is not specified, then the value of the symmetricKeySet attribute is used.

For backward compatibility with the Encryption Key Manager product, you can also specify the alias of an existing key entry.

worldwideName
Specifies the name of a device. This name is a nonsecure address that is used in combination with other device information, such as a serial number, to define devices and device paths. Specify a 16-character hexadecimal value that contains only the characters ABCDEFabcdef1234567890.

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
status Returns the status to indicate whether the device is added with an appropriate message.
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.
status Optional parameter. Returns more information about the error. For example, the status in the following Error response example indicates that the serialNumber that is added for the device was padded with leading zero's ('00').

Examples

Service request to add a device
POST https://localhost:<port>/SKLM/rest/v1/devices
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
{"type":"3592","serialNumber":"CDA39403AQJF","attributes":"worldwideName 
ABCdeF1234567890,description marketingDivisionDrive"}
Success response
 Status Code : 200 OK
Content-Language: en
{"code":"0","status":"Succeeded"}
Error response when device exists
POST https://localhost:<port>/SKLM/rest/v1/devices
Content-Type: application/json
Accept : application/json
Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20
Accept-Language : en
{"type":"LTO","serialNumber":"FAA49403AQ"}
Error response
 Status Code : 500 Internal Server Error
Content-Language: en
{ "code": "CTGKM0648I",
  "message": "CTGKM0648I Device serial number 00FAA49403AQ already 
   exists.",
  "status": "CTGKM0254I The device serial number was converted to 12 
   characters by adding two leading zeros. Modified device serial 
   number " 00FAA49403AQ " ."
}