Viewing associations between root keys and encrypted IBM Cloud resources

Viewing protected resources associated with your root key

1. Log in to the UI.

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 Hyper Protect Crypto Services.

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

5. To view the protected resources of a specific root key, click the Actions icon to open a list of options for the key, and select View associated resources to browse all resources protected by the key.

   Table 2. Describes the table of viewing associated resources

   Column	Description
   Resource name	The name of the cloud resource, such as a Cloud Object Storage bucket, that is associated with the key.
   Service name	The name of the IBM Cloud service instance that the resource resides in.
   Retention policy	Whether the cloud resource has a retention policy. If the value is True, a retention policy is enabled for the cloud resource, and the key that is associated with the cloud resource can't be deleted. If the value is False, the retention policy isn't enabled.

6. To view details of each resource, expand the resource details by clicking the caret (^) icon under the Resource name column.

   The following table describes the registration details.

   Table 3. Describes the properties that are associated with a resource

   Field	Description
   Created	The date and time that the resource was first associated with the key.
   Last updated	The date and time that the registration was updated.
   Description	The description of the registration.
   Key version ID	The version of the root key that's protecting the cloud resource.
   Key version date	The date and time that the root key version was updated.
   Cloud resource name	Represents the cloud resource that is associated with the key, including the Cloud Resource Name (CRN), version, cname, ctype, and so on.

You can use the search field to search for any resources that are associated with the root key either with the resource name or the key version ID.

Viewing resources in your instance

1. Log in to the UI.

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 Hyper Protect Crypto Services.

4. On the KMS associated resources page, use the Key management service associated resources table to browse the registrations in your service.

   Table 4. Describes the table of associated resources

   Column	Description
   Resource name	The name of the cloud resource, such as a Cloud Object Storage bucket, that is associated with the key.
   Key name	The human-readable name that identifies the root key that is associated with the specified cloud resource.
   Key ID	The ID that identifies the root key that is associated with the specified cloud resource.
   Service name	The name of the IBM Cloud service instance that the resource resides in.
   Retention policy	Indicates whether the cloud resource can be erased. If the value is Enabled, the cloud resource can't be erased, and the key that is associated with the cloud resource can't be deleted. If the value is Disabled, the cloud resource can be erased. You can delete the key that is associated with the cloud resource if needed.

5. Click the caret (^) icon under the Resource name column to view a list of details for a specific registration.

   The following table describes the registration details.

   Table 5. Describes the properties that are associated with a resource

   Field	Description
   Created	The date and time that the resource was first associated with the key.
   Last updated	The date and time that the registration was updated.
   Description	The description of the registration.
   Key version ID	The version of the root key that's protecting the cloud resource.
   Key version date	The date and time that the root key version was updated.
   Cloud resource name	Represents the cloud resource that is associated with the key, including the Cloud Resource Name (CRN), version, cname, ctype, and so on.

Besides searching for a resource, you can also for resources by Resource Name, key ID, and retention policy. To do so, click the Filter button, select the filter options from the list, and click Apply.

Listing registrations for a specific root key with the API

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

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/registrations \
   -H 'authorization: Bearer <IAM_token>' \
   -H 'bluemix-instance: <instance_ID>'
   

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

   Table 7. Describes the variables needed to list all registrations that are associated with a root key

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see Regional service endpoints.
   port	Required. The port number of the API endpoint.
   IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request. For more information, see Retrieving an access token.
   instance_ID	Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.

   A successful GET api/v2/keys/<key_ID>/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": "string",
         "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
         "createdBy": "string",
         "creationDate": "2010-01-12T05:23:19+0000",
         "updatedBy": "string",
         "lastUpdated": "2010-01-12T05:23:19+0000",
         "description": "string",
         "preventKeyDeletion": true,
         "keyVersion": {
             "id": "string",
             "creationDate": "2010-01-12T05:23:19+0000"
         }
       },
       {
         "keyId": "string",
         "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
         "createdBy": "string",
         "creationDate": "2010-01-12T05:23:19+0000",
         "updatedBy": "string",
         "lastUpdated": "2010-01-12T05:23:19+0000",
         "description": "string",
         "preventKeyDeletion": true,
         "keyVersion": {
             "id": "string",
             "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 the 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.

Listing registrations for any root keys with the API

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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/registrations?urlEncodedResourceCRNQuery=<url_encoded_CRN_query>

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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/registrations?urlEncodedResourceCRNQuery=<url_encoded_CRN_query> \
   -H 'authorization: Bearer <IAM_token>' \
   -H 'bluemix-instance: <instance_ID>'
   

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

   Table 8. Describes the variables needed to list registrations by CRN query.

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see Regional service endpoints.
   port	Required. The port number of the API endpoint.
   url_encoded_CRN_query	Filters for resources that are associated with a specified Cloud Resource Name (CRN) by using URL encoded wildcard characters (*). The parameter needs to contain all CRN segments and must be URL encoded. To view examples, see CRN query examples.
   IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request. For more information, see Retrieving an access token.
   instance_ID	Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.