src/plugins/wireguard/README.md

   1 # Wireguard vpp-plugin
   2
   3 ## Overview
   4 This plugin is an implementation of [wireguard protocol](https://www.wireguard.com/) for VPP. It allows one to create secure VPN tunnels.
   5 This implementation is based on [wireguard-openbsd](https://git.zx2c4.com/wireguard-openbsd/), using the implementaiton of *ipip-tunnel*.
   6
   7 ## Crypto
   8
   9 The crypto protocols:
  10
  11 - blake2s [[Source]](https://github.com/BLAKE2/BLAKE2)
  12
  13 OpenSSL:
  14
  15 - curve25519
  16 - chachapoly1305
  17
  18 ## Plugin usage example
  19 Usage is very similar to other wireguard implementations.
  20
  21 ### Create connection
  22 Create keys:
  23
  24 ```
  25 > vpp# wg genkey
  26 > *my_private_key*
  27 > vpp# wg pubkey <my_private_key>
  28 > *my_pub_key*
  29 ```
  30
  31 Create tunnel:
  32 ```
  33 > vpp# create ipip tunnel src <ip4_src> dst <ip4_dst>
  34 > *tun_name*
  35 > vpp# set int state <tun_name> up
  36 > vpp# set int ip address <tun_name> <tun_ip4>
  37 ```
  38
  39 After this we can create wg-device. The UDP port is opened automatically.
  40 ```
  41 > vpp# wg set device private-key <my_private_key> src-port <my_port>
  42 ```
  43
  44 Now, we can add a peer configuration:
  45 ```
  46 > vpp# wg set peer public-key <peer_pub_key> endpoint <peer_ip4> allowed-ip <peer_tun_ip4> dst-port <peer_port> tunnel <tun_name> persistent-keepalive <keepalive_interval>
  47 ```
  48 If you need to add more peers, don't forget to first create another ipip-tunnel.
  49 Ping.
  50 ```
  51 > vpp# ping <peer_tun_ip4>
  52 ```
  53 ### Show config
  54 To show device and all peer configurations:
  55 ```
  56 > vpp# show wg
  57 ```
  58
  59 ### Remove peer
  60 Peer can be removed by its public-key.
  61 ```
  62 > vpp# wg remove peer <peer_pub_key>
  63 ```
  64 This removes the associated ipip tunnel as well
  65
  66 ### Clear all connections
  67 ```
  68 > vpp# wg remove device
  69 ```
  70
  71 ## main next steps for improving this implementation
  72 1. Use all benefits of VPP-engine.
  73 2. Add IP6 support (currently only supports IPv4))
  74 3. Add DoS protection as in original protocol (using cookie)