BlockSafe HSM integration guide

Notary Initialization:
1. Notary connects to BlockSafe HSM
2. Master key generated inside HSM
3. Public key exported for Vault configuration

Account Creation:
1. Vault connects to BlockSafe HSM
2. Vault derives account key from master seed (BIP32/SLIP10)
3. Public key exported for blockchain operations

Signing Operation:
1. Transaction data sent to Vault
2. Vault requests signature from BlockSafe HSM
3. HSM performs signing operation with derived key
4. Signature returned to Vault
5. Signed transaction broadcast to blockchain

Source: Kubernetes cluster CIDR (e.g., 10.0.0.0/16)
Destination: BlockSafe HSM IP (e.g., 192.168.1.100)
Port: 3001 (or custom port)
Protocol: TCP
Direction: Outbound from Kubernetes

# production.yaml

components:
  notary:
    enabled: true

    # Platform selection
    platform: kms_blocksafe

    # BlockSafe HSM configuration
    kms_blocksafe:
      device: "3001@192.168.1.100"  # Format: port@hostname
      slot: 0
      pin: "SlotSecurePin123!"

# Create secret for Notary credentials
kubectl create secret generic notary-blocksafe-credentials \
  --namespace custody-core \
  --from-literal=device='3001@192.168.1.100' \
  --from-literal=slot='0' \
  --from-literal=pin='SlotSecurePin123!'

components:
  notary:
    enabled: true
    platform: kms_blocksafe
    kms_blocksafe:
      secretRef: "notary-blocksafe-credentials"

# production.yaml

harmonize:
  vaults:
    "00000000-0000-0000-0000-000000000000":
      enabled: true

      # Platform selection
      platform: kms_blocksafe

      # Notary public key (obtained after Notary initialization)
      notary_public_key: "ed25519:50692dfa472f013e2f87e5d210be40cefe178e33787be4688d5da0afe06ed149"

      # BlockSafe HSM configuration (uses same slot as Notary)
      kms_blocksafe:
        device: "3001@192.168.1.100"
        slot: 0  # Same slot as Notary (one slot per application)
        pin: "SlotSecurePin123!"

# Create secret for Vault credentials (same slot as Notary)
kubectl create secret generic vault-blocksafe-credentials \
  --namespace custody-vault \
  --from-literal=device='3001@192.168.1.100' \
  --from-literal=slot='0' \
  --from-literal=pin='SlotSecurePin123!'

harmonize:
  vaults:
    "00000000-0000-0000-0000-000000000000":
      enabled: true
      platform: kms_blocksafe
      notary_public_key: "ed25519:${NOTARY_PUBLIC_KEY}"
      kms_blocksafe:
        secretRef: "vault-blocksafe-credentials"

# production.yaml - Complete BlockSafe HSM Configuration

# Global settings
harmonize:
  repository:
    base: "my-registry.example.com/harmonize"

  urls:
    base: "custody.example.com"
    tls: true

# Notary configuration
components:
  notary:
    enabled: true
    platform: kms_blocksafe
    kms_blocksafe:
      secretRef: "custody-blocksafe-credentials"
      # Or inline configuration (not recommended for production):
      # device: "3001@192.168.1.100"
      # slot: 0
      # pin: "${SLOT_PIN}"

# Vault configuration (uses same slot as Notary)
harmonize:
  vaults:
    "00000000-0000-0000-0000-000000000000":
      enabled: true
      platform: kms_blocksafe
      notary_public_key: "ed25519:${NOTARY_PUBLIC_KEY}"
      kms_blocksafe:
        secretRef: "custody-blocksafe-credentials"
        # Or inline configuration (not recommended for production):
        # device: "3001@192.168.1.100"
        # slot: 0  # Same slot as Notary
        # pin: "${SLOT_PIN}"

components:
  notary:
    platform: kms_blocksafe
    kms_blocksafe:
      existingSecret: "notary-blocksafe-credentials"  # ESO-managed secret

# Deploy notary first
helm upgrade --install harmonize ./harmonize-custody \
  --namespace custody-core \
  --create-namespace \
  -f production.yaml \
  --set components.vault.enabled=false

# Wait for Notary to be ready
kubectl wait --for=condition=ready pod \
  -l app=notary \
  -n custody-core \
  --timeout=300s

# Check KMS Connect logs
kubectl logs -n custody-core deployment/harmonize-notary -c kms-connect --tail=100

# Expected log entries:
# - "Connected to BlockSafe HSM"
# - "PKCS#11 session established"
# - "Slot 0 authenticated"

# Test network connectivity from pod
kubectl exec -it -n custody-core deployment/harmonize-notary -c kms-connect -- \
  nc -zv 192.168.1.100 3001

# Expected output:
# Connection to 192.168.1.100 3001 port [tcp/*] succeeded!

# Initialize Notary via Genesis API
curl -X POST https://api.custody.example.com/v1/genesis \
  -H "Content-Type: application/json" \
  -d @genesis.json

# Retrieve Notary public key
curl https://api.custody.example.com/v1/system/properties | jq '.notary_public_key'

# Example output:
# "ed25519:50692dfa472f013e2f87e5d210be40cefe178e33787be4688d5da0afe06ed149"

helm upgrade --install harmonize ./harmonize-custody \
  --namespace custody-core \
  -f production.yaml

kubectl wait --for=condition=ready pod \
  -l app=vault \
  -n custody-vault \
  --timeout=300s

# Create blockchain account to verify key derivation
curl -X POST https://api.custody.example.com/v1/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "name": "Test Account",
    "ledger": "ethereum",
    "derivation_strategy": "deterministic"
  }'

# Verify account creation succeeded
# This confirms:
# 1. Vault can communicate with BlockSafe HSM
# 2. Key derivation is working (BIP32/SLIP10)
# 3. Account keys are properly generated

# Create a test transaction
curl -X POST https://api.custody.example.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "account_id": "<account-id-from-step-5>",
    "ledger": "ethereum",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "0.001",
    "currency": "ETH"
  }'

# This confirms:
# 1. Vault can perform signing operations via BlockSafe HSM
# 2. PKCS#11 signing interface is working
# 3. End-to-end transaction flow is functional