Viewing associations between root keys and encrypted IBM Cloud resources

Viewing protected resources in your instance

1. Log in to the IBM Cloud console.

2. Go to Menu > Resource List to view a list of your resources.

3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

4. Select the Associated resources link on the left side menu.

5. On the Associated resources page, use the Associated Resources table to browse the registrations in your service.

6. Click the ^ icon under the Details column to view a list of details for a specific registration.

7. Click Filter button to filter for resources by key ID, Cloud Resource Name (CRN), and retention policy.

Viewing protected resources associated with your key

1. Log in to the IBM Cloud console.

2. Go to Menu > Resource List to view a list of your resources.

3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

4. On the application details page, use the Keys table to browse the keys in your service.

5. Click the ⋯ icon to open a list of options for the key.

6. From the options menu, click Key associated resources to view the key's associated registrations.

Listing registrations for a specific root key

You can retrieve the registration details that are associated with a specific root key by making a GET call to the following endpoint.

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

1. Retrieve your authentication credentials to work with the API.

2. View the registrations that are associated with a root key by running the following curl command.

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/registrations" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>"
   

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

A successful GET api/v2/keys/<keyID_or_alias>/registrations request returns a collection of registrations that are mapped to the specified key ID.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.registration+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "keyId": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6",
            "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
            "createdBy": "IBMid-25555555",
            "creationDate": "2010-01-12T05:23:19+0000",
            "updatedBy": "IBMid-25555555",
            "lastUpdated": "2010-01-12T05:23:19+0000",
            "description": "A description of the registration",
            "preventKeyDeletion": true,
            "keyVersion": {
                "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6",
                "creationDate": "2010-01-12T05:23:19+0000"
            }
        },
        {
            "keyId": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
            "createdBy": "IBMid-25555555",
            "creationDate": "2010-01-12T05:23:19+0000",
            "updatedBy": "IBMid-25555555",
            "lastUpdated": "2010-01-12T05:23:19+0000",
            "description": "A description of the registration",
            "preventKeyDeletion": true,
            "keyVersion": {
                "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
                "creationDate": "2010-01-12T05:23:19+0000"
            }
        }
    ]
}

The resourceCrn value represents the unique identifier of the cloud resource that is encrypted by keyId. The metadata that is associated with the registration, such as its creation date, is also returned in the response body.

By default, GET api/v2/keys/registrations returns the first 200 registrations, but you can adjust this limit by using the limit parameter at query time.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/registrations?preventKeyDeletion=<true|false>&urlEncodedResourceCRNQuery=<url_encoded_CRN>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/registrations?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Listing registrations for any root key

You can also retrieve a list of registrations that are associated with any cloud resource by making a GET call to the following endpoint.

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

1. Retrieve your authentication credentials to work with the API.

2. View the registrations that match a CRN query that you specify by running the following curl command.

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys/registrations" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>"
   

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

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/registrations?preventKeyDeletion=<true|false>&urlEncodedResourceCRNQuery=<url_encoded_CRN>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/registrations?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

CRN query examples

Use URL encoded CRN queries to filter registrations by Key Protect instance, resource type, or resource name. To learn more about CRN segments and format, see Cloud Resource Names.

Cloud Services that use Key Protect to associate keys with resources on your behalf can only view or query for CRNs that match the first 8 segments of their service CRN.

• To search for the existence of a registration up to a specific CRN segment, use a colon followed by an asterisk (*).

  crn:v1:bluemix:public:databases-for-redis:us-south:a/
  274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7:*:*
  

  This query returns Databases for Redis registrations that are associated with all resource types and names for deployment ID 29caf0e7-120f-4da8-9551-3abf57ebcfc7.

• To search for existence of a registration up to a specific CRN segment that's prefixed by <string>, use a colon followed by <string>* on the last segment of the CRN query.

  crn:v1:bluemix:public:cloud-object-storage:global:a/e1bb63d6a20dc57c87501ac4c4c99dcb:*:bucket:prod*
  

  This query returns all Cloud Object Storage bucket registrations within account e1bb63d6a20dc57c87501ac4c4c99dcb that are prefixed by prod.

When listing registrations that are associated with any root key, your CRN query should not contain an asterisk (*) in the first eight segments.

The following tables provides a list of CRN query examples before and after URL encoding. To view the URL encoded values, click the URL encoded tab.