Key Management Service APIs

Use these APIs to manage keys for Key Management Service (KMS).

Access to the API endpoints is governed by the access level of the service ID that makes the call.

To use these APIs, you must have a service ID, and you must add an authorization header to your request. You need an OIDC access token to add to the authorization header. To obtain the access token, see Generate an OpenID Connect (OIDC) token.

<Cluster Master Host>:<Cluster Master API Port> are used to access the APIs. The parameters are defined in Master endpoints.

Generate a key

Required user type or access level: Cluster administrator, Administrator, or Editor

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'content-type: application/vnd.ibm.kms.key+json' \
   -H 'correlation-id: <correlation_ID>' \
   -d '{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
    "type": "application/vnd.ibm.kms.key+json",
    "name": "<key_alias>",
    "description": "<key_description>",
    "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
    "extractable": <key_type>
    }
  ]
 }'

Variable	Description
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.
correlation_ID	The unique identifier that is used to track and correlate transactions.
key_alias	A unique, human-readable name for easy identification of your key. Important: To protect your privacy, do not store your personal data as metadata for your key.
key_description	Optional: An extended description of your key. Important: To protect your privacy, do not store your personal data as metadata for your key.
YYYY-MM-DD HH:MM:SS.SS	Optional: The date and time that the key expires in the system, in RFC 3339 format. If you do not specify the `expirationDate` attribute, the key does not expire.
key_type	A boolean value that determines whether the key material can leave the service. When you set the `extractable` attribute to `false`, the service creates a root key that you can use for `wrap` or `unwrap` operations. Set the `extractable` attribute to `true` to generate a standard key.

A successful response returns the ID value for your key, along with other metadata. The ID is a unique identifier that is assigned to your key and is used for subsequent calls to the Key Protect API.

Import a key

Required user type or access level: Cluster administrator, Administrator, or Editor

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

 curl -X POST \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'content-type: application/vnd.ibm.kms.key+json' \
   -H 'correlation-id: <correlation_ID>' \
   -d '{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
    "type": "application/vnd.ibm.kms.key+json",
    "name": "<key_alias>",
    "description": "<key_description>",
    "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
    "payload": "<key_material>",
    "extractable": <key_type>
    }
  ]
 }'

Variable	Description
IAM_token	Your IBM Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.
correlation_ID	The unique identifier that is used to track and correlate transactions.
key_alias	A unique, human-readable name for easy identification of your key. Important: To protect your privacy, do not store your personal data as metadata for your key.
key_description	Optional: An extended description of your key. Important: To protect your privacy, do not store your personal data as metadata for your key.
YYYY-MM-DD HH:MM:SS.SS	Optional: The date and time that the key expires in the system, in RFC 3339 format. If you do not specify the `expirationDate` attribute, the key does not expire.
key_material	The base64 encoded key material, such as an existing key-wrapping key, that you want to store and manage in the service. Ensure that the key material meets the following requirements: 1. The key must be 256, 384, or 512 bits. 2. The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding.
key_type	A boolean value that determines whether the key material can leave the service. When you set the `extractable` attribute to `false`, the service imports a root key that you can use for `wrap` or `unwrap` operations. Set the `extractable` attribute to `true` to import a standard key.

A successful response returns the ID value for your key, along with other metadata. The ID is a unique identifier that is assigned to your key and is used for subsequent calls to the Key Protect API.

Retrieve list of keys

Required user type or access level: Cluster administrator, Administrator, or Editor

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -X GET \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.collection+json' \

Variable	Description
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.

A successful response returns the number of keys and the key names. It does not return the key material.

Retrieve number of keys

Required user type or access level: Cluster administrator, Administrator, or Editor

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys

Command

HEAD

Command output format

application/json

The sample curl command resembles the following code:

curl -X HEAD \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.collection+json' \

Variable	Description
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.

A successful response returns the number of keys.

Retrieve a key by ID

