Stay organized with collections
Save and categorize content based on your preferences.
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:
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.
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.
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", "GOOGLE_INITIATED_SYSTEM_OPERATION"].
The following example request and request body only allows access
justifications for a few reasons:
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.
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", "GOOGLE_INITIATED_SYSTEM_OPERATION"].
The following example request and request body only allows access
justifications for a few reasons:
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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eKey Access Justifications can be configured with Cloud HSM keys specifically for the Japan Regions control package within Assured Workloads.\u003c/p\u003e\n"],["\u003cp\u003eConfiguring Key Access Justifications for Cloud HSM keys involves setting a policy that controls access by defining allowed justification codes.\u003c/p\u003e\n"],["\u003cp\u003eYou can configure a new Cloud HSM key with a Key Access Justifications policy upon creation or update an existing key with this policy using the REST API.\u003c/p\u003e\n"],["\u003cp\u003eManaging Cloud HSM keys and their Key Access Justifications requires specific IAM permissions, such as the Cloud KMS Admin role, to ensure proper control and access.\u003c/p\u003e\n"],["\u003cp\u003eThe method \u003ccode\u003ecryptoKeys.get\u003c/code\u003e can be utilized to get the metadata, including the key access justification policy, of a specific Cloud HSM key in the cloud KMS.\u003c/p\u003e\n"]]],[],null,["# Configure Key Access Justifications with Cloud HSM\n==================================================\n\nThis page describes how to configure Key Access Justifications with Cloud HSM for\nAssured Workloads'\n[Japan Regions control package](/assured-workloads/docs/control-packages#jp-regions).\n\nDuring the steps to\n[create a new Assured Workloads folder](/assured-workloads/docs/create-folder)\nfor Japan Regions, you have the option of creating a new project and a key ring\nfor your cryptographic keys. [Cloud HSM keys](/kms/docs/hsm) keys can be\nadded to this key ring, and you can also configure a Key Access Justifications policy to\ncontrol access to each key.\n\nBefore you begin\n----------------\n\n- The ability to use Key Access Justifications with Cloud HSM keys is only available for the Japan Regions control package in Assured Workloads.\n- Ensure that your administrator has granted you one of the required [Identity and Access Management (IAM) roles](#iam) to create and manage both your Key Access Justifications policies and the Cloud HSM keys themselves.\n\n### Required IAM permissions\n\n\nTo get the permissions that\nyou need to create and manage Cloud HSM keys and their Key Access Justifications policies,\n\nask your administrator to grant you the\n\n\n[Cloud KMS Admin](/iam/docs/roles-permissions/cloudkms#cloudkms.admin) (`roles/cloudkms.admin`)\nIAM role on the project containing the key ring.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nThis predefined role contains\n\nthe permissions required to create and manage Cloud HSM keys and their Key Access Justifications policies. To see the exact permissions that are\nrequired, expand the **Required permissions** section:\n\n\n#### Required permissions\n\nThe following permissions are required to create and manage Cloud HSM keys and their Key Access Justifications policies:\n\n- ` cloudkms.cryptoKeys.create `\n- ` cloudkms.cryptoKeys.update `\n- ` cloudkms.cryptoKeys.get`\n\n\nYou might also be able to get\nthese permissions\nwith [custom roles](/iam/docs/creating-custom-roles) or\nother [predefined roles](/iam/docs/roles-overview#predefined).\n| **Caution:** The **Cloud KMS Admin** role contains permissions for key maintenance and key version destruction. To protect your Cloud KMS resources, this role should only be assigned to individuals responsible for key administration.\n\nConfigure a Cloud HSM key with Key Access Justifications\n--------------------------------------------------------\n\nTo configure Key Access Justifications with a Cloud HSM key, you can either include the\nkey access policy as a parameter when you create the key, or you can update the\nkey with the policy after the key has been created.\n\n### Create a new key and policy\n\n### REST\n\nCreate a new key and policy using the\n[`cryptoKeys.create`](/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/create)\nmethod: \n\n```bash\nPOST https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME\n```\n\nIn the request, replace the following placeholder values:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The project ID that contains the key ring on which you want to add a key---for example, `919698201234`.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The location of the key ring---for example, `us-west1`.\n- \u003cvar translate=\"no\"\u003eKEY_RING\u003c/var\u003e: 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`.\n- \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e: The name of the HSM key you want to create---for example, `my-hsm-key`.\n\nRequest body: \n\n```json\n{\n \"purpose\": \"\u003cvar translate=\"no\"\u003ePURPOSE\u003c/var\u003e\",\n \"versionTemplate\": {\n \"protectionLevel\": \"HSM\",\n \"algorithm\": \"\u003cvar translate=\"no\"\u003eALGORITHM\u003c/var\u003e\"\n },\n \"keyAccessJustificationsPolicy\": {\n \"allowedAccessReasons\": [\n ALLOWED_ACCESS_REASONS\n ]\n }\n}\n```\n\n\u003cbr /\u003e\n\nIn the request body, replace the following placeholder values:\n\n- \u003cvar translate=\"no\"\u003ePURPOSE\u003c/var\u003e: The purpose for the key. For a list of different key purposes, see [Key purposes](/kms/docs/algorithms#key_purposes)---for example, `ENCRYPT_DECRYPT`.\n- \u003cvar translate=\"no\"\u003eALGORITHM\u003c/var\u003e: The cryptographic algorithm to use. For a list of available algorithms, see [Cloud KMS algorithms](/kms/docs/algorithms)---for example, `GOOGLE_SYMMETRIC_ENCRYPTION`.\n- \u003cvar translate=\"no\"\u003eALLOWED_ACCESS_REASONS\u003c/var\u003e: The Key Access Justifications policy that defines zero or more allowed [justification codes](/assured-workloads/key-access-justifications/docs/justification-codes) for accessing the encryption key---for example, `[\"CUSTOMER_INITIATED_ACCESS\", \"GOOGLE_INITIATED_SYSTEM_OPERATION\"]`.\n\nThe following example request and request body only allows access\njustifications for a few reasons: \n\n```bash\nPOST https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys?crypto_key_id=my-hsm-key\n``` \n\n```json\n{\n \"purpose\": \"ENCRYPT_DECRYPT\",\n \"versionTemplate\": {\n \"protectionLevel\": \"HSM\",\n \"algorithm\": \"GOOGLE_SYMMETRIC_ENCRYPTION\"\n },\n \"keyAccessJustificationsPolicy\": {\n \"allowedAccessReasons\": [\n \"CUSTOMER_INITIATED_ACCESS\",\n \"GOOGLE_INITIATED_SYSTEM_OPERATION\"\n ]\n }\n}\n```\n\n### Update an existing key's policy\n\n### REST\n\nUpdate an existing key in Cloud KMS using the\n[`cryptoKeys.patch`](/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/patch)\nmethod: \n\n```bash\nPATCH https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?update_mask=keyAccessJustificationsPolicy\n```\n\nIn the request, replace the following placeholder values:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The project ID of the project that contains the key ring for the key---for example, `919698201234`.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The location of the key ring---for example, `us-west1`.\n- \u003cvar translate=\"no\"\u003eKEY_RING\u003c/var\u003e: 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`.\n- \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e: The name of the HSM key you want to update---for example, `my-hsm-key`.\n\nRequest body: \n\n```json\n{\n \"purpose\": \"\u003cvar translate=\"no\"\u003ePURPOSE\u003c/var\u003e\",\n \"versionTemplate\": {\n \"protectionLevel\": \"HSM\",\n \"algorithm\": \"\u003cvar translate=\"no\"\u003eALGORITHM\u003c/var\u003e\"\n },\n \"keyAccessJustificationsPolicy\": {\n \"allowedAccessReasons\": [\n ALLOWED_ACCESS_REASONS\n ]\n }\n}\n```\n\n\u003cbr /\u003e\n\nIn the request body, replace the following placeholder values:\n\n- \u003cvar translate=\"no\"\u003ePURPOSE\u003c/var\u003e: The purpose for the key. For a list of different key purposes, see [Key purposes](/kms/docs/algorithms#key_purposes)---for example, `ENCRYPT_DECRYPT`.\n- \u003cvar translate=\"no\"\u003eALGORITHM\u003c/var\u003e: The cryptographic algorithm to use. For a list of available algorithms, see [Cloud KMS algorithms](/kms/docs/algorithms)---for example, `GOOGLE_SYMMETRIC_ENCRYPTION`.\n- \u003cvar translate=\"no\"\u003eALLOWED_ACCESS_REASONS\u003c/var\u003e: The Key Access Justifications policy that defines zero or more allowed [justification codes](/assured-workloads/key-access-justifications/docs/justification-codes) for accessing the encryption key---for example, `[\"CUSTOMER_INITIATED_ACCESS\", \"GOOGLE_INITIATED_SYSTEM_OPERATION\"]`.\n\nThe following example request and request body only allows access\njustifications for a few reasons: \n\n```bash\nPATCH https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys/my-hsm-key?keyAccessJustificationsPolicy\n``` \n\n```json\n{\n \"purpose\": \"ENCRYPT_DECRYPT\",\n \"versionTemplate\": {\n \"protectionLevel\": \"HSM\",\n \"algorithm\": \"GOOGLE_SYMMETRIC_ENCRYPTION\"\n },\n \"keyAccessJustificationsPolicy\": {\n \"allowedAccessReasons\": [\n \"CUSTOMER_INITIATED_ACCESS\",\n \"GOOGLE_INITIATED_SYSTEM_OPERATION\"\n ]\n }\n}\n```\n\n### Get the Key Access Justifications policy for a key\n\n### REST\n\nGet metadata about an existing key in Cloud KMS using the\n[`cryptoKeys.get`](/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/get)\nmethod: \n\n```bash\nGET https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME\n```\n\nIn the request parameters, replace the following placeholder values with your\nown:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The project ID that contains the key ring for the key---for example, `919698201234`.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The location of the key ring---for example, `us-west1`.\n- \u003cvar translate=\"no\"\u003eKEY_RING\u003c/var\u003e: 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`.\n- \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e: The name of the HSM key you want to get---for example, `my-hsm-key`.\n\nThe following example request gets metadata about a key in Cloud KMS: \n\n```bash\nGET https://cloudkms.googleapis.com/v1/projects/919698201234/locations/us-west1/keyRings/my-key-ring/cryptoKeys/my-hsm-key\n```\n\n\u003cbr /\u003e\n\nThe response body contains metadata about your key, including the\n[`keyAccessJustificationsPolicy`](/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys).\nFor example: \n\n```json\n{\n \"purpose\": \"ENCRYPT_DECRYPT\",\n \"versionTemplate\": {\n \"protectionLevel\": \"HSM\",\n \"algorithm\": \"GOOGLE_SYMMETRIC_ENCRYPTION\"\n },\n \"keyAccessJustificationsPolicy\": {\n \"allowedAccessReasons\": [\n \"CUSTOMER_INITIATED_ACCESS\",\n \"GOOGLE_INITIATED_SYSTEM_OPERATION\"\n ]\n }\n}\n```\n\nWhat's next\n-----------\n\n- You can also [Set default Key Access Justifications\n policy](/assured-workloads/key-access-justifications/docs/set-default-policy) ([Preview](/products#product-launch-stages))."]]