{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":true,"active":true,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/deployment/integrate-kms/on-premise-hsm/securosys-primus","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Securosys Primus 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":"securosys-primus-hsm-integration-guide","__idx":0},"children":["Securosys Primus HSM integration guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide provides complete instructions for integrating Securosys Primus HSM with ","Ripple Custody",". The Securosys Primus HSM is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["FIPS 140-2 Level 3"]}," certified hardware security module that generates, manages, and protects cryptographic keys. Securosys is currently pursuing ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["FIPS 140-3 Level 3"]}," certification."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Securosys and Ripple have a partnership that allows customers to access either Securosys Primus HSMs or CloudHSMs under the Ripple contract. Interested customers should contact their customer partner success director for more information."]}]},{"$$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-hardware","__idx":2},"children":["Supported hardware"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ","Ripple Custody"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primus"]}," KMS provider connects through the Securosys PKCS#11 library (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["libprimusP11.so"]},") and relies on Securosys vendor extensions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["C_DeriveKeyPair"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["C_LoadPersistentExternalObject"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["C_GetPersistentExternalObjectData"]},") with per-curve wrapped master key blobs."]},{"$$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":["Primus HSM X-Series and E-Series, and the Securosys CloudHSM service. All share one firmware line that exposes the required extensions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certification"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FIPS 140-2 Level 3, Common Criteria EAL4+."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-ripple-custody-uses-securosys-primus-hsm","__idx":3},"children":["How ","Ripple Custody"," uses Securosys Primus HSM"]},{"$$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 creates three master keys, one for each elliptic curve."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The HSM encrypts the private key using its master key via PKCS#11."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ripple Custody"," stores the encrypted private key (PKCS#11 blob) in its database."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["During signing operations, the HSM performs all private key operations internally."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unencrypted (plaintext) private keys never leave the HSM."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deployment-architecture","__idx":4},"children":["Deployment architecture"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n subgraph compute[\"Compute\"]\n direction LR\n notary[\"Notary + KMS Connect\"]\n vault[\"Vault + KMS Connect\"]\n end\n\n subgraph hsm[\"Securosys Primus HSM HA Group\"]\n direction LR\n p1[\"Partition #1\"]\n p2[\"Partition #2\"]\n p1 <--> p2\n end\n\n notary -->|mTLS port 2410| hsm\n vault -->|mTLS port 2410| hsm\n","diagramHtml":"

mTLS port 2410

mTLS port 2410

Securosys Primus HSM HA Group

Partition #1

Partition #2

Compute

Notary + KMS Connect

Vault + KMS Connect

","diagramHtmlDark":"

mTLS port 2410

mTLS port 2410

Securosys Primus HSM HA Group

Partition #1

Partition #2

Compute

Notary + KMS Connect

Vault + KMS Connect

