-
Notifications
You must be signed in to change notification settings - Fork 273
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
287 additions
and
144 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| # Autonat V1: spec | ||
|
|
||
| | 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 |
Oops, something went wrong.