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.

Setting Up Authentication Method

Once you have the Hashicorp Server up and running and enabled the transit secrets engine mentioned above, we need to either enable AppRole Authentication or User/Pass Authentication to use Hashicorp Vault with the walt.id issuer API.

Setup Policy

Before enabling and configuring authentication methods, a policy must be created to define the permissions and actions that authenticated users or roles are allowed to perform.

Create The Policy File

echo 'path "transit/*" {
  capabilities = ["create", "update", "read", "delete", "list"]
}' > transit-policy.hcl

Check the Client Configuration

If you are configuring vault locally make sure that the client is configured to communicate via HTTP. This can be achieved by setting the VAULT_ADDR environment variable.

export VAULT_ADDR=https://127.0.0.1:8200

Upload the Policy

vault policy write transit-policy transit-policy.hcl
# Expected result:
# Success! Uploaded policy: transit-policy

Setup Auth Method

AppRole Auth
User/Pass Auth

To enable AppRole auth you have two options, the Web UI of Hashicorp Vault or the CLI:

Web UI
CLI
  1. Navigate to Access.
  2. Choose Authentication Methods.
  3. Click on Enable new method.
  4. Select Generic / AppRole.
  5. Click Enable method.

Please note: You might want to disable lockout: select the created approle method, press "Configure", scroll to "User lockout configuration" and select "Disable lockout for this mount".

Configure AppRole

Add a Role

vault write auth/approle/role/my-role token_type=batch
# Additional parameters can include:
# secret_id_ttl, token_num_uses, token_ttl, token_max_ttl, secret_id_num_uses

Show Role ID

vault read auth/approle/role/my-role/role-id
# Save the value of role_id for later use.

Issue a Secret ID

vault write -f auth/approle/role/my-role/secret-id
# Save the value of secret_id for later use.

Associate Policy with AppRole

vault write auth/approle/role/my-role token_policies="transit-policy"
# Expected result:
# Success! Data written to: auth/approle/role/my-role

If you already have a token policy with the AppRole:

vault write auth/approle/role/my-role token_policies="existing-policy,transit-policy"

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",
    "auth": {
      "roleId": "b50427bd-5070-0bec-3a00-dfe470ba349d",
      "secretId": "22ffc0f4-c308-e6d6-f5a4-246cd89bc17c"
    }
  },
  "keyType": "Ed25519"
}'

Body

{
  "backend": "tse",
  "config": {
    "server": "https://2ab1-2001-871-25f-3c00-f8ac-11f4-dce2-9f1a.ngrok-free.app/v1/transit",
    "auth": {
      "roleId": "b50427bd-5070-0bec-3a00-dfe470ba349d",
      "secretId": "22ffc0f4-c308-e6d6-f5a4-246cd89bc17c"
    }
  },
  "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.
    • auth:
    • AppRole Auth:
      • roleId: String - The Role ID for AppRole authentication.
      • secretId: String - The Secret ID for AppRole authentication.
    • User/Pass Auth:
      • username: String - The username for user/pass authentication.
      • password: String - The password for user/pass authentication.
    • AccessToken Auth (Deprecated):
      • accessKey: String - The access token for token-based authentication.
  • 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