CoMatrix: OSCORE
Summary
This documentation describes the usage of an application-layer protocol OSCORE to provide end-to-end protection between the 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 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 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 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
Wireshark Capture
// TODO How to add a picture
Client
// Await docs
Used Hardware
- Raspberry Pi 3B+ Model (CoMatrix Gateway)
- OpenLabs 802.15.4. radio module
- SAMR21-xpro (CoMatrix Client)
- (optional) Raspberry Pi 4 (Matrix Homeserver)