User's Guide: Google Cloud KMS

1.0  Overview

The Fortanix solution for GCP Cloud KMS offers complete Bring Your Own Key (BYOK) and lifecycle management for management and automation of native GCP Cloud keys (CMEK – Customer Master Encryption Key)  and allows users to manage all keys centrally and securely.

2.0  Fortanix Data Security Manager GCP Cloud KMS Group Workflow

The following section describes the workflow to configure Fortanix DSM to interact with the GCP Cloud KMS. A GCP CDC group is created in the Fortanix DSM account, and this group is configured to interact with the GCP Cloud KMS.

3.1  Create a GCP CDC Group

1. In the Fortanix DSM Groups page, click the button to create a new GCP KMS group. 
2. In the Adding new group form:
   1. Enter a title and description for your group.
   2. Next, click the LINK HSM/EXTERNAL KMS button to select the GCP Key Management Service type, so that Fortanix DSM can connect to it.
   3. Select the type of HSM/external KMS as GCP Key Management Service from the drop down menu.
   4. Enter the GCP KMS Service Account Credentials
      • GCP Project ID: This is the unique identifier for the Google Cloud project used to differentiate your project from all others in Google Cloud. For example: fortanix.
      • Select the geographical region/location where the Google Cloud KMS resource is stored or can be accessed within a Google Cloud project. For example: South Carolina (us-east1).
      • Authentication: The following Cloud KMS and Cloud Platform APIs must be enabled for using KMS and Cloud platform related GCP services.

        https://www.googleapis.com/auth/cloudkms

        https://www.googleapis.com/auth/cloud-platform

        Fortanix DSM uses Google Service Account to authenticate with Google Cloud KMS.

        Enter the service account email in the format SERVICEACCOUNT@PROJECT.iam.gserviceaccount.com

        NOTE

        The Google service account must have the role of Cloud KMS Admin.
      • Upload a Private Key: Upload the JSON/p12 file containing the private key of the service account to authenticate with Google Cloud KMS. 
3. Click TEST CONNECTION to test your GCP KMS connection. If Fortanix DSM is able to connect to your GCP KMS using your connection details, then it shows the status as “Connected” with a green tick . Otherwise, it shows the status as “Not Connected” with a yellow warning sign . 
4. After the connection is successful, you will get the list of keyrings from which you have to select the key ring that you want to configure for the GCP KMS group. A key ring organizes keys in a specific Google Cloud location and allows you to manage access control on groups of keys. 

3.2 Save GCP KMS Group Details

Though testing the connection in the previous section is an optional step, you can save your group details even if the connection information might be incorrect or incomplete, you can edit these details later. Now, save your group details by clicking the SAVE button.

After you save your group details, your group is created, and you will see a detailed view of your group.

You can now see that there is an addition of the HSM/KMS tab in the group details, this tab shows the details about your KMS.

3.3  The HSM/KMS Tab

The HSM/KMS tab shows the details of the KMS that was added such as the service account email and key ring name of the GCP KMS. You can also edit the GCP connection details such as the Service account email and the Private key here.

After you edit the connection details and save it, click TEST CONNECTION to test the connection.

Click SYNC KEYS to create virtual copies of all the keys present in the key ring of the location and project provided in the GCP KMS group.

3.4  Not Connected Scenario

On clicking TEST CONNECTION, it is possible that Fortanix DSM is not able to connect to the GCP KMS, in that case, it displays a “Not Connected” status with a warning symbol . You can save the details of the new connection details provided and edit them later.

3.5  Groups Table View

After saving the group details, you can see the list of all groups and notice the special symbol next to the newly created group, this symbol differentiates it from the other groups, as it shows that it is a GCP KMS group.

3.6  User View

Click the Users tab  in the Fortanix DSM UI, and click the user that says “You” to go to the user’s detailed view, as shown below.

The detailed view shows all the groups of which the user is a part of, additionally Fortanix DSM displays which groups are mapped to GCP KMS and whether they are “Connected” or “Not Connected”.

4.0  Fortanix Data Security Manager GCP KMS Security Objects

After the GCP KMS group successfully connects to the GCP KMS using the connection details, the keys from the GCP KMS region are stored in the Fortanix DSM GCP KMS group as virtual keys. A virtual key is a key whose key material is not present in the GCP KMS group. The key material is stored securely in the key ring of the location and project provided in the GCP KMS group. The virtual key is only a pointer with the key information and key attributes, but it does not hold the key material.

4.1  Create a Key in GCP KMS Group - Generate

You can generate a key in a configured GCP KMS region.

4.1.1  Generate a Key

