diff options
Diffstat (limited to 'content/docs/tutorials')
| -rw-r--r-- | content/docs/tutorials/ovpn-tut.md | 217 | ||||
| -rw-r--r-- | content/docs/tutorials/tutorial-2.md | 17 |
2 files changed, 226 insertions, 8 deletions
diff --git a/content/docs/tutorials/ovpn-tut.md b/content/docs/tutorials/ovpn-tut.md new file mode 100644 index 0000000..6db6812 --- /dev/null +++ b/content/docs/tutorials/ovpn-tut.md @@ -0,0 +1,217 @@ +--- +title: "Tutorial: How to create an encrypted IP tunnel" +draft: false +description: "ovpn" +date: 2019-08-31 +#type: page +draft: false +--- + +We recently added 256-bit ECDHE-AES encryption to Ouroboros (in the +_be_ branch). This tutorial shows how to create an *encrypted IP +tunnel* using the Ouroboros VPN (ovpn) tool, which exposes _tun_ +interfaces to inject Internet Protocol traffic into an Ouroboros flow. + +We'll first illustrate what's going on over an ethernet loopback +adapter and then show how to create an encrypted tunnel between two +machines connected over an IP network. + +<center> {{<figure +class="w-80" +src="/images/ovpn_tut.png">}} +</center> + +We'll create an encrypted tunnel between IP addresses 127.0.0.3 /24 and +127.0.0.8 /24, as shown in the diagram above. + +To run this tutorial, make sure that +[openssl](https://www.openssl.org) is installed on your machine(s) and +get the latest version of Ouroboros from the _be_ branch. + +``` +$ git clone --branch be https://ouroboros.rocks/git/ouroboros +$ cd ouroboros +$ mkdir build && cd build +$ cmake .. +$ make && sudo make install +``` + +# Encrypted tunnel over the loopback interface + +Open a terminal window and start ouroboros (add --stdout to log to +stdout): + +``` +$ sudo irmd --stdout +``` + +To start, the network will just consist of the loopback adapter _lo_, +so we'll create a layer _my\_layer_ consisting of a single ipcp-eth-dix +named _dix_, register the name _my\_vpn_ for the ovpn server in +_my\_layer_, and bind the ovpn binary to that name. + +``` +$ irm ipcp bootstrap type eth-dix name dix layer my_layer dev lo +$ irm reg name my_vpn layer my_layer +$ irm bind program ovpn name my_vpn +``` + +We can now start an ovpn server on 127.0.0.3. This tool requires +superuser privileges as it creates a tun device. + +``` +$ sudo ovpn --ip 127.0.0.3 --mask 255.255.255.0 +``` + +From another terminal, we can start an ovpn client to connect to the +server (which listens to the name _my\_vpn_) and pass the --crypt +option to encrypt the tunnel: + +``` +$ sudo ovpn -n my_vpn -i 127.0.0.8 -m 255.255.255.0 --crypt +``` + +The ovpn tool now created two _tun_ interfaces attached to the +endpoints of the flow, and will act as an encrypted pipe for any +packets sent to that interface: + +``` +$ ip a +... +6: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UNKNOWN group default qlen 500 + link/none + inet 127.0.0.3/24 scope host tun0 + valid_lft forever preferred_lft forever + inet6 fe80::f81d:9038:9358:fdf4/64 scope link stable-privacy + valid_lft forever preferred_lft forever +7: tun1: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UNKNOWN group default qlen 500 + link/none + inet 127.0.0.8/24 scope host tun1 + valid_lft forever preferred_lft forever + inet6 fe80::c58:ca40:5839:1e32/64 scope link stable-privacy + valid_lft forever preferred_lft forever +``` + +To test the setup, we can tcpdump one of the _tun_ interfaces, and +send some ping traffic into the other _tun_ interface. +The encrypted traffic can be shown by tcpdump on the loopback interface. +Open two more terminals: + +``` +$ sudo tcpdump -i tun1 +``` + +``` +$ sudo tcpdump -i lo +``` + +and from another terminal, send some pings into the other endpoint: + +``` +$ ping 10.10.10.1 -i tun0 +``` + +The tcpdump on the _tun1_ interface shows the ping messages arriving: + +``` +$ sudo tcpdump -i tun1 +[sudo] password for dstaesse: +tcpdump: verbose output suppressed, use -v or -vv for full protocol decode +listening on tun1, link-type RAW (Raw IP), capture size 262144 bytes +13:35:20.229267 IP heteropoda > 10.10.10.1: ICMP echo request, id 3011, seq 1, length 64 +13:35:21.234523 IP heteropoda > 10.10.10.1: ICMP echo request, id 3011, seq 2, length 64 +13:35:22.247871 IP heteropoda > 10.10.10.1: ICMP echo request, id 3011, seq 3, length 64 +``` + +while the tcpdump on the loopback shows the AES encrypted traffic that +is actually sent on the flow: + +``` +$ sudo tcpdump -i lo +tcpdump: verbose output suppressed, use -v or -vv for full protocol decode +listening on lo, link-type EN10MB (Ethernet), capture size 262144 bytes +13:35:20.229175 00:00:00:00:00:00 (oui Ethernet) > 00:00:00:00:00:00 (oui Ethernet), ethertype Unknown (0xa000), length 130: + 0x0000: 0041 0070 31f2 ae4c a03a 3e72 ec54 7ade .A.p1..L.:>r.Tz. + 0x0010: f2f3 1db4 39ce 3b62 d3ad c872 93b0 76c1 ....9.;b...r..v. + 0x0020: 4f76 b977 aa66 89c8 5c3c eedf 3085 8567 Ov.w.f..\<..0..g + 0x0030: ed60 f224 14b2 72d1 6748 b04a 84dc e350 .`.$..r.gH.J...P + 0x0040: d020 637a 6c2c 642a 214b dd83 7863 da35 ..czl,d*!K..xc.5 + 0x0050: 28b0 0539 a06e 541f cd99 7dac 0832 e8fb (..9.nT...}..2.. + 0x0060: 9e2c de59 2318 12e0 68ee da44 3948 2c18 .,.Y#...h..D9H,. + 0x0070: cd4c 58ed .LX. +13:35:21.234343 00:00:00:00:00:00 (oui Ethernet) > 00:00:00:00:00:00 (oui Ethernet), ethertype Unknown (0xa000), length 130: + 0x0000: 0041 0070 4295 e31d 05a7 f9b2 65a1 b454 .A.pB.......e..T + 0x0010: 5b6f 873f 0016 16ea 7c83 1f9b af4a 0ff2 [o.?....|....J.. + 0x0020: c2e6 4121 8bf9 1744 6650 8461 431e b2a0 ..A!...DfP.aC... + 0x0030: 94da f17d c557 b5ac 1e80 825c 7fd8 4532 ...}.W.....\..E2 + 0x0040: 11b3 4c32 626c 46a5 b05b 0383 2aff 022a ..L2blF..[..*..* + 0x0050: e631 e736 a98e 9651 e017 7953 96a1 b959 .1.6...Q..yS...Y + 0x0060: feac 9f5f 4b02 c454 7d31 e66f 2d19 3eaf ..._K..T}1.o-.>. + 0x0070: a5c8 d77f .... +13:35:22.247670 00:00:00:00:00:00 (oui Ethernet) > 00:00:00:00:00:00 (oui Ethernet), ethertype Unknown (0xa000), length 130: + 0x0000: 0041 0070 861e b65e 4227 5a42 0db4 8317 .A.p...^B'ZB.... + 0x0010: 6a75 c0c1 94d0 de18 10e9 45f3 db96 997f ju........E..... + 0x0020: 7461 2716 d9af 124d 0dd0 b6a0 e83b 95e7 ta'....M.....;.. + 0x0030: 9e5f e4e6 068f d171 727d ba25 55c7 168b ._.....qr}.%U... + 0x0040: 7aab 2d49 be53 1133 eab0 624a 5445 d665 z.-I.S.3..bJTE.e + 0x0050: ca5c 7a28 9dfa 58c2 e2fd 715d 4b87 246a .\z(..X...q]K.$j + 0x0060: f54c b8c8 5040 1c1b aba1 6107 39e7 604b .L..P@....a.9.`K + 0x0070: 5fb2 73ef +``` + +# Encrypted tunnel between two IP hosts connected to the Internet + +To create an encrypted tunnel between two Internet hosts, the same +procedure can be followed. The only difference is that we need to use +an ipcpd-udp on the end hosts connected to the ip address of the +machine, and on the client side, add the MD5 hash for that name to the +hosts file. The machines must have a port that is reachable from +outside, the default is 3435, but this can be configured using the +sport option. + +On both machines (fill in the correct IP address): + +``` +irm i b t udp n udp l my_layer ip <address> +``` + +On the server machine, bind and register the ovpn tool as above: + +``` +$ irm reg name my_vpn layer my_layer +$ irm bind program ovpn name my_vpn +``` + +On the _client_ machine, add a DNS entry for the MD5 hash for "my_vpn" +with the server IP address to /etc/hosts: + +``` +$ cat /etc/hosts +# Static table lookup for hostnames. +# See hosts(5) for details. + +... + +<server_ip> 2694581a473adbf3d988f56c79953cae + +``` + +and you should be able to create the ovpn tunnel as above. + +On the server: + +``` +$ sudo ovpn --ip 127.0.0.3 --mask 255.255.255.0 +``` + +And on the client: + +``` +$ sudo ovpn -n my_vpn -i 127.0.0.8 -m 255.255.255.0 --crypt +``` + +--- + +Changelog: + +2018-08-31: Initial version.
\ No newline at end of file diff --git a/content/docs/tutorials/tutorial-2.md b/content/docs/tutorials/tutorial-2.md index 392a659..c3925dc 100644 --- a/content/docs/tutorials/tutorial-2.md +++ b/content/docs/tutorials/tutorial-2.md @@ -3,18 +3,19 @@ title: "Tutorial 2: Adding a layer" draft: false --- -In this tutorial we will add a *normal layer* on top of the local layer. -Make sure you have a local layer running. The network will look like -this: +In this tutorial we will add a __unicast layer__ on top of the local +layer. Make sure you have a [local +layer](/docs/tutorials/tutorial-1/) running. The network will look +like this: - + -Let's start adding the normal layer. We will first bootstrap a normal -IPCP, with name "normal_1" into the "normal_layer" (using default -options). In terminal 2, type: +Let's start adding the unicast layer. We will first bootstrap a +unicast IPCP, with name "U1" into the layer "U" (using +default options). In terminal 2, type: ``` -$ irm ipcp bootstrap type normal name normal_1 layer normal_layer +$ irm ipcp bootstrap type unicast name U1 layer U ``` The IRMd and IPCP will report the bootstrap: |