{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/deployment/integrate-kms/on-premise-hsm/blocksafe","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/deployment/integrate-kms/on-premise-hsm/blocksafe","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"BlockSafe HSM integration guide","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"blocksafe-hsm-integration-guide","__idx":0},"children":["BlockSafe HSM integration guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide provides complete instructions for integrating BlockSafe HSM with ","Ripple Custody",". BlockSafe is a blockchain-optimized hardware security module designed specifically for cryptocurrency key management and signing operations."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Before you begin:"]}," This guide assumes you have completed ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/install/helm-chart-installation"},"children":["Installation environment setup"]}," and have BlockSafe HSM hardware deployed and accessible from your Kubernetes cluster."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-ripple-custody-uses-blocksafe-hsm","__idx":2},"children":["How ","Ripple Custody"," uses BlockSafe HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ripple Custody"," uses BlockSafe HSM with a key derivation approach similar to Thales Luna HSM:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Master key creation"]},": The master key is created inside the HSM during the key ceremony when creating HSM slots."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key derivation"]},": vault derives account keys from master seed using BIP32/SLIP10."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Signing operations"]},": All private key operations performed inside HSM."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key protection"]},": Private keys never leave the HSM in plaintext."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key Management Flow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Notary Initialization:\n1. Notary connects to BlockSafe HSM\n2. Master key generated inside HSM\n3. Public key exported for Vault configuration\n\nAccount Creation:\n1. Vault connects to BlockSafe HSM\n2. Vault derives account key from master seed (BIP32/SLIP10)\n3. Public key exported for blockchain operations\n\nSigning Operation:\n1. Transaction data sent to Vault\n2. Vault requests signature from BlockSafe HSM\n3. HSM performs signing operation with derived key\n4. Signature returned to Vault\n5. Signed transaction broadcast to blockchain\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deployment-architecture","__idx":3},"children":["Deployment architecture"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n subgraph k8s[\"Kubernetes Cluster\"]\n direction LR\n notary[\"Notary + KMS Connect\"]\n vault[\"Vault + KMS Connect\"]\n end\n\n subgraph blocksafe[\"BlockSafe HSM\"]\n direction LR\n slot0[\"Slot 0: Notary Keys\"]\n slot1[\"Slot 1: Vault Keys\"]\n end\n\n notary -->|PKCS#11 port 3001| blocksafe\n vault -->|PKCS#11 port 3001| blocksafe\n","diagramHtml":"

PKCS#11 port 3001

PKCS#11 port 3001

BlockSafe HSM

Slot 0: Notary Keys

Slot 1: Vault Keys

Kubernetes Cluster

Notary + KMS Connect

Vault + KMS Connect

","diagramHtmlDark":"

PKCS#11 port 3001

PKCS#11 port 3001

BlockSafe HSM

Slot 0: Notary Keys

Slot 1: Vault Keys

Kubernetes Cluster

Notary + KMS Connect

Vault + KMS Connect

