Skip to content

AWS KMS

AWS Key Management Service provides a general purpose secure storage for any sensitive information such as keys, passwords or certificates in Azure Cloud. Similar to an HSM, one can use the AWS KMS to generate/store keys and also perform an array of operations including import/export keys, encrytion/decrytion, signing, verification etc. In this document we will explain in detail about AWS KMS support by Kaleido Cloud HSM signer service and how you can use it to generate an ethereum signing key, and use it to sign and submit transactions.

Create SECP256K1 Keys in AWS KMS

In AWS KMS, Customer Master Key (CMK) is a logical representation of a key. It includes metadata, such as Key ID and the actual Key Material that is used to encrypt/decrypt/sign/verify operations. To use keys for signing Ethereum transactions, you will need to create an Asymmetric CMK with Key Spec ECC_SECG_P256K1 (SECP256K1).

  • Navigate to KMS in AWS Console and click on Customer Managed Keys and Create Key.
  • Select Asymmetric Key Type
  • Select Sign and Verify to create a Keypair for digital signing.
  • Select Key Spec ECC_SECG_P256K1 (represents SECP256K1 key curve)

Ensure that access is provided to the appropriate IAM user whose Access Key ID/Secret will be configured in Kaleido's Cloud HSM Signer service.

Create Kaleido Cloud HSM Signer Service

Creation of Kaleido Cloud HSM signer service in Kaleido is a two step process:

  • Specify the type and access details to AWS KMS 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 Cloud HSM signer service using the configuration created above

Create CloudHSM configuration for AWS KMS

The configuration for AWS KMS 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 aws_kms
-- user_id AWS IAM user Access Key ID
-- user_secret AWS IAM user Secret Access Key
-- target_region AWS Region in which the KMS is configured in AWS

The following is a sample POST request to create an AWS KMS cloudhsm configuration:

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

{
  "type": "cloudhsm",
  "name": "aws-kms",
  "membership_id": "<id>",
  "details": {
    "provider": "aws_kms",
    "user_id": "<clientId>",
    "user_secret": "<clientSecret>",
    "target_region": "<AWS Region>",
  }
}

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 AWS KMS backend provider:

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

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

Transaction Signing with AWS KMS

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 AWS KMS. 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 a hash of the transaction payload to AWS KMS to sign. If the request succeeds, AWS KMS returns a ASN.1 DER encoded 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.