Files
skills/public/hanzo-kms.md

6.9 KiB

Hanzo KMS - Key and Secret Management

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-id.md, hanzo/hanzo-platform.md, hanzo/hanzo-vault.md, hanzo/hanzo-k8s.md

Overview

Hanzo KMS is a centralized secret management platform for the Hanzo ecosystem. Fork of Hanzo KMS with Hanzo branding, 9 ported Vault subsystems, Universal Auth, and K8s-native secret sync via KMSSecret CRD. Live at kms.hanzo.ai. Every secret in the Hanzo stack flows through KMS -- no plaintext credentials in manifests, ever.

When to use

  • Storing API keys, database credentials, tokens for any service
  • Syncing secrets to K8s workloads via KMSSecret CRD
  • CI/CD pipeline secret injection
  • Multi-org secret isolation
  • Auditing secret access
  • Generating dynamic secrets (database users, cloud IAM)
  • Encrypting/decrypting data via Transit encryption

Hard requirements

  1. KMS for ALL secrets: Never hardcode in manifests, env files, or git
  2. Universal Auth credentials (client ID + secret) for machine access
  3. Project slug minimum 5 characters (e.g., hanzo-paas not paas)
  4. RBAC enforced on all key and secret operations
  5. Audit logging enabled for all operations

Quick reference

Item Value
UI https://kms.hanzo.ai
API https://kms.hanzo.ai/api/v1
Auth Universal Auth (client ID + secret)
K8s CRD KMSSecret
Go SDK github.com/hanzoai/kms-go-sdk
Node SDK @hanzo/kms-node-sdk
Python SDK hanzo-kms (pip)
Upstream Hanzo KMS
Repo github.com/hanzoai/kms
K8s manifests universe/infra/k8s/kms/
Image ghcr.io/hanzoai/kms:latest
Operator hanzoai/kms-operator
Backend Node.js/Fastify/TypeScript
Frontend React 18/Vite
Database PostgreSQL + Redis

Vault subsystems (9)

  1. Shamir Secret Sharing -- Split master key across N parties (M-of-N reconstruction)
  2. Transit Encryption -- Encrypt/decrypt without exposing keys (envelope encryption)
  3. Leases -- Time-bound secret access with automatic revocation
  4. Seal/Unseal -- Cold-start protection requiring quorum to activate
  5. ACL Policies -- Fine-grained access control per path/operation
  6. Token Management -- Scoped, renewable auth tokens with TTL
  7. Dynamic Secrets -- On-demand credential generation (DB users, cloud IAM)
  8. TFHE Bridge -- Fully homomorphic encryption for compute-on-encrypted-secrets
  9. Per-Org Root Key Isolation -- Each organization has its own root encryption key

CLI quickstart

# Login via Universal Auth
export KMS_TOKEN=$(curl -s -X POST https://kms.hanzo.ai/api/v1/auth/universal-auth/login \
 -H "Content-Type: application/json" \
 -d '{"clientId": "'$KMS_CLIENT_ID'", "clientSecret": "'$KMS_CLIENT_SECRET'"}' \
 | jq -r '.accessToken')

# Fetch secrets
curl -s https://kms.hanzo.ai/api/v1/secrets \
 -H "Authorization: Bearer ${KMS_TOKEN}" \
 -G -d "workspaceId=${PROJECT_ID}&environment=production"

SDK quickstart

Go

import kms "github.com/hanzoai/kms-go-sdk"

client := kms.NewClient(kms.Config{
 SiteURL: "https://kms.hanzo.ai",
 ClientID: os.Getenv("KMS_CLIENT_ID"),
 ClientSecret: os.Getenv("KMS_CLIENT_SECRET"),
})

secret, err := client.GetSecret(kms.GetSecretOptions{
 ProjectID: "hanzo-paas",
 Environment: "production",
 SecretName: "DATABASE_URL",
})

Node.js

import { KMSClient } from "@hanzo/kms-node-sdk"

const client = new KMSClient({
 siteUrl: "https://kms.hanzo.ai",
 clientId: process.env.KMS_CLIENT_ID!,
 clientSecret: process.env.KMS_CLIENT_SECRET!,
})

