Skip to content

Commit 095087b

Browse files
luke-jrluke-jr
authored
Merge pull request bitcoin#766 from laanwj/2019_02_addvr2
BIP 155: addrv2 BIP proposal
2 parents 15f7e19 + f517419 commit 095087b

File tree

2 files changed

+196
-0
lines changed

2 files changed

+196
-0
lines changed

‎README.mediawiki

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -771,6 +771,13 @@ Those proposing changes should consider that ultimately consent may rest with th
771771
| Standard
772772
| Draft
773773
|-
774+
| [[bip-0155.mediawiki|155]]
775+
| Peer Services
776+
| addrv2 message
777+
| Wladimir J. van der Laan
778+
| Standard
779+
| Draft
780+
|-
774781
| [[bip-0156.mediawiki|156]]
775782
| Peer Services
776783
| Dandelion - Privacy Enhancing Routing

‎bip-0155.mediawiki

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
<pre>
2+
BIP: 155
3+
Layer: Peer Services
4+
Title: addrv2 message
5+
Author: Wladimir J. van der Laan <[email protected]>
6+
Comments-Summary: No comments yet.
7+
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0155
8+
Status: Draft
9+
Type: Standards Track
10+
Created: 2019-02-27
11+
License: BSD-2-Clause
12+
</pre>
13+
14+
==Introduction==
15+
16+
===Abstract===
17+
18+
This document proposes a new P2P message to gossip longer node addresses over the P2P network.
19+
This is required to support new-generation Onion addresses, I2P, and potentially other networks
20+
that have longer endpoint addresses than fit in the 128 bits of the current <code>addr</code> message.
21+
22+
===Copyright===
23+
24+
This BIP is licensed under the 2-clause BSD license.
25+
26+
===Motivation===
27+
28+
Tor v3 hidden services are part of the stable release of Tor since version 0.3.2.9. They have
29+
various advantages compared to the old hidden services, among which better encryption and privacy
30+
<ref>[https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3]</ref>.
31+
These services have 256 bit addresses and thus do not fit in the existing <code>addr</code> message, which encapsulates onion addresses in OnionCat IPv6 addresses.
32+
33+
Other transport-layer protocols such as I2P have always used longer
34+
addresses. This change would make it possible to gossip such addresses over the
35+
P2P network, so that other peers can connect to them.
36+
37+
==Specification==
38+
39+
<blockquote>
40+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
41+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
42+
interpreted as described in RFC 2119<ref>[https://tools.ietf.org/html/rfc2119 RFC 2119]</ref>.
43+
</blockquote>
44+
45+
The <code>addrv2</code> message is defined as a message where <code>pchCommand == "addrv2"</code>.
46+
It is serialized in the standard encoding for P2P messages.
47+
Its format is similar to the current <code>addr</code> message format
48+
<ref>[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message]</ref>, with the difference that the
49+
fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the time and services format has been changed to VARINT.
50+
51+
This means that the message contains a serialized <code>std::vector</code> of the following structure:
52+
53+
{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
54+
!Type
55+
!Name
56+
!Description
57+
|-
58+
| <code>VARINT</code> (unsigned)
59+
| <code>time</code>
60+
| Time that this node was last seen as connected to the network. A time in Unix epoch time format, up to 64 bits wide.
61+
|-
62+
| <code>VARINT</code> (unsigned)
63+
| <code>services</code>
64+
| Service bits. A 64-wide bit field.
65+
|-
66+
| <code>uint8_t</code>
67+
| <code>networkID</code>
68+
| Network identifier. An 8-bit value that specifies which network is addressed.
69+
|-
70+
| <code>std::vector<uint8_t></code>
71+
| <code>addr</code>
72+
| Network address. The interpretation depends on networkID.
73+
|-
74+
| <code>uint16_t</code>
75+
| <code>port</code>
76+
| Network port. If not relevant for the network this MUST be 0.
77+
|}
78+
79+
One message can contain up to 1,000 addresses. Clients SHOULD reject messages with more addresses.
80+
81+
Field <code>addr</code> has a variable length, with a maximum of 32 bytes (256 bits). Clients SHOULD reject
82+
longer addresses.
83+
84+
The list of reserved network IDs is as follows:
85+
86+
{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
87+
!Network ID
88+
!Enumeration
89+
!Address length (bytes)
90+
!Description
91+
|-
92+
| <code>0x01</code>
93+
| <code>IPV4</code>
94+
| 4
95+
| IPv4 address (globally routed internet)
96+
|-
97+
| <code>0x02</code>
98+
| <code>IPV6</code>
99+
| 16
100+
| IPv6 address (globally routed internet)
101+
|-
102+
| <code>0x03</code>
103+
| <code>TORV2</code>
104+
| 10
105+
| Tor v2 hidden service address
106+
|-
107+
| <code>0x04</code>
108+
| <code>TORV3</code>
109+
| 32
110+
| Tor v3 hidden service address
111+
|-
112+
| <code>0x05</code>
113+
| <code>I2P</code>
114+
| 32
115+
| I2P overlay network address
116+
|-
117+
| <code>0x06</code>
118+
| <code>CJDNS</code>
119+
| 16
120+
| Cjdns overlay network address
121+
|}
122+
123+
To allow for future extensibility, clients MUST ignore address types that they do not know about.
124+
Client MAY store and gossip address formats that they do not know about. Further network ID numbers MUST be reserved in a new BIP document.
125+
126+
Clients SHOULD reject addresses that have a different length than specified in this table for a specific address ID, as these are meaningless.
127+
128+
See the appendices for the address encodings to be used for the various networks.
129+
130+
==Compatibility==
131+
132+
Send <code>addrv2</code> messages only, and exclusively, when the peer has a certain protocol version (or higher):
133+
<source lang="c++">
134+
//! gossiping using `addrv2` messages starts with this version
135+
static const int GOSSIP_ADDRV2_VERSION = 70016;
136+
</source>
137+
For older peers keep sending the legacy <code>addr</code> message, ignoring addresses with the newly introduced address types.
138+
139+
==Reference implementation==
140+
141+
The reference implementation is available at (to be done)
142+
143+
==Acknowledgements==
144+
145+
- Jonas Schnelli: change <code>services</code> field to VARINT, to make the message more compact in the likely case instead of always using 8 bytes.
146+
147+
- Luke-Jr: change <code>time</code> field to VARINT, for post-2038 compatibility.
148+
149+
- Gregory Maxwell: various suggestions regarding extensibility
150+
151+
==Appendix A: Tor v2 address encoding==
152+
153+
The new message introduces a separate network ID for <code>TORV2</code>.
154+
155+
Clients MUST send Tor hidden service addresses with this network ID, with the 80-bit hidden service ID in the address field. This is the same as the representation in the legacy <code>addr</code> message, minus the 6 byte prefix of the OnionCat wrapping.
156+
157+
Clients SHOULD ignore OnionCat (<code>fd87:d87e:eb43::/48</code>) addresses on receive if they come with the <code>IPV6</code> network ID.
158+
159+
==Appendix B: Tor v3 address encoding==
160+
161+
According to the spec <ref>[https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3: Encoding onion addresses]</ref>, next-gen <code>.onion</code> addresses are encoded as follows:
162+
<pre>
163+
onion_address = base32(PUBKEY | CHECKSUM | VERSION) + ".onion"
164+
CHECKSUM = H(".onion checksum" | PUBKEY | VERSION)[:2]
165+
166+
where:
167+
- PUBKEY is the 32 bytes ed25519 master pubkey of the hidden service.
168+
- VERSION is an one byte version field (default value '\x03')
169+
- ".onion checksum" is a constant string
170+
- CHECKSUM is truncated to two bytes before inserting it in onion_address
171+
</pre>
172+
173+
Tor v3 addresses MUST be sent with the <code>TORV3</code> network ID, with the 32-byte PUBKEY part in the address field. As VERSION will always be '\x03' in the case of v3 addresses, this is enough to reconstruct the onion address.
174+
175+
==Appendix C: I2P address encoding==
176+
177+
Like Tor, I2P naming uses a base32-encoded address format<ref>[https://geti2p.net/en/docs/naming#base32 I2P: Naming and address book]</ref>.
178+
179+
I2P uses 52 characters (256 bits) to represent the full SHA-256 hash, followed by <code>.b32.i2p</code>.
180+
181+
I2P addresses MUST be sent with the <code>I2P</code> network ID, with the decoded SHA-256 hash as address field.
182+
183+
==Appendix D: Cjdns address encoding==
184+
185+
Cjdns addresses are simply IPv6 addresses in the <code>fc00::/8</code> range<ref>[https://github.com/cjdelisle/cjdns/blob/6e46fa41f5647d6b414612d9d63626b0b952746b/doc/Whitepaper.md#pulling-it-all-together Cjdns whitepaper: Pulling It All Together]</ref>. They MUST be sent with the <code>CJDNS</code> network ID.
186+
187+
==References==
188+
189+
<references/>

0 commit comments

Comments
 (0)