HashiCorp Vault Integration

Use HashiCorp Vault as a key management backend for production-grade security. Keys are encrypted and stored in Vault's transit engine — they never exist in plaintext outside Vault.

Two Modes

Option 1: Managed Vault (CREATE mode)

ChainLaunch deploys Vault as a Docker container and configures it automatically.

Via API

curl -X POST http://localhost:8100/api/v1/key-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vault-managed",
    "type": "VAULT",
    "isDefault": false,
    "vaultConfig": {
      "operation": "CREATE",
      "mode": "docker",
      "network": "bridge",
      "port": 8200,
      "version": "1.20.2"
    }
  }'

ChainLaunch will:

1. Pull the Vault Docker image
2. Start the container on the specified port
3. Initialize and unseal Vault
4. Configure the transit engine
5. Store the root token securely

Via Terraform

resource "chainlaunch_key_provider" "vault" {
  name       = "vault-managed"
  type       = "VAULT"
  is_default = false
 
  vault_config = {
    operation = "CREATE"
    mode      = "docker"
    network   = "bridge"
    port      = 8200
    version   = "1.20.2"   # Required for CREATE mode
  }
}

Verify Status

curl http://localhost:8100/api/v1/key-providers/{providerId}/vault/status | jq

Expected response:

{
  "vault_reachable": true,
  "vault_initialized": true,
  "sealed": false,
  "container_running": true
}

Option 2: Existing Vault (IMPORT mode)

Connect ChainLaunch to your organization's existing Vault cluster.

Prerequisites

Your Vault instance needs:

1. Transit secrets engine enabled:

   vault secrets enable transit

2. KV v2 secrets engine enabled:

   vault secrets enable -version=2 kv

3. A policy with the required permissions:

   # chainlaunch-policy.hcl
   path "transit/*" {
     capabilities = ["create", "read", "update", "list"]
   }
    
   path "kv/data/chainlaunch/*" {
     capabilities = ["create", "read", "update", "delete", "list"]
   }
    
   path "kv/metadata/chainlaunch/*" {
     capabilities = ["read", "delete", "list"]
   }

   Apply it:

   vault policy write chainlaunch chainlaunch-policy.hcl

4. A token with that policy:

   vault token create -policy=chainlaunch -period=768h

Via API

curl -X POST http://localhost:8100/api/v1/key-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vault-production",
    "type": "VAULT",
    "isDefault": true,
    "vaultConfig": {
      "operation": "IMPORT",
      "address": "https://vault.yourcompany.com:8200",
      "token": "hvs.CAESxxxxx",
      "mount": "secret"
    }
  }'

Via Terraform

resource "chainlaunch_key_provider" "vault" {
  name       = "vault-production"
  type       = "VAULT"
  is_default = true
 
  vault_config = {
    operation = "IMPORT"
    address   = "https://vault.yourcompany.com:8200"
    token     = var.vault_token
    mount     = "secret"
  }
}
 
variable "vault_token" {
  type      = string
  sensitive = true
}

Use Vault for an Organization

Once the provider is created, assign it to organizations:

Via CLI

chainlaunch fabric org create \
  --name Org1MSP \
  --msp-id Org1MSP \
  --provider-id 2

Via Terraform

resource "chainlaunch_fabric_organization" "org1" {
  msp_id      = "Org1MSP"
  description = "Production org with Vault keys"
  provider_id = tonumber(chainlaunch_key_provider.vault.id)
}

All keys created for this organization (node identity, TLS, CA) will be stored in Vault.

Supported Key Types

Key Rotation

Vault supports automatic key rotation via its transit engine:

# Rotate a transit key
vault write -f transit/keys/chainlaunch-key-123/rotate
 
# Configure auto-rotation (every 90 days)
vault write transit/keys/chainlaunch-key-123/config auto_rotate_period=2160h

ChainLaunch will automatically use the latest key version for new operations while still being able to decrypt data encrypted with older versions.

High Availability

For production Vault deployments:

• Use Vault's integrated storage (Raft) with 3+ nodes
• Enable auto-unseal with a cloud KMS
• Configure audit devices for compliance
• Use performance replication for multi-region

Troubleshooting

"vault_reachable: false"

• Check the Vault address is accessible from the ChainLaunch server
• Verify firewall rules allow traffic on port 8200
• For managed Vault: check Docker is running and the container is up

"sealed: true"

Vault needs to be unsealed after restart:

vault operator unseal <unseal-key>

For managed Vault (CREATE mode), ChainLaunch handles unsealing automatically.

"permission denied"

The Vault token doesn't have the required policy. Verify:

vault token lookup <token>
vault policy read chainlaunch

Next Steps

• AWS KMS Integration for cloud-native key management
• Key Management for the complete key management overview
• Security Best Practices for production hardening