Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

EIP-778: final update to IPv6 keys, use URL-safe base64 #2097

Merged
merged 1 commit into from
Jun 4, 2019
Merged

EIP-778: final update to IPv6 keys, use URL-safe base64 #2097

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 35 additions & 21 deletions EIPS/eip-778.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,25 +39,31 @@ The components of a node record are:
- `signature`: cryptographic signature of record contents
- `seq`: The sequence number, a 64-bit unsigned integer. Nodes should increase the number
whenever the record changes and republish the record.
- The remainder of the record consists of arbitrary key/value pairs, which must be sorted
by key. Keys must be unique.
- The remainder of the record consists of arbitrary key/value pairs

A record's signature is made and validated according to an *identity scheme*. The identity
scheme is also responsible for deriving a node's address in the DHT.

The keys in key/value pairs can technically be any byte sequence, but ASCII text is
preferred. Keys in the table below have pre-defined meaning.

| Key | Value |
|:------------|:------------------------------------------|
| `id` | name of identity scheme, e.g. "v4" |
| `secp256k1` | compressed secp256k1 public key, 33 bytes |
| `ip` | IPv4 address, 4 bytes |
| `ip6` | IPv6 address, 16 bytes |
| `tcp` | TCP port, big endian integer |
| `udp` | UDP port, big endian integer |

All keys except `id` are optional.
The key/value pairs must be sorted by key and must be unique, i.e. any key may be present
only once. The keys can technically be any byte sequence, but ASCII text is preferred. Key
names in the table below have pre-defined meaning.

| Key | Value |
|:------------|:-------------------------------------------|
| `id` | name of identity scheme, e.g. "v4" |
| `secp256k1` | compressed secp256k1 public key, 33 bytes |
| `ip` | IPv4 address, 4 bytes |
| `tcp` | TCP port, big endian integer |
| `udp` | UDP port, big endian integer |
| `ip6` | IPv6 address, 16 bytes |
| `tcp6` | IPv6-specific TCP port, big endian integer |
| `udp6` | IPv6-specific UDP port, big endian integer |

All keys except `id` are optional, including IP addresses and ports. A record without
endpoint information is still valid as long as its signature is valid. If no `tcp6` /
`udp6` port is provided, the `tcp` / `udp` port applies to both IP addresses. Declaring
the same port number in both `tcp`, `tcp6` or `udp`, `udp6` should be avoided but doesn't
render the record invalid.

### RLP Encoding

Expand All @@ -74,12 +80,14 @@ Records are signed and encoded as follows:
### Text Encoding

The textual form of a node record is the base64 encoding of its RLP representation,
prefixed by `enr:`.
prefixed by `enr:`. Implementations should use the [URL-safe base64 alphabet][base64url]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"should" or "must"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant "must", but it sounds silly.

Copy link
Contributor

@carver carver Jun 4, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see that many (but not all) EIPs explicitly use RFC 2119's definitions: https://github.com/ethereum/EIPs/search?q=2119&type=Code

It might sound silly, but for the sake of precision, I would recommend using RFC 2119 words here. Ambiguity about "is this preferred or required" can lead to some sloppy real-world implementations, and wasted time arguing about whether code is compliant.

and omit padding characters.

### "v4" Identity Scheme

This specification defines a single scheme to be used as the default. The "v4" scheme is
backwards-compatible with the cryptosystem used by Node Discovery v4.
This specification defines a single identity scheme to be used as the default until other
schemes are defined by further EIPs. The "v4" scheme is backwards-compatible with the
cryptosystem used by Node Discovery v4.

- To sign record `content` with this scheme, apply the keccak256 hash function (as used by
the EVM) to `content`, then create a signature of the hash. The resulting 64-byte
Expand All @@ -105,15 +113,19 @@ in size-constrained protocols such as DNS. A record containing a IPv4 address, w
using the "v4" scheme occupies roughly 120 bytes, leaving plenty of room for additional
metadata.

You might wonder about the need for so many pre-defined keys related to IP addresses and
ports. This need arises because residential and mobile network setups often put IPv4
behind NAT while IPv6 traffic—if supported—is directly routed to the same host. Declaring
both address types ensures a node is reachable from IPv4-only locations and those
supporting both protocols.

# Test Vectors

This is an example record containing the IPv4 address `127.0.0.1` and UDP port `30303`.
The node ID is `a448f24c6d18e575453db13171562b71999873db5b286df957af199ec94617f7`.

```text
enr:+IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj
499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2
/oxVtw0RW/QAdpzBQA8yWM0xOIN1ZHCCdl8=
enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8
```

The record is signed using the "v4" identity scheme using sequence number `1` and this
Expand Down Expand Up @@ -143,3 +155,5 @@ The RLP structure of the record is:
# Copyright

Copyright and related rights waived via CC0.

[base64url]: https://tools.ietf.org/html/rfc4648#section-5