Key management

Ripple Custody uses asymmetric cryptography throughout to ensure integrity and non-repudiation.

Ripple Custody uses three types of cryptographic keys:

• User keys
• Notary and vault keys
• Blockchain account keys

All users (human or machine) that require access to Ripple Custody are associated with a key pair:

• Read access: Users can query data (accounts, balances, transactions) after authenticating with their key
• Write access: Users can submit intents (transfers, policy changes) by signing them with their private key

Key storage:

• Private key: Stored externally (never communicated to the platform). Used to authenticate requests and sign intents.
• Public key: Stored in the database (DER format, Base64 encoded). Used by the notary to verify signatures.

A valid public key is in DER format with Base64 encoding:

"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEe32vCCfM0LXmT6VuZo4AykiZ8YfBMB92nKNX8K+PRhN7/qPhILzGlOv/7kDyefTxHSrytXG28OB0cPwErlHgyQ=="

User public keys are registered within the trusted state to prevent identity tampering. Registering a user public key is a governed state change, such as a user creation intent or the genesis setup for initial users.

Users are responsible for protecting their own private keys. The Ripple Custody mobile application stores keys in the device secure enclave. For Windows desktop app users, keys are stored in a YubiKey, which provides smart card functionality based on the Personal Identity Verification (PIV) interface. YubiKey 5 FIPS Series devices are required for Windows desktop use. Alternatively, customers can use another KMS approach.

For API signing setup, see Generate a key pair and register a public key.

• notary: Uses its private key to sign the Merkle tree root (securing system state) and to authenticate messages to external components.
• vault: Uses its private key to authenticate payloads to external components.

These keys are generated during deployment and stored in your KMS. A key exchange during setup ensures mutual trust between the notary and vault. For details on how these components communicate securely, see Secure communication.

Blockchain keys sign transactions for accounts. The signature algorithm varies by ledger protocol. During account creation, keys are derived from a master seed using:

• Deterministic derivation (BIP32, SLIP10): Hard derivation requires master seed access; soft derivation does not.
• Random generation: Key material is generated randomly, not derived from the seed.

These strategies store keys in the database, wrapped with the master seed where applicable.

For more information, see Key derivation.

A KMS manages the lifecycle of protected cryptographic keys: generation, storage, usage, rotation, and destruction. Components that need protected signing operations use KMS-backed integrations: the notary signs trusted-state data, the vault derives account keys and signs blockchain transactions, and system-signed intent deployments can use a Gateway-dedicated KMS Connect path for internal proposal signing. Private keys remain inside the configured KMS, HSM, or MPC protection boundary.

For supported KMS platforms and integration guides, see Integrate a key management system.

An HSM is a dedicated, tamper-resistant hardware device. The core principle: private keys never leave the device.

How HSMs protect keys:

1. Physical security: FIPS 140-2 Level 3+ certified. Tamper-resistant enclosure with environmental sensors. Any breach triggers "zeroization" (key erasure).
2. Logical security: Minimal operating system exposes only a cryptographic API. Applications request operations ("sign this") but cannot extract keys.

Signing workflow:

1. vault sends transaction data to HSM with "sign" command.
2. HSM performs signing internally using protected private key.
3. HSM returns only the signature—key never exposed.

MPC is a cryptographic protocol where no single, complete private key ever exists. The key is split into "shards" held by different parties.

How MPC works:

1. Distributed key generation (DKG): Nodes run a protocol where each ends up with a unique shard. No node sees the full key. A corresponding public key is created.
2. Threshold signing (TSS): To sign, a threshold of nodes (e.g., 3-of-4) collaborate:
   • Each participating node creates a partial signature using its shard.
   • Partial signatures combine into one valid signature.
   • The full private key is never reconstructed.

MPC in Ripple Custody:

• Scheme: Ripple's proprietary 3-of-4 threshold signing
• Distribution: Shards across customer-hosted and Ripple-hosted infrastructure
• Security: No unilateral key usage—neither you nor Ripple can move funds alone
• Resilience: Built-in shard recovery; tolerates node failures

For detailed MPC configuration and deployment, see MPC integration guide.

• You have significant existing HSM investment and specialized staff
• Your compliance framework requires FIPS 140-2/3 certified, tamper-proof hardware
• You prioritize lowest possible signing latency
• Your security model is perimeter-based (single, well-defended location)
• You need decades of regulatory acceptance and proven technology

• You prefer cloud-native, flexible deployment (AWS, GCP, Azure)
• You want to avoid managing physical hardware
• Your security model is distributed trust (no single point of failure)
• You need high availability with online shard recovery
• You value algorithm flexibility for new blockchain support

Both HSM and MPC support deterministic key derivation from a single master seed using hierarchical deterministic (HD) wallet standards. This means you only need to back up one seed to recover all accounts.

For comprehensive details on derivation strategies, supported curves, and KMS platform compatibility, see Key derivation.