CloudHSM Usage

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

• Create a cloudhsm configuration under the environment that specifies the type of backend and access details to the HSM (this can be referenced by one or more cloud HSM service instances created in the same membership).
• Create a Cloud HSM service using the configuration created above.

Provisioning the Service

Via the API

Create cloudhsm configuration

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_id/configurations

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

Create cloudhsm service

Use the _id from the response to the previous request as cloudhsm_id in the request below. 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"
  }
}

Get cloudhsm service status

The service status can be obtained using a GET on the route below:

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

The response to the /status request includes the RPC and WSS endpoints to the service. These urls provide full Ethereum JSON-RPC support and can be the target of Web3 requests. In particular, when sending eth_sendTransaction requests to the service with a from parameter, as specified by Ethereum JSON-RPC API, the service will behave like a signing wallet and sign the transaction then submit to the target blockchain in the Kaleido environment.

{
  "urls": {
    "http": "https://zztqmsszmp-zzprkw067k-cloudhsm.us0-aws.kaleido.io",
    "rpc-http": "https://zztqmsszmp-zzprkw067k-rpc.us0-aws.kaleido.io",
    "rpc-ws": "wss://zztqmsszmp-zzprkw067k-wss.us0-aws.kaleido.io"
  },
  "status": "live",
  "release": "1.0.26",
  "awsCloudHsm": "live"
}

Refresh account list from the configured backend

Cloud HSM service reloads the list of accounts from the backend HSM during startup. The account list can also be reloaded manually by sending a POST /accounts/refresh request to the service via one of the following API endpoints:

• Kaleido's Service Manager endpoint (using a Kaleido API Key, same credentials used to create the service):

  $ curl -H "Content-Type: application/json" -H "Authorization: Bearer $APIKEY" -d '{}' https://console.kaleido.io/api/v1/cloudhsm/:service_id/accounts/refresh
  

• The http endpoint for the service, as obtained in the service /status API call above, using a pair of application credentials:

https://<appcreds>@<environment_id>-<service_id>-cloudhsm.us0-aws.kaleido.io/api/v1/accounts/refresh

Update a cloudhsm service and/or cloudhsm configuration

Cloudhsm configurations can be updated by sending a PATCH request to a previously created configuration. This operation updates the configuration object.

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

{
  "details": {
    "user_secret": "<new_clientSecret>"
  }
}

In order to update a CloudHSM service to use the updated configuration in the previous step, send a PUT request to the /reset endpoint.

Note: This operation results in a restart of the service and involves a minor downtime.

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

Using the RPC and WebSocket Endpoints

A Dapp or a client may send transactions to a CloudHSM service by using the RPC or WSS url returned by the service status (sample output shown below). The request must include the basic auth application credentials since access to the service endpoints is protected.

{
  "urls": {
    "http": "https://zztqmsszmp-zzprkw067k-cloudhsm.us0-aws.kaleido.io",
    "rpc-http": "https://zztqmsszmp-zzprkw067k-rpc.us0-aws.kaleido.io",
    "rpc-ws": "wss://zztqmsszmp-zzprkw067k-wss.us0-aws.kaleido.io"
  },
  "status": "live",
  "release": "1.0.26",
  "awsCloudHsm": "live"
}

Alternatively, if using the API Gateway on a node to send transactions, use the kld-from parameter to specify an account address that is present in the list of accounts returned by CloudHSM service on invoking a /accounts/refresh API call. The API gateway will then be able to route the request to the CloudHSM service for the transaction to be signed by the backend HSM. The signed transaction is submitted to the chain via the node that is bound to the service.

Provisioning via the UI console

The ability to create the configuration and provision the service via the UI console will be available soon.