const secret = await client.getSecret({
 projectId: "hanzo-paas",
 environment: "production",
 secretName: "DATABASE_URL",
})

Python

from hanzo_kms import KMSClient

client = KMSClient(
 site_url="https://kms.hanzo.ai",
 client_id=os.environ["KMS_CLIENT_ID"],
 client_secret=os.environ["KMS_CLIENT_SECRET"],
)

secret = client.get_secret(
 project_id="hanzo-paas",
 environment="production",
 secret_name="DATABASE_URL",
)

K8s secret sync (KMSSecret CRD)

The KMS operator watches KMSSecret resources and auto-syncs to K8s Secrets:

apiVersion: kms.hanzo.ai/v1
kind: KMSSecret
metadata:
 name: my-app-secrets
 namespace: hanzo
spec:
 project: hanzo-paas
 environment: production
 syncInterval: 5m
 secretRef:
 name: my-app-secrets # K8s Secret created/updated
 secrets:
 - DATABASE_URL
 - REDIS_URL
 - HANZO_API_KEY

Deployments reference the synced secret:

spec:
 containers:
 - name: my-app
 envFrom:
 - secretRef:
 name: my-app-secrets

Helm chart: auto-bootstrap

# values.yaml for kms-standalone chart
kms:
 autoBootstrap:
 additionalOrganizations:
 - hanzo
 - lux
 - zoo
 additionalOrganizationAdminEmails:
 - [email protected]
 additionalOrganizationsTokenSecretKey: token

CI/CD integration

# .github/workflows/deploy.yml
jobs:
 deploy:
 steps:
 - name: Login to KMS
 run: |
 export KMS_TOKEN=$(curl -s -X POST $KMS_URL/api/v1/auth/universal-auth/login \
 -d '{"clientId":"${{ secrets.KMS_CLIENT_ID }}","clientSecret":"${{ secrets.KMS_CLIENT_SECRET }}"}' \
 | jq -r '.accessToken')
 echo "KMS_TOKEN=$KMS_TOKEN" >> $GITHUB_ENV

 - name: Fetch deploy secrets
 run: |
 DOCKERHUB_TOKEN=$(curl -s "$KMS_URL/api/v1/secrets/raw/DOCKERHUB_TOKEN?workspaceId=$PROJECT_ID&environment=production" \
 -H "Authorization: Bearer $KMS_TOKEN" | jq -r '.secret.secretValue')

Authentication methods

  • Universal Auth (API key + secret) -- primary for machines
  • Kubernetes Service Account Auth
  • AWS IAM Auth
  • GCP IAM Auth
  • Azure AD Auth
  • OIDC Auth
  • JWT Auth

Environment variables

Variable Required Purpose
ENCRYPTION_KEY Yes 16-byte hex key for platform encryption
AUTH_SECRET Yes JWT signing secret
DB_CONNECTION_URI Yes PostgreSQL connection string
REDIS_URL Yes Redis connection string
SITE_URL Yes Base URL for KMS frontend

Troubleshooting

Issue Cause Solution
Slug error on project creation Slug < 5 chars Use hanzo-paas not paas
Universal Auth login fails Wrong client credentials Regenerate in KMS UI
KMSSecret not syncing Operator not running Check kms-operator pod
Token key mismatch Custom bootstrap template Set additionalOrganizationsTokenSecretKey
HSM connection failed Wrong PKCS#11 path Verify HSM_LIBRARY_PATH and slot number
  • hanzo/hanzo-id.md -- IAM (KMS uses IAM for user auth)
  • hanzo/hanzo-vault.md -- PCI card tokenization
  • hanzo/hanzo-platform.md -- PaaS (uses KMS for secrets)
  • hanzo/hanzo-k8s.md -- K8s infrastructure
  • hanzo/hanzo-deploy.md -- Deployment workflow

Last Updated: 2026-05-12 Category: Hanzo Ecosystem Related: secrets, kms, kms, encryption, security, vault Prerequisites: API key concepts, K8s basics