Hashicorp Vault

Leverage Hashicorp Vault's Transit Secrets Engine to secure keys of wallets manged by the wallet API.

If you are new to Hashicorp Vault make sure to checkout the guides here. The rest of this document assumes you already know how Vault works and have a transit secrets engine setup and running.

Key Creation

Below you find an example call to create a key in Hashicorp Vault and associate it with a wallet managed by the Wallet API.

The only thing that is important to note for the creation, that our system is only compatible with the following Key types offered by the Transit Secrets Engine:

  • ed25519

Transit Secrets Engine key types full list.

CURL

**Endpoint: ** /keys/generate | API Reference

Example Request

curl -X 'POST' \
  'https://wallet.walt.id/wallet-api/wallet/f01f8f55-d098-4c53-b47b-c97552829b39/keys/generate' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "tse",
  "config": {
    "server": "https://2ab1-2001-871-25f-3c00-f8ac-11f4-dce2-9f1a.ngrok-free.app/v1/transit",
    "accessKey": "hvs.0FDU1UfAARMIQHBW9aCAeBRS"
  },
  "keyType": "Ed25519"
}'

Body

{
  "backend": "tse",
  "config": {
    "server": "https://2ab1-2001-871-25f-3c00-f8ac-11f4-dce2-9f1a.ngrok-free.app/v1/transit",
    "accessKey": "hvs.0FDU1UfAARMIQHBW9aCAeBRS"
  },
  "keyType": "Ed25519"
}

Body Parameters

  • backend: String - The location where the key is stored. In our case tse as we want to store it Hashicorp Vault.
  • config
    • server: URL - The endpoint of your Vault instance. Following the structure of https://<yourHost>/v1/<pathOfTransitEngine>, e.g. "https://vault.walt.id/v1/transit". By default the transit engine will live at /transit.
    • accessKey: String - the secret to access the key and perform sign and verify operations.
  • keyType: String - the algorithm used to generate the key. For Vault only ed25519 is possible.

Example Response

The API will respond with the ID of the key. This ID is the internal reference and can be used in operations such as DID create or key delete.

Kki22j4lUwo1gtDfdvdCgOE0hhKcNHgIZSzSxU0CugE
LocalOverview