"},"children":["flowchart TB\n subgraph k8s[\"Kubernetes Cluster\"]\n direction LR\n notary[\"Notary + KMS Connect\"]\n vault[\"Vault + KMS Connect\"]\n end\n\n subgraph blocksafe[\"BlockSafe HSM\"]\n direction LR\n slot0[\"Slot 0: Notary Keys\"]\n slot1[\"Slot 1: Vault Keys\"]\n end\n\n notary -->|PKCS#11 port 3001| blocksafe\n vault -->|PKCS#11 port 3001| blocksafe\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":4},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hardware-requirements","__idx":5},"children":["Hardware requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BlockSafe HSM Appliance"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["BlockSafe HSM appliance deployed and powered on"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network connectivity from Kubernetes cluster to HSM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HSM initialized with admin credentials"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["At least 1 slot configured (one slot per application is sufficient)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network requirements"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TCP connectivity to BlockSafe HSM on configured port (typically 3001)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Low latency network connection (< 10ms recommended)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Firewall rules allowing traffic from Kubernetes nodes to HSM"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"software-requirements","__idx":6},"children":["Software requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["From BlockSafe"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["BlockSafe HSM firmware (latest stable version)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PKCS#11 library (provided by BlockSafe)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Admin tools for HSM management"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["From Ripple"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ripple Custody"," Helm charts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to Ripple container registry (provided by Ripple)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"network-requirements","__idx":7},"children":["Network requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connectivity"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TCP access to BlockSafe HSM on configured port (default: 3001)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Bidirectional network connectivity"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No NAT or proxy between Kubernetes and HSM (recommended)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Firewall rules"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Source: Kubernetes cluster CIDR (e.g., 10.0.0.0/16)\nDestination: BlockSafe HSM IP (e.g., 192.168.1.100)\nPort: 3001 (or custom port)\nProtocol: TCP\nDirection: Outbound from Kubernetes\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hsm-initialization","__idx":8},"children":["HSM initialization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section covers the BlockSafe-specific setup required to prepare your HSM for ","Ripple Custody"," integration. Consult your BlockSafe documentation for model-specific instructions."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customer responsibility"]},": Your infrastructure team performs HSM initialization. ","Ripple Custody"," only requires that the HSM be configured with the settings described below before proceeding to ","Ripple Custody"," configuration."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-deploy-and-initialize-blocksafe-hsm","__idx":9},"children":["Step 1: Deploy and initialize BlockSafe HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete the following using BlockSafe documentation:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Physical deployment"]},": Rack-mount, power, and network-connect the BlockSafe HSM appliance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network configuration"]},": Assign a static IP address accessible from your Kubernetes cluster (default port: 3001)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM initialization"]},": Set Security Officer (SO) PIN and create admin user"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set HSM label"]},": Use a descriptive label (e.g., \"RippleCustodyHSM\")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-configure-hsm-slot","__idx":10},"children":["Step 2: Configure HSM slot"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a dedicated PKCS#11 slot for ","Ripple Custody",":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Slot"},"children":["Slot"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Label Example"},"children":["Label Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Slot 0"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ripple Custody"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CustodySlot"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the slot:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the slot with a descriptive label"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set a strong PIN for slot access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One slot per application is the standard design"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document credentials securely"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CRITICAL:"]}," Save slot PINs securely. Loss of slot PINs will prevent access to keys stored in the HSM. BlockSafe cannot recover lost PINs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-enable-required-policies","__idx":11},"children":["Step 3: Enable required policies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enable the following policies for ","Ripple Custody"," operations (policy names may vary by model):"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Policy"},"children":["Policy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BIP32"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key derivation for blockchain accounts"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SLIP10"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Alternative key derivation scheme"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key wrapping"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for backup operations"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consult your BlockSafe documentation for exact policy names and configuration procedures."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-verify-hsm-connectivity","__idx":12},"children":["Step 4: Verify HSM connectivity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before proceeding to ","Ripple Custody"," configuration, verify:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network connectivity"]},": Port 3001 (or configured port) is reachable from Kubernetes nodes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PKCS#11 connectivity"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pkcs11-tool --list-slots"]}," shows your configured slots"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication"]},": Can login to slots with configured PINs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-document-configuration","__idx":13},"children":["Step 5: Document configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Record the following information for ","Ripple Custody"," configuration:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM IP Address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BlockSafe HSM IP"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["192.168.1.100"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM Port"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PKCS#11 port"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3001"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Device String"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["port@hostname"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3001@192.168.1.100"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notary slot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot number for notary"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notary PIN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot 0 PIN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(stored securely)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Vault slot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot number for vault"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Vault PIN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot 1 PIN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(stored securely)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checkpoint:"]}," If you can successfully list slots and authenticate using PKCS#11 tools, your BlockSafe HSM is properly configured and ready for ","Ripple Custody"," integration."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ripple-custody-configuration","__idx":14},"children":["Ripple Custody"," configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that your BlockSafe HSM is initialized, configure ","Ripple Custody"," to use it for the notary and vault components."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-gather-required-information","__idx":15},"children":["Step 1: Gather required information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll need the following information from your BlockSafe HSM setup:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Device"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HSM address in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["port@hostname"]}," format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3001@192.168.1.100"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Slot"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot number for ","Ripple Custody"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PIN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slot PIN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SlotSecurePin123!"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-configure-notary-with-blocksafe-hsm","__idx":16},"children":["Step 2: Configure notary with BlockSafe HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Edit your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," Helm values file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\ncomponents:\n notary:\n enabled: true\n\n # Platform selection\n platform: kms_blocksafe\n\n # BlockSafe HSM configuration\n kms_blocksafe:\n device: \"3001@192.168.1.100\" # Format: port@hostname\n slot: 0\n pin: \"SlotSecurePin123!\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Security best practice:"]}," Do NOT store PINs directly in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},". Use Kubernetes Secrets to inject credentials at runtime."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using Kubernetes Secrets"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Create secret for Notary credentials\nkubectl create secret generic notary-blocksafe-credentials \\\n --namespace custody-core \\\n --from-literal=device='3001@192.168.1.100' \\\n --from-literal=slot='0' \\\n --from-literal=pin='SlotSecurePin123!'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," to reference the secret:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n notary:\n enabled: true\n platform: kms_blocksafe\n kms_blocksafe:\n secretRef: \"notary-blocksafe-credentials\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-configure-vault-with-blocksafe-hsm","__idx":17},"children":["Step 3: Configure vault with BlockSafe HSM"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\nharmonize:\n vaults:\n \"00000000-0000-0000-0000-000000000000\":\n enabled: true\n\n # Platform selection\n platform: kms_blocksafe\n\n # Notary public key (obtained after Notary initialization)\n notary_public_key: \"ed25519:50692dfa472f013e2f87e5d210be40cefe178e33787be4688d5da0afe06ed149\"\n\n # BlockSafe HSM configuration (uses same slot as Notary)\n kms_blocksafe:\n device: \"3001@192.168.1.100\"\n slot: 0 # Same slot as Notary (one slot per application)\n pin: \"SlotSecurePin123!\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using Kubernetes Secrets for vault"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Create secret for Vault credentials (same slot as Notary)\nkubectl create secret generic vault-blocksafe-credentials \\\n --namespace custody-vault \\\n --from-literal=device='3001@192.168.1.100' \\\n --from-literal=slot='0' \\\n --from-literal=pin='SlotSecurePin123!'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"harmonize:\n vaults:\n \"00000000-0000-0000-0000-000000000000\":\n enabled: true\n platform: kms_blocksafe\n notary_public_key: \"ed25519:${NOTARY_PUBLIC_KEY}\"\n kms_blocksafe:\n secretRef: \"vault-blocksafe-credentials\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-complete-configuration-example","__idx":18},"children":["Step 4: Complete configuration example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml - Complete BlockSafe HSM Configuration\n\n# Global settings\nharmonize:\n repository:\n base: \"my-registry.example.com/harmonize\"\n\n urls:\n base: \"custody.example.com\"\n tls: true\n\n# Notary configuration\ncomponents:\n notary:\n enabled: true\n platform: kms_blocksafe\n kms_blocksafe:\n secretRef: \"custody-blocksafe-credentials\"\n # Or inline configuration (not recommended for production):\n # device: \"3001@192.168.1.100\"\n # slot: 0\n # pin: \"${SLOT_PIN}\"\n\n# Vault configuration (uses same slot as Notary)\nharmonize:\n vaults:\n \"00000000-0000-0000-0000-000000000000\":\n enabled: true\n platform: kms_blocksafe\n notary_public_key: \"ed25519:${NOTARY_PUBLIC_KEY}\"\n kms_blocksafe:\n secretRef: \"custody-blocksafe-credentials\"\n # Or inline configuration (not recommended for production):\n # device: \"3001@192.168.1.100\"\n # slot: 0 # Same slot as Notary\n # pin: \"${SLOT_PIN}\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-secret-management","__idx":19},"children":["Advanced secret management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For production deployments, store sensitive credentials (PKCS#11 PIN, slot ID) in an external secrets manager rather than directly in Helm values or Kubernetes secrets."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production best practice"]},": Never store sensitive credentials in plaintext YAML files or Git repositories."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommended approaches for BlockSafe HSM credentials"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Approach"},"children":["Approach"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use Case"},"children":["Use Case"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["External Secrets Operator (ESO)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sync secrets from HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault to Kubernetes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enterprise environments with centralized secret management"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HashiCorp Vault Agent Injector"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inject secrets directly into pods at runtime"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Organizations already using Vault Agent"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AWS Secrets Manager"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store and rotate secrets in AWS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["AWS-native deployments"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete setup instructions, see the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/integrate-kms/advanced-secret-management"},"children":["Advanced secret management guide"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using external secret management, reference the secret in your Helm values:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n notary:\n platform: kms_blocksafe\n kms_blocksafe:\n existingSecret: \"notary-blocksafe-credentials\" # ESO-managed secret\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-and-testing","__idx":20},"children":["Verification and testing"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-deploy-notary-component","__idx":21},"children":["Step 1: Deploy notary component"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Deploy notary first\nhelm upgrade --install harmonize ./harmonize-custody \\\n --namespace custody-core \\\n --create-namespace \\\n -f production.yaml \\\n --set components.vault.enabled=false\n\n# Wait for Notary to be ready\nkubectl wait --for=condition=ready pod \\\n -l app=notary \\\n -n custody-core \\\n --timeout=300s\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-verify-blocksafe-hsm-connectivity","__idx":22},"children":["Step 2: Verify BlockSafe HSM connectivity"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Check KMS Connect logs\nkubectl logs -n custody-core deployment/harmonize-notary -c kms-connect --tail=100\n\n# Expected log entries:\n# - \"Connected to BlockSafe HSM\"\n# - \"PKCS#11 session established\"\n# - \"Slot 0 authenticated\"\n\n# Test network connectivity from pod\nkubectl exec -it -n custody-core deployment/harmonize-notary -c kms-connect -- \\\n nc -zv 192.168.1.100 3001\n\n# Expected output:\n# Connection to 192.168.1.100 3001 port [tcp/*] succeeded!\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-initialize-notary-and-retrieve-public-key","__idx":23},"children":["Step 3: Initialize notary and retrieve public key"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Initialize Notary via Genesis API\ncurl -X POST https://api.custody.example.com/v1/genesis \\\n -H \"Content-Type: application/json\" \\\n -d @genesis.json\n\n# Retrieve the notary communication key from system properties\ncurl https://api.custody.example.com/v1/properties \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n | jq '.items[] | select(.data.id == \"NOTARY_COMMUNICATION_KEY\") | .data.value.publicKey.value'\n\n# Example output:\n# \"MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-deploy-vault-component","__idx":24},"children":["Step 4: Deploy vault component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," with notary public key, and deploy vault:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"helm upgrade --install harmonize ./harmonize-custody \\\n --namespace custody-core \\\n -f production.yaml\n\nkubectl wait --for=condition=ready pod \\\n -l app=vault \\\n -n custody-vault \\\n --timeout=300s\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-create-test-account","__idx":25},"children":["Step 5: Create test account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All state mutation custody operations, including account creation, go through the signed intent flow. Verifying that the BlockSafe HSM can derive keys means submitting a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreateAccount"]}," intent that targets the vault you just deployed. For the complete intent lifecycle (propose, sign, submit, poll), see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/intents/manage-intents-and-approvals#intent-workflow"},"children":["Intent lifecycle"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The minimal request body for the create-account intent looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"request\": {\n \"author\": { \"id\": \"\", \"domainId\": \"\" },\n \"expiryAt\": \"2027-12-31T23:59:59Z\",\n \"targetDomainId\": \"\",\n \"id\": \"\",\n \"customProperties\": {},\n \"description\": \"BlockSafe HSM verification — test account\",\n \"type\": \"Propose\",\n \"payload\": {\n \"type\": \"v0_CreateAccount\",\n \"id\": \"\",\n \"alias\": \"blocksafe-test\",\n \"description\": \"Account to verify BlockSafe HSM key derivation\",\n \"customProperties\": {},\n \"providerDetails\": {\n \"type\": \"Vault\",\n \"vaultId\": \"\",\n \"keyStrategy\": \"VaultHard\"\n },\n \"ledgerIds\": [\"xrpl-testnet\"],\n \"lock\": \"Unlocked\"\n }\n },\n \"signature\": \"\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Submit it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.custody.example.com/v1/intents \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -d @intent_body.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]},". Poll ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/reference/api/openapi/requests/getrequeststate"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/requests/{requestId}"]}]}," until the status reaches a terminal state. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Executed"]}," confirms:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The vault component can communicate with the BlockSafe HSM via PKCS#11."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Key derivation (BIP32/SLIP10) succeeded for the requested ledger."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Account keys were generated and persisted."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-6-test-signing-operation","__idx":26},"children":["Step 6: Test signing operation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Submit a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreateTransactionOrder"]}," intent against the account from Step 5 to exercise the full HSM signing path (the HSM signs the blockchain transaction bytes, not just the intent envelope). See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/reference/api/openapi/intents/createintent"},"children":["Create transaction order"]}," reference and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/intents/manage-intents-and-approvals#intent-workflow"},"children":["intent lifecycle"]}," walkthrough for the full payload shape."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/reference/api/openapi/intents/intentdryrun"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/intents/dry-run"]}]}," first to validate without committing state. If the dry-run returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: true"]},", submit the same payload to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/intents"]}," and poll the resulting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}," until terminal. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Executed"]}," confirms:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The vault performs blockchain-level signing via the BlockSafe HSM."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The PKCS#11 signing interface produces signatures the target ledger accepts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The end-to-end transaction flow — propose, sign, broadcast, finalize — is functional."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":27},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error Message"},"children":["Error Message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_DEVICE_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HSM not accessible"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check network connectivity and device string format (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["port@hostname"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_PIN_INCORRECT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wrong PIN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify PIN in Kubernetes secret matches slot PIN"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_SLOT_ID_INVALID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid slot number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify slot exists and is initialized"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_SESSION_HANDLE_INVALID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Restart KMS Connect pod"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_FUNCTION_NOT_SUPPORTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsupported operation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check firmware version and policies"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Connection refused"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HSM port not accessible"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check firewall rules and HSM status (default port: 3001)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed troubleshooting, consult your BlockSafe HSM documentation or contact BlockSafe support."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"production-best-practices","__idx":28},"children":["Production best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For production-ready BlockSafe HSM deployments, implement the following patterns. See the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/integrate-kms/production-best-practices"},"children":["Production best practices"]}," guide"]}," for detailed instructions that apply to all KMS platforms."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"blocksafe-hsm-specific-considerations","__idx":29},"children":["BlockSafe HSM-specific considerations"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Practice"},"children":["Practice"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"BlockSafe HSM Implementation"},"children":["BlockSafe HSM Implementation"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["High availability (HA)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure BlockSafe HSM in cluster mode with multiple appliances across racks/locations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Namespace segmentation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Separate PKCS#11 slots per namespace/vault for isolation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitoring"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pkcs11-tool"]}," commands (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--show-info"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--list-slots"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--list-objects"]},") plus Prometheus metrics."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Backup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Export PKCS#11 objects from slots, store backups securely, and test quarterly."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BlockSafe HSM Clustering"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deploy multiple HSM appliances for redundancy"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure automatic failover between HSM nodes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use multiple HSM endpoints in Helm values for failover"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":30},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After successfully integrating BlockSafe HSM with ","Ripple Custody",":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Complete installation"]},": Continue with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/install/first-time-installation"},"children":["Installation and initialization"]}," to deploy remaining components"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configure blockchain indexers"]},": Set up blockchain node connections as described in [Blockchain node connectivity planning(../../deployment/planning/blockchain-nodes.md)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Backup procedures"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document HSM backup procedures."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test key-recovery process."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store backup HSM in secure location."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implement regular backup schedule."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production hardening"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable HSM audit logging."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure HSM monitoring and alerting."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implement PIN-rotation policy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review and harden network access controls."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["High availability (HA)"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deploy backup BlockSafe HSM."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure HSM failover."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test failover procedures."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document recovery runbooks."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Security audit"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review HSM access controls."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Audit slot PINs and credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify network segmentation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test disaster recovery (DR) procedures."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Review ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/integrate-kms/production-best-practices"},"children":["Production best practices"]}]}," for namespace segmentation, HA patterns, and monitoring."]}]}]}]},"headings":[{"value":"BlockSafe HSM integration guide","id":"blocksafe-hsm-integration-guide","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"How Ripple Custody uses BlockSafe HSM","id":"how-ripple-custody-uses-blocksafe-hsm","depth":3},{"value":"Deployment architecture","id":"deployment-architecture","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Hardware requirements","id":"hardware-requirements","depth":3},{"value":"Software requirements","id":"software-requirements","depth":3},{"value":"Network requirements","id":"network-requirements","depth":3},{"value":"HSM initialization","id":"hsm-initialization","depth":2},{"value":"Step 1: Deploy and initialize BlockSafe HSM","id":"step-1-deploy-and-initialize-blocksafe-hsm","depth":3},{"value":"Step 2: Configure HSM slot","id":"step-2-configure-hsm-slot","depth":3},{"value":"Step 3: Enable required policies","id":"step-3-enable-required-policies","depth":3},{"value":"Step 4: Verify HSM connectivity","id":"step-4-verify-hsm-connectivity","depth":3},{"value":"Step 5: Document configuration","id":"step-5-document-configuration","depth":3},{"value":"Ripple Custody configuration","id":"ripple-custody-configuration","depth":2},{"value":"Step 1: Gather required information","id":"step-1-gather-required-information","depth":3},{"value":"Step 2: Configure notary with BlockSafe HSM","id":"step-2-configure-notary-with-blocksafe-hsm","depth":3},{"value":"Step 3: Configure vault with BlockSafe HSM","id":"step-3-configure-vault-with-blocksafe-hsm","depth":3},{"value":"Step 4: Complete configuration example","id":"step-4-complete-configuration-example","depth":3},{"value":"Advanced secret management","id":"advanced-secret-management","depth":2},{"value":"Verification and testing","id":"verification-and-testing","depth":2},{"value":"Step 1: Deploy notary component","id":"step-1-deploy-notary-component","depth":3},{"value":"Step 2: Verify BlockSafe HSM connectivity","id":"step-2-verify-blocksafe-hsm-connectivity","depth":3},{"value":"Step 3: Initialize notary and retrieve public key","id":"step-3-initialize-notary-and-retrieve-public-key","depth":3},{"value":"Step 4: Deploy vault component","id":"step-4-deploy-vault-component","depth":3},{"value":"Step 5: Create test account","id":"step-5-create-test-account","depth":3},{"value":"Step 6: Test signing operation","id":"step-6-test-signing-operation","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Production best practices","id":"production-best-practices","depth":2},{"value":"BlockSafe HSM-specific considerations","id":"blocksafe-hsm-specific-considerations","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"BlockSafe HSM integration guide"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/deployment/integrate-kms/on-premise-hsm/blocksafe","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}