Ripple Custody protects all communications with multiple cryptographic layers: TLS, JWT authentication, mTLS, and application-layer signing.
- TLS 1.2+ encrypts all network traffic between components.
- JWT tokens authenticate every API request with cryptographic signatures.
- mTLS provides mutual authentication for critical internal platform connections.
- Application signing ensures message integrity for requests, trusted-state attestations, and vault signing work.
Communication security prevents man-in-the-middle attacks, credential theft, and message tampering. Even if an attacker gains network access, the layered security model ensures they cannot intercept sensitive data or forge authorized requests. This is essential for meeting SOC 2, ISO 27001, and other security compliance requirements.
For architects and operators: You are responsible for providing TLS certificates and configuring your PKI. Plan certificate rotation procedures before deployment. Ensure your network infrastructure supports encrypted and mutually authenticated communication for internal protected-component paths.
Before reading this page, you should understand:
- Security model - The overall security model and zero-trust principles
The platform implements defense-in-depth for all communications:
| Layer | Protection | Purpose |
|---|---|---|
| Transport | TLS 1.2+ | Encrypts all network traffic |
| Identity | JWT tokens | Authenticates API requests |
| Mutual authentication | mTLS certificates | Verifies both sides of critical internal component connections |
| Application | Digital signatures | Ensures message integrity and non-repudiation |
These controls work together to prevent man-in-the-middle attacks. Even if an attacker intercepts network traffic, they cannot decrypt it (TLS), impersonate a user (JWT signatures), or impersonate a trusted component (mTLS certificates). Messages between the notary and vault are additionally signed at the application layer, providing defense-in-depth.
A JSON Web Token (JWT) is a compact, digitally signed token that proves a user's identity without requiring the server to look up session data. Think of it as a tamper-proof ID badge: it contains claims about who you are, is signed by a trusted authority, and can be verified by any component that trusts that authority.
All requests to the API backend must authenticate using a JWT passed as a bearer token.
| Aspect | Details |
|---|---|
| Identity provider | The Authentication Server (a dedicated OIDC server) verifies user identity and issues JWTs |
| Token expiration | Default is four hours |
| Obtaining a JWT | Challenge-response: user signs a random challenge with their private key; server validates and returns JWT |
| Challenge reuse | Challenges can only be used once to prevent replay attacks |
Any request (Intent) to change the system state requires a digital signature. This proves the request came from the claimed user and has not been modified.
How it works: The user's application creates a unique "fingerprint" of the request and signs it with their private key. The platform verifies this signature using the user's registered public key. If even one character of the request was changed, the signature becomes invalid.
Technical process:
- Canonicalization: Request body converted to canonical JSON (spaces removed, properties sorted, null values removed).
- Hashing: Canonical JSON hashed using SHA-256.
- Signing: Hash signed using the user's private key (stored externally—never communicated to the platform).
- Encoding: Signature serialized in DER format with Base64 encoding.
The notary verifies this signature against the user's registered public key. This prevents both impersonation and tampering.
Standard TLS (Transport Layer Security) is one-way: the client verifies the server's certificate, but the server doesn't verify the client. Mutual TLS (mTLS) requires both parties to present and verify certificates — each side proves its identity to the other before any data is exchanged.
Ripple Custody uses mTLS for critical internal component connections to ensure that even if an attacker gains network access, they cannot impersonate a trusted component.
mTLS in this section refers to communication between Ripple Custody platform components. External API clients use HTTPS/TLS, bearer-token authentication, and request signatures for state mutation operations. API clients are not expected to present mTLS client certificates unless you add that requirement at your own ingress, API gateway, or proxy layer.
You must provide TLS entities from your internal PKI:
- CA certificate
- Server certificate
- Server certificate key
These secure the four ingress endpoints:
The endpoints below are examples. Replace open-shift-cluster-domain with your actual OpenShift cluster domain.
| Endpoint | Purpose |
|---|---|
api.<cluster-domain> | API Gateway |
frontend.<cluster-domain> | Web UI |
openid.<cluster-domain> | OpenID authentication server |
notary-bridge.<cluster-domain> | notary Bridge |
Communication between core components and protected components such as the notary and vault uses:
| Mechanism | Description |
|---|---|
| Application-layer mutual trust | Components verify the signed data they receive before relying on it. |
| Signed messages | Requests, attestations, and signing work are signed and verified by the receiving component. |
| Key exchange at setup | A key exchange during system setup builds the chain of trust |
Connections to infrastructure services you provide:
| Service | Purpose | Security |
|---|---|---|
| KMS/HSM | Protected notary, vault, and configured system-signing operations | mTLS or HSM-specific secure protocol |
| PostgreSQL | Data storage | TLS; data integrity verified cryptographically by notary |
| AMQP (RabbitMQ) | Async message queue | TLS |
| Container registry | Container image distribution | TLS; image signatures verified |
| Connection | Description |
|---|---|
| Indexer to node | Chain-specific indexers monitor your blockchain nodes (direct or via http_proxy; Bitcoin supports socks5) |
| Transaction broadcast | Ledger Accounting Service broadcasts signed transactions |
A typical governed transaction follows this flow:
| Step | Security Controls |
|---|---|
| 1-4 | TLS encryption, JWT authentication, digital signature, request ID tracking |
| 5-10 | mTLS where configured, signature verification, policy evaluation, Merkle state validation, ARF protection, notary KMS isolation |
| 11-16 | Application-layer verification, notary attestation checks, vault KMS isolation, signed transaction submission |
| Term | Definition |
|---|---|
| ARF | Anti-rewind file. A cryptographically protected file that tracks the current state version to prevent replay attacks. See Data integrity. |
| Bearer token | An authentication token included in HTTP request headers. Anyone "bearing" the token can use it, so it must be transmitted over TLS. |
| Canonical JSON | A standardized JSON format with sorted keys and no whitespace, ensuring the same data always produces the same byte sequence for signing. |
| DER format | Distinguished Encoding Rules. A binary encoding for cryptographic data structures like signatures and certificates. |
| Intent | A signed request to change system state (e.g., transfer funds, update a policy). |
| JWT | JSON Web Token. A compact, signed token containing identity claims, used for stateless authentication. |
| mTLS | Mutual TLS. A TLS connection where both client and server present certificates and verify each other's identity. |
| OIDC | OpenID Connect. An identity layer built on OAuth 2.0 that enables authentication and identity verification. |
| PKI | Public Key Infrastructure. A system of certificates, certificate authorities, and trust relationships used to verify identities. |
| TLS | Transport Layer Security. A cryptographic protocol that encrypts network traffic and verifies server identity. |