Overview
There are several ways to export Self-Defending KMS keys to major cloud providers that support BYOK for server-side encryption. This document describes the process for importing HSM-protected keys to Key Vault.
Actions to be performed on Azure
You will need to provide the tool your Azure credentials, which will be used to authenticate to Azure and perform interactions with Azure Key Vault. You can do the following to get these credentials:
- Log in to https://portal.azure.com/.
- Register an application.
Figure 1: Initiate app registration Figure 2: Register an App Figure 3: App registered - Create a client secret for the above application.
Figure 4: Client secret for the app - Give the App permission to access the Azure Key Vault.
Figure 5: Key Vault permission to access app - Create an Azure Key Vault.
NOTE: This Key Vault should have a premium subscription.
Figure 6: Create Azure Key Vault HSM
Figure 7: Create Azure Key Vault HSM - Add the application in the Access Policy of the Key Vault.
Figure 8: Add access policy Figure 9: Select Principal Figure 10: Add access policy Figure 11: Access policy added - In the Key Vault, generate a key (referred to as a Key Exchange Key (KEK)). The KEK must be an RSA-HSM key that has only the
import
key operation. Only Key Vault Premium SKU supports RSA-HSM keys.Figure 12: Create a KEK Key - Key Created.
Figure 13: KEK Key created - Make note of the following information:
- KEK Identifier (Full URL)
- Key Vault name
Figure 14: KEK Key details
Actions to be performed on Fortanix Self-Defending KMS
- Log in to Fortanix Self-Defending KMS ( https://sdkms.fortanix.com/ ).
- Create an account in Fortanix Self-Defending KMS.
- Create a group in Fortanix Self-Defending KMS account.
- Create an app in Fortanix Self-Defending KMS.
Refer to the Fortanix Getting Started Guide for instructions on how to do the Steps 1-4 above.
Make sure that the app you are going to use, has access to the group where the Self-Defending KMS key exists that you want to use for this BYOK operation.
Azure Key Vault HSM BYOK Automation
Running Azure Key Vault HSM BYOK tool - Automated
Download the Fortanix Self-Defending KMS Azure Key Vault HSM BYOK tool from here.
Prerequisites
In order to run Fortanix Self-Defending KMS Azure Key Vault HSM BYOK tool, you need the following:
- Install sdkms-cli.
You can also do this by running the command:pip install sdkms-cli
- Install Azure CLI
Automation
- Once you download the tool, you can run this tool from any machine that can reach your Self-Defending KMS cluster over the network.
- Perform Steps 1-10 in the section Azure App Configuration.
- Perform Steps 1-4 in the section Fortanix Self-Defending KMS Configuration.
- Create KEK key.
az keyvault key create --kty RSA-HSM --size 2048 --name <KEY-NAME> --ops import --vault-name <KEY-VAULT-NAME>
- Run the script.
- Help:
python sdkms-azure-hsm-byok.py -h
- Import:
python sdkms-azure-hsm-byok.py --azure-client-id <AZURE_CLIENT_ID> --azure-client-secret <AZURE_CLIENT_SECRET> --azure-tenant-id <AZURE_TENANT_ID> --azure-kek-id <AZURE_KEK_ID> --sdkms-api-endpoint <SDKMS_API_ENDPOINT> --sdkms-api-key <SDKMS_API_KEY> --target-key-size <TARGET_KEY_SIZE> --target-key-name <TARGET_KEY_NAME>
- Help:
-
The tool takes the following arguments:
--azure-client-id
User name, service principal, or managed service identity ID / Application ID
--azure-client-secret
Azure client secret
--azure-tenant-id
The AAD tenant
--azure-kek-id
Azure KEK Identifier (Full URL)
--sdkms-api-endpoint
Self-Defending KMS API Endpoint
--sdkms-api-key
Self-Defending KMS API Key
--target-key-size
RSA key size 2048, 3072, 4096
--target-key-name
Name of the target key in Azure Key Vault
Running Azure Key Vault HSM BYOK - Using Plugin
- Go to the Fortanix Self-Defending KMS home page and click the Plugins icon.
Figure 15: Plugins - In the Plugins page, click the PLUGIN LIBRARY tab and then click the Self-Defending KMS-Azure Bring Your Own Key (BYOK) tile to load the associated plugin page with detailed information about the plugin, common use cases, setup, and format of the plugin inputs and outputs.
Figure 16: Plugin Library - In the "Self-Defending KMS-Azure Bring Your Own Key (BYOK) plugin" page, to install a plugin the user needs to click the GET PLUGIN button to go to the plugin creation page.
Figure 17: Get Plugin - Review the plugin name and assign it to a group, and then click Save.
Figure 18: Review plugin details - Now go to the detailed view of the plugin, where you can also test the plugin's request and response using the Test Plugin text box where you can paste a sample request from the plugin code and see the response in the Test output section. To configure and run the plugin click the INVOKE PLUGIN button.
Figure 19: Invoke Plugin For more request and response operations go to Fortanix Self-Defending KMS Plugin Library -> <plugin-name> -> OVERVIEW page as shown in Figure 17.
For more details on how to use the Plugin Library, see the article https://support.fortanix.com/hc/en-us/articles/360041950371-User-s-Guide-Plugin-Library