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"
    ]
  }
}