Skip to content

Azure Key Vault

Azure Key Vault provides hardware security modules (HSM) that are maintained in the Azure Cloud. This allows client total control of their cryptographic materials in hardware and firmware without being exposed to any operators including Microsoft. Using an HSM based keys management provides the highest level of security.

Kaleido CloudHSM service supports using keys maintained by Azure Key Vault to sign transactions. The Kaleido service communicates with Azure Key Vault via HTTP over TLS to discover the list of signing accounts and sending it payload to sign. During the entire process the signing keys stay safe inside the customer's Azure Key Vault instance and are never shared with Kaleido.

This document details the steps to:

  • Create a Key Vault in Azure
  • Create one or more keys in the vault that can be used to sign Ethereum transactions
  • Create and configure a Kaleido CloudHSM signer service which has the ability to interact with the Key Vault in Azure to sign and send transactions to an Ethereum node in the Kaleido environment

Create & Configure Key Vault in Azure

Azure Key Vault is backed by FIPS 140-2 Level 2 certified HSMs keeping your keys secure. The first step is to provision a Key Vault in Azure and generate secp256k1 keys suitable for signing Ethereum transactions.

This section provides information about steps to carry out to create a Key Vault and keys. If you already have a Key Vault and keys within the vault that can be used for signing, you may skip to the section Create Kaleido CloudHSM Service

Register App

Azure Key Vault authenticates requests using Azure Active Directory access tokens in the header as a bearer token. Clients can obtain access tokens by registering an OAuth 2 App with Azure.

Register an app with the Microsoft Identity Platform for authentication and authorization of requests. Search for and bring up App Registrations in Azure Portal. Register an app by providing a user facing display name (specifying a name that includes the name of the key vault name is one way to make the association explicit), and the supported account types that can access the application. This app will be allowed access to the Key Vault in a subsequent step, with specific authorization settings. If you are using an existing Key Vault in Azure, we highly recommend you register a new app as specified in this step (vs. reusing credentials from an existing app registration for your Key Vault) that the Kaleido CloudHSM service can use for authenticated access to your organization's Azure Key Vault. Note down the client ID, tenant ID and subscription ID for the registered app. For further information on how to register an app with the Microsoft Identity Platform, please refer to Azure Documentation

Generate Client Secret to Access the App

After the Key Vault app is successfully registered, you can create a secret for the app that can be used by external clients to authenticate with Microsoft identity platform for access to the Key Vault. Select the Certificates & Secrets in the menu and click on Client secrets -> New client secret. Provide a description and duration of validity for the secret and click Add. The value for the secret is displayed. It is important that you note down the secret at this point, because it cannot be retrieved later.

Create Key Vault

Create a Key Vault in Azure by providing Subscription, Resource Group, Key Vault Name and Region. Note down the value for the Key Vault Name.

Click Next: Access policy and click Add Access Policy. Use the following settings to configure the right level of authorization for keys in the Key Vault:

  • From Configure from template drop-down, pick Key management.
  • From Key Permissions drop-down, leave only the following options checked:
    • Key Management Operations: Get, List
    • Cryptographic Operations: Verify, Sign
      The above options ensures that Kaleido CloudHSM service has read only access to the key(s) in the key vault and is only allowed to execute sign/verify cryptographic operations using the key(s).
  • From Select Principal, select the app that was created in the previous step. This ensures that the secret value generated in the app can be used to create an authenticated session to the Key Vault.

Complete creation by clicking the Review & Create button. For further information on how to create a Key Vault, please refer to Azure Documentation.

Create SECP256K1 Key for Ethereum Transaction Signing

In Azure Portal, go to Key Vault and bring up the key vault that was created in the previous step. Click the Keys selection in the left hand menu and click on Generate/Import. Use the following options for creating the key:

Field Value
Options Generate
Name name for the key
Key Type EC (elliptic curve)
Elliptic Curve Name SECP256K1
Enabled Yes

Repeat this step for any additional keys you'd like to create

Create Kaleido CloudHSM Service

Creation of Kaleido CloudHSM service in Kaleido is a two step process:

  • Specify the type and access details to Azure Key Vault as a configuration under the environment (this can be referenced by one or more cloud HSM service instances created in the same membership)
  • Create the CloudHSM service using the configuration created above

Create CloudHSM configuration for Azure Key Vault

The configuration for Azure Key Vault has the following mandatory parameters:

Field Usage
type Type of configuration. Must be cloudhsm
name User-defined name for the configuration
membership_id ID of membership under which this configuration is available
details
-- provider CloudHSM backend provider. Must be azure
-- target_address The base URL for key vault, defaults to https://vault.azure.net
-- user_id Azure clientId
-- user_secret Azure clientSecret
-- subscription_id Azure subscriptionId
-- tenant_id Azure tenantId
-- vault_name Azure Key Vault vault name

The following is a sample POST request to create an Azure key vault cloudhsm configuration:

https://console.kaleido.io/api/v1/consortia/:consortia_id/environments/:environment_is/configurations

{
  "type": "cloudhsm",
  "name": "azure-key-vault",
  "membership_id": "<id>",
  "details": {
    "provider": "azure",
    "user_id": "<clientId>",
    "user_secret": "<clientSecret>",
    "subscription_id": "<subscriptionId>",
    "tenant_id": "<tenantId>",
    "vault_name": "name_of_vault"
  }
}

Create Cloud HSM service

Using the configuration created above, cloud HSM service can be created using the request fields:

Field Usage
name User-defined name for the service
membership_id ID of membership under which this service is available
service Type of service. Must be cloudhsm
details
-- cloudhsm_id ID of the configuration created in the previous step

The following is a sample POST request to create a Cloud HSM service that uses an Azure Key Vault backend provider:

https://console.kaleido.io/api/v1/consortia/:consortia_id/environments/:environment_id/services

{
  "name": "cloudhsm-azure",
  "membership_id": "<id>",
  "service": "cloudhsm",
  "details": {
    "cloudhsm_id": "<cloudhsm_configuration_id>"
  }
}

Transaction Signing with Azure Key Vault

Transactions can be sent to the Kaleido CloudHSM service by specifying a from address that corresponds to a SECP256K1 type key that is present in the Azure Key Vault. Any of RPC, WSS or the API Gateway interfaces can be used to send transactions. The URLs for the interfaces can be obtained by querying the service's /status route

A sample GET request to obtain the service status is as below:

https://console.kaleido.io/api/v1/consortia/:consortia_id/environments/:environment_id/services/:service_id/status

When a eth_sendTransaction request is received by the Kaleido CloudHSM service, it uses the from address to determine whether the configured backend cloud HSM contains the keys for the address. The Kaleido CloudHSM service sends a /sign request with the KEY ID of the from address and the transaction payload to Azure Key Vault to sign. If the request succeeds, Key Vault returns the signature, from which the Ethereum signature parameters - R, S and V are extracted, as well as making sure the S value is compatible with Ethereum's malleability protection rule, and included in the transaction before sending it to the Ethereum blockchain node in the Kaleido environment that the service is bound to.