Skip to main content

Key Management & Seed Security

Overview​

Urblock uses hierarchical deterministic (HD) wallet derivation (BIP-32/44) from a master seed to generate custodial wallets for tenants. Securing this master seed is critical — compromise of the seed means compromise of all derived wallets across all tenants.

Production Architecture​

Required: Hardware Security Module (HSM) / KMS​

In production deployments, the master seed MUST be stored in a Hardware Security Module (HSM) or a cloud Key Management Service (KMS):

ProviderServiceRecommended Tier
AWSCloudHSM / KMSFIPS 140-2 L3
Google CloudCloud HSM / Cloud KMSFIPS 140-2 L3
AzureDedicated HSM / Key VaultFIPS 140-2 L3
HashiCorpVault (Transit secrets engine)Enterprise

Environment Variables​

# Required in production
MASTER_SEED_PROVIDER=aws-kms       # Options: aws-kms, gcp-kms, azure-kms, vault, env
MASTER_SEED_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789:key/...

# Only for development — NEVER use in production
MASTER_SEED=0x...  # ⚠️ Plaintext seed — dev/test only

Migration Path​

If you are currently using MASTER_SEED as a plaintext environment variable:

  1. Generate KMS key in your cloud provider
  2. Encrypt the seed using the KMS key and store the ciphertext
  3. Update configuration to use MASTER_SEED_PROVIDER=aws-kms (or equivalent)
  4. Remove the plaintext MASTER_SEED env var from all environments
  5. Rotate the seed if there's any suspicion of exposure

Per-Tenant Key Isolation​

Each tenant derives wallets from a unique derivation path:

m/44'/60'/0'/{tenant_index}'/{wallet_index}

This ensures that even within a single seed, tenant key material is isolated at the derivation level. However, seed compromise still exposes all paths — hence the HSM/KMS requirement.

Audit Logging​

All seed access operations are logged to the audit trail:

  • Wallet derivation events
  • Key export operations (admin-only)
  • Seed rotation events

Rotation​

Seed rotation is supported but requires a coordinated migration:

  1. Generate a new seed in KMS
  2. Deploy new wallets from the new seed
  3. Transfer assets from old wallets to new wallets
  4. Update derivation index tracking
  5. Decommission old seed (mark as rotated, keep for audit)

Note: Seed rotation is an advanced operation. Contact support for guidance on production rotations.