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.

To create an adapter:

1. Navigate to the KMIP Adapters panel using the left navigation. If this is your first adapter, the table should be empty. Note that you must either have the Manager role or the KmipAdapterManager role on the instance in order to create an adapter.

2. Find the Create Adapter button and click it.

3. In the open side panel, give the adapter a Name and, optionally, a Description. Note that names must contain at least two and no more than 40 characters. If you choose to give it a description, it must be at least two and no more than 240 characters. After that has been completed, you can choose the root key you want to use to create this adapter and to encrypt the KMIP keys it creates. Choosing a root key is mandatory. Note that your root key must be in an active state for your adapter to function correctly.

4. Adding a public TLS certificate allows the holder of its corresponding private certificate to communicate with Key Protect via its associated KMIP adapter. Only certificates authorized under a KMIP adapter will be permitted to make KMIP protocol requests against your instance. Note that resources managed via the KMIP protocol cannot be accessed via HTTP API.

   While you do not need to add any certificates during the creation of the adapter, if you know which certificates you want to add, you can do so by clicking the Add certificates (optional) tab in the panel. In the resulting screen, click the Upload certificate button, give the certificate a name, and input the contents of the certificate (the material must be in PEM format and contain the BEGIN CERTIFICATE and END CERTIFICATE tags). Note that it can take a few minutes for the certificate to be associated. Also, a certificate can only be associated with a single adapter in a Key Protect region.

Keep the private key of any uploaded certificates secure, as any certificate uploaded to a KMIP adapter will have the ability to make all supported KMIP operations.

Viewing and updating adapter details

The adapter details panel allows you to learn about an adapter (for example, through its description) and also allows you to do actions like adding certificates.

To view the adapter details, click the ⋯ icon. This shows all of the details about the adapter. Here you can see its name, its description, any KMIP symmetric keys associated with the adapter, and certificates that have been uploaded to it. You can also use this panel to upload more certificates, as desired.

KMIP symmetric keys cannot be deleted using the UI. To delete keys, you must use the CLI. Only KMIP symmetric keys that are in a state other than the Active (state 1) can be deleted. An adapter cannot be deleted if it contains keys that are in the Active state.

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

Each KMIP symmetric key that is created counts as a single key version and may incur a charge, depending on the number of key versions you have. If you want to delete a KMIP symmetric key, you can only do so using the API, CLI, or SDK. You cannot use the UI. Note that deletions of a KMIP symmetric is permanent.

Creating and using KMIP adapters in the API

This will walk through using KMIP adapters of profile native_1.0 using the API, adding and removing KMIP client certificates from the adapter, then viewing and deleting KMIP objects associated with the adapter.

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.