Crate coapcore

A CoAP security tool for embedded devices, supporting OSCORE/EDHOC and managing credentials.

This crate is under active development; breaking changes will be made as necessary. It currently only handles the server side of CoAP exchanges. At runtime, there is more copying of messages than is generally preferred; those result from limitations of underlying tools and are being addressed there.

This crate builds on several components technically and logically:

• libOSCORE provides the OSCORE implementation.
• Lakers provides the EDHOC implementation.
• The combined handling of OSCORE and EDHOC was originally explored in EDF’s CoAP/ACE-OAuth proof-of-concept firmware. Since this crate matured, that firmware now uses coapcore.
• The crate is maintained as part of Ariel OS, whose CoAP stack integrates it and manages server access policies. Nothing in this crate depends on Ariel OS, but some examples may refer to it.

Usage

This crate is mainly used with a CoAP stack (something that takes a [coap_handler::Handler]) and a CoAP server application (an implementation of a [coap_handler::Handler]). Rather than passing the handler directly to the stack (which then only applies security mechanisms built into that concrete stack, if any), a OscoreEdhocHandler is created from the application, and passed into the stack.

The arguments passed to the OscoreEdhocHandler at construction guide its behavior.

Logging

Extensive logging is available in this crate through [defmt_or_log], depending on features enabled.

Errors from CoAP are currently logged through its Debug2Format facility, representing a compromise between development and runtime complexity. Should benchmarks show this to be a significant factor in code size in applications that need error handling, more fine grained control can be implemented (eg. offering an option to make Debug2Format merely print the type name or even make it empty).

This crate mainly logs on the trace, debug and error level; the latter provides details when an error is sent over the network and the details are not visible to the peer.

See the book for how defmt is configured in Ariel OS; outside of that, regular [defmt_or_log] practica applies.

Warning: At the Debug level, this module may show cryptographic key material. This will be revised once all components have been interop-tested.

Caveats

Currently, this has hidden dependencies on a particular implementation of the [coap-message] provided (it needs to be a [coap_message_implementations::inmemory_write::Message]) by the stack. There are plans for removing this limitation by integrating deeper with libOSCORE.

Cargo features

• defmt — Sends the output of the crate’s log statements to the defmt ecosystem.

• log — Sends the output of the crate’s log statements to the log ecosystem.

• liboscore-defaults (enabled by default) — Selects the libOSCORE default features.

  libOSCORE generally provides abort and assert symbols for its C code. When used in environments where they are provided by other code (eg. ESP32 some variants), this default feature can be disabled, leaving the user to manually select the right libOSCORE features.

• liboscore-provide-abort — Feature passed on to libOSCORE (see liboscore-defaults)

• liboscore-provide-assert — Feature passed on to libOSCORE (see liboscore-defaults)

Modules

ace

Types representing ACE, COSE and CWT structures.

scope

Expressions for access policy as evaluated for a particular security context.

seccfg

Descriptions of trust sources for the Resource Server (RS) which coapcore runs on.

time

Traits and types around representing time, as used to consider token expiration.

Structs

CredentialError

Error type returned from various functions that ingest any input to an authentication or authorization step.

OscoreEdhocHandler

A CoAP handler wrapping inner resources, and adding EDHOC, OSCORE and ACE support.

Traits

GeneralClaims

Claims about a peer that are independent of the security mechanism.