Author: Harry Pantazis

It has been a wild ride and this post marks the completion of GSoC 2019 for WireGuard Tunneling in BMX7. Throughout the summer a lot of effort has been put into coding, documentation and codebase restructuring; it has been a appetizer for what awaits us coming Autumn.

• My fork can be found here.
• WireGuard Plugin branch can be found here.

Overview

During the final phase of GSoC 2019, focus has been put into recombining what has already been done. An ideal goal had been to extend the wg_tun plugin functionality with the routing of traffic between associated peers, but this remains a work in progress. Testing has taken place and quite a few SIGSEGVs have monopolized interest. Also, research has been contacted on whether and how to cryptographic primitives used in BMX7 and WireGuard. This seems infeasible currently, due to the differences between cryptographic keys of the two.

The wg_tun Plugin

Our ultimate and prime goal has been the beta release of this plugin. The plugin offers BMX7 the capability of setting up an iproute2 WireGuard device interface with a unique pair of keys that is automatically looking for all available peers and establishes a connection with them.

In the current approach we have designed along with Axel an approach about the unique cryptographic address assigned to the wg interface (a concept similar to the existing), where the BMX7-WG auto-configured IPv6 address is a product of the unique prefix fd77::16 and the first 14 bytes of the node’s SHA224 hash. Research goes on in this to figure out the best approach (network and cryptography wise).

In the past days we saw the creation of wg_status option and the addition of debug flags to inform an administrator of the state of his WG device (related commit).

At this stage, testing is being performed to analyse the behaviour of the plugin after the associations among peers and include more status information and more options for the control of the plugin by the user.

The “misses”

Of course when you go too optimistic into the dark something’s gonna not work out.

In this project the misses can be summarized in: devoting more time than initially expected into studying and researching and dropping some core goals for the sake of more important ones.

The goals we “skipped” have been the Debian Package and the refactoring of Mesh Linux Containers to aid with testing.

In the studying part, I was supposed to devote only the community bonding period and part of the first phase to study white paper and get up to speed with theory between what needed be implemented and fiddled. I ended up devoting time throughout all the phases, but I’m happy with what I’ve learned.

Further Work

The intention to continue work on BMX7 is trivial to answer. GSoC has been a good experience and way to get started with the codebase of BMX7, but free flowing, detrimental work is scheduled for after it.

• Add command line functionality for the wg_tun plugin, include it along with the Refactor of command line arguments issue,
• Add more developer documentation for BMX7 newcomers, like Plugin Creation and Glossary,
• Create the bmx7 Debian package (check here),
• Rework mlc into mlc-ng (as reported here).

Final Thoughts

I’m very happy I got the chance to help Freifunk’s goals and hope to continue however I can.

Battlmesh V12 was super nice and I look forward to next year’s (I hope it’s Netherlands).

At last, I would like to thank my mentors Paul Spooren and Axel Neumann for their advice and way they approach cooperation.

It’s a wrap for phase one! We have managed to keep up with the goals we set for ourselves and along with my mentor Paul Spooren we have shaken up BMX7 development all around.

Documentation Refactor

One of this phase’s goals was to understand BMX7 functionality, usage and plugins. With a lot of reading (both in-project documentation and with external sources) this was achieved and I was much more synced. While doing so I refactored some pieces of docs to help me and I found a branch I had created with some generic changes that I made in the Community Bonding phase.

These acted as inspiration and I got together a big batch of changes commited and PR’d to the bmx7 upstream.

The PR can be found here and its purpose is to achieve generic changes to ease the introduction of new developers and users to the project, as well as ease the learning curve of usage.

More info one can found in the following blogpost that describes things in detail:

• https://blog.luserx0.cc/GSoC-GSoC-2019-Week-3-Documentation-and-Instrumentation/

It’s worth to be noted that this was not a goal per-se of the phase and that changes did take place, but they sparked other changes that are still WIP on the PR.

Testing Infrastructure

Establish the following Testing setups for testing and later on continuous integration:

• LXC running OpenWrt bridged mesh.
• Qemu OpenWrt bridged mesh networks