"},"children":["flowchart TB\n subgraph compute[\"Compute\"]\n direction LR\n notary[\"Notary + KMS Connect\"]\n vault[\"Vault + KMS Connect\"]\n end\n\n subgraph hsm[\"Securosys Primus HSM HA Group\"]\n direction LR\n p1[\"Partition #1\"]\n p2[\"Partition #2\"]\n p1 <--> p2\n end\n\n notary -->|mTLS port 2410| hsm\n vault -->|mTLS port 2410| hsm\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":5},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hardware-and-software-requirements","__idx":6},"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 Securosys HSMs"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Securosys Primus HSM appliance deployed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HSM initialized with admin credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network connectivity on port ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2410"]}," (typical)."]}]},{"$$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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Securosys Primus PKCS#11 API Provider client software downloaded and installed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network access from the chosen compute infrastructure to the HSM."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Firewall rules allowing bidirectional traffic from Kubernetes nodes to HSM."]}]},{"$$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.30+)"]},{"$$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":"key-derivation-scheme","__idx":7},"children":["Key derivation scheme"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The vault automatically detects the HSM capabilities at startup and selects the appropriate derivation scheme. For Securosys Primus HSM, use only SLIP10."]},{"$$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"]}]},{"$$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":["v2.11.0+"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"documentation-references-securosys","__idx":8},"children":["Documentation references (Securosys)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/primus_hsm_settings"},"children":["Primus HSM Configuration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/pkcs11_provider_installation"},"children":["PKCS#11 API Provider Installation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/pkcs11_provider_configuration/"},"children":["PKCS#11 API Provider Configuration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/permanent_secret_management/"},"children":["Permanent Secret Fetching"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/cloudhsm/Architecture/cluster_synchronization/"},"children":["Cluster Synchronization"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/cloudhsm/Architecture/backups/"},"children":["Backups"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hsm-initialization","__idx":9},"children":["HSM initialization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section covers the vendor-specific setup required to prepare your Securosys Primus HSM for use with ","Ripple Custody",". Detailed step-by-step commands are available in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/primus_hsm_settings"},"children":["Securosys Primus HSM 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. You must configure the HSM with the settings described below before proceeding to ","Ripple Custody"," configuration."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-deploy-and-initialize-securosys-primus-hsm-appliance","__idx":10},"children":["Step 1: Deploy and initialize Securosys Primus HSM appliance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete the following using Securosys Primus 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 Securosys Primus HSM appliance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initial setup"]},": Complete the Initial Wizard as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://support.securosys.com/external/knowledge-base/article/63"},"children":["Chapter 3 of the Primus HSM User Guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Firmware verification"]},": For the most robust support (including SLIP10), and compliance (including FIPS/CC considerations), firmware ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2.11+"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3.1+"]}," (for X2/E2-series hardware) is recommended."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-configure-the-hsm","__idx":11},"children":["Step 2: Configure the HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the steps in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/primus_hsm_settings"},"children":["Primus HSM Configuration"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Primus PKCS#11 API Provider has two main configuration files:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["/etc/primus/primus.cfg"]}," contains public settings, such as connectivity details (hostname, port) and partition names."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["/etc/primus/.secrets.cfg"]}," contains secret values, such as the permanent secret used to authenticate to the HSM."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a template ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["primus.cfg"]}," configuration file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"cpp","header":{"controls":{"copy":{}}},"source":"#-----------------------------\n# Primus PKCS#11 configuration\n#-----------------------------\nversion = \"1.0\";\n/* This example configuration template contains 1 slot: */\n/* hsm0: standalone hsm with one partition (slot id 0) */\n/*--- GLOBAL CONFIGURATION SECTION ----------------------------------------*/\nprimus:\n{\n wait_delay = 250; /* in ms*/\n wait_max_tries = 5;\n connect_on_init = true;\n /*--- HSM CONFIGURATION SECTION -----------------------------------------*/\n hsms:\n {\n /*--- HSM0, e.g. standalone hsm with one partition, slot id 0 */\n hsm0:\n {\n host = \"grimsel.securosys.ch\";\n port = \"2410\";\n priority = 0; /* Optional priority. Default 0, which is highest priority */\n slots:\n {\n slot0:\n {\n client_id = \"Client_ID0\"; /* Client-supplied, determined by us */\n user_name = \"PRIMUSDEV390\"; /* partition/slot name */\n id = 0;\n }; /* end slot0 */\n }; /* end slots */\n }; /* end hsm0 */\n }; /* end hsms */\n /*--- LOG CONFIGURATION SECTION -----------------------------------------*/\n log:\n {\n/* file = \"/tmp/primus.log\"; /* optional for unix, logs to LOCAL1 syslog */\n/* file = \"%PUBLIC%\\Securosys\\Primus P11\\primus.log\"; /* for windows */\n write_log_file = true; /* write to log-file */\n write_syslog = true; /* write to syslog */\n trace_linenumber = false; /* true or false */\n trace_timestamp = true; /* true or false */\n trace_function = true; /* true or false */\n trace_inout = false; /* true or false */\n trace_pid = true; /* true or false */\n trace_filename = false; /* true or false */\n trace_mask = 0x00;\n trace_level = 4; /* 0-7 log level details */\n }; /* end log */\n}; /* end primus */\n","lang":"cpp"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a template ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":[".secrets.cfg"]}," configuration file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"cpp","header":{"controls":{"copy":{}}},"source":"version = \"1.0\";\nprimus :\n{\n users :\n {\n user0 :\n {\n name = \"PRIMUSDEV390\"; /* partition name */\n secret = \"\";\n };\n };\n};\n","lang":"cpp"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-fetch-permanent-secret","__idx":12},"children":["Step 3: Fetch permanent secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To authenticate to Securosys Primus HSMs, you must generate a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["permanent secret"]}," in addition to the PIN. Use the Securosys-provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ppin"]}," tool with a temporary setup secret:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"$ ppin -a -e HSM_USERNAME \n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that this requires write access to ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["/etc/primus/.secrets.cfg"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Installation/permanent_secret_management/"},"children":["Permanent Secret Fetching"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-configure-high-availability-ha-groups","__idx":13},"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":"p","attributes":{},"children":["You can run Securosys Primus HSMs in a partition-synced cluster for HA. This configuration makes the partition keys available on each instance and allows you to clone them for backup."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/primus-hsm/Concepts/ha_cloning"},"children":["Primus HSM - High Availability Cloning"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-configure-network-access-and-mtls","__idx":14},"children":["Step 5: Configure network access and mTLS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Network ACL"]},": Add the IP range for your PKCS#11 client(s) to the HSM's network ACL, using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network add"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-6-verify-hsm-connectivity","__idx":15},"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 2410 is reachable from PKCS#11 client application"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PKCS#11 connectivity"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ppin --test"]}," tests connectivity to your defined HSMs and partitions (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Tutorials/ppin_tool#connection-test"},"children":["Connection Test"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication"]},": Can login to partitions with configured PIN and permanent secret fetched in Step 3."]},{"$$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":["ppin --test"]}," shows your HSMs, and you can successfully login to partitions, your Securosys Primus 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":16},"children":["Ripple Custody"," configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that your Securosys Primus 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-the-configuration-information","__idx":17},"children":["Step 1: Gather the configuration information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have the necessary configuration information:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PIN code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Permanent secret"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM hostname"]}," (one or more)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HSM port"]}," (typically ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2410"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partition name"]}," (only one partition name, as this partition is to be cloned to the other HSMs as part of HA configuration)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-configure-notary-with-securosys-primus-hsm","__idx":18},"children":["Step 2: Configure notary with Securosys Primus HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is an example ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["production.yaml"]}," file for a Kubernetes environment using the simplified configuration Custodian Chart."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need to:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Declare the HSMS list, and their network address and relative priorities."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Declare the partition name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(If you are an existing Kubernetes Secret user), declare before installation."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\nnotary:\n install: true\n bridge:\n endpoint: \"https://foo.bar\"\n kms:\n kind: \"primus\"\n existingSecret: \"primus-secret\"\n primus:\n hsms:\n - host: \"grimsel.securosys.ch\"\n port: 2410\n priority: 0\n haGroup:\n - member: \"PRIMUSDEV390\"\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":"Heading","attributes":{"level":3,"id":"step-3-configure-vault-with-securosys-primus-hsm","__idx":19},"children":["Step 3: Configure vault with Securosys Primus HSM"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure the vault component to use Securosys Primus HSM for key encryption. As with the notary, you need to:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Declare the HSMS list, and their network address and relative priorities."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Declare the partition name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(If you are an existing Kubernetes Secret user), declare before installation."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\nvault:\n install: true\n http:\n endpoint: \"https://foo.bar\"\n kms:\n kind: \"primus\"\n existingSecret: \"primus-secret\"\n primus:\n hsms:\n - host: \"grimsel.securosys.ch\"\n port: 2410\n priority: 0\n haGroup:\n - member: \"PRIMUSDEV390\"\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 primus-secret \\\n --namespace custody-vault \\\n --from-literal=pin='partition-password'\n","lang":"bash"},"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":"p","attributes":{},"children":["After configuring your Helm values, do the following to verify the integration."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify that the application starts successfully with no errors and no crashes during init."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the KMS log messages."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With Securosys Primus HSM, the startup log should look somewhat like the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"log","header":{"controls":{"copy":{}}},"source":"{\"date\":1769688916.132,\"time\":\"2026-01-29 12:15:16.132\",\"app\":\"kms-server[1:1]\",\"level_int\":\"6\",\"function\":\"loadConfig()\",\"message\":\"Log configuration - Tracing: 'Parameters'\"}\n{\"date\":1769688916.403,\"time\":\"2026-01-29 12:15:16.403\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_Initialize()\",\"message\":\"rv: CKR_OK\"}\n{\"date\":1769688916.403,\"time\":\"2026-01-29 12:15:16.403\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_GetSlotList()\",\"message\":\"rv: CKR_OK\"}\n{\"date\":1769688916.403,\"time\":\"2026-01-29 12:15:16.403\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_GetSlotList()\",\"message\":\"rv: CKR_OK\"}\n{\"date\":1769688916.439,\"time\":\"2026-01-29 12:15:16.439\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_GetTokenInfo()\",\"message\":\"rv: CKR_OK\"}\n{\"date\":1769688916.439,\"time\":\"2026-01-29 12:15:16.439\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_OpenSession()\",\"message\":\"rv: CKR_OK\"}\n{\"date\":1769688916.471,\"time\":\"2026-01-29 12:15:16.471\",\"app\":\"kms-server[1:1]\",\"level_int\":\"5\",\"function\":\"C_Login()\",\"message\":\"rv: CKR_OK\"}\n","lang":"log"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":21},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.securosys.com/pkcs/Tutorials/troubleshooting/"},"children":["PKCS#11 Troubleshooting"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"production-best-practices","__idx":22},"children":["Production best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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":"p","attributes":{},"children":["For production-ready Securosys Primus HSM deployments, implement the following patterns."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"securosys-primus-hsm-specific-considerations","__idx":23},"children":["Securosys Primus 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":"Securosys Primus HSM Implementation"},"children":["Securosys Primus 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 Securosys Primus 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":["One partition per application (","Ripple Custody",") per environment (to ensure the partition master keys differ between environments)"]}]},{"$$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":["Securosys Primus 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":24},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After successfully integrating Securosys Primus 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 Securosys Primus 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":["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":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Congratulations!"]}," You have successfully integrated Securosys Primus HSM with ","Ripple Custody",". Your notary and vault components are now protected by FIPS 140-2 Level 3 certified hardware security."]}]}]},"headings":[{"value":"Securosys Primus HSM integration guide","id":"securosys-primus-hsm-integration-guide","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Supported hardware","id":"supported-hardware","depth":3},{"value":"How Ripple Custody uses Securosys Primus HSM","id":"how-ripple-custody-uses-securosys-primus-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":"Key derivation scheme","id":"key-derivation-scheme","depth":3},{"value":"Documentation references (Securosys)","id":"documentation-references-securosys","depth":3},{"value":"HSM initialization","id":"hsm-initialization","depth":2},{"value":"Step 1: Deploy and initialize Securosys Primus HSM appliance","id":"step-1-deploy-and-initialize-securosys-primus-hsm-appliance","depth":3},{"value":"Step 2: Configure the HSM","id":"step-2-configure-the-hsm","depth":3},{"value":"Step 3: Fetch permanent secret","id":"step-3-fetch-permanent-secret","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: Gather the configuration information","id":"step-1-gather-the-configuration-information","depth":3},{"value":"Step 2: Configure notary with Securosys Primus HSM","id":"step-2-configure-notary-with-securosys-primus-hsm","depth":3},{"value":"Step 3: Configure vault with Securosys Primus HSM","id":"step-3-configure-vault-with-securosys-primus-hsm","depth":3},{"value":"Verification and testing","id":"verification-and-testing","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Production best practices","id":"production-best-practices","depth":2},{"value":"Securosys Primus HSM-specific considerations","id":"securosys-primus-hsm-specific-considerations","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Securosys Primus HSM integration guide"}},"lastModified":"2026-08-04T20:25:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/deployment/integrate-kms/on-premise-hsm/securosys-primus","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}