This action will generate the configured key type in the configured GCP KMS regions directly, and it will be represented as a virtual key in the corresponding GCP KMS group. This means that the virtual key in the GCP KMS group will point to the actual key in GCP KMS that stores the key material of this new key. The virtual key only stores the key information and key attributes, but it does not have the key material.

In your Fortanix DSM console, follow the process below to create a new key:

1. Click the Security Objects tab.
2. Click to create a new Security Object. 
3. In the Add New Security Object form enter a name for the Security Object (Key).
4. Select the This is an HSM/external KMS object check box. This will show the GCP KMS configured groups in the Select group list.
5. In the GCP KMS group list, select the GCP KMS group into which the keys will be generated. The keys will be generated into the region that was selected in the GCP KMS group. 
6. Select GENERATE IN GCP to initiate the generate key in the GCP KMS workflow.
7. Enter the GCP key name The GCP key name is the key name that will be stored in the GCP Key Ring. The GCP key name will be used to correlate between different versions of a key. All the key versions will have the same GCP key name.
8. Select the key type for the new GCP KMS key.
   
   NOTE

   For Fortanix DSM 4.4, the allowed key type for a GCP KMS key generated using the Generate Key flow in Fortanix DSM is AES 256.

   These key types can further be restricted by setting a Cryptographic policy for the account or group or a Key Metadata Policy for the group. For more details about the Cryptographic policy, please refer to the article: User's Guide: Cryptographic Policy..

   For more details about the Key metadata policy, please refer to the article: User's Guide: Key Metadata Policy.

9. Enter the Key size and select the permitted key operations under Key operations permitted section.
10. Add custom attributes by clicking the ADD ATTRIBUTE button.
    NOTE

    The custom attributes also depend on the Key metadata policy for the group. If the GCP KMS group has a Key metadata policy configured with restrictions for custom attributes, then these rules will be applied while creating the security object.
11. To store audit logs for the object in the group, enable the toggle for Keep detailed log for the object. The initial state of the toggle is based on the parent Crypto policy if any.
12. Click the GENERATE button to generate the key in GCP KMS. 
13. The new GCP Key is created and represented with a special symbol to denote it is of type HSM/External KMS. In the detailed view of the GCP key you will notice the following things:
    • The group to which it belongs (in the Group field). It also shows if the group is mapped to a GCP KMS or not using the special icon .
    • How the key was created (in the Created by field). If it is a GCP KMS key, this field shows the group that created this key. It also shows minor details such as if the group is “Connected” or “Not Connected”.
14. The new GCP KMS key is in an Enabled state by default which means that all the Encrypt and Decrypt operations can be performed on the actual key in the GCP KMS according to the key permissions. Click the toggle for Enabled to disable it. This will disable the GCP KMS key temporarily. 
15. The new key will be added to the Security Objects table. 
    TIP

    • You can also access the new key from the Group detailed view from the SECURITY OBJECTS tab.
    • You can also add a new key from the Group detailed view from the SECURITY OBJECTS tab, click ADD SECURITY OBJECT button, and follow steps 3-10 above.

4.1.2  Bring Your Own Key - Import Key 

This action will import the configured key type in the key ring in one of the configured GCP KMS regions directly, and it will be represented as a virtual key in the corresponding GCP KMS group. This means that the virtual key in the GCP KMS group will point to the actual key in GCP KMS that stores the key material of this new key. The virtual key only stores the key information and key attributes, but it does not have the key material. The import action will not store a copy of the key material in Fortanix DSM.

1. Follow Steps 1-5 from Section 4.1.1
2. Select IMPORT to initiate the import key in the GCP KMS workflow.
3. Enter the GCP key name The GCP key name is the key name that will be stored in GCP Key Ring. The GCP key name will be used to correlate between different versions of a key. All the key versions will have the same GCP key name.
4. Select the key type for the new GCP KMS key.
   
   NOTE

   For Fortanix DSM 4.4, the allowed key type for a GCP KMS key generated using the import Key button in Fortanix DSM is AES 256.

   These key types can further be restricted by setting a Cryptographic policy for the account or group or a Key Metadata Policy for the group. For more details about the Cryptographic policy, please refer to the article: User's Guide: Cryptographic Policy.

   For more details about the Key metadata policy, please refer to the article: User's Guide: Key Metadata Policy.

