Skip to content

Commit

Permalink
fix(doc/coap): Editorial fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
chrysn committed Oct 24, 2024
1 parent 3e71461 commit 7c39a64
Showing 1 changed file with 8 additions and 8 deletions.
16 changes: 8 additions & 8 deletions book/src/tooling/coap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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".
Expand All @@ -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 <!-- "deny everything" is not sensible, could just not include CoAP then -->
when all are disabled, the only sensible policy that is left <!-- "deny everything" is not sensible, could just not include CoAP then -->
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:
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down

0 comments on commit 7c39a64

Please sign in to comment.