Integrate with Microsoft Azure Key Vault

Access Microsoft Azure Key Vault

Microsoft Azure Key Vault can be accessed in the Azure Portal or by using the Azure Command-Line Interface (CLI). Follow the Microsoft Azure documentation to ensure that you use the appropriate authentication and are communicating with a genuine Azure Key Vault server.

This operation requires the use of Key Vault HSM keys which are currently only available using the Key Vault Premium SKU.

Entrust recommends that you use the Microsoft BYOK guide when carrying out the Azure operations because they might have been updated after the publication of the User Guide for the Cloud Integration Option Pack. See https://docs.microsoft.com/en-us/azure/key-vault/keys/hsm-protected-keys-byok.

Generate the Azure Key Exchange Key

The Key Exchange Key (KEK) is an RSA key generated in a Key Vault HSM. The KEK is used to encrypt the key that you want to import and must be:

  • A 2048-bit, 3072-bit, or 4096-bit RSA-HSM key.

  • Generated in the same key vault where you intend to import the target key.

  • Created with allowed key operations set to import.

The KEK can be generated using the online portal or using the Azure CLI. For example:

az keyvault key create --kty RSA-HSM --size 4096 --name <KEK name> --ops import --vault-name <key vault>

Make a note of the resulting key identifier (kid) as you will need this value later. It is in the following form:

https://<container-name>.<container-type>.azure.net/keys/<key-name>/<key-version>

where <container-type> is either vault or managedhsm.

Download the Azure Key Exchange Key

Use the Azure CLI to download the KEK public key to a .pem file. For example:

az keyvault key download --name <KEK name> --vault-name <key vault> --file <download file>

Use cloud_integration_tool to generate, wrap and export a key

Using the downloaded KEK file, call cloud_integration_tool as follows:

cloud_integration_tool microsoft-azure <key name> <wrapping key> --azure-kek <azure kid> --key-type <key type>

Where:

wrapping key

The file you downloaded, for example KEKforBYOK.publickey.pem.

azure kid

The Key Identifier of the KEK, for example https://mykeyvault.vault.azure.net/keys/my-key/version.

key-type

Optional and defaults to RSA 2048-bit if none is provided.

No wrapping algorithm parameter is required with Microsoft Azure because it only supports one algorithm.

The following target key types are available:

RSA Keys

  • 2048-bit

  • 3072-bit

  • 4096-bit

Elliptic Curve Keys

  • NISTP256

  • NISTP384

  • NISTP521

  • SECP256K1

To maintain the security strength of the transferred target key, ensure that the security strength of the chosen KEK is greater than or equal to the security strength of the chosen target key. For example, for an Elliptic Curve key generated using NISP256, the KEK must be RSA 3072-bit or greater.

Running the cloud_integration_tool command creates a file called KeyTransferPackage-<key name>.byok.

Upload the wrapped key material

To import the target key into your Azure Key Vault, use the Azure CLI command to upload the BYOK file to the Key Vault HSM.

For RSA keys:

az keyvault key import --vault-name <vault name> --name <target key name> --byok-file <key transfer package>

For EC keys:

az keyvault key import --vault-name <vault name> --name <target key name> --kty EC --curve <curve name> --byok-file <key transfer package>

where

key transfer package

The byok file produced in Use cloud_integration_tool to generate, wrap and export a key.

You can also do this step using the Azure Portal.

If the upload is successful, you can use this HSM-protected key in your key vault.