Using the key management interoperability protocol (KMIP)

Creating an adapter

A maximum of 200 adapters can be created on a single instance. Each adapter can have a maximum of 200 certificates associated with it.

KMIP adapters are created using Key Protect root keys. If you do not have a root key, create one.

Before you begin, ensure that you have the Manager role or the KmipAdapterManager role on the instance.

To create an adapter:

1. In the navigation menu, click KMIP adapters. If this is your first adapter, the table is empty.

2. Click Create.

3. In the side panel, provide the following information:

   • Name - Enter a name for the adapter (2-40 characters).
   • Description (optional) - Enter a description for the adapter (2-240 characters).
   • Root key - Select the root key to use for this adapter. The root key encrypts the KMIP keys that the adapter creates. Your root key must be in an active state for your adapter to function correctly.

4. Optional: Add a public TLS certificate to allow the holder of the corresponding private certificate to communicate with Key Protect through the KMIP adapter. Only authorized certificates can make KMIP protocol requests against your instance.

   To add a certificate:

   1. Click Add.
   2. Enter a name for the certificate.
   3. Enter the certificate contents in PEM format, including the BEGIN CERTIFICATE and END CERTIFICATE tags.
   4. Click Add certificate.

   Certificate association can take a few minutes. A certificate can only be associated with a single adapter in a Key Protect region.

Resources managed through the KMIP protocol cannot be accessed through the HTTP API.

Keep the private key of any uploaded certificates secure. Any certificate uploaded to a KMIP adapter can make all supported KMIP operations.

Viewing and updating adapter details

The adapter details panel displays information about an adapter and allows you to perform actions such as adding certificates.

To view adapter details:

1. Click the actions menu (⋯) for the adapter.
2. Select Details.

The details panel displays the adapter's name, description, associated KMIP symmetric keys, and uploaded certificates. You can also upload additional certificates from this panel.

KMIP symmetric keys cannot be deleted using the console. To delete keys, use the CLI. Only KMIP symmetric keys that are not in the Active state (state 1) can be deleted. You cannot delete an adapter if it contains keys in the Active state.

Each adapter's resources are protected with a root key. You cannot delete a root key that is active and associated with an adapter.

Each KMIP symmetric key that is created counts as a single key version and incurs a charge of one key version. Deletion of a KMIP symmetric key is permanent.

Creating and using KMIP adapters in the API

This section describes how to use KMIP adapters of profile native_1.0 with the API, including adding and removing KMIP client certificates and viewing and deleting KMIP objects.

You can create a KMIP adapter by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters

Operations on KMIP adapter subresources, including KMIP client certificates and KMIP objects will be in the following endpoints:

https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name_or_ID>/certificates
https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name_or_ID>/kmip_objects

1. Retrieve authentication credentials to work with keys in the service.

2. Copy the ID of the root key that you want to use to create your KMIP adapter.

   You can find the ID for a key in your Key Protect instance by retrieving a list of your keys, or by accessing the Key Protect dashboard.

3. Create a KMIP adapter with the following curl command:

   $ curl -X POST \
       "https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters" \
       -H "accept: application/vnd.ibm.kms.kmip_adapter+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "content-type: application/vnd.ibm.kms.kmip_adapter+json" \
       -d '{
               "metadata": {
                   "collectionType": "application/vnd.ibm.kms.kmip_adapter+json",
                   "collectionTotal": 1
               },
               "resources": [
                   {
                   "name": "<adapter_name>",
                   "description": "<adapter_description>",
                   "profile": "native_1.0",
                   "profile_data": {
                       "crk_id": "<root_keyID_or_alias>"
                   }
                   }
               ]
           }'
   

   Replace the variables in the example request according to the following table.

4. Optional: you can list KMIP adapters that exist in an instance with the following curl command:

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters" \
       -H "accept: application/vnd.ibm.kms.kmip_adapter+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "content-type: application/vnd.ibm.kms.kmip_adapter+json"
   

   You can also get a specific KMIP adapter by using the following curl command:

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name_or_ID>" \
       -H "accept: application/vnd.ibm.kms.kmip_adapter+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "content-type: application/vnd.ibm.kms.kmip_adapter+json"
   

   Note that you can use either the adapter's UUID or the adapter's name to get a specific adapter.

5. You can delete a KMIP adapter with the following curl command:

   $ curl -X DELETE \
       "https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name_or_ID>" \
       -H "accept: application/vnd.ibm.kms.kmip_adapter+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "content-type: application/vnd.ibm.kms.kmip_adapter+json"
   

   You can only delete the KMIP adapter if all the KMIP objects under the adapter are deleted.