{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/deployment/integrate-kms/on-premise-hsm/thales-luna","default":true,"active":true,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/deployment/integrate-kms/on-premise-hsm/thales-luna","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/deployment/integrate-kms/on-premise-hsm/thales-luna","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/deployment/integrate-kms/on-premise-hsm/thales-luna","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/deployment/integrate-kms/on-premise-hsm/thales-luna","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/deployment/integrate-kms/on-premise-hsm/thales-luna","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Thales Luna 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":"thales-luna-hsm-integration-guide","__idx":0},"children":["Thales Luna HSM integration guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide provides complete instructions for integrating the Thales Luna 7 HSM with ","Ripple Custody",". It covers both form factors of the Luna 7 A-series — the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Luna Network HSM 7"]}," appliance and the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Luna PCIe HSM 7 (A700)"]}," card. Both are FIPS 140-2 Level 3 certified hardware security modules that provide hardware-based key protection for your notary and vault components."]},{"$$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/deployment/install/helm-chart-installation"},"children":["Installation environment setup"]}," and are ready to configure your HSM for use with ","Ripple Custody","."]}]},{"$$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":"supported-form-factors","__idx":2},"children":["Supported form factors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide covers both form factors of the Thales Luna 7 A-series HSM. Both use an identical PKCS#11 cryptographic interface and Luna 7.x firmware — only the transport layer differs, so the ","Ripple Custody"," integration is the same for both."]},{"$$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":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Luna Network HSM 7"},"children":["Luna Network HSM 7"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Luna PCIe HSM 7 (A700)"},"children":["Luna PCIe HSM 7 (A700)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connection"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NTLS (network transport layer security), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NetClient=1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Local PCI bus (card installed in the host server)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Crypto interface"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PKCS#11"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PKCS#11 (identical)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Firmware"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Luna 7.x"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Luna 7.x (identical)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Form factor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standalone network appliance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PCIe card in host server"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Shared configuration:"]}," Because the cryptographic interface and firmware are identical, the HSM policies, scalable key storage (SKS) setup, key-derivation behavior, and ","Ripple Custody"," configuration described in this guide apply to both form factors. The only differences are the steps that set up the network transport — network ACLs, NTLS/mTLS certificates, and port 1792 — which do not apply to the locally-installed PCIe card (A700)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-hardware-and-minimum-versions","__idx":3},"children":["Supported hardware and minimum versions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ","Ripple Custody"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["luna"]}," KMS provider connects through the Luna client library (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["libCryptoki2.so"]},") and relies on Thales BIP32/SLIP-10 vendor extensions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKK_BIP32"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKM_BIP32_MASTER_DERIVE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_SIMInsert"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_SIMExtract"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_Bip32ExportPublicKey"]},"), so the supported hardware is the Luna 7 generation, which exposes these extensions."]},{"$$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":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detail"},"children":["Detail"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supported models"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Luna Network HSM 7: A700, A750, A790, S700, S750, S790."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Minimum firmware and client"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SLIP-10 derivation (secp256k1, ed25519, P-256) requires HSM firmware 7.8.7 or later and Luna client 10.7.1 or later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FIPS 140-2 and 140-3 Level 3."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-ripple-custody-uses-luna-hsm","__idx":4},"children":["How ","Ripple Custody"," uses Luna HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ripple Custody"," uses Luna HSM in two critical components:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notary"]},": Uses the master signing key in the HSM to authenticate governance operations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Vault"]},": Uses the master encryption key in the HSM to protect account private keys"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key generation flow"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["During account creation, the vault requests key generation from the HSM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The HSM generates the private key internally using its secure random number generator"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The private key is encrypted using the HSM master key via PKCS#11"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The encrypted key (SKS blob) is stored in the ","Ripple Custody"," database"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The HSM master key and plaintext private keys never leave the HSM hardware"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deployment-architecture","__idx":5},"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 hsm[\"Thales Luna HSM HA Group\"]\n direction LR\n p1[\"Partition #1\"]\n p2[\"Partition #2\"]\n p1 <--> p2\n end\n\n notary -->|mTLS port 1792| hsm\n vault -->|mTLS port 1792| hsm\n","diagramHtml":"","diagramHtmlDark":""},"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 hsm[\"Thales Luna HSM HA Group\"]\n direction LR\n p1[\"Partition #1\"]\n p2[\"Partition #2\"]\n p1 <--> p2\n end\n\n notary -->|mTLS port 1792| hsm\n vault -->|mTLS port 1792| hsm\n"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram above shows the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network HSM"]}," topology, where the notary and vault reach the HSM over mTLS on port 1792. For the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PCIe HSM (A700)"]},", the card is installed directly in the host server and accessed over the local PCI bus, so there is no network hop between the ","Ripple Custody"," components and the HSM."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":6},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hardware-and-software-requirements","__idx":7},"children":["Hardware and software requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before starting, ensure you have:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["From Thales Luna HSM"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One of the following Luna 7 A-series HSMs:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Thales Luna Network HSM 7 appliance (physical or virtual), or"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Thales Luna PCIe HSM 7 (A700) card installed in the host server"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Firmware version:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7.7.1 or higher"]}," for BIP32 derivation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7.8.7 or higher"]}," for SLIP10 derivation (recommended)"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Application software 7.8.5-300 (for SLIP10)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network HSM only:"]}," network connectivity on port ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1792"]}," (typical). The PCIe HSM (A700) is accessed locally over the PCI bus and does not use network transport."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Limited Crypto Officer (LCO) role configured on the assigned partition and mapped to the corresponding slot"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Slot number and partition PIN, which ","Ripple Custody"," uses to open a session on the partition"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network HSM only:"]}," NTLS certificate bundle — client certificate, client private key, and HSM server certificate"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["From your infrastructure"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Linux client machine for HSM administration (LunaCM client)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network access from Kubernetes cluster to HSM on port 1792"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Firewall rules allowing bidirectional traffic"]}]},{"$$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 (version 1.16+ for SLIP10)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to the Ripple container registry (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metaco.azurecr.io"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-hsm-policies","__idx":8},"children":["Required HSM policies"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CRITICAL:"]}," The following policies are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["destructive"]}," and will erase existing HSM data when enabled. Enable these policies BEFORE storing any production keys."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM-level policies"]}," (apply to entire HSM):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 6"]},": Allow masking (required for SKS)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 12"]},": Allow non-FIPS algorithms (required for vault operations)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partition-level policies"]}," (apply to each partition):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 22"]},": Allow activation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 23"]},": Allow auto-activation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 41"]},": Partition version"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Policy 43"]},": Allow non-FIPS algorithms"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-derivation-schemes","__idx":9},"children":["Key derivation schemes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The vault automatically detects HSM capabilities at startup and selects the appropriate derivation scheme:"]},{"$$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":"Scheme"},"children":["Scheme"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Supported Curves"},"children":["Supported Curves"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Supported Blockchains"},"children":["Supported Blockchains"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Firmware Required"},"children":["Firmware Required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SLIP10"]}," (preferred)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["secp256k1, Ed25519"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All blockchains (Bitcoin, Ethereum, XRPL, Solana, Algorand, etc.)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["7.8.7+"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BIP32"]}," (fallback)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["secp256k1 only"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin, Ethereum, XRPL, Litecoin, Polygon"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["7.7.1+"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatic selection:"]}," The vault will automatically choose SLIP10 if the HSM firmware supports it (7.8.7+), otherwise it defaults to BIP32. No manual configuration is required."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-storage-strategy","__idx":10},"children":["Key storage strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, ","Ripple Custody"," vaults use hierarchical-deterministic (HD) key derivation (SLIP10). You can optionally configure a vault to use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["random keys"]}," instead, but this is not the recommended default."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Random key backups:"]}," The random key strategy has implications for backups. Unlike HD-derived keys, random keys cannot be regenerated from a single seed, so their backups must be managed manually and periodically reconducted. Use HD derivation (the default) unless you have a specific requirement for random keys."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"documentation-references","__idx":11},"children":["Documentation references"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/Home_Luna.htm"},"children":["Thales Luna Network HSM 7 documentation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/sdk/extensions/BIP32.htm"},"children":["BIP32 mechanism support"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/admin_partition/Preface.htm"},"children":["Partition administration guide"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/admin_partition/ha/ha.htm"},"children":["High-availability groups"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hsm-initialization","__idx":12},"children":["HSM initialization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section covers the vendor-specific setup required to prepare your Luna HSM for use with ","Ripple Custody",". Detailed step-by-step commands are available in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/Home_Luna.htm"},"children":["Thales Luna Network HSM 7 documentation"]},"."]},{"$$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-luna-hsm-appliance","__idx":13},"children":["Step 1: Deploy and initialize Luna HSM appliance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete the following using Thales documentation:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Physical deployment"]},": Rack, power, and network-connect the Luna HSM appliance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initial setup"]},": Complete the setup wizard via serial console or web interface"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network configuration"]},": Assign a static IP address accessible from your Kubernetes cluster"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Firmware verification"]},": Confirm firmware is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7.7.1+"]}," (BIP32) or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7.8.7+"]}," (SLIP10)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-enable-required-hsm-policies","__idx":14},"children":["Step 2: Enable required HSM policies"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WARNING:"]}," Enabling these policies will ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["destroy all existing keys and data"]}," on the HSM. Perform this step on a freshly initialized HSM or after backing up all existing keys."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM-level policies"]}," (required 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":"Policy"},"children":["Policy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required Value"},"children":["Required Value"]},{"$$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":["6"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow masking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for Scalable Key Storage (SKS)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["12"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow non-FIPS algorithms"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for vault operations"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hsm changePolicy"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hsm showPolicies"]}," commands to configure and verify."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-configure-scalable-key-storage-sks-partition","__idx":15},"children":["Step 3: Configure scalable key storage (SKS) partition"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SKS allows you to store unlimited keys while maintaining hardware-level security. The SKS master key (SMK) remains in the HSM, while encrypted key blobs are stored externally in the ","Ripple Custody"," database."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create one partition"]}," for ","Ripple Custody",":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Partitions must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["type V1"]}," for SKS support"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Assign a strong password for the partition"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One partition per application is the standard design (partitions are expensive)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Enable partition-level policies"]}," on the partition:"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required Value"},"children":["Required Value"]},{"$$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":["22"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow activation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for partition access"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["23"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow auto-activation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for automatic login"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["41"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partition version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for SKS"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["43"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow non-FIPS algorithms"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (enabled)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for blockchain operations"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Assign client access"]}," by registering the Kubernetes client with partition access using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client assignPartition"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-configure-high-availability-ha-groups","__idx":16},"children":["Step 4: Configure high availability (HA) groups"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["HA groups provide redundancy by synchronizing keys across multiple HSM partitions. If one HSM fails, the other continues to provide cryptographic services."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n subgraph prod[\"Production HA Cluster\"]\n subgraph apps[\"Client Applications\"]\n direction LR\n notary[\"Notary\"]\n vault1[\"Vault Replica\"]\n vault2[\"Vault Replica\"]\n end\n\n subgraph luna[\"Thales Luna HA Group\"]\n hsm1[\"HSM 1 Partition\"]\n hsm2[\"HSM 2 Partition\"]\n hsm3[\"HSM 3 Partition\"]\n\n hsm1 <-->|\"Replication\"| hsm2\n hsm2 <-->|\"Replication\"| hsm3\n end\n end\n\n notary -->|\"Client Cert\"| luna\n vault1 -->|\"Client Cert\"| luna\n vault2 -->|\"Client Cert\"| luna\n","diagramHtml":"","diagramHtmlDark":""},"children":["flowchart TB\n subgraph prod[\"Production HA Cluster\"]\n subgraph apps[\"Client Applications\"]\n direction LR\n notary[\"Notary\"]\n vault1[\"Vault Replica\"]\n vault2[\"Vault Replica\"]\n end\n\n subgraph luna[\"Thales Luna HA Group\"]\n hsm1[\"HSM 1 Partition\"]\n hsm2[\"HSM 2 Partition\"]\n hsm3[\"HSM 3 Partition\"]\n\n hsm1 <-->|\"Replication\"| hsm2\n hsm2 <-->|\"Replication\"| hsm3\n end\n end\n\n notary -->|\"Client Cert\"| luna\n vault1 -->|\"Client Cert\"| luna\n vault2 -->|\"Client Cert\"| luna\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Requirements"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["At least 2 Luna HSM appliances (one partition per HSM for replication)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Matching partition configurations on each HSM"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lunacm"]}," on your Linux client to create HA groups using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup createGroup"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add additional HSM partitions as members using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup addMember"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify HA configuration is saved to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/etc/Chrystoki.conf"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Chrystoki.conf"]}," settings:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HAOnly = 1"]}," ensures PKCS#11 operations only use HA groups"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VirtualTokenActiveRecovery = activeEnhanced"]}," enables automatic failover"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/admin_partition/ha/ha.htm"},"children":["Thales HA configuration guide"]}," for detailed instructions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-configure-network-access-and-mtls","__idx":17},"children":["Step 5: Configure network access and mTLS"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PCIe HSM (A700):"]}," Skip this step. The card communicates with its host over the local PCI bus, so there is no network ACL, NTLS/mTLS certificate exchange, or port 1792 to configure. Instead, confirm the card is visible as a local slot using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slot list"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lunacm"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network ACL"]},": Add your Kubernetes cluster node IP range to the HSM's network ACL using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network add"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mTLS Certificates"]},": Luna HSM uses mutual TLS (mTLS) for secure communication."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate client certificate"]}," on your Linux client using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vtl createCert"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Register client with HSM"]}," using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client register"]}," and assign partition access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Download HSM server certificate"]}," for client-side verification."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need three files for ","Ripple Custody"," configuration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Client certificate (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.pem"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Client private key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.key"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HSM server certificate (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["server.pem"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-6-verify-hsm-connectivity","__idx":18},"children":["Step 6: 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 1792 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":["vtl verify"]}," shows your HA groups"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication"]},": Can login to partitions with configured PINs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cryptographic operations"]},": Basic operations execute without errors"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checkpoint:"]}," If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vtl verify"]}," shows your HA groups and you can successfully login to partitions, your Luna 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":19},"children":["Ripple Custody"," configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that your Luna HSM is initialized, configure ","Ripple Custody"," to use it for the notary and vault components."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PCIe HSM (A700):"]}," The network transport fields shown in the examples below — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["host"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["port"]},", and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["server"]}," certificate blocks — do not apply, because the card is accessed locally over the PCI bus rather than over NTLS. Configure the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_luna"]}," platform with your partition ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slot"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pin"]},". If you are unsure which fields your deployment requires for the PCIe form factor, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/support/get-support"},"children":["contact Ripple"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-prepare-certificate-files","__idx":20},"children":["Step 1: Prepare certificate files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll need to provide three certificate files in your Helm configuration:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client certificate"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".pem"]},"): Authenticates ","Ripple Custody"," to the HSM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client private key"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Key.pem"]},"): Private key for client certificate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Server certificate"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["server.pem"]},"): HSM's server certificate for verification"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Convert certificates to base64 for Helm values"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Client certificate\n$ cat /usr/safenet/lunaclient/cert/client/.pem | base64 -w 0 > client-cert.b64\n\n# Client private key\n$ cat /usr/safenet/lunaclient/cert/client/Key.pem | base64 -w 0 > client-key.b64\n\n# Server certificate\n$ cat /usr/safenet/lunaclient/cert/server/server.pem | base64 -w 0 > server-cert.b64\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-configure-notary-with-luna-hsm","__idx":21},"children":["Step 2: Configure notary with Luna HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Edit your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," Helm values file to configure the notary component:"]},{"$$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_luna\n\n # Luna HSM configuration\n kms_luna:\n host: \"luna-hsm.example.com\" # Luna HSM hostname or IP\n port: \"1792\" # Luna HSM port (must be string)\n slot: \"0\" # HA group slot number (0 for first HA group)\n pin: \"notary-partition-password\" # Partition password\n\n # Client certificate (for mTLS)\n client:\n certificate: |\n -----BEGIN CERTIFICATE-----\n MIIDXTCCAkWgAwIBAgIJAKZ...\n -----END CERTIFICATE-----\n key: |\n -----BEGIN PRIVATE KEY-----\n MIIEvQIBADANBgkqhkiG9w0...\n -----END PRIVATE KEY-----\n\n # Server certificate (Luna HSM)\n server:\n certificate: |\n -----BEGIN CERTIFICATE-----\n MIIDXTCCAkWgAwIBAgIJAKZ...\n -----END CERTIFICATE-----\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 the partition PIN directly in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},". Use Kubernetes Secrets or an external secrets manager (HashiCorp Vault, Conjur) to inject the PIN at runtime."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using Kubernetes Secrets for PIN"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Create secret for Notary PIN\nkubectl create secret generic notary-luna-pin \\\n --namespace custody-core \\\n --from-literal=pin='notary-partition-password'\n\n# Reference secret in production.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n notary:\n platform: kms_luna\n kms_luna:\n # ... other config ...\n pinSecretRef: notary-luna-pin # Reference to Kubernetes secret\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-configure-vault-with-luna-hsm","__idx":22},"children":["Step 3: Configure vault with Luna HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure the vault component to use Luna HSM for key encryption:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\nharmonize:\n vaults:\n \"00000000-0000-0000-0000-000000000000\": # Default vault UUID\n enabled: true\n\n # Platform selection\n platform: kms_luna\n\n # Notary public key (obtained after Notary initialization - see Step 4)\n notary_public_key: \"ed25519:50692dfa472f013e2f87e5d210be40cefe178e33787be4688d5da0afe06ed149\"\n\n # Luna HSM configuration\n kms_luna:\n host: \"luna-hsm.example.com\"\n port: \"1792\"\n slot: \"0\" # Same partition as Notary (one partition per application)\n pin: \"partition-password\"\n\n client:\n certificate: |\n -----BEGIN CERTIFICATE-----\n MIIDXTCCAkWgAwIBAgIJAKZ...\n -----END CERTIFICATE-----\n key: |\n -----BEGIN PRIVATE KEY-----\n MIIEvQIBADANBgkqhkiG9w0...\n -----END PRIVATE KEY-----\n\n server:\n certificate: |\n -----BEGIN CERTIFICATE-----\n MIIDXTCCAkWgAwIBAgIJAKZ...\n -----END CERTIFICATE-----\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using Kubernetes Secrets for vault PIN"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Create secret for Vault PIN (same partition as Notary)\nkubectl create secret generic vault-luna-pin \\\n --namespace custody-vault \\\n --from-literal=pin='partition-password'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-complete-configuration-example","__idx":23},"children":["Step 4: Complete configuration example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a complete example showing both notary and vault configured with Luna HSM:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml - Complete Luna 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_luna\n kms_luna:\n host: \"luna-hsm.example.com\"\n port: \"1792\"\n slot: \"0\"\n pin: \"${NOTARY_PIN}\" # Injected from secrets manager\n client:\n certificate: |\n -----BEGIN CERTIFICATE-----\n ${LUNA_CLIENT_CERT}\n -----END CERTIFICATE-----\n key: |\n -----BEGIN PRIVATE KEY-----\n ${LUNA_CLIENT_KEY}\n -----END PRIVATE KEY-----\n server:\n certificate: |\n -----BEGIN CERTIFICATE-----\n ${LUNA_SERVER_CERT}\n -----END CERTIFICATE-----\n\n# Vault configuration (uses same partition as Notary)\nharmonize:\n vaults:\n \"00000000-0000-0000-0000-000000000000\":\n enabled: true\n platform: kms_luna\n notary_public_key: \"ed25519:${NOTARY_PUBLIC_KEY}\" # Set after Notary initialization\n kms_luna:\n host: \"luna-hsm.example.com\"\n port: \"1792\"\n slot: \"0\" # Same partition as Notary\n pin: \"${PARTITION_PIN}\"\n client:\n certificate: |\n -----BEGIN CERTIFICATE-----\n ${LUNA_CLIENT_CERT}\n -----END CERTIFICATE-----\n key: |\n -----BEGIN PRIVATE KEY-----\n ${LUNA_CLIENT_KEY}\n -----END PRIVATE KEY-----\n server:\n certificate: |\n -----BEGIN CERTIFICATE-----\n ${LUNA_SERVER_CERT}\n -----END CERTIFICATE-----\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-secret-management","__idx":24},"children":["Advanced secret management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For production deployments, store sensitive credentials (PKCS#11 PIN, certificates) 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 Luna 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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/deployment/integrate-kms/advanced-secret-management"},"children":["Advanced secret management"]}]},"."]},{"$$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_luna\n kms_luna:\n existingSecret: \"notary-luna-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":25},"children":["Verification and testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After configuring your Helm values, follow these steps to deploy and verify the integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-verify-hsm-connectivity-before-deployment","__idx":26},"children":["Step 1: Verify HSM connectivity (before deployment)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before deploying ","Ripple Custody"," components, verify network connectivity to the Luna HSM:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Test network connectivity from a Kubernetes node or test pod\nnc -zv luna-hsm.example.com 1792\n\n# Expected output:\n# Connection to luna-hsm.example.com 1792 port [tcp/*] succeeded!\n\n# Verify PKCS#11 connectivity using vtl (from Luna client machine)\nvtl verify\n\n# Expected output should show your HA groups\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IMPORTANT:"]}," Verify HSM connectivity before deploying components. Troubleshooting connectivity issues after deployment is more difficult."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-deploy-notary-component","__idx":27},"children":["Step 2: Deploy notary component"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Deploy Notary first (Vault needs Notary's public key)\nhelm upgrade --install harmonize ./harmonize-custody \\\n --namespace custody-core \\\n --create-namespace \\\n -f production.yaml \\\n --set components.vault.enabled=false \\\n --set components.indexers.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\n# Check KMS Connect sidecar logs to verify HSM connection\nkubectl logs -n custody-core deployment/harmonize-notary -c kms-connect --tail=100\n\n# Expected output should show:\n# - Successful PKCS#11 connection to Luna HSM\n# - HA group detection\n# - Partition login success\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-initialize-notary-and-retrieve-public-key","__idx":28},"children":["Step 3: Initialize notary and retrieve public key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After notary is deployed and connected to the HSM, initialize it and retrieve the public key. For detailed API instructions, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/deployment/install/first-time-installation"},"children":["Installation and initialization"]}," guide."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Check Notary logs for successful initialization\nkubectl logs -n custody-core deployment/harmonize-notary -c notary-core --tail=50\n\n# Retrieve Notary public key via the System Properties API\n# See: API Reference > System Properties > Get System Properties\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save the notary public key"]}," - you'll need it for the vault configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-deploy-vault-component","__idx":29},"children":["Step 4: Deploy vault component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," with the notary public key and deploy vault:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Deploy Vault\nhelm upgrade --install harmonize ./harmonize-custody \\\n --namespace custody-core \\\n -f production.yaml\n\n# Wait for Vault to be ready\nkubectl wait --for=condition=ready pod \\\n -l app=vault \\\n -n custody-vault \\\n --timeout=300s\n\n# Verify Vault HSM connectivity\nkubectl logs -n custody-vault deployment/harmonize-vault -c kms-connect --tail=100\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-verify-end-to-end-functionality","__idx":30},"children":["Step 5: Verify end-to-end functionality"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a test blockchain account to verify the complete integration:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Register the vault"]}," via the Web UI: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Administration > Vaults > Create a vault"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a test account"]}," via the Web UI: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Accounts > Create account"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify account creation"]}," succeeded with a valid blockchain address"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This confirms:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["vault can communicate with Luna HSM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Key derivation is working (BIP32/SLIP10)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SKS blob encryption/storage is functional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed instructions on account creation, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/accounts/manage-accounts-ui#create-an-account-in-the-ui"},"children":["Create an account"]}," guide."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":31},"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 reachable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check network connectivity and firewall rules for port 1792"]}]},{"$$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 partition password"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify PIN in Kubernetes secret matches HSM partition password"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CKR_TOKEN_NOT_PRESENT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HA group not configured"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure HA group and verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Chrystoki.conf"]}]}]},{"$$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":["Increase session timeout or check HSM load"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SSL handshake failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certificate mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Regenerate certificates and verify mTLS configuration"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BIP32_DERIVE not supported"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Firmware too old"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upgrade to firmware 7.7.1+"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SLIP10_DERIVE not supported"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Firmware too old"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upgrade to firmware 7.8.7+"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed troubleshooting, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://thalesdocs.com/gphsm/luna/7/docs/network/Content/Home_Luna.htm"},"children":["Thales Luna Network HSM 7 documentation"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"production-best-practices","__idx":32},"children":["Production best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For production-ready Luna HSM deployments, implement the following patterns. See ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/deployment/integrate-kms/production-best-practices"},"children":["Production best practices"]}]}," for detailed instructions that apply to all KMS platforms."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"luna-hsm-specific-considerations","__idx":33},"children":["Luna 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":"Luna HSM Implementation"},"children":["Luna 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"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure Luna HA groups with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup createGroup"]}," and add multiple HSM members"]}]},{"$$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 Luna partitions 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":["lunacm"]}," commands (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hsm show"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partition show"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup show"]},") plus Prometheus metrics"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Certificate Rotation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generate new certificates with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vtl createCert"]},", update Kubernetes secrets, perform rolling update"]}]},{"$$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":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partition backup"]}," command, store backups securely, test quarterly"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HA Sync"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Regularly verify HA group synchronization with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup synchronize"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Luna HSM HA group configuration"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hagroup createGroup"]}," to create HA groups for notary and vault partitions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HAOnly = 1"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Chrystoki.conf"]}," to ensure operations only use HA groups"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VirtualTokenActiveRecovery = activeEnhanced"]}," for automatic failover"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":34},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After successfully integrating Luna 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":["Backup HSM keys"]},": Implement backup procedures for SKS master keys."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Back up SMK to a secondary Luna HSM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store backup HSM in secure, off-site location"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document recovery procedures"]}]}]},{"$$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 HSM access controls (role-based access)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Schedule regular HSM firmware updates"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Disaster recovery planning"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document HSM replacement procedures"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test HA failover scenarios"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create runbooks for common HSM issues"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Establish HSM vendor support contacts"]}]}]},{"$$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 policies and partition configurations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Audit certificate expiration dates"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify network ACLs are restrictive"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test backup and recovery 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/deployment/integrate-kms/production-best-practices"},"children":["Production best practices"]}]}," for namespace segmentation, HA patterns, and monitoring"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"aws-nitro-enclave-deployment","__idx":35},"children":["AWS Nitro Enclave deployment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For enhanced security, you can deploy the vault in an AWS Nitro enclave to connect your Luna HSM to ","Ripple Custody","."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These steps require support assistance from Ripple to complete. For more information, contact your Ripple liaison."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites-1","__idx":36},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure a Luna HSM with AWS Nitro enclave to work with ","Ripple Custody",", you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From Ripple:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An AWS enclave Terraform script"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encrypt-cli"]}," tool"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From your ","Ripple Custody"," environment:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The notary messaging public key, retrieved with a call to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/systemproperties/getsystemproperties"},"children":["List system properties"]}," API operation."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deploy-the-vault","__idx":37},"children":["Deploy the vault"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create your enclave contract, in a format similar to the following Podman Play YAML file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Enclave configuration (required)\nkind: Enclave\napiVersion: v1\n#\n# specify if enclaves requires disk storage via NBD\nrequireVarDisk: false\nrequireDataDisk: false\n#\n# base64 encoded disk encryption keys, min=32 byte. If empty keys are auto-generated on every boot!\n# Example: dd if=/dev/random bs=1 count=32 | base64\nencryptionKeyVar: \nencryptionKeyData: \n#\n# auths: login credentials for private container registries (optional)\nauths:\n - registry: metaco.azurecr.io\n username: \n password: \nhostname: enclave-vault-1\n---\n# POD definition (required)\n# Pod configuration map (optional)\nkind: ConfigMap\napiVersion: v1\nmetadata:\n name: config\ndata:\n\n---\nkind: Pod\napiVersion: v1\nmetadata:\n name: vault-pod\nspec:\n volumes:\n - name: config\n configMap:\n name: config\n containers:\n\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For help to define an appropriate pod structure for the current release, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/support/get-support"},"children":["contact Ripple"]},"."]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encrypt-cli"]},", generate the enclave contract token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run the Terraform script with the contract token created in step 2 as an input parameter."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Congratulations!"]}," You have successfully integrated Thales Luna HSM with ","Ripple Custody",". Your notary and vault components are now protected by FIPS 140-2 Level 3 certified hardware security."]}]}]},"headings":[{"value":"Thales Luna HSM integration guide","id":"thales-luna-hsm-integration-guide","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Supported form factors","id":"supported-form-factors","depth":3},{"value":"Supported hardware and minimum versions","id":"supported-hardware-and-minimum-versions","depth":3},{"value":"How Ripple Custody uses Luna HSM","id":"how-ripple-custody-uses-luna-hsm","depth":3},{"value":"Deployment architecture","id":"deployment-architecture","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Hardware and software requirements","id":"hardware-and-software-requirements","depth":3},{"value":"Required HSM policies","id":"required-hsm-policies","depth":3},{"value":"Key derivation schemes","id":"key-derivation-schemes","depth":3},{"value":"Key storage strategy","id":"key-storage-strategy","depth":3},{"value":"Documentation references","id":"documentation-references","depth":3},{"value":"HSM initialization","id":"hsm-initialization","depth":2},{"value":"Step 1: Deploy and initialize Luna HSM appliance","id":"step-1-deploy-and-initialize-luna-hsm-appliance","depth":3},{"value":"Step 2: Enable required HSM policies","id":"step-2-enable-required-hsm-policies","depth":3},{"value":"Step 3: Configure scalable key storage (SKS) partition","id":"step-3-configure-scalable-key-storage-sks-partition","depth":3},{"value":"Step 4: Configure high availability (HA) groups","id":"step-4-configure-high-availability-ha-groups","depth":3},{"value":"Step 5: Configure network access and mTLS","id":"step-5-configure-network-access-and-mtls","depth":3},{"value":"Step 6: Verify HSM connectivity","id":"step-6-verify-hsm-connectivity","depth":3},{"value":"Ripple Custody configuration","id":"ripple-custody-configuration","depth":2},{"value":"Step 1: Prepare certificate files","id":"step-1-prepare-certificate-files","depth":3},{"value":"Step 2: Configure notary with Luna HSM","id":"step-2-configure-notary-with-luna-hsm","depth":3},{"value":"Step 3: Configure vault with Luna HSM","id":"step-3-configure-vault-with-luna-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: Verify HSM connectivity (before deployment)","id":"step-1-verify-hsm-connectivity-before-deployment","depth":3},{"value":"Step 2: Deploy notary component","id":"step-2-deploy-notary-component","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: Verify end-to-end functionality","id":"step-5-verify-end-to-end-functionality","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Production best practices","id":"production-best-practices","depth":2},{"value":"Luna HSM-specific considerations","id":"luna-hsm-specific-considerations","depth":3},{"value":"Next steps","id":"next-steps","depth":2},{"value":"AWS Nitro Enclave deployment","id":"aws-nitro-enclave-deployment","depth":2},{"value":"Prerequisites","id":"prerequisites-1","depth":3},{"value":"Deploy the vault","id":"deploy-the-vault","depth":3}],"frontmatter":{"seo":{"title":"Thales Luna HSM integration guide"}},"lastModified":"2026-08-04T20:25:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/deployment/integrate-kms/on-premise-hsm/thales-luna","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}