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.