User's Guide: AWS External KMS

1.0  Overview

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

2.0  Fortanix Data Security Manager Group Workflow

2.1  Create an AWS KMS Group

  1. In the Fortanix Data Security Manager (DSM) Groups AWS_41.png page, click the Add.png button to create a new AWS KMS group. AWS_0.png Figure 1: Create new group
  2. In the Add new group form,
    1. Enter a title and description for your group.
    2. Next, click the LINK HSM/EXTERNAL KMS button to choose the AWS External KMS type, so that Fortanix DSM can connect to it.
    AWS_1a.png
    Figure 2: Link AWS

2.2  Configure the AWS KMS

2.2.1  Prerequisites

To configure the AWS group, the following are the AWS KMS permissions that the AWS Identity and Access Management (IAM) users must have to authenticate the Fortanix DSM group with AWS Key Management Services.

LIST:

  • ListKeys
  • ListKeyPolicies
  • ListRetirableGrants
  • ListAliases
  • ListGrants
  • ListResourceTags

READ:

  • DescribeKey
  • GetPublicKey
  • GetKeyRotationStatus
  • GetKeyPolicy
  • GetParametersForImport

WRITE:

  • CreateKey
  • ImportKeyMaterial
  • DeleteImportedKeyMaterial
  • EnableKey
  • DisableKey
  • ScheduleKeyDeletion
  • CancelKeyDeletion
  • EnableKeyRotation
  • DisableKeyRotation
  • CreateAlias
  • DeleteAlias
  • UpdateAlias
  • PutKeyPolicy
  • TagResource
  • UntagResource
  • CreateGrant
  • RetireGrant
  • RevokeGrant

2.2.2  Create AWS KMS Group

  1. Select the AWS Type. Click the drop-down to select the AWS Type. For example, AWS KMS. AWSKMS.png
    Figure 3: Choose AWS type
  2. In the Choose Region field, select the AWS region from which the keys should be imported. AWS_1.png
    Figure 4: Select region
  3. Enter the AWS KMS Service Account Credentials,
    1. URL: The URL of the AWS region gets auto-populated based on the region selected. This is an editable field, so a user can also add a custom URL of the AWS region.
    2. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: Access key and Secret Access Key are used for accessing the AWS services. Each AWS account has its unique login credentials; Fortanix DSM should allow its users to log in and securely save AWS credentials to do native cloud key management and offline automation such as automatic key rotation based on a set schedule and so on.
    AWS_2.png
    Figure 5: Service account credentials

2.3  Test Connection

  1. Click TEST CONNECTION to test your AWS KMS connection. If Fortanix DSM is able to connect to your AWS using your connection details, then it shows the status as “Connected” with a green tick AWS_43a.png. Otherwise, it shows the status as “Not Connected” with a yellow warning sign AWS_44a.png .AWS_3.png
    Figure 6: Test connection - successful

2.4  Save AWS 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.

Once you save your group details, your group is created, and you will see the detailed view of your group. AWS_4.png
Figure 7: Group detailed view

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

2.5  The HSM/KMS Tab

The HSM/KMS tab shows the details of the KMS that was added such as the URL, access key, and secret of the AWS. You can also edit the AWS connection details here.

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

Click SYNC KEYS to sync keys from the configured AWS KMS to the AWS group.

AWS_45a.pngFigure 8: Sync keys

2.6  Not Connected Scenario

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

2.7  Groups Table View

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

AWS_5.pngFigure 9: AWS KMS groups

2.8  User's View

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

AWS_6.pngFigure 10: User's table

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

AWS_7.png
Figure 11: User detailed view

3.0  Fortanix Data Security Manager AWS KMS Security Objects

3.1  Create a Key in AWS KMS Group - Generate

You can generate a key in a configured AWS KMS.

3.1 1  Generate a Key

