tendermint/p2p/docs/peer.md

# Tendermint Peers

This document explains how Tendermint Peers are identified, how they connect to one another,
and how other peers are found.

## Peer Identity

Tendermint peers are expected to maintain long-term persistent identities in the form of a private key.
Each peer has an ID defined as `peer.ID == peer.PrivKey.Address()`, where `Address` uses the scheme defined in go-crypto.

Peer ID's must come with some Proof-of-Work; that is,
they must satisfy `peer.PrivKey.Address() < target` for some difficulty target.
This ensures they are not too easy to generate.

A single peer ID can have multiple IP addresses associated with - for simplicity, we only keep track
of the latest one.

When attempting to connect to a peer, we use the PeerURL: `<ID>@<IP>:<PORT>`.
We will attempt to connect to the peer at IP:PORT, and verify,
via authenticated encryption, that it is in possession of the private key
corresponding to `<ID>`. This prevents man-in-the-middle attacks on the peer layer.

Peers can also be connected to without specifying an ID, ie. `<IP>:<PORT>`.
In this case, the peer cannot be authenticated and other means, such as a VPN,
must be used.

## Connections

All p2p connections use TCP.
Upon establishing a successful TCP connection with a peer,
two handhsakes are performed: one for authenticated encryption, and one for Tendermint versioning.
Both handshakes have configurable timeouts (they should complete quickly).

### Authenticated Encryption Handshake

Tendermint implements the Station-to-Station protocol
using ED25519 keys for Diffie-Helman key-exchange and NACL SecretBox for encryption.
It goes as follows:
- generate an emphemeral ED25519 keypair
- send the ephemeral public key to the peer
- wait to receive the peer's ephemeral public key
- compute the Diffie-Hellman shared secret using the peers ephemeral public key and our ephemeral private key
- generate nonces to use for encryption
    - TODO
- all communications from now on are encrypted using the shared secret
- generate a common challenge to sign
- sign the common challenge with our persistent private key
- send the signed challenge and persistent public key to the peer
- wait to receive the signed challenge and persistent public key from the peer
- verify the signature in the signed challenge using the peers persistent public key


If this is an outgoing connection (we dialed the peer) and we used a peer ID,
then finally verify that the `peer.PubKey` corresponds to the peer ID we dialed,
ie. `peer.PubKey.Address() == <ID>`.

The connection has now been authenticated. All traffic is encrypted.

Note that only the dialer can authenticate the identity of the peer,
but this is what we care about since when we join the network we wish to
ensure we have reached the intended peer (and are not being MITMd).


### Peer Filter

Before continuing, we check if the new peer has the same ID has ourselves or
an existing peer. If so, we disconnect.

We also check the peer's address and public key against
an optional whitelist which can be managed through the ABCI app -
if the whitelist is enabled and the peer is not on it, the connection is
terminated.


### Tendermint Version Handshake

The Tendermint Version Handshake allows the peers to exchange their NodeInfo, which contains:

```
type NodeInfo struct {
	PubKey     crypto.PubKey `json:"pub_key"`
	Moniker    string        `json:"moniker"`
	Network    string        `json:"network"`
	RemoteAddr string        `json:"remote_addr"`
	ListenAddr string        `json:"listen_addr"` // accepting in
	Version    string        `json:"version"` // major.minor.revision
    Channels   []int8        `json:"channels"` // active reactor channels
	Other      []string      `json:"other"`   // other application specific data
}
```

The connection is disconnected if:
- `peer.NodeInfo.PubKey != peer.PubKey`
- `peer.NodeInfo.Version` is not formatted as `X.X.X` where X are integers known as Major, Minor, and Revision
- `peer.NodeInfo.Version` Major is not the same as ours
- `peer.NodeInfo.Version` Minor is not the same as ours
- `peer.NodeInfo.Network` is not the same as ours


At this point, if we have not disconnected, the peer is valid and added to the switch,
so it is added to all reactors.


### Connection Activity