|
1 |
| -# WireGuard Implementation for lwIP |
| 1 | +# WireGuard Implementation for ESP-IDF |
2 | 2 |
|
3 |
| -This project is a C implementation of the [WireGuard®](https://www.wireguard.com/) protocol intended to be used with the [lwIP IP stack](https://www.nongnu.org/lwip/) |
| 3 | +This is an implementation of the [WireGuard®](https://www.wireguard.com/) for ESP-IDF. |
4 | 4 |
|
5 |
| -# Motivation |
| 5 | +Almost all of this code is based on the [WireGuard Implementation for lwIP](https://github.com/smartalock/wireguard-lwip), but some potion of the code is adjusted to build with ESP- to run on ESP32 devices. |
6 | 6 |
|
7 |
| -There is a desire to use secure communication in smaller embedded devices to communicate with off-premises devices; WireGuard® seems perfect for this task due to its small code base and secure nature |
8 |
| - |
9 |
| -This project tackles the problem of using WireGuard® on embedded systems in that it is: |
10 |
| -- malloc-free so fits into a fixed RAM size |
11 |
| -- written entirely in C |
12 |
| -- has low memory requirements in terms of stack size, flash storage and RAM |
13 |
| -- compatible with the popular lwIP IP stack |
14 |
| - |
15 |
| -# Code Layout |
16 |
| - |
17 |
| -The code is split into four main portions |
18 |
| - |
19 |
| -- wireguard.c contains the bulk of the WireGuard® protocol code and is not specific to any particular IP stack |
20 |
| -- wireguardif.c contains the lwIP integration code and makes a netif network interface and handles periodic tasks such as keepalive/expiration timers |
21 |
| -- wireguard-platform.h contains the definition of the four functions to be implemented per platform (a sample implementation is given in wireguard-platform.sample) |
22 |
| -- crypto code (see below) |
23 |
| - |
24 |
| -## Crypto Code |
25 |
| - |
26 |
| -The supplied cryptographic routines are written entirely in C and are not optimised for any particular platform. These work and use little memory but will probably be slow on your platform. |
27 |
| - |
28 |
| -You probably want to swap out the suplied versions for optimised C or assembly versions or those available throught the O/S or crypto libraries on your platform. Simply edit the crypto.h header file to point at the routines you want to use. |
29 |
| - |
30 |
| -The crypto routines supplied are: |
31 |
| -- BLAKE2S - adapted from the implementation in the RFC itself at https://tools.ietf.org/html/rfc7693 |
32 |
| -- CHACHA20 - adapted from code at https://cr.yp.to/streamciphers/timings/estreambench/submissions/salsa20/chacha8/ref/chacha.c |
33 |
| -- HCHACHA20 - implemented from scratch following description here https://tools.ietf.org/id/draft-arciszewski-xchacha-02.html |
34 |
| -- POLY1305 - taken from https://github.com/floodyberry/poly1305-donna |
35 |
| -- CHACHA20POLY1305 - implemented from scratch following description here https://tools.ietf.org/html/rfc7539 |
36 |
| -- AEAD_XChaCha20_Poly1305 - implemented from scratch following description here https://tools.ietf.org/id/draft-arciszewski-xchacha-02.html |
37 |
| -- X25519 - taken from STROBE project at https://sourceforge.net/p/strobe, in addition there is a version optimised for Cortex-M0 processors which requires very little stack taken from https://munacl.cryptojedi.org/curve25519-cortexm0.shtml |
38 |
| - |
39 |
| -# Integrating into your platform |
40 |
| - |
41 |
| -You will need to implement a platform file that provides four functions |
42 |
| -- a monotonic counter used for calculating time differences - e.g. sys_now() from lwIP |
43 |
| -- a tain64n timestamp function, although there are workarounds if you don't have access to a realtime clock |
44 |
| -- an indication of whether the system is currently under load and should generate cookie reply messages |
45 |
| -- a good random number generator |
46 |
| - |
47 |
| -# lwIP Code Example |
48 |
| -(note error checking omitted) |
49 |
| - |
50 |
| - #include "wireguardif.h" |
51 |
| - |
52 |
| - static struct netif wg_netif_struct = {0}; |
53 |
| - static struct netif *wg_netif = NULL; |
54 |
| - static uint8_t wireguard_peer_index = WIREGUARDIF_INVALID_INDEX; |
55 |
| - |
56 |
| - static void wireguard_setup() { |
57 |
| - struct wireguard_interface wg; |
58 |
| - struct wireguardif_peer peer; |
59 |
| - ip_addr_t ipaddr = IPADDR4_INIT_BYTES(192, 168, 40, 10); |
60 |
| - ip_addr_t netmask = IPADDR4_INIT_BYTES(255, 255, 255, 0); |
61 |
| - ip_addr_t gateway = IPADDR4_INIT_BYTES(192, 168, 40, 1); |
62 |
| - |
63 |
| - // Setup the WireGuard device structure |
64 |
| - wg.private_key = "8BU1giso23adjCk93dnpLJnK788bRAtpZxs8d+Jo+Vg="; |
65 |
| - wg.listen_port = 51820; |
66 |
| - wg.bind_netif = NULL; |
67 |
| - |
68 |
| - // Register the new WireGuard network interface with lwIP |
69 |
| - wg_netif = netif_add(&wg_netif_struct, &ipaddr, &netmask, &gateway, &wg, &wireguardif_init, &ip_input); |
70 |
| - |
71 |
| - // Mark the interface as administratively up, link up flag is set automatically when peer connects |
72 |
| - netif_set_up(wg_netif); |
73 |
| - |
74 |
| - // Initialise the first WireGuard peer structure |
75 |
| - wireguardif_peer_init(&peer); |
76 |
| - peer.public_key = "cDfetaDFWnbxts2Pbz4vFYreikPEEVhTlV/sniIEBjo="; |
77 |
| - peer.preshared_key = NULL; |
78 |
| - // Allow all IPs through tunnel |
79 |
| - peer.allowed_ip = IPADDR4_INIT_BYTES(0, 0, 0, 0); |
80 |
| - peer.allowed_mask = IPADDR4_INIT_BYTES(0, 0, 0, 0); |
81 |
| - |
82 |
| - // If we know the endpoint's address can add here |
83 |
| - peer.endpoint_ip = IPADDR4_INIT_BYTES(10, 0, 0, 12); |
84 |
| - peer.endport_port = 12345; |
85 |
| - |
86 |
| - // Register the new WireGuard peer with the netwok interface |
87 |
| - wireguardif_add_peer(wg_netif, &peer, &wireguard_peer_index); |
88 |
| - |
89 |
| - if ((wireguard_peer_index != WIREGUARDIF_INVALID_INDEX) && !ip_addr_isany(&peer.endpoint_ip)) { |
90 |
| - // Start outbound connection to peer |
91 |
| - wireguardif_connect(wg_net, wireguard_peer_index); |
92 |
| - } |
93 |
| - } |
94 |
| - |
95 |
| - |
96 |
| -# More Information |
97 |
| - |
98 |
| -WireGuard® was created and developed by Jason A. Donenfeld. "WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld. See https://www.wireguard.com/ for more information |
| 7 | +# License |
99 | 8 |
|
100 |
| -This project is not approved, sponsored or affiliated with WireGuard or with the community. |
| 9 | +The original WireGuard implementation for lwIP is licensed under BSD 3 clause license so the code in this repository also licensed under the same license. |
101 | 10 |
|
102 |
| -- The whitepaper https://www.wireguard.com/papers/wireguard.pdf |
103 |
| -- The Wikipedia page https://en.wikipedia.org/wiki/WireGuard |
104 |
| - |
105 |
| -# License |
| 11 | +Original license is below: |
106 | 12 |
|
107 | 13 | The code is copyrighted under BSD 3 clause Copyright (c) 2021 Daniel Hope (www.floorsense.nz)
|
108 | 14 |
|
109 | 15 | See LICENSE for details
|
110 |
| - |
111 |
| -# Contact |
112 |
| - |
113 |
| -Daniel Hope at Smartalock |
0 commit comments