Configure Key Access Justifications with Cloud HSM
This page describes how to configure Key Access Justifications with Cloud HSM for Assured Workloads' Japan Regions control package.
During the steps to create a new Assured Workloads folder for Japan Regions, you have the option of creating a new project and a key ring for your cryptographic keys. Cloud HSM keys keys can be added to this key ring, and you can also configure a Key Access Justifications policy to control access to each key.
Before you begin
- The ability to use Key Access Justifications with Cloud HSM keys is only available for the Japan Regions control package in Assured Workloads.
- Ensure that your administrator has granted you one of the required Identity and Access Management (IAM) roles to create and manage both your Key Access Justifications policies and the Cloud HSM keys themselves.
Required IAM permissions
To get the permissions that you need to create and manage Cloud HSM keys and their Key Access Justifications policies,
ask your administrator to grant you the
Cloud KMS Admin (roles/cloudkms.admin
) IAM role on the project containing the key ring.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to create and manage Cloud HSM keys and their Key Access Justifications policies. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create and manage Cloud HSM keys and their Key Access Justifications policies:
-
cloudkms.cryptoKeys.create
-
cloudkms.cryptoKeys.update
-
cloudkms.cryptoKeys.get
You might also be able to get these permissions with custom roles or other predefined roles.
Configure a Cloud HSM key with Key Access Justifications
To configure Key Access Justifications with a Cloud HSM key, you can either include the key access policy as a parameter when you create the key, or you can update the key with the policy after the key has been created.
Create a new key and policy
REST
Create a new key and policy using the
cryptoKeys.create
method:
POST https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME
In the request, replace the following placeholder values:
- PROJECT_ID: The project ID that contains the key ring on which
you want to add a key—for example,
919698201234
. - LOCATION: The location of the key ring—for example,
us-west1
. - KEY_RING: The name of the key ring that you specified when
you created your Assured Workloads folder's key management project
and key ring—for example,
my-key-ring
. - KEY_NAME: The name of the HSM key you want to create—for
example,
my-hsm-key
.
Request body:
{ "purpose": "PURPOSE", "versionTemplate": { "protectionLevel": "HSM", "algorithm": "ALGORITHM" }, "keyAccessJustificationsPolicy": { "allowedAccessReasons": [ ALLOWED_ACCESS_REASONS ] } }
In the request body, replace the following placeholder values:
- PURPOSE: The purpose for the key. For a list of different key
purposes, see
Key purposes—for example,
ENCRYPT_DECRYPT
. - ALGORITHM: The cryptographic algorithm to use. For a list of
available algorithms, see
Cloud KMS algorithms—for example,
GOOGLE_SYMMETRIC_ENCRYPTION
. - ALLOWED_ACCESS_REASONS: The Key Access Justifications policy that defines zero
or more allowed
justification codes
for accessing the encryption key—for example,
CUSTOMER_INITIATED_ACCESS
.
The following example request and request body only allows access justifications for a few reasons:
POST https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys?crypto_key_id=my-hsm-key
{ "purpose": "ENCRYPT_DECRYPT", "versionTemplate": { "protectionLevel": "HSM", "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION" }, "keyAccessJustificationsPolicy": { "allowedAccessReasons": [ "CUSTOMER_INITIATED_ACCESS", "GOOGLE_INITIATED_SYSTEM_OPERATION" ] } }
Update an existing key's policy
REST
Update an existing key in Cloud KMS using the
cryptoKeys.patch
method:
PATCH https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?update_mask=keyAccessJustificationsPolicy
In the request, replace the following placeholder values:
- PROJECT_ID: The project ID of the project that contains the key
ring for the key—for example,
919698201234
. - LOCATION: The location of the key ring—for example,
us-west1
. - KEY_RING: The name of the key ring that you specified when
you created your Assured Workloads folder's key management project
and key ring—for example,
my-key-ring
. - KEY_NAME: The name of the HSM key you want to update—for
example,
my-hsm-key
.
Request body:
{ "purpose": "PURPOSE", "versionTemplate": { "protectionLevel": "HSM", "algorithm": "ALGORITHM" }, "keyAccessJustificationsPolicy": { "allowedAccessReasons": [ ALLOWED_ACCESS_REASONS ] } }
In the request body, replace the following placeholder values:
- PURPOSE: The purpose for the key. For a list of different key
purposes, see
Key purposes—for example,
ENCRYPT_DECRYPT
. - ALGORITHM: The cryptographic algorithm to use. For a list of
available algorithms, see
Cloud KMS algorithms—for example,
GOOGLE_SYMMETRIC_ENCRYPTION
. - ALLOWED_ACCESS_REASONS: The Key Access Justifications policy that defines zero
or more allowed
justification codes
for accessing the encryption key—for example,
CUSTOMER_INITIATED_ACCESS
.
The following example request and request body only allows access justifications for a few reasons:
PATCH https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys/my-hsm-key?keyAccessJustificationsPolicy
{ "purpose": "ENCRYPT_DECRYPT", "versionTemplate": { "protectionLevel": "HSM", "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION" }, "keyAccessJustificationsPolicy": { "allowedAccessReasons": [ "CUSTOMER_INITIATED_ACCESS", "GOOGLE_INITIATED_SYSTEM_OPERATION" ] } }
Get the Key Access Justifications policy for a key
REST
Get metadata about an existing key in Cloud KMS using the
cryptoKeys.get
method:
GET https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME
In the request parameters, replace the following placeholder values with your own:
- PROJECT_ID: The project ID that contains the key ring for the
key—for example,
919698201234
. - LOCATION: The location of the key ring—for example,
us-west1
. - KEY_RING: The name of the key ring that you specified when
you created your Assured Workloads folder's key management project
and key ring—for example,
my-key-ring
. - KEY_NAME: The name of the HSM key you want to get—for
example,
my-hsm-key
.
The following example request gets metadata about a key in Cloud KMS:
GET https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys/my-hsm-key
The response body contains metadata about your key, including the
keyAccessJustificationsPolicy
.
For example:
{ "purpose": "ENCRYPT_DECRYPT", "versionTemplate": { "protectionLevel": "HSM", "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION" }, "keyAccessJustificationsPolicy": { "allowedAccessReasons": [ "CUSTOMER_INITIATED_ACCESS", "GOOGLE_INITIATED_SYSTEM_OPERATION" ] } }