From 34534b5ee1cf49cf67005b5457fce110ea6b0f4b Mon Sep 17 00:00:00 2001 From: "Wladimir J. van der Laan" Date: Thu, 18 Jul 2019 00:17:55 +0200 Subject: bip155: fill in BIP number --- bip-0155.mediawiki | 189 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 bip-0155.mediawiki (limited to 'bip-0155.mediawiki') diff --git a/bip-0155.mediawiki b/bip-0155.mediawiki new file mode 100644 index 0000000..27bec17 --- /dev/null +++ b/bip-0155.mediawiki @@ -0,0 +1,189 @@ +
+  BIP: 155
+  Layer: Peer Services
+  Title: addrv2 message
+  Author: Wladimir J. van der Laan 
+  Comments-Summary: No comments yet.
+  Comments-URI: 
+  Status: Draft
+  Type: Standards Track
+  Created: 2019-02-27
+  License: BSD-2-Clause
+
+ +==Introduction== + +===Abstract=== + +This document proposes a new P2P message to gossip longer node addresses over the P2P network. +This is required to support new-generation Onion addresses, I2P, and potentially other networks +that have longer endpoint addresses than fit in the 128 bits of the current addr message. + +===Copyright=== + +This BIP is licensed under the 2-clause BSD license. + +===Motivation=== + +Tor v3 hidden services are part of the stable release of Tor since version 0.3.2.9. They have +various advantages compared to the old hidden services, among which better encryption and privacy +[https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3]. +These services have 256 bit addresses and thus do not fit in the existing addr message, which encapsulates onion addresses in OnionCat IPv6 addresses. + +Other transport-layer protocols such as I2P have always used longer +addresses. This change would make it possible to gossip such addresses over the +P2P network, so that other peers can connect to them. + +==Specification== + +
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119[https://tools.ietf.org/html/rfc2119 RFC 2119]. +
+ +The addrv2 message is defined as a message where pchCommand == "addrv2". +It is serialized in the standard encoding for P2P messages. +Its format is similar to the current addr message format +[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message], with the difference that the +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. + +This means that the message contains a serialized std::vector of the following structure: + +{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;" +!Type +!Name +!Description +|- +| VARINT (unsigned) +| time +| Time that this node was last seen as connected to the network. A time in Unix epoch time format, up to 64 bits wide. +|- +| VARINT (unsigned) +| services +| Service bits. A 64-wide bit field. +|- +| uint8_t +| networkID +| Network identifier. An 8-bit value that specifies which network is addressed. +|- +| std::vector +| addr +| Network address. The interpretation depends on networkID. +|- +| uint16_t +| port +| Network port. If not relevant for the network this MUST be 0. +|} + +One message can contain up to 1,000 addresses. Clients SHOULD reject messages with more addresses. + +Field addr has a variable length, with a maximum of 32 bytes (256 bits). Clients SHOULD reject +longer addresses. + +The list of reserved network IDs is as follows: + +{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;" +!Network ID +!Enumeration +!Address length (bytes) +!Description +|- +| 0x01 +| IPV4 +| 4 +| IPv4 address (globally routed internet) +|- +| 0x02 +| IPV6 +| 16 +| IPv6 address (globally routed internet) +|- +| 0x03 +| TORV2 +| 10 +| Tor v2 hidden service address +|- +| 0x04 +| TORV3 +| 32 +| Tor v3 hidden service address +|- +| 0x05 +| I2P +| 32 +| I2P overlay network address +|- +| 0x06 +| CJDNS +| 16 +| Cjdns overlay network address +|} + +To allow for future extensibility, clients MUST ignore address types that they do not know about. +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. + +Clients SHOULD reject addresses that have a different length than specified in this table for a specific address ID, as these are meaningless. + +See the appendices for the address encodings to be used for the various networks. + +==Compatibility== + +Send addrv2 messages only, and exclusively, when the peer has a certain protocol version (or higher): + +//! gossiping using `addrv2` messages starts with this version +static const int GOSSIP_ADDRV2_VERSION = 70016; + +For older peers keep sending the legacy addr message, ignoring addresses with the newly introduced address types. + +==Reference implementation== + +The reference implementation is available at (to be done) + +==Acknowledgements== + +- Jonas Schnelli: change services field to VARINT, to make the message more compact in the likely case instead of always using 8 bytes. + +- Luke-Jr: change time field to VARINT, for post-2038 compatibility. + +- Gregory Maxwell: various suggestions regarding extensibility + +==Appendix A: Tor v2 address encoding== + +The new message introduces a separate network ID for TORV2. + +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 addr message, minus the 6 byte prefix of the OnionCat wrapping. + +Clients SHOULD ignore OnionCat (fd87:d87e:eb43::/48) addresses on receive if they come with the IPV6 network ID. + +==Appendix B: Tor v3 address encoding== + +According to the spec [https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3: Encoding onion addresses], next-gen .onion addresses are encoded as follows: +
+onion_address = base32(PUBKEY | CHECKSUM | VERSION) + ".onion"
+ CHECKSUM = H(".onion checksum" | PUBKEY | VERSION)[:2]
+
+ where:
+   - PUBKEY is the 32 bytes ed25519 master pubkey of the hidden service.
+   - VERSION is an one byte version field (default value '\x03')
+   - ".onion checksum" is a constant string
+   - CHECKSUM is truncated to two bytes before inserting it in onion_address
+
+ +Tor v3 addresses MUST be sent with the TORV3 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. + +==Appendix C: I2P address encoding== + +Like Tor, I2P naming uses a base32-encoded address format[https://geti2p.net/en/docs/naming#base32 I2P: Naming and address book]. + +I2P uses 52 characters (256 bits) to represent the full SHA-256 hash, followed by .b32.i2p. + +I2P addresses MUST be sent with the I2P network ID, with the decoded SHA-256 hash as address field. + +==Appendix D: Cjdns address encoding== + +Cjdns addresses are simply IPv6 addresses in the fc00::/8 range[https://github.com/cjdelisle/cjdns/blob/6e46fa41f5647d6b414612d9d63626b0b952746b/doc/Whitepaper.md#pulling-it-all-together Cjdns whitepaper: Pulling It All Together]. They MUST be sent with the CJDNS network ID. + +==References== + + -- cgit v1.2.3