IBM Cloud Docs
Viewing associations between root keys and encrypted IBM Cloud resources

Viewing associations between root keys and encrypted IBM Cloud resources

You can view associations between root keys and other cloud resources, such as IBM Cloud Object Storage buckets, by using the IBM Cloud® Hyper Protect Crypto Services key management service API.

When you use a root key to protect at-rest data with envelope encryption, the cloud services that use the key can create a registration between the key and the resource that it protects. Registrations are associations between keys and cloud resources that help you get a full view of which encryption keys protect what data on IBM Cloud.

Table 1. Describes the benefits of key registration
Benefit Description
Centralized view of protected resources As an administrator for your Hyper Protect Crypto Services instance, you want to quickly understand which cloud resources are protected by a root key.
Security and compliance As a security admin, you need a way to determine the risk that's involved with destroying a root key. You want to examine which keys are actively protecting what data so that you can evaluate exposures based on your organization's security or compliance needs.

Key registration is an extra feature that's available only if the cloud service enables it as part of the integration with Hyper Protect Crypto Services. To determine whether an integrated service supports key registration, see the service documentation for more information.

Viewing protected resources with the UI

You can browse the registrations that are available between your Hyper Protect Crypto Services keys and cloud resources by using the Hyper Protect Crypto Services GUI.

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 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.

Viewing protected resources with the API

You can also browse the registrations that are available between your Hyper Protect Crypto Services keys and cloud resources by using the Hyper Protect Crypto Services key management service API.

For example, when you call GET api/v2/keys/{id}/registrations, Hyper Protect Crypto Services returns details about the key registration. The following JSON output represents a registration between a key and a cloud resource.

{
  "metadata": {
      "collectionType": "application/vnd.ibm.kms.registration+json",
      "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "string",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<region>: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"
      }
    }
  ]
}

The following table describes the properties of a registration.

Table 6. Properties that are associated with a registration
Parameter Description
keyID The ID that identifies the root key that is associated with the cloud resource.
resourceCrn The Cloud Resource Name (CRN) that represents the cloud resource, such as a Cloud Object Storage bucket, that is associated with the key.
createdBy The unique identifier for the resource that created the registration.
creationDate The date the registration was created.
updatedBy The unique identifier for the resource that updated the registration.
lastUpdatedDate The date the registration was created.
description A description for the registration.
preventKeyDeletion A boolean that determines whether Hyper Protect Crypto Services must prevent deletion of the root key. If true, the associated resource is nonerasable due to a retention policy, and the Hyper Protect Crypto Services key that is encrypting the resource cannot be deleted.
keyVersion The version of the root key that's protecting the cloud resource.

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://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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.

CRN query examples

Use URL encoded CRN queries that contain all CRN segments. To learn more about CRN segments and format, see Cloud Resource Names.

When an integrated service calls the Hyper Protect Crypto Services key management service API, Hyper Protect Crypto Services replaces the given CRN query (up to the service-instance segment) with the CRN of the calling service. This means that the services that use Hyper Protect Crypto Services to associate keys with resources on your behalf can only view or query for CRNs that match the first eight segments of their service CRN.

  • To search for the existence of a 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 a CRN segment that is 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.

    crn:v1:bluemix:public:databases-for-postgresql:us-south:a/e1bb63d6a20dc57c87501ac4c4c99dcb:76b98bfd-f730-47b8-b163-515187e070a7:*:<string>*
    

    This query returns all Cloud Databases registrations for deployment ID 76b98bfd-f730-47b8-b163-515187e070a7 that are prefixed by <string>.

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

Table 9. CRN query examples
Value
crn:v1:bluemix:public:databases-for-redis:us-south:a/274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7:*:*
crn:v1:bluemix:public:cloud-object-storage:global:a/e1bb63d6a20dc57c87501ac4c4c99dcb:*:bucket:prod*
crn:v1:bluemix:public:cloudantnosqldb:us-south:a/f586c28d154d4c65a4a4a34cf75f55d0:94255ea3-af1c-41b7-9805-61f775e20702:*:prod*.
Table 9. CRN query examples
Value
crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-redis%3Aus-south%3Aa%2F274074dce64e9c423ffc238516c755e1%3A29caf0e7-120f-4da8-9551-3abf57ebcfc7%3A*%3A*
crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2Fe1bb63d6a20dc57c87501ac4c4c99dcb%3A*%3Abucket%3Aprod*
crn%3Av1%3Abluemix%3Apublic%3Acloudantnosqldb%3Aus-south%3Aa%2Ff586c28d154d4c65a4a4a34cf75f55d0%3A94255ea3-af1c-41b7-9805-61f775e20702%3A%2A%3Aprod%2A

What's next

To find out more about viewing registrations, check out the Hyper Protect Crypto Services key management service API reference doc.