From ccf03847fc701452ad95e11ea502e358c4b1901f Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Fri, 2 Jul 2021 23:07:44 +0100 Subject: [PATCH 1/4] Update changelog --- CHANGELOG.md | 55 ++++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c4c82d3..4487ba2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,58 +27,53 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [0.4.0] - 2021-07-04 ### Added +- New routing scheme, which is backwards incompatible with previous versions of Yggdrasil + - The wire protocol version number, exchanged as part of the peer setup handshake, has been increased to 0.4 + - Nodes running this new version **will not** be able to peer with earlier versions of Yggdrasil + - Please note that **the network may be temporarily unstable** while infrastructure is being upgraded to the new release - TLS connections now use public key pinning - If no public key was already pinned, then the public key received as part of the TLS handshake is pinned to the connection - The public key received as part of the handshake is checked against the pinned keys, and if no match is found, the connection is rejected ### Changed -- This version is backwards incompatible with previous versions of Yggdrasil - - The wire protocol version number, exchanged as part of the peer setup handshake, has been increased to 0.4 - - Nodes running this version will **not** be able to peer with earlier versions of Yggdrasil - - Please note that **the network may be temporarily unstable** while infrastructure is being upgraded to the new release - - Please also note that nodes may be removed from the public peers repository if they do not upgrade within some time period after release (perhaps a couple of weeks) -- IP addresses are derived from ed25519 public (signing) keys +- IP addresses are now derived from ed25519 public (signing) keys - Previously, addresses were derived from a hash of X25519 (Diffie-Hellman) keys - - Note that this means **all node addresses have changed with respect to previous releases**, so any existing services will be hosted at new addresses - - The services page of the main repo has been updated to only list services in the new v0.4 network - - Service operators are encouraged to submit a PR if they wish to be (re-)added to the list + - Importantly, this means that **all internal IPv6 addresses will change with this release** — this will affect anyone running public services or relying on Yggdrasil for remote access - It is now recommended to peer over TLS - - Link-local peers from multicast peer discovery will now connect over TLS, with the key from the multicast announcement pinned to the connection - - `socks://` peers now expect the destination endpoint to be a `tls://` listener + - Link-local peers from multicast peer discovery will now connect over TLS, with the key from the multicast beacon pinned to the connection + - `socks://` peers now expect the destination endpoint to be a `tls://` listener, instead of a `tcp://` listener - Multicast peer discovery is now more configurable - There are separate configuration options to control if beacons are sent, what port to listen on for incoming connections (if sending beacons), and whether or not to listen for beacons from other nodes (and open connections when receiving a beacon) - Each configuration entry in the list specifies a regular expression to match against interface names - If an interface matches multiple regex in the list, it will use the settings for the first entry in the list that it matches with -- The session and routing code has been redesigned and rewritten: - - This is still an early work-in-progress, so the code hasn't been as well tested or optimized as the old code base. Please bear with us for these next few releases as we work through any bugs or issues - - Generally speaking, we expect to see reduced bandwidth use and improved reliability with the new design, especially in mobile networks - - Cryptographic sessions no longer use a single shared (ephemeral) secret for the entire life of the session. Keys are now rotated regularly for ongoing sessions (both nodes will rotate keys at least once per round trip exchange of traffic, which is arguably *too* aggressive, we may throttle this somehow in a future release) +- The session and routing code has been entirely redesigned and rewritten + - This is still an early work-in-progress, so the code hasn't been as well tested or optimized as the old code base — please bear with us for these next few releases as we work through any bugs or issues + - Generally speaking, we expect to see reduced bandwidth use and improved reliability with the new design, especially in cases where nodes move around or change peerings frequently + - Cryptographic sessions no longer use a single shared (ephemeral) secret for the entire life of the session. Keys are now rotated regularly for ongoing sessions (currently rotated at least once per round trip exchange of traffic, subject to change in future releases) - Source routing has been added. Under normal circumstances, this is what is used to forward session traffic (e.g. the user's IPv6 traffic) - DHT-based routing has been added. This is used when the sender does not know a source route to the destination. Forwarding through the DHT is less efficient, but the only information that it requires the sender to know is the destination node's (static) key. This is primarily used during the key exchange at session setup, or as a temporary fallback when a source route fails due to changes in the network - - The new DHT design does not support crawling, and does not inherently allow nodes to look up the owner of an arbitrary key. In Yggdrasil, responding to lookups is implemented at the application level, and a response is only sent if the destination key matches the node's IP or /64 prefix + - The new DHT design is no longer RPC-based, does not support crawling and does not inherently allow nodes to look up the owner of an arbitrary key. Responding to lookups is now implemented at the application level and a response is only sent if the destination key matches the node's `/128` IP or `/64` prefix - The greedy routing scheme, used to forward all traffic in previous releases, is now only used for protocol traffic (i.e. DHT setup and source route discovery) - - The code now lives in a [standalone library](https://github.com/Arceliar/ironwood). You are encouraged **not** to use it, as it's still considered pre-alpha, but it's available for those who want to experiment with the new routing algorithm in other contexts + - The routing logic now lives in a [standalone library](https://github.com/Arceliar/ironwood). You are encouraged **not** to use it, as it's still considered pre-alpha, but it's available for those who want to experiment with the new routing algorithm in other contexts - Many of the admin functions available over `yggdrasilctl` have been changed or removed as part of rewrites to the code - Several remote `debug` functions have been added temporarily, to allow for crawling and census gathering during the transition to the new version, but we intend to remove this at some point in the (possibly distant) future - The list of available functions will likely be expanded in future releases - The configuration file format has been updated in response to the changed/removed features ### Removed -- TunnelRouting (aka cryptokey routing) has been removed - - It was too easy to accidentally break routing by capturing the route to peers with the tun adapter - - We recommend tunneling an existing standard over Yggdrasil instead (e.g. `ip6gre` and `ip6gretap`) -- SessionFirewall has been removed - - This was never a true firewall, it was simply a way to prevent a node from being flooded with unwanted sessions, so the name could be misleading and lead to a false sense of security - - Due to design changes, the new code needs to address the possible memory exhaustion attacks in other ways, and a single configurable list no longer makes sense +- Tunnel routing (a.k.a. crypto-key routing or "CKR") has been removed + - It was far too easy to accidentally break routing altogether by capturing the route to peers with the TUN adapter + - We recommend tunnelling an existing standard over Yggdrasil instead (e.g. `ip6gre`, `ip6gretap` or other encapsulations) + - All `TunnelRouting` configuration options will no longer take effect +- Session firewall has been removed + - This was never a true firewall — it didn't behave like a stateful IP firewall, often allowed return traffic unexpectedly and was simply a way to prevent a node from being flooded with unwanted sessions, so the name could be misleading and usually lead to a false sense of security + - Due to design changes, the new code needs to address the possible memory exhaustion attacks in other ways and a single configurable list no longer makes sense - Users who want a firewall or other packet filter mechansim should configure something supported by their OS instead (e.g. `ip6tables`) -- SIGHUP handling has been removed - - Previously, we set a custom SIGHUP handler, and used it to reload (parts of) the config file - - It was never obvious which parts could be reloaded while live, and which required the application to be killed and restarted to take effect + - All `SessionFirewall` configuration options will no longer take effect +- `SIGHUP` handling to reload the configuration at runtime has been removed + - It was not obvious which parts of the configuration could be reloaded at runtime, and which required the application to be killed and restarted to take effect - Reloading the config without restarting was also a delicate and bug-prone process, and was distracting from more important developments - - SIGHUP will be handled normally (i.e. by exiting) -- The `doc` folder has been removed - - In light of the routing scheme's redesign and reimplementation, the documentation was out out-of-date - - New documentation may be added in a future release + - `SIGHUP` will be handled normally (i.e. by exiting) - `cmd/yggrasilsim` has been removed, and is unlikely to return to this repository ## [0.3.16] - 2021-03-18 From 540e0bc2ce92202745ed49891d8bb3adbe36b749 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Fri, 2 Jul 2021 23:11:16 +0100 Subject: [PATCH 2/4] Update changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4487ba2..bdb634f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -55,6 +55,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - The new DHT design is no longer RPC-based, does not support crawling and does not inherently allow nodes to look up the owner of an arbitrary key. Responding to lookups is now implemented at the application level and a response is only sent if the destination key matches the node's `/128` IP or `/64` prefix - The greedy routing scheme, used to forward all traffic in previous releases, is now only used for protocol traffic (i.e. DHT setup and source route discovery) - The routing logic now lives in a [standalone library](https://github.com/Arceliar/ironwood). You are encouraged **not** to use it, as it's still considered pre-alpha, but it's available for those who want to experiment with the new routing algorithm in other contexts + - Session MTUs may be slightly lower now, in order to accommodate large packet headers if required - Many of the admin functions available over `yggdrasilctl` have been changed or removed as part of rewrites to the code - Several remote `debug` functions have been added temporarily, to allow for crawling and census gathering during the transition to the new version, but we intend to remove this at some point in the (possibly distant) future - The list of available functions will likely be expanded in future releases @@ -63,7 +64,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Removed - Tunnel routing (a.k.a. crypto-key routing or "CKR") has been removed - It was far too easy to accidentally break routing altogether by capturing the route to peers with the TUN adapter - - We recommend tunnelling an existing standard over Yggdrasil instead (e.g. `ip6gre`, `ip6gretap` or other encapsulations) + - We recommend tunnelling an existing standard over Yggdrasil instead (e.g. `ip6gre`, `ip6gretap` or other similar encapsulations, using Yggdrasil IPv6 addresses as the tunnel endpoints) - All `TunnelRouting` configuration options will no longer take effect - Session firewall has been removed - This was never a true firewall — it didn't behave like a stateful IP firewall, often allowed return traffic unexpectedly and was simply a way to prevent a node from being flooded with unwanted sessions, so the name could be misleading and usually lead to a false sense of security From 4d47ba8bf4815855d75cb2fcac3568aadb8cecad Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Fri, 2 Jul 2021 23:21:38 +0100 Subject: [PATCH 3/4] Update README.md --- README.md | 33 ++++++++------------------------- 1 file changed, 8 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index d1d254a..a709ae4 100644 --- a/README.md +++ b/README.md @@ -20,25 +20,11 @@ internet-like topologies. ## Supported Platforms -We actively support the following platforms, and packages are available for -some of the below: +Yggdrasil works on a number of platforms, including Linux, macOS, Ubiquiti +EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt. -- Linux - - `.deb` and `.rpm` packages are built by CI for Debian and Red Hat-based - distributions - - Arch, Nix, Void packages also available within their respective repositories -- macOS - - `.pkg` packages are built by CI -- Ubiquiti EdgeOS - - `.deb` Vyatta packages are built by CI -- Windows -- FreeBSD -- OpenBSD -- OpenWrt - -Please see our [Platforms](https://yggdrasil-network.github.io/platforms.html) pages for more -specific information about each of our supported platforms, including -installation steps and caveats. +Please see our [Installation](https://yggdrasil-network.github.io/installation.html) +page for more information. You may also find other platform-specific wrappers, scripts or tools in the `contrib` folder. @@ -97,21 +83,18 @@ by giving the Yggdrasil binary the `CAP_NET_ADMIN` capability. ## Documentation -Documentation is available on our [GitHub -Pages](https://yggdrasil-network.github.io) site, or in the base submodule -repository within `doc/yggdrasil-network.github.io`. +Documentation is available on our [GitHub Pages](https://yggdrasil-network.github.io) +site. -- [Configuration file options](https://yggdrasil-network.github.io/configuration.html) -- [Platform-specific documentation](https://yggdrasil-network.github.io/platforms.html) +- [Configuration file](https://yggdrasil-network.github.io/configuration.html) - [Frequently asked questions](https://yggdrasil-network.github.io/faq.html) -- [Admin API documentation](https://yggdrasil-network.github.io/admin.html) - [Version changelog](CHANGELOG.md) ## Community Feel free to join us on our [Matrix channel](https://matrix.to/#/#yggdrasil:matrix.org) at `#yggdrasil:matrix.org` -or in the `#yggdrasil` IRC channel on Freenode. +or in the `#yggdrasil` IRC channel on [libera.chat](https://libera.chat). ## License From f7b91a8f939420f74ce8b911a6690fc961086033 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Fri, 2 Jul 2021 23:24:34 +0100 Subject: [PATCH 4/4] Update README.md --- README.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a709ae4..f1f71d1 100644 --- a/README.md +++ b/README.md @@ -11,23 +11,14 @@ allows pretty much any IPv6-capable application to communicate securely with other Yggdrasil nodes. Yggdrasil does not require you to have IPv6 Internet connectivity - it also works over IPv4. -Although Yggdrasil shares many similarities with -[cjdns](https://github.com/cjdelisle/cjdns), it employs a different routing -algorithm based on a globally-agreed spanning tree and greedy routing in a -metric space, and aims to implement some novel local backpressure routing -techniques. In theory, Yggdrasil should scale well on networks with -internet-like topologies. - ## Supported Platforms Yggdrasil works on a number of platforms, including Linux, macOS, Ubiquiti EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt. Please see our [Installation](https://yggdrasil-network.github.io/installation.html) -page for more information. - -You may also find other platform-specific wrappers, scripts or tools in the -`contrib` folder. +page for more information. You may also find other platform-specific wrappers, scripts +or tools in the `contrib` folder. ## Building @@ -83,10 +74,10 @@ by giving the Yggdrasil binary the `CAP_NET_ADMIN` capability. ## Documentation -Documentation is available on our [GitHub Pages](https://yggdrasil-network.github.io) -site. +Documentation is available [on our website](https://yggdrasil-network.github.io). -- [Configuration file](https://yggdrasil-network.github.io/configuration.html) +- [Installing Yggdrasil](https://yggdrasil-network.github.io/installation.html) +- [Configuring Yggdrasil](https://yggdrasil-network.github.io/configuration.html) - [Frequently asked questions](https://yggdrasil-network.github.io/faq.html) - [Version changelog](CHANGELOG.md)