Required user type or access level: Cluster administrator, Administrator, or Editor

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys/{ID}

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -X GET \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys/{ID} \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.collection+json' \

Variable	Description
ID	The v4 UUID of the key.
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.

A successful response returns the details of the requested key.

Wrap a key

Required user type or access level: Cluster administrator, Administrator, Editor, or Viewer

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys/{ID}

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys/{ID}?action=wrap \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.kms.key_action+json' \
   -H 'content-type: application/vnd.ibm.kms.key+json' \   
   -d '{
     'plaintext': '<data_key>',
     'aad': ['<additional_data>', '<additional_data>']
   }'

Variable	Description
ID	The root key that is used as the wrapping key. It must be a v4 UUID for an active key.
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.
correlation_ID	The unique identifier that is used to track and correlate transactions.
data_key	The data encryption key (DEK). Provide a base64 encoded plaintext during a wrap action. To generate a new DEK, omit the plaintext property. KMS generates a random plaintext of 32 bytes that is rooted in an HSM device and then wraps that value. The key length must be less than or equal to 4096 bytes.
additional_data	The additional authentication data (AAD) that is used to secure the key. If you use AAD when you make a wrap call, you must use the same AAD during an unwrap call. You can specify up to 126 AADs. The length of the AAD must be in the range 0-255.

Unwrap a key

Required user type or access level: Cluster administrator, Administrator, Editor, or Viewer

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys/{ID}

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys/{ID}?action=unwrap \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.kms.key_action+json' \
   -H 'content-type: application/vnd.ibm.kms.key+json' \   
   -d '{
     'ciphertext': '<data_key>',
     'aad': ['<additional_data>', '<additional_data>']
   }'

Variable	Description
ID	The root key that is used as the wrapping key. It must be a v4 UUID for an active key.
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.
correlation_ID	The unique identifier that is used to track and correlate transactions.
data_key	The wrapped DEK (WDEK) that is used in `unwrap` actions. Provide a base64 encoded ciphertext during an unwrap action. The response is a base64 encoded plaintext in the response body.
additional_data	The AAD that is used to secure the key. If you used AADs when you made a wrap call, you must use the same AADs during the unwrap call.

Rotate a key

Required user type or access level: Cluster administrator or Administrator

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys/{ID}

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys/{ID}?action=rotate \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.kms.key_action+json' \
   -H 'content-type: application/vnd.ibm.kms.key+json' \   
   -d '{
     'payload': '<data_key>'
   }'

Variable	Description
ID	The root key that is used as the wrapping key. It must be a v4 UUID for an active key.
ACCESS_TOKEN	Your IBM Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.
correlation_ID	The unique identifier that is used to track and correlate transactions.
data_key	The base64 encoded key material, such as an existing key-wrapping key, that you want to store and manage in the service. To rotate a key that was initially generated by KMS, omit the payload attribute and pass an empty request entity body. To rotate an imported key, provide a key material that meets the following requirements: 1. The key must be 256, 384, or 512 bits. 2. The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding.

Delete a key by ID

Required user type or access level: Cluster administrator or Administrator

API version

2.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

/kms/api/v2/keys/{ID}

Command

DELETE

Command output format

application/json

The sample curl command resembles the following code:

curl -X DELETE \
   https://<Cluster Master Host>:<Cluster Master API Port>/kms/api/v2/keys/{ID} \
   -H 'authorization: Bearer $ACCESS_TOKEN' \
   -H 'icp-instance: <instance_ID>' \
   -H 'accept: application/vnd.ibm.collection+json' \

Variable	Description
ID	The v4 UUID of the key.
ACCESS_TOKEN	Your IBM® Cloud Private access token. Include the full contents of the access token, including the Bearer value, in the curl request.
instance_ID	The unique identifier that is assigned to your KMS instance.

When you delete a key, the key content and associated data is permanently removed. You cannot reverse the action.