Peer Handshake Protocol
Introduction
When two rippled nodes connect over the internet, they can't trust each other initially. How does node A know that the node claiming to be B really controls B's private key? How do they prevent man-in-the-middle attacks? How do they avoid accidentally connecting to themselves?
The peer handshake protocol solves all these problems through careful cryptographic design. This chapter explores how XRPL nodes establish secure, authenticated connections.
The Challenge
What We Need to Prove
Node A Node B
| |
| "I am Node A with public key PK_A" |
| "Prove you have secret key SK_A" |
|────────────────────────────────────────>|
| |
| "I am Node B with public key PK_B" |
| "Prove you have secret key SK_B" |
|<────────────────────────────────────────|
| |
| Both nodes must prove: |
| 1. Identity (I own this key) |
| 2. Liveness (I'm here NOW, not replay)|
| 3. Session binding (THIS connection) |Attack Scenarios to Prevent
1. Man-in-the-Middle (MITM)
Node A ──┐ ┌── Node B
│ │
└─> Evil <┘
Evil intercepts and relays messages
A thinks it's talking to B
B thinks it's talking to A2. Replay Attack
Evil records handshake messages from previous session
Replays them to impersonate Node A3. Self-Connection
Node A tries to connect to itself through network loop
Could cause infinite recursion/waste resources4. Network Mismatch
Mainnet node connects to testnet node
Could cause confusion/invalid transactionsThe Solution: Cryptographic Handshake
High-Level Flow
1. SSL/TLS Connection Established
├─ Provides encryption (confidentiality)
├─ Provides basic authentication
└─ Creates shared session state
2. Extract Shared Value from SSL Session
├─ Unique to THIS specific SSL connection
├─ Both nodes can compute it independently
└─ Cannot be predicted beforehand
3. Sign the Shared Value
├─ Node A signs with SK_A
├─ Node B signs with SK_B
└─ Proves possession of private keys
4. Exchange Signatures in HTTP Headers
├─ Verify each other's signatures
├─ Check network IDs match
└─ Prevent self-connection
5. Connection Authenticated!The Shared Value: Session Binding
Why We Need It
Signatures alone aren't enough:
// ❌ INSECURE: Sign static message
auto sig = sign(pk, sk, "I am Node A");
// Problem: Can be replayed in future connections!We need something unique to THIS specific connection:
// ✅ SECURE: Sign session-specific value
auto sharedValue = deriveFromSSL(session);
auto sig = sign(pk, sk, sharedValue);
// Can only be used for THIS sessionImplementation
// From src/xrpld/overlay/detail/Handshake.cpp
std::optional<uint256>
makeSharedValue(stream_type& ssl, beast::Journal journal)
{
// Get our "Finished" message from SSL handshake
auto const cookie1 = hashLastMessage(
ssl.native_handle(),
SSL_get_finished);
// Get peer's "Finished" message from SSL handshake
auto const cookie2 = hashLastMessage(
ssl.native_handle(),
SSL_get_peer_finished);
if (!cookie1 || !cookie2)
return std::nullopt;
// XOR the two hashes together
auto const result = (*cookie1 ^ *cookie2);
// Ensure they're not identical (would result in zero)
if (result == beast::zero)
{
JLOG(journal.error()) << "Identical finished messages";
return std::nullopt;
}
// Hash the XOR result to get final shared value
return sha512Half(Slice(result.data(), result.size()));
}Hashing the SSL Finished Messages
static std::optional<base_uint<512>>
hashLastMessage(
SSL const* ssl,
size_t (*get)(const SSL*, void*, size_t))
{
// Buffer for SSL finished message
unsigned char buf[1024];
size_t len = get(ssl, buf, sizeof(buf));
if (len < 12) // Minimum valid length
return std::nullopt;
// Hash it with SHA-512
base_uint<512> cookie;
SHA512(buf, len, cookie.data());
return cookie;
}What are "Finished" messages?
In the SSL/TLS handshake, both parties send a "Finished" message that contains:
A hash of all previous handshake messages
A MAC (Message Authentication Code) proving they know the session keys
These messages are:
Unique per session: Different for every SSL connection
Unpredictable: Depend on random values exchanged during handshake
Authenticated: Part of SSL's own security
Properties of the Shared Value
Properties:
1. Session-specific: Different for every connection
2. Unpredictable: Cannot be known before handshake completes
3. Mutual: Both nodes contribute (via XOR)
4. Verifiable: Both nodes can compute independently
5. Binding: Tied to THIS specific SSL sessionBuilding the Handshake
// From src/xrpld/overlay/detail/Handshake.cpp
void buildHandshake(
boost::beast::http::fields& h,
ripple::uint256 const& sharedValue,
std::optional<std::uint32_t> networkID,
beast::IP::Address public_ip,
beast::IP::Address remote_ip,
Application& app)
{
// 1. Network identification
if (networkID)
h.insert("Network-ID", std::to_string(*networkID));
// 2. Timestamp (freshness, prevent replay)
h.insert("Network-Time",
std::to_string(app.timeKeeper().now().time_since_epoch().count()));
// 3. Node's public key
h.insert("Public-Key",
toBase58(TokenType::NodePublic, app.nodeIdentity().first));
// 4. CRITICAL: Session signature
auto const sig = signDigest(
app.nodeIdentity().first, // Public key
app.nodeIdentity().second, // Secret key
sharedValue); // Session-specific value
h.insert("Session-Signature", base64_encode(sig));
// 5. Instance cookie (prevent self-connection)
h.insert("Instance-Cookie",
std::to_string(app.getInstanceCookie()));
// 6. Optional: Server domain
auto const domain = app.config().SERVER_DOMAIN;
if (!domain.empty())
h.insert("Server-Domain", domain);
// 7. Ledger information
if (auto closed = app.getLedgerMaster().getClosedLedger())
h.insert("Closed-Ledger", to_string(closed->info().hash));
}Header Fields Explained
Network-ID:
// Mainnet: 0
// Testnet: 1
// Devnet: 2, etc.
// Prevents nodes from different networks connectingNetwork-Time:
// Current time in milliseconds since epoch
// Helps detect replayed handshakes (timestamps too old)
// Not strictly enforced (clocks may be slightly off)Public-Key:
// Node's public key in Base58 format
// Example: nHUpcmNsxAw47yt2ADDoNoQrzLyTJPgnyq5o3xTmMcgV8X3iVVa7
// Used to verify the signatureSession-Signature:
// Signature of the shared value
// Proves: "I have the secret key for this public key"
// AND "I'm participating in THIS specific SSL session"Instance-Cookie:
// Random value generated on node startup
// If we receive our own cookie back → we're connecting to ourselves!Server-Domain (optional):
// Domain name like "ripple.com"
// Can be verified against validator list
// Helps with node identificationVerifying the Handshake
std::optional<PublicKey>
verifyHandshake(
http_request_type const& request,
uint256 const& sharedValue,
std::optional<std::uint32_t> networkID,
uint64_t instanceCookie,
beast::Journal journal)
{
// 1. Extract and parse public key
auto const pkStr = request["Public-Key"];
auto const pk = parseBase58<PublicKey>(
TokenType::NodePublic,
pkStr);
if (!pk)
{
JLOG(journal.warn()) << "Invalid public key";
return std::nullopt;
}
// 2. Check network ID matches
if (networkID)
{
auto const theirNetworkID = request["Network-ID"];
if (theirNetworkID.empty() ||
std::to_string(*networkID) != theirNetworkID)
{
JLOG(journal.warn()) << "Network ID mismatch";
return std::nullopt;
}
}
// 3. Check for self-connection
auto const theirCookie = request["Instance-Cookie"];
if (theirCookie == std::to_string(instanceCookie))
{
JLOG(journal.warn()) << "Detected self-connection";
return std::nullopt;
}
// 4. Verify session signature
auto const sigStr = request["Session-Signature"];
auto const sig = base64_decode(sigStr);
if (!verifyDigest(*pk, sharedValue, sig, true))
{
JLOG(journal.warn()) << "Invalid session signature";
return std::nullopt;
}
// 5. Optional: Validate server domain
auto const domain = request["Server-Domain"];
if (!domain.empty() && !isProperlyFormedTomlDomain(domain))
{
JLOG(journal.warn()) << "Invalid server domain";
return std::nullopt;
}
// Success! Return authenticated public key
JLOG(journal.info()) << "Handshake verified for " << toBase58(*pk);
return pk;
}Complete Handshake Flow
Node A Node B
| |
| 1. TCP connection established |
|<--------------------------------------------------->|
| |
| 2. SSL/TLS handshake |
| (Both send "Finished" messages) |
|<--------------------------------------------------->|
| |
| 3. Both compute shared value |
| shared = sha512Half(finishedA XOR finishedB) |
| |
| 4. HTTP Upgrade Request |
| Headers: |
| Public-Key: PK_A |
| Session-Signature: sign(SK_A, shared) |
| Network-ID: 0 |
| Instance-Cookie: COOKIE_A |
|---------------------------------------------------->|
| |
| 5. Node B: |
| - Verify PK_A|
| - Check sig |
| - Check net |
| - Check cookie|
| |
| 6. HTTP Upgrade Response |
| Headers: |
| Public-Key: PK_B |
| Session-Signature: sign(SK_B, shared) |
| Network-ID: 0 |
| Instance-Cookie: COOKIE_B |
|<----------------------------------------------------|
| |
| 7. Node A verifies Node B |
| |
| 8. Begin XRPL protocol |
|<--------------------------------------------------->|Security Properties
1. Mutual Authentication
Both nodes prove they possess their private keys:
Node A proves: "I have SK_A"
Node B proves: "I have SK_B"2. Session Binding
Signatures are specific to this connection:
Signature valid ONLY for THIS SSL session
Cannot be replayed in different session3. Replay Prevention
sharedValue = derived from THIS session's SSL handshake
Old signatures from previous sessions won't verify4. MITM Prevention
Attacker cannot forge signatures without private keys
SSL provides encryption, handshake provides authentication5. Self-Connection Prevention
if (theirCookie == myCookie) {
// We're talking to ourselves!
reject();
}6. Network Segregation
if (theirNetwork != myNetwork) {
// Different networks (mainnet vs testnet)
reject();
}Attack Analysis
Can an attacker impersonate Node A?
No:
Attacker needs to:
1. Know Node A's secret key (impossible - properly secured)
2. Sign the shared value (requires secret key)
Without SK_A, cannot create valid signatureCan an attacker replay old handshakes?
No:
Shared value is different for each SSL session
Old signature: sign(SK, oldSharedValue)
New session: verify(PK, newSharedValue, oldSignature)
Result: Verification fails (different shared values)Can an attacker perform MITM?
Very difficult:
SSL provides:
- Encryption (attacker can't read/modify)
- Certificate validation (can detect impersonation)
Application handshake provides:
- Signature verification (requires private keys)
- Session binding (tied to SSL session)
Attacker would need to:
1. Break SSL (extremely difficult)
2. AND forge signatures (impossible without keys)Implementation Best Practices
✅ DO:
// 1. Always verify the shared value
auto sharedValue = makeSharedValue(ssl, journal);
if (!sharedValue) {
disconnect("Failed to create shared value");
}
// 2. Always require canonical signatures
if (!verifyDigest(pk, sharedValue, sig, true)) {
disconnect("Invalid signature");
}
// 3. Always check network ID
if (theirNetwork != myNetwork) {
disconnect("Network mismatch");
}
// 4. Always check instance cookie
if (theirCookie == myCookie) {
disconnect("Self-connection detected");
}❌ DON'T:
// ❌ Don't skip signature verification
if (config.TRUSTED_NODE) {
// Skip verification - WRONG!
}
// ❌ Don't ignore network ID
// connect(); // Oops, might be wrong network
// ❌ Don't allow self-connections
// They waste resources and can cause issuesPerformance Considerations
// Handshake happens once per connection
// Not a performance bottleneck
Typical handshake time:
- SSL/TLS handshake: 50-100ms
- Shared value computation: <1ms
- Signature creation: <1ms
- Signature verification: <1ms
Total: ~50-100ms
// Amortized over connection lifetime (hours/days)
// Cost is negligibleSummary
The peer handshake protocol provides:
Mutual authentication: Both nodes prove identity
Session binding: Signatures tied to specific SSL session
Replay prevention: Old signatures don't work
MITM protection: Requires private keys to forge
Self-connection prevention: Instance cookies detect loops
Network segregation: Network IDs prevent cross-network connections
Key components:
Shared value: Derived from SSL session, unique per connection
Signatures: Prove possession of private keys
Headers: Exchange identities and verification data
Validation: Multiple checks ensure security
This cryptographic handshake enables XRPL to operate as a decentralized network where nodes don't need to trust each other—they can verify everything cryptographically.
Last updated