# Handshake Protocol

[← Back to Protocol Extensions and Quantum Signatures](/core-dev-bootcamp/module05.md)

***

### Introduction

When two nodes in the XRP Ledger overlay network establish a connection, they must verify each other's identity, agree on communication protocols, and establish mutual trust. This process, called the **handshake**, is critical for network security and interoperability.

The handshake prevents unauthorized nodes from joining the network, ensures protocol compatibility between peers, and establishes the cryptographic foundation for secure communication. Understanding this process is essential for debugging connection issues and implementing protocol upgrades.

***

### Handshake Objectives

The handshake accomplishes several essential goals:

**Authentication**: Each node proves its identity using cryptographic signatures. This prevents impersonation attacks where a malicious node pretends to be a trusted validator.

**Protocol Negotiation**: Nodes agree on the protocol version and features they will use for communication. This enables the network to evolve while maintaining backward compatibility.

**Trust Establishment**: Both parties verify that the other is a legitimate participant running compatible software. This ensures network integrity.

**Capability Exchange**: Nodes share information about their supported features, enabling peers to optimize their communication strategies.

***

### HTTP Upgrade and Handshake

([README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md))

* Outbound peer initiates a TLS connection, then sends an HTTP/1.1 request with URI "/" and uses the HTTP/1.1 Upgrade mechanism with custom headers.
* Both sides verify the provided signature against the session's unique fingerprint.
* If signature check fails, the link is dropped.

### PeerImp::run and doAccept

**PeerImp::run** ([PeerImp.cpp](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/detail/PeerImp.cpp)):

* Ensures execution on the correct strand for thread safety.
* Parses handshake headers ("Closed-Ledger", "Previous-Ledger").
* Stores parsed ledger hashes in peer state.
* If inbound, calls `doAccept()`. If outbound, calls `doProtocolStart()`.

**PeerImp::doAccept** ([PeerImp.cpp](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/detail/PeerImp.cpp)):

* Asserts read buffer is empty.
* Logs the accept event.
* Generates shared value for session.
* Logs protocol and public key.
* Checks for cluster membership and assigns name if present.
* Calls `overlay_.activate(shared_from_this())` to register the peer as active.
* Prepares and sends handshake response.
* On successful write, calls `doProtocolStart()`.

### Conclusion

The handshake protocol establishes secure, authenticated connections between XRP Ledger nodes. Through TLS encryption, cryptographic signatures, and careful protocol negotiation, it ensures that only legitimate nodes can participate in the network while maintaining compatibility across different software versions. Understanding this process is essential for diagnosing connection issues and implementing protocol enhancements.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xrpl-commons.org/core-dev-bootcamp/module05/handshake-protocol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.