Google Cloud External Key Manager (Cloud EKM) Integration

KMES Series 3 Integration Guide

key management service KMES Series 3

Table of Contents

Overview of the Google Cloud EKM / KMES Series 3 Integration

Terminology

  • External key manager (EKM)
    The key manager used outside of Google Cloud to manage your keys (i.e., KMES Series 3).
  • Cloud External Key Manager (Cloud EKM)
    A Google Cloud service for using your external keys that are managed within a supported EKM.
  • Cloud EKM through the internet
    A version of Cloud EKM where Google Cloud communicates with your external key manager over the internet.
  • Cloud EKM through a VPC
    A version of Cloud EKM where Google Cloud communicates with your external key manager over a Virtual Private Cloud (VPC).

Google Cloud EKM Features

  • Base Google EKM Support
    With Google Cloud EKM, you can use keys that you manage within a supported external key management partner (i.e., KMES Series 3) to protect data within Google Cloud. You can protect data at rest in supported CMEK integration services, or by calling the Cloud Key Management Service API directly.
  • Justification
    Justification is a feature that requires users to provide a reason or justification for any critical operation they perform on the key management system. This feature is designed to enhance accountability and enable better auditing of actions taken within the system. By mandating justifications, it becomes easier to trace back decisions, identify patterns of misuse, and ensure that only authorized and necessary operations are executed.
  • VPC Support
    Virtual Private Cloud (VPC) support allows the KMES Series 3 to be integrated seamlessly into a customer’s existing VPC infrastructure on Google Cloud. This feature ensures that the key management server operates within a secure, isolated environment, which reduces the potential attack surface and provides better protection for sensitive data. VPC support also simplifies network configurations and allows for more granular control over access to the key management server.
  • Checksum support (validity checks on keys via a CMAC)
    Checksum support, using a Cipher-based Message Authentication Code (CMAC), enables the KMES Series 3 to perform validity checks on cryptographic keys. When keys are generated, stored, or transmitted, a CMAC is calculated and attached to the key. The CMAC acts as a checksum that allows the recipient to verify the integrity of the key. This feature enhances the security of key management operations by ensuring that keys have not been tampered with or corrupted during storage or transmission. This feature is transparent to the user.
  • Asymmetric Signing (RSA keys)
    Asymmetric signing support for RSA keys enables the KMES Series 3 to generate and manage RSA key pairs, which can be used for digital signatures and public key encryption. With this feature, users can create, store, and manage RSA keys in the KMES Series 3, while leveraging Google Cloud External Key Manager for operations that require the private key, such as signing or decrypting data. This expands the range of cryptographic operations that can be performed using the integrated solution and provides increased flexibility for users.
  • Key Management commands (in beta with Google)
    The Key Management commands feature, currently in beta with Google, enables users to execute a wider range of key management operations directly from the Google Cloud External Key Manager interface. This includes actions such as key rotation, deletion, and metadata updates. By providing a more comprehensive set of key management commands, users can streamline their workflows and manage their cryptographic keys more efficiently within the integrated environment. These new features will significantly enhance the capabilities of the KMES Series 3 and Google Cloud External Key Manager integration, providing users with improved security, accountability, and flexibility in managing their cryptographic keys.

Key Benefits of the Integration

The Google Cloud EKM / KMES Series 3 integration provides several benefits:

  • Key provenance: You control the location and distribution of your externally managed keys. Externally managed keys are never cached or stored within Google Cloud. Instead, Cloud EKM communicates directly with the KMES Series 3 for each request.
  • Access control: You manage access to your externally managed keys. Before you can use an externally managed key in Google Cloud, you must grant the Google Cloud project access to use the key. You can revoke this access at any time.
  • Centralized key management: You can manage your keys and access policies from a single user interface, whether the data they protect resides in the cloud or on your premises.

In all cases, the key resides on the KMES Series 3, and is never sent to Google.

Please refer to Google’s EKM documentation for the full list of services that support CMEK with Cloud EKM.

How it Works

