Use Key Import REST
Service to import
secret keys or public/private key pairs. A secret key is a symmetric
key. A public/private key pair is an asymmetric key pair that contains
a public key and a private key. The private key file is in PKCS#12
format.
Table 1. Topic change
log
Date |
Change description |
10 Feb 2021 |
Corrected instances of 'TLSServer' to 'SSLServer', and 'TLSClient' to 'SSLClient'. Refreshed
only the English language content. |
08 Dec 2020 |
Initial version. |
To
import secret keys, the import file might contain multiple
keys. Each key contains the required alias value for that key. The
import file must be generated by a previous
Key Export REST
Service.
- Operation
POST
- URL
- https://<host>:<port>/SKLM/rest/v1/keys/import
By default,
Guardium® Key Lifecycle Manager server
listens to non-secure port 9080 (HTTP) and secure port
9443
(HTTPS) for communication. During
IBM® Security Guardium Key Lifecycle Manager
installation, you can modify these default ports.
Note: The non-secure port 9080 is not applicable
when IBM Security Guardium Key Lifecycle Manager is deployed in a containerized
environment.
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. |
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 |
alias |
Required parameter in the following scenarios:
This parameter is not required when the keystore file contains only one private key. If you
specify a value, it is ignored.
|
fileName |
Required. Specify the path and file name of
the file from which the keys are imported. |
keyAlias |
This
parameter is required if the value of the
type attribute is secretkey . Specify the alias of
the private key entry in the keystore that decrypts the secret key
or keys, from the file. Use the same alias value to import and export
a secret key or keys. |
newAlias |
Specify a new value for the key alias. |
password |
This parameter is required if the type parameter
is privatekey . This password was previously specified
with the Key Export REST Service. If you export
private keys to a PKCS#12 file, ensure that the
file with the key is wrapped with a FIPS-approved method before the
file leaves the computer. |
type |
Specify whether the keys are secret or private.
- secretkey
- Specifies a symmetric key.
If you
select this value, specify
a value for the usage attribute for a device
group family that administers keys.
- privatekey
- Specifies an asymmetric key in a key pair with a public key and
a private key.
If you select this value, specify a value for the usage attribute
for a device group that administers keys. You can specify any of the
following values:
|
usage |
Specify the target application usage such as LTO device
group. You can specify the following values:
- 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.
|
usage |
- ETERNUS_DX
- Specifies the ETERNUS_DX device group that is in the DS5000 device family.
- XIV®
- Specifies the IBM Spectrum® Accelerate (previously known as XIV) 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.
|
usage |
- 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.
- SSLCLIENT
- Client-side certificate that is used in secure communication by using Transport Layer Security
protocol to authenticate the client device.
- SSLSERVER
- Server-side certificate that is used in secure communication by using Transport Layer Security
protocol.
- 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.
|
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 for privatekey
type
JSON
object with the following specification:
JSON
property name |
Description |
code |
Returns an integer value such as 0 to indicate
the key import status. |
status |
Returns the status to indicate that the key
import task is succeeded. |
Success response body for secretkey
type
JSON
array that contains JSON objects with the following specification:
JSON property name |
Description |
ImportedKeys |
JSON array that contains JSON objects with a
list of imported keys. If no keys are imported, an empty list is returned. |
ExistingKeys |
JSON array that contains JSON objects with a
list of duplicate keys. If there are no duplicate keys, an empty list
is returned. |
FailedToImportKeys |
JSON array that contains JSON objects with a
list of failed keys. If there are no keys failed keys, an empty list
is returned. |
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 import a symmetric key (
secretkey
type)
POST https://localhost:<port>/SKLM/rest/v1/keys/import
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"keyAlias":" sklmCertificate", "alias":"xyz000000000000000000","newAlias":"ayz000000000000000000","type":"secretkey","fileName":
"mykey","usage":"LTO"}
- Success response
Status Code : 200 OK
{"ImportedKeys":[{"KeyAlias":"ayz000000000000000000"}],
"ExistingKeys":[],"FailedToImportKeys":[]}
- Service request to import a private key (
privatekey
type)
POST https://localhost:<port>/SKLM/rest/v1/keys/import
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"type":"privatekey","fileName":"mykey","usage":"SSLSERVER","password":"mypassword","newAlias":"mykey"}
- Success response
Status Code : 200 OK
{"code":"0","status":"Succeeded"}
- Service request to import multiple private keys (
privatekey
type)
POST https://localhost:<port>/SKLM/rest/v1/keys/import
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"type":"privatekey","fileName":"mykey","usage":"3592","password":"mypassword","alias":"abc1","newAlias":"mykey"}
- Success response
Status Code : 200 OK
{"code":"0","status":"Succeeded"}
- Error response for an invalid request
POST https://localhost:<port>/SKLM/rest/v1/keys/import
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m{"type":"privatekey",
"fileName":"privatekeys","usage":"3592","password":"SKLM@admin123","newAlias":"mykey"}
- Error response
Status Code : 500 Internal Server Error
{"code":"CTGKM3306E","message":"CTGKM3306E
Multiple aliases found in the file. Please mention the alias to be imported."}