This action will generate the configured key type in the configured AWS KMS regions directly, and it will be represented as a virtual key in the corresponding AWS KMS group. This means that the virtual key in the AWS KMS group will point to the actual key in AWS 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 AWS_48.png tab (Figure 12).
  2. Click AWS_42.pngto create a new Security Object. AWS_8.png Figure 12: Security objects tab in Fortanix Data Security Manager
  3. In the Add New Security Object form (Figure 13) enter a name for the Security Object (Key).
  4. Select the This is an HSM/external KMS object check box (Figure 13). This will show the AWS KMS configured groups in the Select group
  5. In the AWS group list, select the AWS group into which the keys will be generated. The keys will be generated into the region that was selected in the AWS group. AWS_9.png Figure 13: Assign key to the AWS group
  6. Select GENERATE IN AWS to initiate the generate key in AWS workflow.
  7. Add an alias in the AWS Aliases Use the ADD ALIAS button if you are adding more than two aliases. AWS_10.png Figure 14: Generate key in AWS and Add Aliases
  8. Select the key type for the new AWS KMS key.
    NOTE
    The allowed key types for an AWS key generated using the Generate Key button are:
    • AES 256
    • RSA key pairs ( RSA_2048, RSA_3072, and RSA_4096)
    • Elliptic curve key pairs (ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, and ECC_SECG_P256K1).
    These key types can further be restricted by setting a crypto policy for the account or group. For more details about the crypto policy, please refer to the article: https://support.fortanix.com/hc/en-us/articles/360042064051-User-s-Guide-Crypto-Policy.
     
  9. Enter the Key size and select the permitted key operations under Key operations permitted section.
  10. Click the GENERATE button to generate the key in AWS. AWS_11.png Figure 15: Generate key
  11. The new AWS Key is created and represented with a special symbol Group_7.png to denote it is of type AWS/KMS. In the detailed view of the AWS key you will notice the following things:
    • The group and region to which it belongs (in the Group field). It also shows if the group is mapped to an AWS or not using the special icon AWS_46.png.
    • How the key was created (in the Created by field). If it is an AWS 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”.
    AWS_12.pngFigure 16: Security objects detailed view
  12. The new key will be added to the Security Objects table. AWS_13.png Figure 17: Key added
    TIP
    • You can also access the new key from the Group detailed view from the SECURITY OBJECTS tab (Figure 18).
    • You can also add a new key from the Group detailed view from the SECURITY OBJECTS tab (Figure 18), click ADD SECURITY OBJECT button, and follow steps 3-10 above.
    AWS_14.pngFigure 18: View/add AWS KMS security objects

3.1.2  Bring Your Own Key - Import Key 

This action will import the configured key type in one of the configured AWS KMS regions directly, and it will be represented as a virtual key in the corresponding AWS KMS group. This means that the virtual key in the AWS KMS group will point to the actual key in AWS 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 3.1.1
  2. Select IMPORT to initiate the import key in AWS workflow.
  3. Add an alias in the AWS Aliases section. Use the ADD ALIAS button if you are adding more than two aliases. 
  4. Select the key type for the new AWS KMS key.
    NOTE
    The allowed key type for an AWS key generated using the Import Key button is only AES 256 keys.
  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. Click UPLOAD A FILE to upload the key file in Raw, Base64, or Hex format.
  8. Select the permitted key operations and click IMPORT to import the key.
  9. The key is successfully imported.

3.1.3  Bring Your Own Key - Copy Key to AWS

Use this option when you want to generate a key in Fortanix DSM and then import the key into the configured AWS KMS. The copy key to AWS feature will copy a security object from one regular Fortanix DSM group to another regular/AWS 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
NOTE
The name of the copied key is suggested automatically to the user as [original key name]_[copy1,2,...], but can be replaced with an alternative unique name.

