Data integrity and governance

Trust in the state of the system is critical to integrity and auditing. The platform uses blockchain-inspired mechanisms to ensure data cannot be tampered with:

The platform is architecturally segregated to minimize the attack surface. From a data integrity perspective, only two components are trusted, the notary and the vault:

This architecture means that even if an attacker compromises the database, API gateway, or any other untrusted component, they cannot forge trusted entities or execute unauthorized transactions.

For a complete list of all platform components and their functions, see System architecture.

Entities are the data objects that make up the Ripple Custody environment. As with components, entities can be trusted or untrusted.

Trusted entities are protected by the data integrity model and signed by the notary:

Untrusted entities are used or exposed without a signature. They must be protected with standard database security:

A Merkle tree is a cryptographic data structure invented by Ralph Merkle in 1979 and now widely used in blockchain technology. The key insight is simple but powerful: by organizing data as a tree of hashes, you can detect any tampering instantly — if even a single byte changes anywhere in the data, the entire tree's "fingerprint" (the root hash) changes.

In Ripple Custody, the Merkle tree stores the cryptographic fingerprint of every trusted entity in the system. The notary signs the root hash after each state change. This means:

• Auditors can verify history: Given any historical root hash, you can prove exactly what the system state was at that moment.
• Tampering is impossible to hide: An attacker cannot modify the database without invalidating the signed root.
• Verification is efficient: To verify one entity, you only need to check its path to the root, not the entire database.

This is the same principle that makes blockchains tamper-evident, applied to the custody platform's internal state.

The Merkle tree organizes all trusted entities into a hierarchical structure:

1. Leaf nodes: Each trusted entity (user, account, policy, etc.) is hashed to create a unique fingerprint.
2. Parent nodes: Each parent node contains the combined hash of its children.
3. Root: The single root hash represents the entire system state.

Only the notary can update the Merkle tree. After each state change, it computes the new root and signs it, making any unauthorized modification immediately detectable.

The anti-rewind file (ARF) keeps track of the most up-to-date Ripple Custody state version. This tracking is protected by cryptographic signatures, and is tamper-proof.

The ARF protects against replay attacks & mdash; attempts by an attacker to:

When an intent is submitted, the notary:

1. Compares the database state version against the ARF version
2. Verifies the Merkle tree root signature matches
3. Confirms the intent has not been previously executed

If any check fails, the intent is rejected.

If the ARF is lost, corrupted, or inaccessible, the notary immediately halts all write operations. This is a security feature, not a bug — it prevents the system from operating without its anti-rewind protection.

Recovery requires a formal, audited process involving a designated State Review Authority:

1. Database verification: The State Review Authority uses a secure, offline tool to export and validate all collections from a database backup.
2. Integrity check: The tool computes the Merkle tree root hash and verifies it matches the signed state.
3. Manifest generation: If valid, a signed manifest is generated attesting to the database's integrity.
4. Recovery mode: The notary restarts in recovery mode, processes the signed manifest, and rebuilds the ARF.
5. Normal operation: Once the ARF is rebuilt and verified, normal operations resume.

This process ensures that even in a disaster scenario, the system cannot be tricked into accepting a tampered database.

For detailed recovery procedures, see Recover the anti-rewind file.

Updates to the system state follow this process:

All data payloads retrieved from Ripple Custody that are part of the secure data include a cryptographic signature. You can verify these signatures to confirm the data's authenticity and integrity.

Signature verification ensures:

• The data was genuinely produced by Ripple Custody
• The data has not been modified since it was signed
• You can independently audit the integrity of historical data

1. Retrieve the Ripple Custody public key using the Get system properties API operation. The response includes the platform's public key:

{
    "id": "CUSTODY_API_KEY",
    "value": {
        "publicKey": {
            "value": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1WXjDbBcWEVmqObzEndfnug+nd4EOEqcXMY5a5I0XvfRq1+K6Z9K1DdZ2YgFIbuzdX2Z2kOfE/fcDj/QzF5IAw==",
            "type": "PublicKey"
        }
    }
}

2. Save the public key to a file with PEM headers:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1WXjDbBcWEVmqObzEndfnug+nd4EOEqcXMY5a5I0XvfRq1+K6Z9K1DdZ2YgFIbuzdX2Z2kOfE/fcDj/QzF5IAw==
-----END PUBLIC KEY-----

3. Canonicalize the data object. The signature was computed from canonical JSON, so you must recreate the same format:

cat data.json | jq -j -S -c > sorted_object.json

jq flags explained:

• -S — Sort object keys alphabetically
• -c — Compact output (removes all whitespace)
• -j — No trailing newline (critical for matching the original hash)

For full canonicalization rules including null removal and array handling, see Canonicalization rules.

4. Convert the signature from Base64 to binary:

openssl enc -d -A -base64 -in signature.txt -out signature.bin

5. Verify the signature:

openssl pkeyutl -verify -pubin -inkey CustodyPublicKey.pem -rawin -in sorted_object.json -sigfile signature.bin

If valid, the output is: Signature Verified Successfully