The idea was to establish Linux Containers and Qemu infrastructures to do testing and experimentation. Along with aparcar my mentor “we salvaged from oblivion” a very interesting and well-set project that axn had created named Mesh Linux Containers (MLC) and which takes on its own the creation, configuration and command and control (CnC) of a virtualized mesh network on a Linux host, supporting an abundance of community mesh protocols. Paul took on him the modernization of this project producing the new generation of MLC, which switches mlc’s functionalities from the shell scripting era to LXC and distrobuilder to autocreate and populate an OpenWRT mesh mother and OpenWRT clients.

On the above I also based my testing infrastructure, but being a Qubes OS user and relatively confused with LXC versions (a newb), I kept coming across issues.

The situation was able to be relaxed by investing time on QEMU for love and support (as one may find here). Again though problems like libvirt on Qubes, multiple Qemu interfaces and tricky bridging tricks on a standalone VM didn’t allow me to have the results I was hoping for.

Hence, armboards were chosen. I borrowed boards from the hackerspace.gr common sharing stash of toys and I was able to interconnect a Raspberry Pi 1B, one Raspberry Pi 3B and a BeagleBone Black.

This approach is optimal for me to establish decent OpenWrt routers to test and play, that can painlessly run BMX7 (and Wireguard) and leave to the local community things to use like mesh boxes and on-the-go VPN-configured APs.

(The bmx7 luci app works like clockwork btw.)

BMX7 wg_tun Plugin

The initial goal was to implement wrapper functions to WG and establish a secure tunnel that way. This adds an overhead in the development phase, because making wg binary calls is both costly and requires to place code in places where no further improvements can be achieved.

For this reason, the embeddable wireguard implementation was chosen and we switched from addition(to the current tun src) to the creation of the wg_tun plugin earlier on than what was planned.

The idea is that adhering to the current implementation of the tunneling plugin of BMX7 we can reuse some minimum parts and establish:

• The creation of a public and a private wg key associated with the current bmx7 session (or persist across sessions).
• The advertisement of these keys and the network(IP) associated with our interface through descriptive updates for our peers to find us.
• The establishment of connections with peers that have advertised their public keys and networks (and we’ve caught them), a la tunnel announcements style.

This goal is still WIP as more testing needs to take place and optimal ways and options for bmx7 node administrators to use it. In general, for this part and until further work has been put in, the paradigm of danrl for the luci-proto-wireguard package is being followed in the sense that we want the establishment of bmx7 wg tunnel to be that easy and the static configuration or the randomized UDP ports can help get there faster.

