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.
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
-
Go to Menu > Resource list to view a list of your resources.
-
From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.
-
On the KMS keys page, use the Keys table to browse the keys in your service.
-
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 isFalse
, the retention policy isn't enabled. -
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
-
Go to Menu > Resource list to view a list of your resources.
-
From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.
-
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 isDisabled
, the cloud resource can be erased. You can delete the key that is associated with the cloud resource if needed. -
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.
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
-
Retrieve your authentication credentials to work with the API.
-
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
oreu-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 bykeyId
. 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 thelimit
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>
-
Retrieve your authentication credentials to work with the API.
-
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
oreu-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.
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* . |
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.