This section provides a broad overview of how Cloud EKM works with an external key.

  1. First, you create or use an existing key in the KMES Series 3 application interface. This key has a unique URI or key path.
  2. Next, you grant your Google Cloud project access to use the key, on the KMES Series 3.
  3. In your Google Cloud project, you create a Cloud EKM key, using the URI or key path for the externally managed key.

Within Google Cloud, the key appears alongside your other Cloud KMS and Cloud HSM keys, with protection level “EXTERNAL” or “EXTERNAL_VPC”. The Cloud EKM key and the external key management partner key work together to protect your data. The external key is never exposed to Google. The following diagram shows how Cloud KMS fits into the key management model. This diagram uses Compute Engine and BigQuery as two examples.Diagram shows how Cloud KMS fits into the key management model. Diagram uses Compute Engine and BigQuery as two examples.
Important: Both the Cloud EKM key version and the external key are required for each encryption and decryption request. If you lose access to either key, your data cannot be recovered. It is not possible to recreate an identical Cloud EKM key version by using the same external key URI or key path.

Please refer to Google’s EKM documentation for information about the considerations and restrictions when using Cloud EKM.

Download this integration guide as a PDF

Futurex Certification Process

The Futurex Certification Process is a rigorous and standardized approach to testing and certifying integrations between third-party applications and Futurex’s HSMs and key management servers (i.e., KMES Series 3). The certification process is designed to ensure that third-party application integrations are fully tested and validated in a lab environment before they are deployed in a production environment. Futurex’s Integration Engineering team implements this process so that customers can have confidence that third-party applications will integrate seamlessly with Futurex’s HSMs and KMES Series 3 devices, and that all operations will result in the expected behavior. The certification process involves several steps, including research, testing, troubleshooting, and certification, and is fully documented in an integration guide for each integration. The full process is outlined below:

  1. Research the third-party application to gain a general understanding of the solution and the protocol it uses to integrate with an HSM or KMS device (i.e., PKCS #11, Microsoft CNG, JCE, OpenSSL Engine, KMIP).
  2. Determine the scope of the third-party application’s use of the HSM or KMS device, including the specific functionalities it utilizes (i.e., data encryption, key protection, entropy, etc.).
  3. Install and configure the third-party application in a lab environment, where all testing and validation will take place.
  4. Establish a connection between the third-party application and the Futurex device, which typically involves configuring TLS certificates and creating roles and identities that the third-party application will use to connect and authenticate to the Futurex device.
  5. Initiate a request from the third-party application to the Futurex device, such as generating keys or certificates, encrypting or decrypting data, or other cryptographic functions.
  6. If any errors occur during the testing process, the Integration Engineering team will diagnose the issues and take necessary corrective actions. If necessary, the team will also document the error(s) by creating engineering change requests (ECRs) to ensure all issues are addressed and resolved before certification.
  7. After any necessary engineering changes have been made, a new end-to-end test will be performed to ensure that all errors have been resolved and that all operations are successful.
  8. Certify the integration by creating an integration guide that covers all necessary prerequisites, configurations required in both the third-party application and the Futurex device, and how to test the functionality.

Overall, following these steps helps ensure that the integration between the third party application and the Futurex device is fully tested and validated, and that any errors or issues are resolved before the integration is certified as fully supported.

Initial Setup in Google Cloud External Key Manager (EKM)

  1. From the main Google Cloud dashboard, type “Key Management”, into the search bar at the top of the page. Then, select Key Management – Security service.

Create a New Key Ring

  1. From the Key Management dashboard, click the [ Create Key Ring ] button at the top of the page.google cloud key management dashboard create key ring
  2. This will bring up the Create key ring wizard.google cloud create key ring wizard
  3. Enter a name for the key ring.
    Note: Key ring names can only contain letters, numbers, underscores (_), and hyphens (-). Key rings can’t be renamed or deleted.
  4. Select Region as the Location type (EKM does not support Multi-region). Then, in the drop-down menu, select the Google region where you want the key ring to be created.
  5. Click [ Create ].
    Note the following regarding the key ring location:

    • Cloud EKM needs to be able to reach your keys quickly to avoid an error. When creating a Cloud EKM key, choose a Google Cloud location that is geographically near the location of the KMES Series 3.
    • You can use Cloud EKM in any Google Cloud location supported for Cloud KMS, except for global.

Note the Service Account Email Address

After the Key Ring is created, the browser redirects to the key creation wizard. A portion of which is shown below:google cloud key creation wizard

  1. Enter a name for the key.
  2. Select the External as the protection level for the key.
  3. Select either via internet or via VPC as the External key manager (EKM) connection type.
  4. Click [ Continue ].
  5. Note the service account email address in the Key material section. The service account email address will later be copied to the email field of the identity that Google will use to interact with the KMES Series 3.google cloud service account email address in the key material section

You will return to this dialog in the Google Cloud dashboard after creating a Google Crypto Space on the KMES.

TLS and Authentication Setup on the KMES Series 3

This section covers configurations users must make on the KMES Series 3 for Google EKM to access externally managed keys.

For all of the following sections, you need to be logged in to the KMES application interface with the default Admin identities.

Configure TLS Certificates for the REST API Connection Pair

  1. Go to Administration > Configuration > Network Options.
  2. In the Network Options dialog, select the TLS/SSL Settings tab.
  3. Select the REST API connection pair in the dropdown menu.
  4. Ensure that the REST API connection pair is Enabled and configure the TLS settings per your requirements.

Add JWT Identity Provider

A JSON Web Token (JWT) must be configured to allow Google to authenticate against the KMES using Google’s generated JWT.

  1. Navigate to Identity Management > Identity Providers, then right-click and select Add > Provider > JSON Web Token. This will open the Identity Provider Editor dialog.
  2. In the Info tab, specify a name for the Identity Provider and de-select Enforce Dual Factor.
  3. In the JWT Options tab, specify “https://accounts.google.com” as the issuer. Set leeway and max validity according to your requirements.
  4. In the JWT Key tab, select JWKS and then specify “https://www.googleapis.com/oauth2/v3/certs” in the JWKS URL field. Leave the TLS PKI field blank and click [ OK ] to save.
  5. Right-click on the Identity Provider that was just created and select Add -> Mechanism – > Google External Key Manager.
  6. In the Info tab, specify a name for the authentication mechanism.
  7. In the Audience tab, specify the hostname of your KMES and the REST API port number (it is 8081 by default) in the following format: https://< host name >:< port >
  8. Click [ OK ] to save. The newly added Identity Provider and authentication mechanism are now listed.newly added identity provider and authentication mechanism listed

Create an Identity for the Google Service Account and Grant it the Required Permissions

Create a new role

  1. Navigate to the Identity Management > Roles menu and add a new role. This will open the Role Editor dialog.
  2. Name the role “Google Key Management” and change the number of login required to 1. Leave all other fields set as the default values under the Info tab.
  3. In the Permissions tab, select the following Cryptographic Operations permissions:
    • Sign
    • Wrap
    • Unwrap
  4. Click [ OK ] to save.

Create a new identity and assign it the Google Key Management role

  1. Navigate to the Identity Management > Identities menu. Right-click and select Add > Client Application to add a new identity. This will open the Identity Editor dialog.
  2. In the Info tab, specify any name for the identity.
  3. In the Assigned Roles tab, select the Google Key Management role.
  4. In the Device Info tab, type into the Email field the Google service account email address (e.g., service54255661635@gcp-sa-ekms.iam.gserviceaccount.com) that you noted in the key creation wizard in the previous section.
  5. In the Authentication tab, click the Add button to add a new credential. In the Configure Credential dialog, select Google External Key Manager as the credential type, and then select the provider and mechanism configured in the previous section and click [ OK ].
  6. Remove the default API Key mechanism, leaving only the Google External Key Manager credential, and click [ OK ] to save.

Manually Managed Keys

Manually managed keys use created keys on the KMES Series 3 to perform cryptographic requests by Google Cloud. The key path can be copied from KMES key settings and combined with the KMES hostname or IP and the System/Host API port number to create a url for accessing the key. The KMES manages key rotation automatically for symmetric keys.

The URL must be entered for every creation and key rotation.

Internet URL format: https://<server ip>:<port>/v0/key-encrypt/external/<key uuid>

VPC key path format: /v0/key-encrypt/external/<key uuid>

Create a New Google Crypto Space on the KMES Series 3

  1. Login to the KMES Series 3 application interface with the default Admin identities.
  2. Navigate to the Key Management > Google Crypto Spaces menu and click the [ Add… ] button. This will pull up the Google Crypto Space dialog.
  3. In the Info tab:
    1. Enter a name for the Google Crypto Space.
    2. Set permissions:
      • For symmetric key permissions – CREATE_KEY, DESTROY_KEY, WRAP, UNWRAP
      • For asymmetric key permissions – CREATE_KEY, DESTROY_KEY, GET_PUBLIC_KEY, ASYMMETRIC_SIGN
        Note: Be sure to select the GET_INFO permission if using a VPC connection between Google Cloud and the KMES Series 3.
  4. In the Justifications tab, select the access reason. The following are the default access reasons:google crypto space justifications tab default access reasons
  5. Click [ OK ]. You will see the following message confirming that the CryptoSpace was successfully created.google crypto space successfully created message
  6. Click [ OK ]. The Google Crypto Space dialog will appear again, now with additional tabs, allowing you to create Symmetric or Asymmetric keys.

Creating Keys in the Google Crypto Space

How to create a symmetric key

  1. In the Google Crypto Space dialog, navigate to the Symmetric Keys tab and click the [ Add ] button.
  2. In the Google Symmetric Key dialog:
    1. Copy the key path to your clipboard.
    2. Enter a name for the key.
    3. Specify the desired key rotation period.
    4. In the Justifications tab, select the access reason.
    5. Click [ OK ].

The new key will now be listed in the Symmetric Keys tab.

How to create an asymmetric key

  1. In the Google Crypto Space dialog, navigate to the Asymmetric Keys tab and click the [ Add ] button.
  2. In the Google Asymmetric Key dialog:
    1. Copy the key path to your clipboard.
    2. Enter a name for the key.
    3. Select an algorithm from the following options in the drop-down menu:
      Note: It must match the algorithm set in Google Cloud.

      • RSA 2048 PSS SHA-256
      • RSA 3072 PSS SHA-256
      • RSA 4096 PSS SHA-256
      • RSA 4096 PSS SHA-512
      • RSA 2048 PKCS#1 SHA-256
      • RSA 3072 PKCS#1 SHA-256
      • RSA 4096 PKCS#1 SHA-256
      • RSA 4096 PKCS#1 SHA-512
      • EC P-256 SHA-256
      • EC P-384 SHA-384
    4. Click [ OK ].

The new key will now be listed in the Asymmetric Keys tab.

Grant the Google EKM Identity Permissions to Use the Crypto Space

  1. Right-click the Google Crypto Space you just created and select Permission. This will pull up the Set Object-Group Permissions dialog.
  2. Grant the Google EKM identity the Use permission.
  3. Click [ OK ].

Google Crypto Space Managed Keys

Google Crypto Space managed keys allow users to manage key creation, rotation, and destruction of KMESstored keys directly from the Google Cloud dashboard. Both symmetric and asymmetric keys can be created inside key rings.

Note: This feature requires a VPC connection to be configured between Google Cloud and the KMES Series 3. Once configured, Google EKM will only require the Google Crypto Space URL in the KMS Infrastructure menu. Please refer to VPC and KMS Infrastructure setup instructions.

Caution: When changing existing KMS Infrastructure from Manual to Crypto Space, keys will not be able to be rotated if the wrapping key exists outside of the Google Crypto Space. Key rotation period can be set in key settings, but will default to never rotate.

The Google Crypto Space URL is in the following format: /v0/key-encrypt/external/<crypto-space name>

Note: The URL must start with ‘/v0’. Otherwise Google will append it to the returned Crypto Space path resulting in a mismatching URL check.

Create a New Google Crypto Space on the KMES Series 3

  1. Login to the KMES Series 3 application interface with the default Admin identities.
  2. Navigate to the Key Management > Google Crypto Spaces menu and click the [ Add… ] button. This will pull up the Google Crypto Space dialog.
  3. In the Info tab:
    1. Enter a name for the Google Crypto Space.
    2. Set permissions:
      • For symmetric key permissions – CREATE_KEY, DESTROY_KEY, WRAP, UNWRAP
      • For asymmetric key permissions – CREATE_KEY, DESTROY_KEY, GET_PUBLIC_KEY, ASYMMETRIC_SIGN
        Note: Be sure to select the GET_INFO permission if using a VPC connection between Google Cloud and the KMES Series 3.
  4. In the Justifications tab, select the access reason. The following are the default access reasons:google crypto space justifications tab default access reasons
  5. Click [ OK ]. You will see the following message confirming that the CryptoSpace was successfully created.google crypto space successfully created message
  6. Click [ OK ]. The Google Crypto Space dialog will appear again, now with additional tabs for Symmetric and Asymmetric keys.
  7. Since keys will be created on the KMES through the Google Cloud dashboard, click [ OK ] to save and close the Google Crypto Space dialog.

Grant the Google EKM Identity Permissions to Use the Crypto Space

  1. Right-click the Google Crypto Space you just created and select Permission. This will pull up the Set Object-Group Permissions dialog.
  2. Grant the Google EKM identity the Use permission.
  3. Click [ OK ].

Creating an Externally Managed Key in Google Cloud

Regardless of whether you are using Manual or Crypto Space for your Google KMS Infrastructure, follow the steps described in section to create a key in the Google Cloud Key Management dashboard.

  1. From the main Google Cloud dashboard, type “Key Management”, into the search bar at the top of the page. Then, select Key Management – Security service.

Create an Externally Managed Key

  1. Select the Key Ring you created in the Create a New Key Ring section of this guide.
  2. Select [ Create Key ]. This will open the key creation wizard.
  3. Enter a name for the key.
    Note: The key name you specify here does not need to match the name of the key that is created on the KMES Series 3.
  4. Select the External as the protection level for the key.
  5. Select either via internet or via VPC as the External key manager (EKM) connection type.
  6. Click [ Continue ].
  7. Enter the Key URI.
    • If using Manual for your Google KMS Infrastructure, you must specify the full identifying string for the external key that was created on the KMES Series 3. Format: https://<hostname>:<port>/v0/key-encrypt/external/<key name> Example: https://ekms.virtucrypt.com:8081/v0/key-encrypt/external/Demo-Key
    • If using Crypto Space for your Google KMS Infrastructure, you only need to specify this portion of the identifying string for the Google Crypto Space you created on the KMES Series 3: /v0/key-encrypt/external/<crypto space name> The two fields that need to be configured specifically to your use case are the <server ip> and <key name> fields. In the field, the name of the key that was created on the KMES needs to be specified. In the field, the hostname or IP address of the KMES Series 3 device needs to be specified. The field needs to be set to the REST API port on the KMES. By default, the REST API port is 8081. Important: In addition to the steps above, Google must whitelist the domain specified in the Key URI field for your specific Google Cloud account.
  8. Click the [ Continue ] button again. This will allow you to select either Symmetric encrypt/decrypt or Asymmetric sign in the Purpose dropdown menu.
  9. Click [ Create ] to create the externally managed key.

Testing Encryption and Decryption with Externally Managed Key

Download and Install Google Cloud SDK

Please follow the instructions here to download, install, and configure Google Cloud SDK: https://cloud.google.com/sdk/docs/install

Encrypt a Test File Using the Externally Managed Key

NOTE: Before proceeding with next two steps, ensure the GCP user that is calling the encrypt and decrypt methods has the cloudkms.cryptoKeyVersions.useToEncrypt and cloudkms.cryptoKeyVersions.useToDecrypt permissions on the key used to encrypt or decrypt. One way to permit a user to encrypt or decrypt is to add the user to the roles/cloudkms.cryptoKeyEncrypter, roles/cloudkms.cryptoKeyDecrypter, or roles/cloudkms.cryptoKeyEncrypterDecrypter IAM roles for that key. For more information, see Permissions and Roles.

Run the following gcloud kms command to encrypt a test file using the externally managed key.

gcloud kms encrypt \
--key [key] \
--keyring [key-ring] \
--location [location] \
--plaintext-file [file-with-data-to-encrypt] \
--ciphertext-file [file-to-store-encrypted-data]

Replace [key] with the name of the key to use for encryption. Replace [key-ring] with the name of the key ring where the key is located. Replace [location] with the Cloud KMS location for the key ring. Replace [file-with-data-to-encrypt] and [file-to-store-encrypted-data] with the local file paths for reading the plaintext data and saving the encrypted output.

If the command is successful it will return no output.

Decrypt a Test File Using the Externally Managed Key

Run the following gcloud kms command to decrypt the file that was encrypted in the previous step, using the externally managed key.

gcloud kms decrypt \
--key [key] \
--keyring [key-ring] \
--location [location] \
--ciphertext-file [file-path-with-encrypted-data] \
--plaintext-file [file-path-to-store-plaintext]

Replace [key] with the name of the key to use for decryption. Replace [key-ring] with the name of the key ring where the key is located. Replace [location] with the Cloud KMS location for the key ring. Replace [file-path-with-encrypted-data] and [file-path-to-store-plaintext] with the local file paths for reading the encrypted data and saving the decrypted output.

If the command is successful it will return no output.

View the contents of the plaintext file that was output from this decryption command and confirm that it is identical to the original file that was encrypted. If the two files are identical then it confirms that the externally managed key is successfully performing encryption and decryption operations.

Google VPC and KMS Infrastructure Setup

Virtual Private Cloud (VPC) uses a private network to connect directly to a network without the using the public internet. Follow the steps outlined below in the Google Cloud dashboard to set up a VPC connection to the KMES Series 3.

VPC Configuration

Please refer to Google’s documentation for how to configure a VPC in your Google Cloud account: https://cloud.google.com/vpc/docs/create-modify-vpc-networks

You can use the steps below as an outline:

  1. Computer Engine → VM Instance → Create VM Instance
  2. Network Services → VPC Network → Create VPC Network
    1. Enter VPC Network name
    2. Enter Subnet name
    3. Enter Subnet region
  3. Click created VPC Network → Add Route
    1. Enter VPC Route name
    2. Enter Destination IP
  4. Network Services → Service Directory →Namespace list → Create Namespace
    1. Select region – must match VPC Network
    2. Enter Namespace name
  5. Network Services → Service Directory → Register Service
    1. Click Standard
    2. Enter region – should be the same as the VPC network
    3. Select Namespace
    4. Enter service name
  6. Click created Service Directory → Create Endpoint
    1. Enter endpoint name
    2. Enter IP of the KMES Series 3
    3. Enter the KMES REST API port number
    4. Select Choose from list
      • Select VPC network

KMS Infrastructure Configuration

  1. From the main Google Cloud dashboard, type “Key Management”, into the search bar at the top of the page. Then, select Key Management – Security service.
  2. Click [ KMS Infrastructure ].
  3. Click [ Create Connection ]. This opens the Create EKM via VPC connection wizard.google cloud create ekm via vpc connection wizard
  4. In the Create EKM via VPC connection wizard:
    1. Enter a name for the connection.
    2. Select a region for the connection. It must be the same region as the VPC network.
    3. Enter the resource ID (self link) of Service Directory’s service to use with this connection. The service must point to your external key manager’s IP address and must exist in the same region as this connection.
      Example : projects/futurex-ekms-test/locations/us-east1/ekmConnections/futurex-ekm-east
    4. Enter the EKM hostname. It should match the Common Name of the TLS certificate.
    5. Upload the external key manager’s X.509 server certificates (also known as end-entity or leaf certificates) in DER format with the .crt extention. Note: This is the TLS certificate that is configured for the REST API connection pair on the KMES.
    6. Enter the EKM management mode.
      1. Manual – Manually manage key rotation from your EKM (i.e., KMES Series 3). Will require URL for each rotation. Example: /v0/key-encrypt/external/0147E96A-77F2-0001-000A-34BE0BC561B5
      2. Cloud KMS – Crypto Space where Google will manage key rotation. Example: /v0/key-encrypt/external/<Crypto Space Name>
    7. (Optional) Set default – will use this interface for all keys using External via VPC connection as default.

Want to learn more?

If you are interested in our solution for Google Cloud EKM, or would like to inquire about a demo, please contact us.

Give us a call