GCP hosted key

To allow root keys to be hosted externally, a number of key providers are supported. One such provider is Google Cloud Platform (GCP) Cloud Key Management. Currently, Antimatter supports two methods for hosting the domain Root Encryption Key via GCP Cloud Key Management:

• Hold the key in GCP Cloud Key Management and delegate access to the key to the Antimatter account.
• Hold the key in GCP Cloud Key Management and create a service account for Antimatter to use to access the key.

Both options are covered below. For this guide, we assume that the Antimatter CLI has been installed (see CLI) and that a domain has been created.

Access the key management page.

Dashboard

If using the dashboard, navigate to Domain Configuration -> Encryption Rotation and select the option: "Change Root Encryption Key Configuration"

This will redirect you to the key management modal where the REK source can be selected.

CLI

If using the CLI, a link to the key management page can be generated using the self-serve subcommand. First, ensure the CLI is authenticated and using the relevant domain. You will need to provide an API key or specify a suitable Oauth provider.

am config domain login --api-key <api-key>

Or

am config domain login --oauth-provider  <provider>

Once the CLI is authenticated, the key management URL can be generated using:

am keys self-serve --vendor <company-name>

This will generate a URI for the key management landing page.

From here, select "Edit Settings" and you will be presented with the different key hosting options.

Adding a GCP Root Key

Delegated Key

To delegate a key hosted by GCP Cloud Key Management for use by Antimatter, the following operations need to occur:

• A key must be created if it does not already exist.
• A label must be added to the key in the form <domain-id>=allow
• Permission must be given to allow the Antimatter GCP service account the correct role to access the key.

The simplest way to perform the above steps is through the key management UI, however, it is also possible to add a key through the CLI.

From the key management UI, delegating a GCP key is done by first selecting the option; "I want to configure my own externally-held key." and then selecting 'Next'. The user can then select a provider to host the key. For this example, select "Cloud key management" and click 'Next'.

You will now be given the option to use either an existing key, or be guided through the process of creating a new one. In both cases, the next step will require access to a terminal with an authenticated gcloud client. The easiest is to use Cloud Shell in the GCP web console. You can find other ways of creating a key in GCP here.

Existing Key

If you wish to use an existing key, then select "I have an existing root key I wish to use for wrapping" and click 'Next'. On the subsequent pane, you will be provided with a script that must be run in a terminal with the gcloud CLI available.

note

While this script is intended to be used as-is, it does require two modifications.

1. You will be required to include the keyring ID that contains the key to be shared with Antimatter on line three.
2. You will be required to include the key ID to be shared with Antimatter on line four.

The script will perform the following actions:

1. Fetch the current project ID. It is assumed that this project contains the keyring supplied.
2. Add the label <domain-id>=allow to the key.
3. Assign the roles cloudkms.viewer and cloudkms.cryptoKeyEncrypterDecrypter to the Antimatter account.
4. Print out the full key resource path.

Note, it is important that the key includes the label <domain-id>=allow. This is required so that Antimatter can confirm that the key supplied is intended for the domain id. Removing the label or supplying a key that does not contain it will result in Antimatter being unable to use it as a Root Key. Additionally, note the permissions added to the key. These are the minimal permissions required to allow Antimatter to describe the key and use it to wrap internally generated keys used for encryption.

Once run, the script will return: Key alias (save this for next step): <project-id>/global/<keyring-id>/<key-id>. Note this down for the final step.

New Key

If you wish to use a new key, then select "Guide me through creating a new key for wrapping" and click 'Next'. On the subsequent pane, you will be provided with a script that must be run in a terminal with the gcloud CLI available.

The script will perform the following actions:

1. Create a new GCP keyring called antimatter-domain-keyring,
2. Create a new key called <domain-id>-key
3. Fetch the current project ID. It is assumed that this project contains the keyring supplied.
4. Add the label <domain-id>=allow to the key.
5. Assign the roles cloudkms.viewer and cloudkms.cryptoKeyEncrypterDecrypter to the Antimatter account.
6. Print out the full key resource path.

Note, it is important that the key includes the label <domain-id>=allow. This is required so that Antimatter can confirm that the key supplied is intended for the domain. Removing the label or supplying a key that does not contain it will result in Antimatter being unable to use it as a Root Key. Additionally, note the permissions added to the key. These are the minimal permissions required to allow Antimatter to describe the key and use it to wrap internally generated keys used for encryption.

Once run, the script will return: Key alias (save this for next step): <project-id>/global/<keyring-id>/<key-id>. Note this down for the final step.

After running the generated script, return to the key management page and click 'Next'. On the next pane you will be asked to submit the key path that was printed out after running the script. After pasting, click 'Apply' and wait for the pairing check to complete. Once complete, click 'Done'.

Service Account

Although the delegated GCP key is the pattern that most BYOK/HYOK implementers have settled on, we also support access to a GCP key via a provided service account.

First, we create the keyring and a key, then assign it the appropriate permissions. To follow along, you will need to use AWS CloudShell or have an authenticated AWS CLI tool locally.

note

The variables provided in the script blow are placeholders. Please replace them with the appropriate information for the target keyring.

# Set up some useful variables
KEYRING_NAME="antimatter-rek"
PROJECT="my-gcp-project"
PROJECT="antimatter-dev-ephemeral-1"
LOCATION="us-central1"

gcloud services enable cloudkms.googleapis.com --project=${PROJECT}
gcloud kms keyrings create ${KEYRING_NAME} --location ${LOCATION} --project=${PROJECT}
gcloud kms keys create root-key \
  --keyring ${KEYRING_NAME} \
  --purpose "encryption" \
  --location${LOCATION}  \
  --project=${PROJECT}

Next, create a service account and give it access to this key:

SA_NAME="antimatter-service"

gcloud iam service-accounts create ${SA_NAME} \
  --display-name ${SA_NAME} \
  --project=${PROJECT}

gcloud kms keyrings add-iam-policy-binding ${KEYRING_NAME} \
      --location us-central1 \
      --member serviceAccount:${SA_NAME}@${PROJECT}.iam.gserviceaccount.com \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
      --project=${PROJECT}
      
gcloud iam service-accounts keys create sa_credentials.json \
      --iam-account=${SA_NAME}@${PROJECT}.iam.gserviceaccount.com \
      --project=${PROJECT}

Export the service account credentials as sa_credentials.json. Further information on ths can be found here. Now you can add the key to Antimatter using the Antimatter CLI:

am keys create --provider gcp_sa \
  --project-id ${PROJECT} \
  --keyring-id ${KEYRING_NAME} \
  --key-id root-key \
  --location ${LOCATION} \
  --description "my new key" \
  --service-account-credentials sa_credentials.json