diff --git a/book/src/tooling/coap.md b/book/src/tooling/coap.md index 590b4de88..5cb2d24e1 100644 --- a/book/src/tooling/coap.md +++ b/book/src/tooling/coap.md @@ -9,7 +9,7 @@ but geared towards IoT devices in its format and its security mechanisms. CoAP provides a versatile set of transports (with IETF Proposed Standards for running [over UDP] including multicast, [over TCP and WebSockets], other standards for running [over SMS and NB-IoT], and more in development). -It relies on proxies to span across transports and accommodate the characteristics of particular networks, +It relies on proxies to span across transports and to accommodate the characteristics of particular networks, and offers features exceeding the classical REST set such as [observation]. **RIOT-rs supports** the use of CoAP @@ -51,7 +51,7 @@ A program that triggers a CoAP request provides[^whatsinarequest] some component Note that while the address is printed here as a text URL (and may even be entered as such in code), - it is kept in memory and sent as binary components. + its memory and transmitted representations are binary components. * Optionally, directions regarding how to reach or find the host. @@ -94,10 +94,10 @@ A policy is configured for the whole server depending on the desired security me Examples of described policy entries are: * This is a fixed public key, and requests authenticated with that key are allowed to GET and PUT to `/limit`. -* The device has a shared secret from its authorization server, with which the authorization server secures the tokens it issues to clients. Clients may perform any action as long as they securely present a token that allows it. For example, a token may allow GET on `/limit` and PUT on `/led/0`". +* The device has a shared secret from its authorization server, with which the authorization server secures the tokens it issues to clients. Clients may perform any action as long as they securely present a token that allows it. For example, a token may allow GET on `/limit` and PUT on `/led/0`. * Any (even unauthenticated) device may GET `/hello/`. -#### Interacting with RIOT-rs CoAP server from the host +#### Interacting with a RIOT-rs CoAP server from the host A convenient policy (which is the default of RIOT-rs's examples) is to grant the user who flashes the device all access on it. @@ -110,7 +110,7 @@ when a CoAP server is provisioned through the RIOT-rs build system, public keys and their device associations are stored in the developer's state home directory. -Together, these files act in a similar way as the classic UNIX files `~/.netrc`, `~/.ssh/id_rsa{,.pub}`. +Together, these files act in a similar way as the classic UNIX files `~/.netrc` and `~/.ssh/id_rsa{,.pub}`. They can also double as templates for an application akin to `ssh-copy-id` in that they enable a server policy like "any device previously flashed on this machine may GET all resources". @@ -132,7 +132,7 @@ Examples of policies that can be available are ### Available security mechanisms These components are optional, but enabled by default -- -when disabled, the only sensible policy that is left +when all are disabled, the only sensible policy that is left is to allow unauthenticated access everywhere. For example, this may make sense on a link layer with tight access control. The components also have internal dependencies: @@ -213,7 +213,7 @@ and sends the token along with the same OSCORE key through its secure connection Before the client can send OSCORE requests, it POSTs the token to the server over an unprotected connection (the token itself is encrypted), -along with a random number and some housekeeping +along with a random number and some housekeeping data that go into the establishment of an OSCORE context. The [documentation of the CoAP/ACE-OAuth PoC project] describes the whole setup in more detail. @@ -235,7 +235,7 @@ but as part of the EDHOC exchange. [under development in the ACE working group]: https://datatracker.ietf.org/doc/draft-ietf-ace-edhoc-oscore-profile/ -##### ACE during development +##### Using ACE from the host during development While full operation of ACE requires having an AS as part of the network, CoAP servers running on RIOT-rs can be used in the ACE framework without a live server.