#HashiCorp Vault Transit Secrets Engine

When using the HashiCorp Vault integration with the Enterprise Stack Key Management Service, the Enterprise Stack can leverage HashiCorp Vault's Transit Secrets Engine to hook into the "cryptography as a service" or "encryption as a service" features provided by HashiCorp Vault. With that, services like issuer or credential-status can sign credentials whilst keeping the secrets (signing keys) in an external secure environment.

#HashiCorp Vault Setup

If you are new to HashiCorp Vault, make sure to check out 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 Enterprise Stack.

#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

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

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

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

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

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

#KMS Service Setup in the Enterprise Stack

#Setup Key Service

In the following section, we will setup a KMS service inside of a tenant. If you don't have a tenant yet, you can learn how to create one here.

When configuring the KMS service, you can set default access credentials for the Enterprise API to authenticate with HashiCorp Vault. This means that whenever you call the key generation endpoint without specifying any authentication credentials for HashiCorp Vault, the system will automatically use the default credentials you provided during setup.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "kms"
}'

{
  "type": "kms"
}

#Key Creation

Use backend: "tse" to create keys in the HashiCorp Vault Transit Secrets Engine. The Enterprise API accepts walt.id keyType values and maps them to the matching Vault Transit key type before calling Vault.

secp256k1 is not supported by the TSE integration. See the HashiCorp Vault Transit Secrets Engine key types full list for the provider-side names.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/generate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "tse",
  "keyType": "Ed25519",
  "config": {
    "server": "http://127.0.0.1:8200/v1/transit",
    "auth": {
      "roleId": "6823b3c7-60f7-db0b-c663-7359f17c0c30",
      "secretId": "aba4f28b-524c-db63-bae2-67a0e094f46a"
    }
  }
}'

{
  "backend": "tse",
  "keyType": "Ed25519",
  "config": {
    "server": "http://127.0.0.1:8200/v1/transit",
    "auth": {
      "roleId": "6823b3c7-60f7-db0b-c663-7359f17c0c30",
      "secretId": "aba4f28b-524c-db63-bae2-67a0e094f46a"
    }
  }
}