View source for CoMatrix: OSCORE

== Summary == 

This documentation describes the usage of an application-layer protocol OSCORE to provide end-to-end protection between the [https://comatrix.eu/setup/architecture_and_testbed CoMatrix Gateway and CoMatrix Client].


== Requirements ==

* Operating system: 
** Ubuntu 22.04 (Gateway)
** RIOT OS (Client)
* See [#Used Hardware]

In order to complete these steps, you must set up the [https://comatrix.eu/setup/ CoMatrix project] before.

== Description ==

OSCORE is a security protocol designed to provide end-to-end protection between endpoints communicating using CoAP.

A key exchange protocol does not exist OSCORE and the keys are pre-shared between Gateway and Client. However, there is ongoing work with key exchanges such as EDHOC or [https://datatracker.ietf.org/doc/html/draft-ietf-ace-oscore-profile-11 ACE-OSCORE]

=== Gateway ===

The Python library aiocoap provided the OSCORE functionality and was implemented in order for the gateway to talk in OSCORE

==== Imports ====


Following imports were added

 from aiocoap.oscore_sitewrapper import OscoreSiteWrapper
 from aiocoap.credentials import CredentialsMap
 from plugtest_common import *
 from aiocoap.cli.common import server_context_from_arguments, add_server_arguments

* The plugtest_common import was extracted from the aiocoap OSCORE plugtest and provides verification for external AADs and returning the security context.

==== Main ====

When starting the gateway, new parameters have been added to list the directory where the pre-shared secrets are held and sequence numbers will be saved. These sequence numbers are necessary for replay protection.

 parser.add_argument("contextdir", help="Directory name where to persist sequence numbers and the location of the secrets", type=Path)
 
 // Necessary to add these arguments provided by the aiocoap library in order for the server to start correctly. More info under aiocoap/cli/common.py
 add_server_arguments(parser)


The context directory may contain two files:
* secrets.json
* settings.json
As per implementation it is sufficient to only have one of these files in the directory.

The format of the file is the following JSON:
 {
   "sender-id_hex": "01",
   "recipient-id_ascii": "file",
   "secret_ascii": "Correct Horse Battery Staple"
 }
 
Important properties are:
* sender-id
* recipient-id
* secret

These three properties must be appended with either _hex or _ascii and have the values according to the suffix.

Assume that the file above was for the server and for our client we would need the following file:
 {
   "sender-id_ascii": "file",
   "recipient-id_hex": "01",
   "secret_ascii": "Correct Horse Battery Staple"
 }

Notice how sender-id and recipient-id had to be swapped.
With these two secret files it is now possible to start a gateway and a client each using a different JSON file with the ids flipped.

For further information see [https://aiocoap.readthedocs.io/en/latest/stateofoscore.html#oscore-credentials aiocoap-OSCORE]


Loading these in the code was done in the following way - For testing purposes there were two pairs of credentials a / b and c / d whereas the first one is used for the test client and the latter for the gateway:
 
 // Loading the pre-shared secrets
 server_credentials = CredentialsMap()
 // the first parameter states the name of the context in this case it's b but can be named in any way and the second parameter is the path to the folder e.g. the file would be located in /contextdir/b/settings.json
 server_credentials[':b'] = get_security_context('b', args.contextdir / "b")
 server_credentials[':d'] = get_security_context('d', args.contextdir / "d")

To enable OSCORE for the server now the following code was added/adjusted:
 // root is the variable for the site
 // Enable the site to talK OSCORE with the credentials loaded from before
 root = OscoreSiteWrapper(root, server_credentials)
 args.bind = bind
 // Now we create a server context with arguments added
 asyncio.Task(server_context_from_arguments(root, args))

'''USAGE:''' ./comatrix_gateway.py contextdir

// TODO How to add picture in 

To test if the gateway actually talks in OSCORE the plugtest-client from the aiocoap library was adjusted to meet our needs for comatrix.

'''USAGE:''' ./unit-tests.py host contextdir

// TODO Picture

== Client ==
// Await docs

== Used Hardware ==

* Raspberry Pi 3B+ Model (CoMatrix Gateway)
* OpenLabs 802.15.4. radio module
* SAMR21-xpro (CoMatrix Client)
* Raspberry Pi 4 (Matrix Homeserver)

== References ==

* https://comatrix.eu
* https://aiocoap.readthedocs.io
* https://github.com/chrysn/liboscore

[[Category:Documentation]]