See more

Exporting Self-Defending KMS keys to Cloud Providers for BYOK - Azure Key Vault HSM

  • Last updated:
  • access_time Reading time:

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:

  1. Log in to https://portal.azure.com/.
  2. Register an application. azure_byok1.png
    Figure 1: Initiate app registration
      azure_byok2.png
    Figure 2: Register an App
      azure_byok3.png
    Figure 3: App registered
     
  3. Create a client secret for the above application. azure_byok7.png
    Figure 4: Client secret for the app
     
  4. Give the App permission to access the Azure Key Vault. azure_byok4.1.png
    Figure 5: Key Vault permission to access app
     
  5. Create an Azure Key Vault.
      Note.png NOTE: This Key Vault should have a premium subscription. azure_byok5.png
    Figure 6: Create Azure Key Vault HSM
      
      azure_byok16_HSM.png
    Figure 7: Create Azure Key Vault HSM
       
  6. Add the application in the Access Policy of the Key Vault. azure_byok21.1_HSM.png
    Figure 8: Add access policy
      azure_byok22_HSM.png
    Figure 9: Select Principal 
      azure_byok23_HSM.png
    Figure 10: Add access policy 
      azure_byok17.1_HSM.png
    Figure 11: Access policy added
         
  7. 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. azure_byok18_HSM.png
    Figure 12: Create a KEK Key
     
  8. Key Created. azure_byok19_HSM.png
    Figure 13: KEK Key created
     
  9. Make note of the following information:
    • KEK Identifier (Full URL)
    • Key Vault name
    azure_byok20_HSM.png
    Figure 14: KEK Key details

Actions to be performed on Fortanix Self-Defending KMS

  1. Log in to Fortanix Self-Defending KMS ( https://sdkms.fortanix.com/ ).
  2. Create an account in Fortanix Self-Defending KMS.
  3. Create a group in Fortanix Self-Defending KMS account.
  4. 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

Automation

  1. Once you download the tool, you can run this tool from any machine that can reach your Self-Defending KMS cluster over the network. 
  2. Perform Steps 1-10 in the section Azure App Configuration.
  3. Perform Steps 1-4 in the section Fortanix Self-Defending KMS Configuration.
  4. Create KEK key. 
    az keyvault key create --kty RSA-HSM --size 2048 --name <KEY-NAME> --ops import --vault-name <KEY-VAULT-NAME>
  5. 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>

  6. 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

  1. Go to the Fortanix Self-Defending KMS home page and click the Plugins icon. sdkms_aws_byok10.png
    Figure 15: Plugins
     
  2. 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. azure_byok24_HSM.png
    Figure 16: Plugin Library
     
  3. 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.azure_byok25_HSM.png
    Figure 17: Get Plugin
     
  4. Review the plugin name and assign it to a group, and then click Save. azure_byok26_HSM.png
    Figure 18: Review plugin details
  5. 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. sdkms_aws_byok15.png
    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