To copy a key from a regular Fortanix DSM group to an AWS group:

  1. Go to the detailed view to a key and click the Plus icon AWS_42.png on the far right of the screen. AWS_26a.png Figure 19: Initiate copy key
  2. In the menu that appears, click the COPY KEY button. AWS_27a.png Figure 20: Click copy key
    NOTE
    • To copy a key from a regular Fortanix DSM group to an AWS KMS group, the key must be AES 256. AWS KMS only supports 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.
  3. In the COPY KEY window, update the name of the key if required.
  4. Click Import key to HSM/External KMS check box to filter the groups to show only AWS KMS groups. Select the AWS group for the new key into which the copied key should be imported.
  5. Add aliases in the AWS Aliases section.
  6. Update KEY PERMISSIONS if you want to modify the permissions of the key. AWS_31.pngFigure 21: Create copy
  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. AWS_32a.pngFigure 22: Key link
    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 AWS using the “copy key” workflow.

3.2  Sync Keys

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

NOTE
  • When keys are synced with AWS KMS, the metadata of the existing keys for the configured service account and region are downloaded and represented as virtual keys. The actual key material for those keys is always stored in AWS KMS.
  • Clicking SYNC KEYS only returns the keys from AWS that are not present in Fortanix DSM. That is, every click will append only new keys to Fortanix DSM.

3.3  Attributes/Tags Tab

This tab will have all the attributes and tags of the AWS key. You can add new tags as attributes using the NEW TAG button. 

AWS_49a.pngFigure 23: Key attributes

3.4  AWS Key Details

This tab displays details of the AWS key aliases, Key ARN for Key ID, and the AWS key policy. 

AWS_17.pngFigure 24: AWS key details

The AWS KEY DETAILS tab also contains SCHEDULE KEY DELETION and DELETE KEY MATERIAL options which are explained in Section 3.8 and Section 3.9, respectively.

3.5  Security Objects Table View

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

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 AWS, belongs to a group with a special symbol AWS_46.png. The security objects table view will continue to show all the keys irrespective of if they belong to an AWS group or not.

AWS_13.pngFigure 25: Security objects table view

3.6  Deactivate a Key in AWS Group

When you deactivate an AWS key in Fortanix DSM, the action will deactivate the virtual key in Fortanix DSM and the actual key in the configured AWS KMS will be disabled.

To deactivate a key:

  1. Select the AWS key to deactivate.
  2. In the security object detailed view, scroll down, and click the DEACTIVATE button.
    AWS_18.png Figure 26: Deactivate key

3.7  Delete a Key in AWS Group

When you delete a key from an AWS group, the action will only delete the virtual key in Fortanix DSM and will not delete the actual key in the configured AWS.

To delete a virtual key:

  1. Select the AWS key to delete.
  2. In the security object detailed view, scroll down and click the DELETE SECURITY OBJECT button.
    AWS_50.png Figure 27: Delete AWS virtual key

3.8  Schedule to Delete a Key in AWS KMS

When you delete a key from an AWS KMS, the action will delete the actual key in the configured AWS and will appear as disabled in the security objects table.

To delete a key from an AWS KMS:

  1. Go to the detailed view of an AWS virtual key and select the AWS KEY DETAILS tab.
  2. Click the link SCHEDULE KEY DELETION. AWS_20a.png Figure 28: AWS schedule key deletion
  3. In the Schedule Key Deletion in the AWS KMS window, enter a waiting period (in days) to verify whether you still need the AWS key.
     
    NOTE
    Data encrypted with the key can no longer be used once the key is deleted.
  4. Click SCHEDULE KEY DELETE button to mark the key for deletion. AWS_21.png Figure 29: Configure the key deletion schedule
  5. You can cancel the key deletion any time before the waiting period ends using the CANCEL KEY DELETION IN AWS link on the top of the screen in the detailed view of the virtual key.
      AWS_22a.png Figure 30: Cancel key deletion

3.9  Delete Key Material in AWS KMS

When an AES 256 key is copied into AWS KMS from Fortanix DSM, the key material is stored in two places, the source key in the regular Fortanix DSM group and in the configured AWS KMS for a specific account and region. This key is represented as a virtual key in the AWS KMS group. A virtual key is only a virtual representation of the actual AWS KMS key that contains the key information and key attributes; however, this virtual key does not contain the key material. Users may want to delete the key material from the configured AWS KMS to maintain a single copy of key material stored securely in the source key in the regular Fortanix DSM group.