Progress can be found on the implementation’s branch on my fork (https://github.com/luserx0/bmx7/tree/wg_tun_plugin)

Developer Misc

My dotfiles repo has seen a lot of action this first period. The refactoring of my vimrc took place to help me in reading through code (a lot of code). The configs are managed through GNU Stow. If something catches your eye, clone, run the install script, tweak and share back.

My personal Blog saw also some pretty intense developments too to make progress report sharing and tutorial posting humane. It’s based on hexo and hexo-next, it’s static and hosted on gh-pages. Perfect combo for a GSoC student. Feel free to grab it from here and use it under CC.

If you have questions on how BMX7 operates and/or is different from other mesh routing protocols feel free to post them here.

Next Steps

• Additions of features and options of the wg_plugin. Getting it merged on the upstream is a good milestone.
• Cleanup and research on reusing cryptographic and networking primitives common to Wireguard and BMX7.
• Creation of the bmx7 Debian Package.
• Port mlc functionality to mlc-ng.
• Finish the second phase of the documentation refactor.
• Attending Battemesh V12 😉
• Order hardware to play with

BMX7 is an IPv6 native dynamic routing protocol for mesh networks which offers very advanced features and a small network overhead – thanks to the distance-vector strategy and a set of optimizations – and a great way to extend its functionality via plugins. BMX7 is also referenced as SEMTOR (Securely-Entrusted Multi-Topology Routing for Community Networks).

(For Axel Neumann’s presentation of BMX7 on BattleMesh, as well as the SEMTOR Whitepapers refer to the Further Info section).

Project Abstract

BMX7 offers plugins which are used for the distribution of small files, settings up tunnels or offer stats of the network structure. Currently the connection between a client node and the gateway are established via IPIP (IPv4/6 over IPv6), which is unencrypted and therefore possibly readable by attackers. As mesh networks usually operate on unencrypted wireless connections, the attack vector is considerably big.

Our proposed solution is to combine the current cryptographic stack of BMX7 with the one used by WireGuard. The process via which this will be achieved will be iterative; meaning that first binary calls from bmx7 to userland WG will be introduced, afterwards the efforts will be centered in the creation of a new plugin implementing WireGuard routing by using part of the existing cryptographic primitives and at last the effort to combine the tunnel plugin with the wg one. In all of these one rule must be set: do not implement cryptography yourself; mistakes will be made.

The detail that distinguishes our approach’s difficulty from hard to medium is cryptographic keys. It’s simpler to announce new public keys for WireGuard and have a separate plugin than replacing the existing BMX7 keys to allow signing of descriptive updates and encryption of traffic.

WireGuard Overview

To portray some of the perks of the implementation, the following sections are quoted from the WireGuard Whitepaper.

WireGuard is a secure network tunnel, operating at layer 3, implementd as a kernel virtual network interface for Linux. (..) The virtual tunnel interface is based on a proposed fundamental principle of secure tunnels: an association between a peer public key and a tunnel source IP address. It uses a single round trip key exchange, based on NoiseIK, and handles all session creation transparently to the user using a novel timer state machine mechanism. Short pre-shared static keys–Curve25519 points–are used for mutual authentication. (..) Peers are identified strictly by their public key, a 32-byte Curve25519 point. (..) The protocol provides strong perfect forward secrecy in addition to a high degree of identity hiding. (..) An improved take-on IP-binding cookies is used for mitigating denial of service attacks, to add encryption and authentication. (..) Two WireGuard peers exchange their public keys through some unspecified mechanism, and afterwards they are able to communicate. (..) It intentionally lacks cipher and protocol agility (H: opinionated protocol).

From the official WireGuard Technical Paper, Sections: Intro, 1 and 2

For further, technical details refer to Section 5 of the WG paper.

Deliverables

• Implementation of wrapper functions to native WireGuard API for the establishment of the WireGuard tunnel.
• Creation of a new WG tunnel plugin based on a simplified version of the existing tun plugin, by use the aforementioned wrapper functions.
• The ultimate goal is the combination of the current tunnel plugin of BMX7 that incorporates IPv4/6 over IPv6 tunnels with the cryptographic stack of Wireguard, offering each administrator’s node to choose whether to encrypt or not through a command line parameter (tun + wg == crypt-tun).
• Stretch Goal: Applying the optional 32-byte pre-shared key that is mixed into the public key cryptography supported by WG for an additional layer of symmetric-key crypto for the purposes of resistance against post-quantum attacks that are potential for Curve25519.

Objectives

• Phase 1:
  • Understand BMX7 functionality, descriptions (descriptive updates) and plugin system.
  • Understand the WireGuard cryptographic stack and tunneling.
  • Establish the following Testing setups for testing and later on continuous integration:
    • LXC running OpenWrt bridged mesh.
    • Qemu OpenWrt bridged mesh networks.
  • Implement the initial wrapper functions to WG.
• Phase 2:
  • Release a Debian package for BMX7 (as described in the issue referenced in Further Info section)
  • Polish and test the wrapper function for the establishment of the WireGuard tunnel
  • Create the WG tunnel plugin, based on the wrapper functions.
• Phase 3:
  • Test extensively on the CI environments and troubleshoot.
  • Try to combine/reuse the cryptographic primitives of BMX7 and WG.
  • Refresh the user and developer documentation of BMX7.

About Me

I’m an open-source advocate, supporter of FOSS communities and student currently dwelling in Athens. My purposes span around the empowering of pro-consensus community networks (either technical or human), distributed and censorship resistant (focusing in the lower Balkan area communities, where adversaries for freedom in the mainstream Internet have begun to thrive).

A milestone for myself would be to meet the people that have created the software that our communities use and be able to interact and hack together.

For this reason my best efforts will go into making it to meetings such as Battlemesh in Paris, CC Camp and Bornhack happening this summer.

Further Info:

1. Debian Packaging for BMX7 GH Issue
2. WireGuard Network Namespaces and Routing
3. BattleMesh 2016 BMX7 Presentation
4. WireGuard Key Exchange
5. WireGuard mailing list on roaming between IPv4 and IPv6
6. WireGuard mailing list on HW-related Timestamps
7. SEMTOR Overview
8. SEMTOR in detail