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 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 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 " ."
}