5. Sometimes keys of type AES that need to be imported from a file were previously wrapped (encrypted) by a key from Fortanix DSM. This is done so that the key should not go over the TLS in plain text format. In such scenarios select the check box The key has been encrypted.
6. Next enter or select a Key ID or SO name in the Select Key Encryption Key section which will be used to unwrap (decrypt) the encrypted key in the file which will later be stored securely in Fortanix DSM. This key should have already been created or imported in Fortanix DSM.
7. Select the mode of operation.
8. Enter the Key Check Value (KCV).
9. Click UPLOAD A FILE to upload the key file in Raw, Base64, or Hex format.
10. Select the permitted key operations.
11. Add custom attributes by clicking the ADD ATTRIBUTE button.
    NOTE

    The custom attributes also depend on the Key metadata policy for the group. If the GCP KMS group has a Key metadata policy configured with restrictions for custom attributes, then these rules will be applied while creating the security object.
12. To store audit logs for the object in the group, enable the toggle for Keep detailed log for the object. The initial state of the toggle is based on the parent Crypto policy if any.
13. Click IMPORT to import the key in GCP KMS. The key is now successfully imported.

4.1.3  Bring Your Own Key - Copy Key to GCP KMS

Use this option when you want to generate a key in Fortanix DSM and then import the key into the configured GCP KMS. The copy key to GCP feature will copy a security object from one regular Fortanix DSM group to another regular/GCP KMS Fortanix DSM group. This feature has the following advantages:

• Maintains a single source of key material while using/importing that key into various Fortanix DSM groups where applications may need to use a single key to meet business objectives.
• Maintains a link of various copies of the same key material to the source key for audit and tracking purposes.

The following actions will happen as part of the copy key operation:

• A new key will be created in the target group: The new key will have the same key material as the original.
• The source key links to the copied keys: There will be a link maintained from all copied keys to the source key.
• The Source key will also have basic metadata-based information about the linked keys such as:
  • Copied by <user-name/app id>
  • Date of Copy <time stamp>
  • Target copy group name

To copy a key from a regular Fortanix DSM group to a GCP KMS group:

1. Go to the detailed view to a key and click the NEW OBJECT icon on the far right of the screen. Figure 1: Initiate copy key
2. In the menu that appears, click the COPY KEY button. 
   NOTE

   • To copy a key from a regular Fortanix DSM group to a GCP KMS group, the key must be AES 256. In Fortanix DSM 4.4, GCP KMS only supports only AES 256 keys during copy or import operations.
   • The AES 256 key to be copied must have the “Export” permission enabled or the copy key operation will fail.
   • The COPY KEY button will be disabled for all the GCP KMS virtual keys.
3. In the COPY KEY window, update the name of the key if required.
4. Click the Import key to HSM/External KMS check box to filter the groups to show only GCP KMS groups. Select the GCP group for the new key into which the copied key should be imported.
5. Enter the GCP key name.
6. Update KEY PERMISSIONS if you want to modify the permissions of the key. 
7. Click CREATE COPY to create a copy of the key as shown in the figure above.
8. The source key will now appear as a key link in the KEY LINKS tab in the detailed view of the copied key. 
   NOTE

   If a user wants to maintain a copy of the key material in Fortanix DSM, then the user can import a regular AES 256 key into Fortanix DSM using the “import key” workflow and then copy this key into GCP KMS using the “copy key” workflow.

4.2  Sync Keys

When you edit the GCP KMS connection details in the GCP KMS group detailed view under HSM/KMS tab, click SYNC KEYS to import new keys. On clicking SYNC KEYS, Fortanix DSM connects to GCP KMS and gets all the keys available. Fortanix DSM then stores them as virtual keys.

4.3  Attributes/Tags Tab

This tab will have all the attributes and tags of the GCP key. 

4.4  GCP Key Details

This tab displays details of the GCP key name and GCP protection level. For more details about GCP protection level, refer to the Google documentation.

4.5  Security Objects Table View

After you add new GCP keys, go to the Security Objects page to view all the security objects from all the groups (GCP and non-GCP).

In the security object table, you will notice that every key belongs to a group and some keys which are virtual keys added from an GCP, belongs to a group with a special symbol . The security objects table view will continue to show all the keys irrespective of if they belong to a GCP KMS group or not.

5.0 Rotate a Key in GCP CDC Group

The following section explains the Key Rotation in the GCP CDC Group. A Key is rotated when you want to retire an encryption key and replace that old key by generating a new cryptographic key.

5.1 Rotating GCP Native Key with Another Native Key

*Native key is one where the key material was generated by GCP KMS.

When you rotate a virtual key in a GCP CDC group, the action will rotate the key inside the GCP KMS by generating another version of the key within the configured GCP KMS. To rotate a key in GCP:

1. Select the GCP virtual key to rotate.
2. In the detailed view of the GCP virtual key, click the ROTATE KEY button. 
3. In the Key Rotation window, click the ROTATE KEY button to rotate the virtual key. 

A new rotated key is now generated.