Grouping keys together using key rings

Creating key rings with the UI

You must have either the service "Writer" or "Manager" role to create a key ring.

To create a key ring:

1. Click on Key rings in the left navigation.
2. In the Key rings panel, click the Create button.
3. In the Create a key ring tab, give your new key ring a name, following the instructions on permitted characters. Then click Create.

After it is created, your new key ring will appear in the list of key rings and you are able to transfer keys to it or create keys for it.

Creating key rings with the API

Create a key ring by making a POST call to the following endpoint.

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

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

2. Create a key ring by running the following curl command.

   $ curl -X POST \
       "https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "correlation-id: <correlation_ID>"
   

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

A successful POST api/v2/key_rings request returns an HTTP 201 Created response, which indicates that the key ring was created and is now available for to hold standard and root keys.

Granting access to a key ring

You can grant access to a key ring within a Key Protect instance by using the IBM Cloud console, IAM API, or CLI{ :external}.

Review roles and permissions to learn how IBM Cloud IAM roles map to Key Protect actions.

To assign access to a key ring with the console:

1. From the menu bar, click Manage > Access (IAM), and select Users to browse the existing users in your account.

2. Select a table row, and click the ⋯ icon to open a list of options for that user.

3. From the options menu, click Assign access.

4. Click Assign users additional access.

5. Click the IAM services button.

6. From the list of services, select Key Protect.

7. Select Services based on attributes.

8. Select the Instance ID attribute and select the instance in which the key ring resides.

9. Select the Key Ring ID attribute and enter the ID associated with the key ring.

10. Choose a combination of platform and service access roles to assign access for the user.

11. Click Add.

12. Continue to add platform and service access roles as needed and when you are finished, click Assign. Note that the user must be assigned at least Reader access to the entire instance in order for them to list, create and delete key rings within the instance.

Listing key rings with the API

For a high-level view, you can browse the key rings that are managed in your provisioned instance of Key Protect by making a GET call to the following endpoint.

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

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

2. View general characteristics about your key rings by running the following curl command.

   $ curl -X GET \ "https://<region>.kms.cloud.ibm.com/api/v2/key_rings?totalCount=<show_total>&offset=<offset_value>&limit=<offset_limit>" \
       -H "accept: application/vnd.ibm.kms.key_ring+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "correlation-id: <correlation_ID>"
   

   Query parameters following the question mark ? are optional, but included here to document their use. (: :note)

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

A successful GET api/v2/key_rings request returns a collection of key rings that are available in your Key Protect service instance.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key_ring+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "default"
        },
        {
            "id": "Sample Key Ring 2",
            "creationDate": "2020-03-12T11:00:06Z",
            "createdBy": "..."
        }
    ]
}

Deleting key rings with the API

You can delete a key ring by making a DELETE call to the following endpoint.

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

This action won't succeed if the key ring contains at least one key in a state other than the Destroyed state. If the only keys in the key ring are in the Destroyed state, the key ring can be deleted if force=true is added to the delete command. The keys in that state are automatically transferred to the default key ring.

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

2. Retrieve the ID of the key ring that you want to delete.

   You can find the ID for a key ring in your Key Protect instance by retrieving a list of your key rings.

3. Run the following curl command to delete the key ring. Note the presence of force=true, which force deletes the key ring in the event that it contains keys in the Destroyed state.

   $ curl -X DELETE \
       "https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>?force=true" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "prefer: <return_preference>"
   

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

A successful request returns an HTTP 204 No Content response, which indicates that the key ring was successfully deleted.