RIOT/tests/pkg_edhoc_c/README.md

# EDHOC-C test application

This test application sets up a RIOT node that can run as an EDHOC handshake
initiator and/or responder. The handshake can be run between two RIOT nodes or
between a RIOT node and a Linux host or for testing purposes the node can
perform an auto-handshake.

In this example credentials based on LAKE IETF WG are used. These are RPK keys.
Normally different credentials should be used depending on the authentication
method, but currently no validation is done so the same credentials can be
used for any method.

## EDHOC handshake between host and RIOT node

### Pre-requisites

- install [py-edhoc](https://github.com/openwsn-berkeley/py-edhoc):

```
$ pip install edhoc
```

This will install two cli utils `edhoc-responder` and `edhoc-initiator` to
facilitate testing.

#### `native`

- if using native set up a tap interface:

```
$ sudo ip tuntap add tap0 mode tap user ${USER}
$ sudo ip link set tap0 up
```

#### physical `BOARD`

- If using any other (non-emulated) `BOARD` then in one terminal:

```
 $ sudo dist/tools/ethos/setup_network.sh riot0 2001:db8::/64
```

This will create a tap interface called `riot0`, owned by the user. It will
also run an instance of uhcpcd, which starts serving the prefix
`2001:db8::/64`. Keep the shell open as long as you need the network.
Make sure to exit the "make term" instance from the next section *before*
exiting this, as otherwise the "riot0" interface doesn't get cleaned up
properly.

### Responder

Find out the ipv6 address of the device is by running the `ifconfig`
command in the shell.

```
ifconfig
Starting the shell
> ifconfig
ifconfig
Iface  5  HWaddr: 0A:94:29:80:74:23
          L2-PDU:1500  MTU:1500  HL:64  RTR
          RTR_ADV
          Source address length: 6
          Link type: wired
          inet6 addr: fe80::894:29ff:fe80:7423  scope: link  VAL
          inet6 group: ff02::2
          inet6 group: ff02::1
          inet6 group: ff02::1:ff80:7423
```

In this case its `fe80::894:29ff:fe80:7423` and since we setup `tap0` as
the tap interface the device is reachable at `[fe80::894:29ff:fe80:7423%tap0]`.

Initiate the handshake by running the `edhoc-initiator` cli tool:

```
$ edhoc-initiator  fe80::894:29ff:fe80:7423%tap0]
INFO:root:POST (EdhocState.MSG_1_SENT)  b'\x01\x00X \x89\x8f\xf7\x9a\x02\x06z\x16\xea\x1e\xcc\xb9\x0f\xa5"F\xf5\xaaM\xd6\xec\x07k\xba\x02Y\xd9\x04\xb7\xec\x8b\x0c@'
INFO:root:CHANGED (EdhocState.MSG_1_SENT)  b'X q\xa3\xd5\x99\xc2\x1d\xa1\x89\x02\xa1\xae\xa8\x10\xb2\xb68,\xcd\x8d_\x9b\xf0\x19R\x81uL^\xbc\xaf0\x1e\x13XP\x99\xd58\x01\xa7%\xbf\xd6\xa4\xe7\x1d\x04\x84\xb7U\xec8=\xf7z\x91n\xc0\xdb\xc0+\xba|!\xa2\x00\x80{OX_r\x8bg\x1a\xd6x\xa4:\xac\xd3;x\xeb\xd5f\xcd\x00O\xc6\xf1\xd4\x06\xf0\x1d\x97\x04\xe7\x05\xb2\x15R\xa9\xeb(\xea1j\xb6P7\xd7\x17\x86.'
INFO:root:POST (EdhocState.MSG_3_SENT)  b'\x01\x00X \x89\x8f\xf7\x9a\x02\x06z\x16\xea\x1e\xcc\xb9\x0f\xa5"F\xf5\xaaM\xd6\xec\x07k\xba\x02Y\xd9\x04\xb7\xec\x8b\x0c@'
INFO:root:EDHOC key exchange successfully completed:
INFO:root: - connection IDr: b'+'
INFO:root: - connection IDi: b''
INFO:root: - aead algorithm: AES_CCM_16_64_128
INFO:root: - hash algorithm: SHA_256
INFO:root: - OSCORE secret : b'Y!1k\xae\x12\xc9\xc4\xd2\xb9\xfb \xcc\x1a\x12\xdd'
INFO:root: - OSCORE salt   : b'\xad\xf9\xfd\xbed\x98\xa3\x02'
```

And on the device (responder):

```
> [responder]: received an EDHOC message (len 37)
0x01 0x00 0x58 0x20 0x89 0x8f 0xf7 0x9a
0x02 0x06 0x7a 0x16 0xea 0x1e 0xcc 0xb9
0x0f 0xa5 0x22 0x46 0xf5 0xaa 0x4d 0xd6
0xec 0x07 0x6b 0xba 0x02 0x59 0xd9 0x04
0xb7 0xec 0x8b 0x0c 0x40

[responder]: sending msg2 (117 bytes)
0x58 0x20 0x71 0xa3 0xd5 0x99 0xc2 0x1d
0xa1 0x89 0x02 0xa1 0xae 0xa8 0x10 0xb2
0xb6 0x38 0x2c 0xcd 0x8d 0x5f 0x9b 0xf0
0x19 0x52 0x81 0x75 0x4c 0x5e 0xbc 0xaf
0x30 0x1e 0x13 0x58 0x50 0x99 0xd5 0x38
0x01 0xa7 0x25 0xbf 0xd6 0xa4 0xe7 0x1d
0x04 0x84 0xb7 0x55 0xec 0x38 0x3d 0xf7
0x7a 0x91 0x6e 0xc0 0xdb 0xc0 0x2b 0xba
0x7c 0x21 0xa2 0x00 0x80 0x7b 0x4f 0x58
0x5f 0x72 0x8b 0x67 0x1a 0xd6 0x78 0xa4
0x3a 0xac 0xd3 0x3b 0x78 0xeb 0xd5 0x66
0xcd 0x00 0x4f 0xc6 0xf1 0xd4 0x06 0xf0
0x1d 0x97 0x04 0xe7 0x05 0xb2 0x15 0x52
0xa9 0xeb 0x28 0xea 0x31 0x6a 0xb6 0x50
0x37 0xd7 0x17 0x86 0x2e

[responder]: received an EDHOC message (len 91)
0x13 0x58 0x58 0x2d 0x88 0xff 0x86 0xda
0x47 0x48 0x2c 0x0d 0xfa 0x55 0x9a 0xc8
0x24 0xa4 0xa7 0x83 0xd8 0x70 0xc9 0xdb
0xa4 0x78 0x05 0xe8 0xaa 0xfb 0xad 0x69
0x74 0xc4 0x96 0x46 0x58 0x65 0x03 0xfa
0x9b 0xbf 0x3e 0x00 0x01 0x2c 0x03 0x7e
0xaf 0x56 0xe4 0x5e 0x30 0x19 0x20 0x83
0x9b 0x81 0x3a 0x53 0xf6 0xd4 0xc5 0x57
0x48 0x0f 0x6c 0x79 0x7d 0x5b 0x76 0xf0
0xe4 0x62 0xf5 0xf5 0x7a 0x3d 0xb6 0xd2
0xb5 0x0c 0x32 0x31 0x9f 0x34 0x0f 0x4a
0xc5 0xaf 0x9a

[responder]: finalize exchange
[responder]: handshake successfully completed
```

### Initiator

First find out the local ipv6 address of the tap interface:

```
ifconfig tap0
tap0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet6 fe80::894:29ff:fe80:7422  prefixlen 64  scopeid 0x20<link>
        ether 0a:94:29:80:74:22  txqueuelen 1000  (Ethernet)
        RX packets 68  bytes 5962 (5.9 KB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 542  bytes 55480 (55.4 KB)
        TX errors 0  dropped 1 overruns 0  carrier 0  collisions 0
```

In this case its `fe80::894:29ff:fe80:7422`. Next start the `py-edhoc`
based responder.

```
$ edhoc-reponder
INFO:root:Booting CoAP server
INFO:root:Initializing 'core' resource
INFO:root:Initializing 'edhoc' resource
```

Now from the RIOT shell initiate the handshake:

```
Starting the shell
> ini handshake fe80::894:29ff:fe80:7422 5683
init handshake fe80::894:29ff:fe80:7422 5683
[initiator]: sending message (37 bytes)
0x01 0x00 0x58 0x20 0x71 0xa3 0xd5 0x99
0xc2 0x1d 0xa1 0x89 0x02 0xa1 0xae 0xa8
0x10 0xb2 0xb6 0x38 0x2c 0xcd 0x8d 0x5f
0x9b 0xf0 0x19 0x52 0x81 0x75 0x4c 0x5e
0xbc 0xaf 0x30 0x1e 0x13

[initiator]: send 37 bytes to fe80::894:29ff:fe80:7422 on port 5683

[initiator]: received a message (124 bytes):
0x58 0x20 0x71 0xa3 0xd5 0x99 0xc2 0x1d
0xa1 0x89 0x02 0xa1 0xae 0xa8 0x10 0xb2
0xb6 0x38 0x2c 0xcd 0x8d 0x5f 0x9b 0xf0
0x19 0x52 0x81 0x75 0x4c 0x5e 0xbc 0xaf
0x30 0x1e 0x13 0x58 0x50 0x99 0xe1 0x3b
0xa4 0x65 0x44 0x44 0xe8 0xb6 0xd4 0x04
0x01 0x1e 0x01 0xa3 0x29 0xa3 0x26 0x05
0x45 0x99 0x33 0x95 0xf9 0x34 0x2b 0x43
0xa7 0x54 0xf9 0xe1 0x8b 0x0f 0xdc 0x46
0xc2 0xcc 0x4e 0x25 0x24 0x77 0xe0 0x83
0x52 0x0b 0xf4 0x36 0x74 0x53 0xb6 0x2b
0xbf 0x3e 0x14 0xb7 0xb0 0xea 0x0e 0xee
0x84 0xc5 0x5b 0x9e 0x64 0xfc 0x03 0x97
0xc0 0x45 0x18 0x6d 0x14 0xdb 0x88 0x8c
0x73 0x2f 0x95 0x52 0xf5 0x68 0xd1 0x61
0x56 0x6c 0xd1 0x61

[initiator]: sending message (91 bytes)
0x13 0x58 0x58 0x49 0x7a 0x3e 0x46 0xac
0xa1 0x36 0xbf 0xff 0xb9 0x5c 0x00 0x46
0x89 0x69 0x68 0x4a 0xe8 0x2d 0x83 0xf0
0xe5 0xc5 0xe3 0x3f 0x8f 0x17 0xdf 0x7c
0x72 0xe1 0xf2 0x9e 0x7a 0x2a 0xe8 0x88
0x75 0x16 0xd2 0x6a 0xe3 0xa7 0x73 0x76
0xe8 0xe5 0x22 0x14 0x43 0x6d 0xb0 0x37
0xb8 0x48 0x31 0xf3 0xa9 0xb3 0xfc 0x82
0x9c 0x4a 0x92 0x19 0x2c 0x3e 0x4a 0xfe
0x42 0x6c 0x11 0x39 0x6c 0x48 0x48 0x06
0x6b 0xf0 0xed 0x2e 0xff 0x16 0x91 0x08
0xf4 0xee 0x6e

[initiator]: send 91 bytes to fe80::894:29ff:fe80:7422 on port 5683

[initiator]: handshake successfully completed
```

And on the `edhoc-responder`:

```
INFO:root:CHANGED (EdhocState.MSG_2_SENT)  b'X q\xa3\xd5\x99\xc2\x1d\xa1\x89\x02\xa1\xae\xa8\x10\xb2\xb68,\xcd\x8d_\x9b\xf0\x19R\x81uL^\xbc\xaf0\x1e\x13XP\x99\xe1;\xa4eDD\xe8\xb6\xd4\x04\x01\x1e\x01\xa3)\xa3&\x05E\x993\x95\xf94+C\xa7T\xf9\xe1\x8b\x0f\xdcF\xc2\xccN%$w\xe0\x83R\x0b\xf46tS\xb6+\xbf>\x14\xb7\xb0\xea\x0e\xee\x84\xc5[\x9ed\xfc\x03\x97\xc0E\x18m\x14\xdb\x88\x8cs/\x95R\xf5'
INFO:root:POST (EdhocState.MSG_2_SENT)  b'\x13XXIz>F\xac\xa16\xbf\xff\xb9\\\x00F\x89ihJ\xe8-\x83\xf0\xe5\xc5\xe3?\x8f\x17\xdf|r\xe1\xf2\x9ez*\xe8\x88u\x16\xd2j\xe3\xa7sv\xe8\xe5"\x14Cm\xb07\xb8H1\xf3\xa9\xb3\xfc\x82\x9cJ\x92\x19,>J\xfeBl\x119lHH\x06k\xf0\xed.\xff\x16\x91\x08\xf4\xeen'
INFO:root:EDHOC key exchange successfully completed:
INFO:root: - connection IDr: b'+'
INFO:root: - connection IDi: b'+'
INFO:root: - aead algorithm: AES_CCM_16_64_128
INFO:root: - hash algorithm: SHA_256
INFO:root: - OSCORE secret : b'\xd8\x1e\xa3@\xec\xe3?3\xe1\xfe\x8a\x1d\x0c|\xd0\xbe'
INFO:root: - OSCORE salt   : b'\x87\xf9J\xf7\x82Tq\xa3'
```

Congratulations you have performed an EDHOC handshake fo your HOST to
a RIOT node running as the initiator and responder. In all cases you can
now derive symmetric encryption keys from the shared master secret, in this
case a shell command `initiator/responder oscore` is available that derives
keys that could be used for an OSCORE context:

```
> ini oscore
init oscore
OSCORE secret:
0x43 0x83 0x97 0xe7 0xa8 0x3b 0xd7 0x35
0xdf 0x0d 0x47 0xdc 0x45 0x44 0xa4 0x63

OSCORE salt:
0x22 0x3b 0x3c 0xb1 0x03 0xc8 0xa3 0xd0
```

## EDHOC handshake between two RIOT nodes

### Pre-requisites

#### `native`

- if using `native` `BOARD`'s then create two tap interfaces linked
through a bridge:

```
sudo dist/tools/tapsetup/tapsetup -c 2
```

- bootstrap the `BOARD`s and specify the tap interface to use for each

```
PORT=tap0 make -C tests/pkg_edhoc_c all term
PORT=tap1 make -C tests/pkg_edhoc_c all term
```

#### physical `BOARD`s

- for other `BOARD`s make sure the chosen `BOARD`s has a netdev
through which they will be able to communicate.

- bootstrap the `BOARD`s

```
make -C tests/pkg_edhoc_c flash term
```

### Perform the handshake

One of the devices shall be the initiator and the other one the responder.
Both are already setup to listen for the first message.

In the shell of the node that will act as the responder identify its ipv6
address:

```
Starting the shell
> ifconfig
ifconfig
Iface  5  HWaddr: D6:76:BB:62:F2:AE
          L2-PDU:1500  MTU:1500  HL:64  RTR
          RTR_ADV
          Source address length: 6
          Link type: wired
          inet6 addr: fe80::d476:bbff:fe62:f2ae  scope: link  VAL
          inet6 group: ff02::2
          inet6 group: ff02::1
          inet6 group: ff02::1:ff62:f2ae
```

In this case `fe80::d476:bbff:fe62:f2ae`.

From the initiator now start the handshake:

```
initiator handshake fe80::d476:bbff:fe62:f2ae 5683
```

Yo should see the different messages being exchanged on both nodes, and
now both can derive OSCORE keys as well with the `responder/initiator oscore`
command:

- initiator:

```
> ini handshake fe80::d476:bbff:fe62:f2ae 5683
init handshake fe80::d476:bbff:fe62:f2ae 5683
[initiator]: sending message (37 bytes)
0x01 0x00 0x58 0x20 0x71 0xa3 0xd5 0x99
0xc2 0x1d 0xa1 0x89 0x02 0xa1 0xae 0xa8
0x10 0xb2 0xb6 0x38 0x2c 0xcd 0x8d 0x5f
0x9b 0xf0 0x19 0x52 0x81 0x75 0x4c 0x5e
0xbc 0xaf 0x30 0x1e 0x13
[initiator]: send 37 bytes to fe80::d476:bbff:fe62:f2ae on port 5683

[initiator]: received a message (126 bytes):
0x58 0x20 0x71 0xa3 0xd5 0x99 0xc2 0x1d
0xa1 0x89 0x02 0xa1 0xae 0xa8 0x10 0xb2
0xb6 0x38 0x2c 0xcd 0x8d 0x5f 0x9b 0xf0
0x19 0x52 0x81 0x75 0x4c 0x5e 0xbc 0xaf
0x30 0x1e 0x13 0x58 0x50 0x99 0xe1 0x3b
0xa4 0x65 0x44 0x44 0xe8 0xb6 0xd4 0x04
0x01 0x1e 0x01 0xa3 0x29 0xa3 0x26 0x05
0x45 0x99 0x33 0x95 0xf9 0x34 0x2b 0x43
0xa7 0x54 0xf9 0xe1 0x8b 0x0f 0xdc 0x46
0xc2 0xcc 0x4e 0x25 0x24 0x77 0xe0 0x83
0x52 0x0b 0xf4 0x36 0x74 0x53 0xb6 0x2b
0xbf 0x3e 0x14 0xb7 0xb0 0xea 0x0e 0xee
0x84 0xc5 0x5b 0x9e 0x64 0xfc 0x03 0x97
0xc0 0x45 0x18 0x6d 0x14 0xdb 0x88 0x8c
0x73 0x2f 0x95 0x52 0xf5 0x60 0x56 0x6c
0xa1 0x60 0x56 0x70 0xa1 0x60
[initiator]: sending message (91 bytes)
0x13 0x58 0x58 0x49 0x7a 0x3e 0x46 0xac
0xa1 0x36 0xbf 0xff 0xb9 0x5c 0x00 0x46
0x89 0x69 0x68 0x4a 0xe8 0x2d 0x83 0xf0
0xe5 0xc5 0xe3 0x3f 0x8f 0x17 0xdf 0x7c
0x72 0xe1 0xf2 0x9e 0x7a 0x2a 0xe8 0x88
0x75 0x16 0xd2 0x6a 0xe3 0xa7 0x73 0x76
0xe8 0xe5 0x22 0x14 0x43 0x6d 0xb0 0x37
0xb8 0x48 0x31 0xf3 0xa9 0xb3 0xfc 0x82
0x9c 0x4a 0x92 0x19 0x2c 0x3e 0x4a 0xfe
0x42 0x6c 0x11 0x39 0x6c 0x48 0x48 0x06
0x6b 0xf0 0xed 0x2e 0xff 0x16 0x91 0x08
0xf4 0xee 0x6e
[initiator]: send 91 bytes to fe80::d476:bbff:fe62:f2ae on port 5683

[initiator]: handshake successfully completed
```

- responder:

```
> [responder]: received an EDHOC message (len 37)
0x01 0x00 0x58 0x20 0x71 0xa3 0xd5 0x99
0xc2 0x1d 0xa1 0x89 0x02 0xa1 0xae 0xa8
0x10 0xb2 0xb6 0x38 0x2c 0xcd 0x8d 0x5f
0x9b 0xf0 0x19 0x52 0x81 0x75 0x4c 0x5e
0xbc 0xaf 0x30 0x1e 0x13
[responder]: sending msg2 (117 bytes)
0x58 0x20 0x71 0xa3 0xd5 0x99 0xc2 0x1d
0xa1 0x89 0x02 0xa1 0xae 0xa8 0x10 0xb2
0xb6 0x38 0x2c 0xcd 0x8d 0x5f 0x9b 0xf0
0x19 0x52 0x81 0x75 0x4c 0x5e 0xbc 0xaf
0x30 0x1e 0x13 0x58 0x50 0x99 0xe1 0x3b
0xa4 0x65 0x44 0x44 0xe8 0xb6 0xd4 0x04
0x01 0x1e 0x01 0xa3 0x29 0xa3 0x26 0x05
0x45 0x99 0x33 0x95 0xf9 0x34 0x2b 0x43
0xa7 0x54 0xf9 0xe1 0x8b 0x0f 0xdc 0x46
0xc2 0xcc 0x4e 0x25 0x24 0x77 0xe0 0x83
0x52 0x0b 0xf4 0x36 0x74 0x53 0xb6 0x2b
0xbf 0x3e 0x14 0xb7 0xb0 0xea 0x0e 0xee
0x84 0xc5 0x5b 0x9e 0x64 0xfc 0x03 0x97
0xc0 0x45 0x18 0x6d 0x14 0xdb 0x88 0x8c
0x73 0x2f 0x95 0x52 0xf5
[responder]: received an EDHOC message (len 91)
0x13 0x58 0x58 0x49 0x7a 0x3e 0x46 0xac
0xa1 0x36 0xbf 0xff 0xb9 0x5c 0x00 0x46
0x89 0x69 0x68 0x4a 0xe8 0x2d 0x83 0xf0
0xe5 0xc5 0xe3 0x3f 0x8f 0x17 0xdf 0x7c
0x72 0xe1 0xf2 0x9e 0x7a 0x2a 0xe8 0x88
0x75 0x16 0xd2 0x6a 0xe3 0xa7 0x73 0x76
0xe8 0xe5 0x22 0x14 0x43 0x6d 0xb0 0x37
0xb8 0x48 0x31 0xf3 0xa9 0xb3 0xfc 0x82
0x9c 0x4a 0x92 0x19 0x2c 0x3e 0x4a 0xfe
0x42 0x6c 0x11 0x39 0x6c 0x48 0x48 0x06
0x6b 0xf0 0xed 0x2e 0xff 0x16 0x91 0x08
0xf4 0xee 0x6e
[responder]: finalize exchange
[responder]: handshake successfully completed
```

- oscore keys:

```
> ini oscore
init oscore
OSCORE secret:
0x43 0x83 0x97 0xe7 0xa8 0x3b 0xd7 0x35
0xdf 0x0d 0x47 0xdc 0x45 0x44 0xa4 0x63

OSCORE salt:
0x22 0x3b 0x3c 0xb1 0x03 0xc8 0xa3 0xd0
```

## EDHOC automatic test

As long as a BOARD with a netdev interface is used is as simple as:

```
$ make -C tests/pkg_edhoc_c flash test-with-config
```