# Secure communication

Executive summary
**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.


Why this matters
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.

Prerequisites
Before reading this page, you should understand:

- [Security model](/products/custody/overview/security-model) - The overall security model and zero-trust principles


## Overview

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 |


Key Takeaway
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.

## Authentication

### JWT authentication

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 |


### Digital signatures for authorization

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:**

1. **Canonicalization**: Request body converted to canonical JSON (spaces removed, properties sorted, null values removed).
2. **Hashing**: Canonical JSON hashed using SHA-256.
3. **Signing**: Hash signed using the user's private key (stored externally—never communicated to the platform).
4. **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.

## Network security

### Mutual TLS (mTLS)

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.

Client integrations
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.

### Your internal PKI

You must provide TLS entities from your internal PKI:

- CA certificate
- Server certificate
- Server certificate key


These secure the four ingress endpoints:

Note
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 |


### Internal platform communication

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 |


### Dependency connections

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 |


### Blockchain connections

| 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 |


## The security lifecycle in practice

A typical governed transaction follows this flow:


```mermaid
sequenceDiagram
    participant User
    participant Auth as Auth Server
    participant API as API Gateway
    participant AMQP as AMQP broker
    participant Bridge as Approval / Notary Bridge
    participant Notary
    participant NotaryKMS as Notary KMS
    participant Vault
    participant VaultKMS as Vault KMS

    User->>Auth: 1. Authenticate (challenge-response)
    Auth-->>User: JWT token

    User->>API: 2. Submit signed Intent (JWT + TLS)
    API-->>User: 3. 202 Accepted with requestId
    API->>AMQP: 4. Queue workflow task
    Bridge->>AMQP: 5. Consume workflow task
    Notary->>Bridge: 6. Poll for signed request and approvals
    Bridge-->>Notary: 7. Return signed request and approvals

    Notary->>Notary: 8. Verify user signature, policy, Merkle state, and ARF
    Notary->>NotaryKMS: 9. Sign trusted-state attestation
    NotaryKMS-->>Notary: 10. Return signature

    Vault->>API: 11. Poll for attested operation
    API-->>Vault: 12. Return operation and notary attestation
    Vault->>Vault: 13. Verify notary attestation and request data
    Vault->>VaultKMS: 14. Request blockchain transaction signature
    VaultKMS-->>Vault: 15. Return signature only
    Vault-->>API: 16. Submit signed transaction
```

| 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 |


## Glossary

| Term | Definition |
|  --- | --- |
| **ARF** | Anti-rewind file. A cryptographically protected file that tracks the current state version to prevent replay attacks. See [Data integrity](/products/custody/overview/security/data-integrity-and-audit-trail#anti-rewind-file-arf). |
| **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. |