NOTE
The Delete Key material feature is enabled only for keys of type AES 256 that have been externally imported into AWS KMS.

To delete the key material:

  1. Go to the detailed view of a virtual key in the AWS group and select the AWS KEY DETAILS tab.
  2. Click the DELETE KEY MATERIAL link to delete the key material in AWS KMS. AWS_23a.png Figure 31: Delete key material
  3. In the Delete Key Material in AWS KMS window, click the DELETE KEY MATERIAL button. AWS_24.png &Figure 32: Confirm delete key material The status of the key in the AWS KMS changes to “Pending import”.
  4. Once the key material is deleted from AWS KMS, it can be reimported back into AWS KMS to reverse the key material deletion. To reimport the key material:
    1. Go to the detailed view of the virtual key and click the REIMPORT KEY MATERIAL link on top of the screen. AWS_51a.png Figure 33: Reimport key material
    2. The key material is reimported successfully.

4.0  Rotate Key in AWS Group

4.1  Rotating AWS Native Key* with Another Native Key

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

When you rotate a virtual key in an AWS group, the action will rotate the key inside the AWS KMS by generating another key within the configured AWS KMS by moving the key alias from the old key to the new key.

To rotate a key in AWS:

  1. Select the AWS virtual key to rotate.
  2. In the detailed view of the AWS virtual key, click the ROTATE KEY button. AWS_25a.png Figure 34: Rotate key
  3. In the Key Rotation window, click the ROTATE KEY button to rotate the virtual key. AWS_36.png Figure 35: Rotate virtual key A new rotated key is now generated.

4.2  Rotating Keys in Fortanix Data Security Manager Source Group

When a key is rotated that belongs to a Fortanix DSM source group and has linked keys that are copies of the Fortanix DSM source key with the same key material as the source key, then the user is given the option to select the linked keys for key rotation. If these linked keys belong to an AWS group, then rotating the linked keys results in rotating the keys in AWS KMS as well by generating new keys within the configured AWS KMS and by moving the aliases from old to new keys.

  1. Click ROTATE KEY in the detailed view of a Fortanix DSM Source Key.
  2. In the KEY ROTATION window, select the Rotate linked keys check box.
  3. Select the AWS Virtual Keys that needs to be rotated along with the Fortanix DSM source key and click the ROTATE KEYS button.
    NOTE
    In the KEY ROTATION window, if the user edits the default Key Size of the Source key from AES 256 to a new value, then selecting the “Rotate linked key “ option disables the AWS virtual keys. AWS KMS only supports AES 256 keys. Linked keys that are not AWS KMS keys will still be available for rotation with the new key size value.
    AWS_35.png Figure 36: Disable AWS KMS key
  4. Once the keys are rotated, click the OK button. AWS_34.png Figure 37: Rotate linked keys

4.3  Rotate AWS Native Key to Fortanix Data Security Manager Owned Key

When an AWS virtual key whose key material is owned by AWS KMS is rotated, the user is given an option to rotate the virtual key with a Fortanix DSM-backed key. When the user selects this option and performs the rotation, a new virtual key is created with the key material of the Fortanix DSM-backed key. As a result, the AWS virtual key is backed by a Fortanix DSM Source key.

To rotate a virtual key with Fortanix DSM-backed key:

  1. Click ROTATE KEY in the detailed view of an AWS virtual key.
  2. In the Key Rotation window, select the Rotate to S-D KMS key check box.
  3. Select the Fortanix DSM group that contains the source key.
  4. Select the source key and click the ROTATE KEY button. AWS_37.png Figure 38: Rotate virtual key with Fortanix DSM Key

    The Virtual key is successfully rotated and backed by the source key. To confirm go to the detailed view of the AWS virtual key and click the AWS KEY DETAILS tab. The SOURCE field now points to “FortanixHSM” instead of “External”.

    AWS_38.png Figure 39: AWS virtual key's source changed
Was this article helpful?
0 out of 0 found this helpful