boringtun - a userspace Wireguard implementation

.cargo/config

@@ -0,0 +1,8 @@
+[build]
+rustflags = [
+    "-C", "llvm-args=-slp-recursion-max-depth=1024",
+    "--emit", "asm", # For whatever reason rustc produces faster code when this flag is enabled
+]
+
+[target.'cfg(unix)']
+runner = 'sudo -E'

.gitignore

@@ -0,0 +1,2 @@
+/target
+**/*.rs.bk

Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "boringtun"
+version = "0.2.0"
+authors = ["Vlad Krasnov <[email protected]>"]
+
+[dependencies]
+base64 = "0.9.2"
+hex = "0.3.2"
+untrusted = "0.6.2"
+spin = { version = "0.5", default-features=false }
+libc = "0.2"
+
+[target.'cfg(not(target_arch="arm"))'.dependencies]
+ring = "0.14"
+
+[target.'cfg(not(any(target_os="windows", target_os="ios", target_os="android")))'.dependencies]
+chrono = "0.4"
+daemonize = {git = "https://github.com/vkrasnov/daemonize", rev = "fedb687a8d99b300b8461e650a598ded54a334a0"}
+clap = { version = "2.32.0", default-features=false, features = ["suggestions"] }
+
+[target.'cfg(target_os="android")'.dependencies]
+jni = "0.10.2"
+
+[lib]
+crate-type = ["lib", "staticlib", "dylib"]
+
+[[bin]]
+name = "boringtun"
+path = "src/main.rs"
+
+[[example]]
+name = "benchmarks"
+path = "src/benchmarks_example.rs"

LICENSE.md

@@ -0,0 +1,9 @@
+Copyright (c) 2019 Cloudflare, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,71 @@
+# boringtun
+
+**boringtun** is an implementation of the [WireGuard<sup>®</sup>](https://www.wireguard.com/) protocol designed for portability and speed.
+
+The project consists of two parts:
+
+* The executable `boringtun`, a [userspace WireGuard](https://www.wireguard.com/xplatform/) implementation for Linux and macOS.
+* The library `boringtun` that can be used to implement fast and efficient WireGuard client apps on various platforms, including iOS and Android. It implements the underlying WireGuard protocol, without the network or tunnel stacks, those can be implemented in a platform idiomatic way.
+
+### Building
+
+- Library only: `cargo build --lib --release [--target $(TARGET_TRIPLE)]`
+- Executable: `cargo build --bin boringtun --release [--target $(TARGET_TRIPLE)]`
+
+By default the executable is placed in the `./target/release` folder. You can copy it to a desired location manually, or install it using `cargo install --bin boringtun --path .`.
+
+### Running
+
+As per the specification, to start a tunnel use:
+
+`boringtun [-f/--foreground] INTERFACE-NAME`
+
+The tunnel can then be configured using [wg](https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8), as a regular WireGuard tunnel, or any other tool.
+
+It is also possible to use with [wg-quick](https://git.zx2c4.com/WireGuard/about/src/tools/man/wg-quick.8) by setting the enviroment variable `WG_QUICK_USERSPACE_IMPLEMENTATION` to `boringtun`. For example:
+
+`sudo WG_QUICK_USERSPACE_IMPLEMENTATION=boringtun wg-quick up CONFIGURATION`
+
+## Supported platforms
+
+Target triple                 |Binary|Library|                 |
+------------------------------|:----:|:-----:|-----------------|
+x86_64-unknown-linux-gnu      |  ✓   |   ✓   |[![Build Status](https://dev.azure.com/cloudflare-ps/wireguard-cf/_apis/build/status/cloudflare.wireguard?branchName=server&jobName=Linux%20x86-64)](https://dev.azure.com/cloudflare-ps/wireguard-cf/_build/latest?definitionId=3&branchName=server)
+aarch64-unknown-linux-gnu     |  ✓   |   ✓   |[![Build Status](https://dev.azure.com/cloudflare-ps/wireguard-cf/_apis/build/status/cloudflare.wireguard?branchName=server&jobName=Linux%20aarch64)](https://dev.azure.com/cloudflare-ps/wireguard-cf/_build/latest?definitionId=3&branchName=server)
+armv7-unknown-linux-gnueabihf |  ✓   |   ✓   |[![Build Status](https://dev.azure.com/cloudflare-ps/wireguard-cf/_apis/build/status/cloudflare.wireguard?branchName=server&jobName=Linux%20armv7)](https://dev.azure.com/cloudflare-ps/wireguard-cf/_build/latest?definitionId=3&branchName=server)
+x86_64-apple-darwin           |  ✓   |   ✓   |[![Build Status](https://dev.azure.com/cloudflare-ps/wireguard-cf/_apis/build/status/cloudflare.wireguard?branchName=server&jobName=macOS)](https://dev.azure.com/cloudflare-ps/wireguard-cf/_build/latest?definitionId=3&branchName=server)
+x86_64-pc-windows-msvc        |      |   ✓   |[![Build Status](https://dev.azure.com/cloudflare-ps/wireguard-cf/_apis/build/status/cloudflare.wireguard?branchName=server&jobName=Windows)](https://dev.azure.com/cloudflare-ps/wireguard-cf/_build/latest?definitionId=3&branchName=server)
+aarch64-apple-ios             |      |   ✓   |FFI bindings
+armv7-apple-ios               |      |   ✓   |FFI bindings
+armv7s-apple-ios              |      |   ✓   |FFI bindings
+aarch64-linux-android         |      |   ✓   |JNI bindings
+arm-linux-androideabi         |      |   ✓   |JNI bindings
+
+<sub>Other platforms may be added in the future</sub>
+
+#### Linux
+
+`x86-64`, `aarch64` and `armv7` architecures are supported. The behaviour should be identical to that of [wireguard-go](https://git.zx2c4.com/wireguard-go/about/), with the following difference:
+
+`boringtun` will drop priviliges when started. When priviliges are dropped it is not possible to set `fwmark`. If `fwmark` is required, instead running with `sudo`, give the executable the `CAP_NET_ADMIN` capability using: `sudo setcap cap_net_admin+epi boringtun`. Alternatively run with `--disable-drop-priviliges`.
+
+#### macOS
+
+The behaviour is similar to that of [wireguard-go](https://git.zx2c4.com/wireguard-go/about/). Specifically the interface name must be `utun[0-9]+` for an explicit interface name or `utun` to have the kernel select the lowest available. If you choose `utun` as the interface name, and the environment variable `WG_TUN_NAME_FILE` is defined, then the actual name of the interface chosen by the kernel is written to the file specified by that variable.
+
+---
+
+#### FFI bindings
+
+The library exposes a set of C ABI bindings, those are defined in the `wireguard_ffi.h` header file. The C bindings can be used with C/C++, Swift (using a bridging header) or C# (using [DLLImport](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.dllimportattribute?view=netcore-2.2) with [CallingConvention](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.dllimportattribute.callingconvention?view=netcore-2.2) set to `Cdecl`).
+
+#### JNI bindings
+
+The library exposes a set of Java Native Interface bindings, those are defined in `src/cfjni/mod.rs`.
+
+## License
+
+The project is licensed under the [3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).
+
+---
+<sub><sub><sub><sub>WireGuard is a registered trademark of Jason A. Donenfeld. boringtun is not sponsored or endorsed by Jason A. Donenfeld.</sub></sub></sub></sub>

azure-pipelines.yml

@@ -0,0 +1,67 @@
+jobs:
+
+- job: Windows
+  displayName: 'Windows'
+  pool:
+    vmImage: 'vs2017-win2016'
+  continueOnError: true
+  steps:
+  - script: curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
+    displayName: 'Install cargo'
+  - script: |
+      PATH=%PATH%;%USERPROFILE%\.cargo\bin
+      cargo build --lib
+    displayName: 'Build library'
+  - script: |
+      PATH=%PATH%;%USERPROFILE%\.cargo\bin
+      cargo test --lib
+    displayName: 'Test library'
+
+- job: macOS
+  displayName: 'macOS'
+  pool:
+    vmImage: 'macOS-10.13'
+  continueOnError: true
+  steps:
+  - script: |
+      brew install wireguard-go wireguard-tools
+    displayName: 'Install wireguard-go'
+  - template: ci/azure-build.yml
+    parameters:
+      runBinaryTests: 'false'
+  - script: |
+      export PATH=$PATH:$HOME/.cargo/bin
+      rustup target add aarch64-apple-ios
+      cargo build --lib --target aarch64-apple-ios
+    displayName: 'Build library for iOS'
+
+- job: Linux_x86_64
+  displayName: 'Linux x86-64'
+  pool:
+    vmImage: 'ubuntu-16.04'
+  continueOnError: true
+  steps:
+  - script: |
+      sudo add-apt-repository ppa:wireguard/wireguard
+      sudo apt-get update
+      sudo apt-get install wireguard -y
+    displayName: 'Install wireguard'
+  - template: ci/azure-build.yml
+
+- job: Linux_aarch64
+  displayName: 'Linux aarch64'
+  pool:
+    name: default
+    demands: agent.name -equals aarch64
+  continueOnError: true
+  steps:
+  - template: ci/azure-build.yml
+
+- job: Linux_armv7
+  displayName: 'Linux armv7'
+  pool: 
+    name: default
+    demands: agent.name -equals armv7
+  continueOnError: true
+  steps:
+  - template: ci/azure-build.yml

benches/mod.rs

@@ -0,0 +1,100 @@
+// Copyright (c) 2019 Cloudflare, Inc. All rights reserved.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#![feature(test)]
+extern crate boringtun;
+extern crate test;
+
+#[cfg(test)]
+mod tests {
+    use boringtun::crypto::blake2s::*;
+    use boringtun::crypto::chacha20poly1305::*;
+    use boringtun::crypto::x25519::*;
+    use test::{black_box, Bencher};
+
+    #[bench]
+    fn bench_x25519_public_key(b: &mut Bencher) {
+        let secret_key = X25519SecretKey::new();
+
+        b.iter(|| {
+            black_box(secret_key.public_key());
+        });
+    }
+
+    #[bench]
+    fn bench_x25519_shared_key(b: &mut Bencher) {
+        let secret_key = X25519SecretKey::new();
+        let public_key = X25519SecretKey::new().public_key();
+
+        b.iter(|| {
+            black_box(secret_key.shared_key(&public_key));
+        });
+    }
+
+    #[bench]
+    fn bench_blake2s_hash_128b(b: &mut Bencher) {
+        let data = [0_u8; 128];
+        b.iter(|| black_box(Blake2s::new_hash().hash(&data).finalize()));
+    }
+
+    #[bench]
+    fn bench_blake2s_hash_1024b(b: &mut Bencher) {
+        let data = [0_u8; 1024];
+        b.iter(|| black_box(Blake2s::new_hash().hash(&data).finalize()));
+    }
+
+    #[bench]
+    fn bench_chacha20poly1305_seal_192b(b: &mut Bencher) {
+        let pc = ChaCha20Poly1305::new_aead(&[
+            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
+            25, 26, 27, 28, 29, 30, 31, 32,
+        ]);
+        let pt = [0_u8; 192];
+        let mut ct = [0_u8; 192 + 16];
+        b.iter(|| {
+            black_box(pc.seal_wg(0, &[], &pt, &mut ct));
+        });
+    }
+
+    #[bench]
+    fn bench_chacha20poly1305_open_192b(b: &mut Bencher) {
+        let pc = ChaCha20Poly1305::new_aead(&[
+            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
+            25, 26, 27, 28, 29, 30, 31, 32,
+        ]);
+        let mut pt = [0_u8; 192];
+        let mut ct = [0_u8; 192 + 16];
+
+        pc.seal_wg(0, &[], &pt, &mut ct);
+
+        b.iter(|| {
+            black_box(pc.open_wg(0, &[], &ct, &mut pt).unwrap());
+        });
+    }
+
+    #[bench]
+    fn bench_chacha20poly1305_seal_512b(b: &mut Bencher) {
+        let pc = ChaCha20Poly1305::new_aead(&[
+            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
+            25, 26, 27, 28, 29, 30, 31, 32,
+        ]);
+        let pt = [0_u8; 512];
+        let mut ct = [0_u8; 512 + 16];
+        b.iter(|| {
+            black_box(pc.seal_wg(0, &[], &pt, &mut ct));
+        });
+    }
+
+    #[bench]
+    fn bench_chacha20poly1305_seal_8192b(b: &mut Bencher) {
+        let pc = ChaCha20Poly1305::new_aead(&[
+            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
+            25, 26, 27, 28, 29, 30, 31, 32,
+        ]);
+        let pt = [0_u8; 8192];
+        let mut ct = [0_u8; 8192 + 16];
+        b.iter(|| {
+            black_box(pc.seal_wg(0, &[], &pt, &mut ct));
+        });
+    }
+}

ci/azure-build.yml

@@ -0,0 +1,29 @@
+
+parameters:
+  runBinaryTests: 'true'
+
+steps:
+  - script: |
+      curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
+    displayName: 'Install cargo'
+  - script: |
+      export PATH=$PATH:$HOME/.cargo/bin
+      cargo build --lib
+    displayName: 'Build library'
+  - script: |
+      export PATH=$PATH:$HOME/.cargo/bin
+      cargo test --lib -- --test-threads=1
+    displayName: 'Test library'
+  - script: |
+      export PATH=$PATH:$HOME/.cargo/bin
+      cargo test --lib -- --ignored --test-threads=1
+    displayName: 'Library integration tests'
+  - script: |
+      export PATH=$PATH:$HOME/.cargo/bin
+      cargo build --bin boringtun
+    displayName: 'Build executable'
+  - ${{ if eq(parameters.runBinaryTests, 'true') }}:
+    - script: |
+        export PATH=$PATH:$HOME/.cargo/bin
+        cargo test --bin boringtun -- --test-threads=1
+      displayName: 'Test executable'

src/benchmarks_example.rs

@@ -0,0 +1,28 @@
+// Copyright (c) 2019 Cloudflare, Inc. All rights reserved.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#![allow(warnings)]
+extern crate base64;
+extern crate hex;
+extern crate libc;
+extern crate ring;
+extern crate spin;
+
+mod crypto;
+mod ffi;
+mod noise;
+
+use ffi::benchmark::do_benchmark;
+use std::io::prelude::Write;
+
+fn main() {
+    let mut i = 0;
+    while let Some(benchmark_name) = do_benchmark(true, i) {
+        print!("{}", benchmark_name);
+        std::io::stdout().flush().unwrap();
+        let benchmark_result = do_benchmark(false, i).unwrap();
+        println!("{}", benchmark_result);
+        i += 1;
+    }
+    println!("Done");
+}