add autonat v2 spec

libp2p · Apr 11, 2023 · b95fb58 · b95fb58
1 parent 6634ca7
commit b95fb58
Show file tree

Hide file tree

Showing 3 changed files with 288 additions and 144 deletions.
diff --git a/autonat/README.md b/autonat/README.md
@@ -1,148 +1,7 @@
 # NAT Discovery  <!-- omit in toc -->
 > 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]
-
-[@marten-seemann]: https://github.com/marten-seemann
-[@mxinden]: https://github.com/mxinden/
-[@vyzo]: https://github.com/vyzo
-[@raulk]: https://github.com/raulk
-[@stebalien]: https://github.com/stebalien
-[@willscott]: https://github.com/willscott
-
-See the [lifecycle document][lifecycle-spec] for context about the maturity level
-and spec status.
-
-[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md
-
-## Table of Contents  <!-- omit in toc -->
-
-- [Overview](#overview)
-- [AutoNAT Protocol](#autonat-protocol)
-- [RPC messages](#rpc-messages)
-- [Security Considerations](#security-considerations)
-
-## 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](https://www.rfc-editor.org/rfc/rfc3489#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][uvarint-spec].
-
-```proto
-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.
-
-[uvarint-spec]: https://github.com/multiformats/unsigned-varint
+Specifications:
+- [autonat v1](autonat-v1.md)
+- [autonat v2](autonat-v2.md)
diff --git a/autonat/autonat-v1.md b/autonat/autonat-v1.md
@@ -0,0 +1,149 @@
+# NAT Discovery  <!-- omit in toc -->
+> 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]
+
+[@marten-seemann]: https://github.com/marten-seemann
+[@mxinden]: https://github.com/mxinden/
+[@vyzo]: https://github.com/vyzo
+[@raulk]: https://github.com/raulk
+[@stebalien]: https://github.com/stebalien
+[@willscott]: https://github.com/willscott
+
+See the [lifecycle document][lifecycle-spec] for context about the maturity level
+and spec status.
+
+[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md
+
+## Table of Contents  <!-- omit in toc -->
+
+- [Overview](#overview)
+- [AutoNAT Protocol](#autonat-protocol)
+- [RPC messages](#rpc-messages)
+- [Security Considerations](#security-considerations)
+
+## 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](https://www.rfc-editor.org/rfc/rfc3489#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][uvarint-spec].
+
+```proto
+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.
+
+[uvarint-spec]: https://github.com/multiformats/unsigned-varint