Skip to content

Latest commit

 

History

History
148 lines (116 loc) · 5.63 KB

README.md

File metadata and controls

148 lines (116 loc) · 5.63 KB
Raw

NAT Discovery

How we detect if we're behind a NAT.

Lifecycle Stage Maturity Status Latest Revision
3A Recommendation Active r1, 2023-02-16

Authors: @marten-seemann

Interest Group: @mxinden, @vyzo, @raulk, @stebalien, @willscott

See the lifecycle document for context about the maturity level and spec status.

Table of Contents

Overview

A priori, a node cannot know if it is behind a NAT / firewall or if it is publicly reachable. Knowing its NAT status is essential for the node to be well-behaved in the network: A node that's behind a NAT doesn't need to advertise its (undiable) addresses to the rest of the network, preventing superfluous dials from other peers. Furthermore, it might actively seek to improve its connectivity by finding a relay server, which would allow other peers to establish a relayed connection.

To determine if it is located behind a NAT, nodes use the autonat protocol. Using this protocol, the node requests other peers to dial its presumed public addresses. If a couple of these dial attempts succeed, the node can be reasonably certain that it is not located behind a NAT. Likewise, if a couple of these dial attempts fail, this is a strong indicator that a NAT is blocking incoming connections.

AutoNAT Protocol

The AutoNAT Protocol uses the Protocol ID /libp2p/autonat/1.0.0. The node wishing to determine its NAT status opens a stream using this protocol ID, and then sends a Dial message. The Dial message contains a list of multiaddresses. Upon receiving this message, the peer starts to dial these addresses. It MAY add the observed address of the connection on which the request was received to the list of addresses. It MAY dial the addresses in parallel. The peer MAY also use a different IP and peer ID than it uses for its regular libp2p connection to perform these dial backs.

In order to prevent attacks like the one described in RFC 3489, Section 12.1.1 (see excerpt below), implementations MUST NOT dial any multiaddress unless it is based on the IP address the requesting node is observed as. This restriction as well implies that implementations MUST NOT accept dial requests via relayed connections as one can not validate the IP address of the requesting node.

RFC 3489 12.1.1 Attack I: DDOS Against a Target

In this case, the attacker provides a large number of clients with the same faked MAPPED-ADDRESS that points to the intended target. This will trick all the STUN clients into thinking that their addresses are equal to that of the target. The clients then hand out that address in order to receive traffic on it (for example, in SIP or H.323 messages). However, all of that traffic becomes focused at the intended target. The attack can provide substantial amplification, especially when used with clients that are using STUN to enable multimedia applications.

If all dials fail, the receiver sends a DialResponse message with the ResponseStatus E_DIAL_ERROR. If at least one of the dials complete successfully, it sends a DialResponse with the ResponseStatus OK. It SHOULD include the address it successfully dialed in its response.

The initiator uses the responses obtained from multiple peers to determine its NAT status. If more than 3 peers report a successfully dialed address, the node SHOULD assume that it is not located behind a NAT and publicly accessible. On the other hand, if more than 3 peers report unsuccessful dials, the node SHOULD assume that it is not publicly accessible. Nodes are encouraged to periodically re-check their status, especially after changing their set of addresses they're listening on.

RPC messages

Messages are exchanged by:

  1. Opening a new stream.
  2. Sending the RPC request message.
  3. Listening for the RPC response message.

All RPC messages sent over a stream are prefixed with the message length in bytes, encoded as an unsigned variable length integer as defined by the multiformats unsigned-varint spec.

syntax = "proto2";

message Message {
  enum MessageType {
    DIAL          = 0;
    DIAL_RESPONSE = 1;
  }

  enum ResponseStatus {
    OK               = 0;
    E_DIAL_ERROR     = 100;
    E_DIAL_REFUSED   = 101;
    E_BAD_REQUEST    = 200;
    E_INTERNAL_ERROR = 300;
  }

  message PeerInfo {
    optional bytes id = 1;
    repeated bytes addrs = 2;
  }

  message Dial {
    optional PeerInfo peer = 1;
  }

  message DialResponse {
    optional ResponseStatus status = 1;
    optional string statusText = 2;
    optional bytes addr = 3;
  }

  optional MessageType type = 1;
  optional Dial dial = 2;
  optional DialResponse dialResponse = 3;
}

Security Considerations

Note that in the current iteration of this protocol, a node doesn't check if a peer's report of a successful dial is accurate. This might be solved in a future iteration of this protocol, see https://github.com/libp2p/go-libp2p-autonat/issues/10 for a detailed discussion.