diff --git a/docs/components/firmware/app-nrf91-origin/index.md b/docs/components/firmware/app-nrf91-origin/index.md index c2a5a5ab..0eda45a2 100644 --- a/docs/components/firmware/app-nrf91-origin/index.md +++ b/docs/components/firmware/app-nrf91-origin/index.md @@ -7,5 +7,107 @@ draft: true # app-nrf91-origin :::info -This page is currently marked as draft and will not be inclueded in builds of this documentation. +This page is currently marked as draft and will not be included in builds of this documentation. ::: + + +## MQTT Communication +The device can be configured to connect and upload to an MQTT broker by setting a host with +protocol `mqtt://` or `mqtts://` in the configuration. To use MQTTs, the device must have a +device certificate. There can be a mixture of the four protocols (CoAP, CoAPs, MQTT, MQTTs), +the hosts are tried in the order they are set in the configuration, until one is successful. + + +### MQTT host configuration +A `host` entry for MQTT(s) must be given in URI form. Hosts can be set either by IPv4 addressed +or by domain names. There can be a port number specified; without one it will default to 1883 +for MQTT and 8883 for MQTTs. A username and password can be added, optionally. No topic must be +added to the host entry. The format is + + mqtt://[username:password@]host[:port] + mqtts://[username:password@]host[:port] + +If username or password contain special characters, they must be URL-encoded. + + +### MQTT topics +The device will only publish on topics that conform to this syntax: + + LOB//up/ + LOB//req/ + +and will only subscribe to topics that conform to this syntax: + + LOB//down/ + +where `` is the device's EUI in urn form, e.g. `urn:dev:mac:70b3d5e05001c6f3`, and +`` is a string that describes the message type. + +Uplinks to the `up` topics never expect a response, they can be processed in a queue with +a delay. + +Uplinks to the `req` topics expect a response, on the `down` topic with the same ``. +The response must be sent within a few seconds and reference the original message number. +See documentation in https://github.com/lobaro/refend for more information. + + +## Certificate Handling +Certificates for Platform instances and for the Devices are handles in different trust chains. The Platform is +handles as before. The Platform certificates are used for both, CoAPs over DTLS and MQTT over TLS. HTTPs is +its own thing using Let's Encrypt and not covered here. + +### Self-signed Certificates +Devices can create a self-signed certificate. This is done over the Shell, using the command + + cert self-signed + +The CN is automatically set using the DevEUI in urn form, e.g. `urn:dev:mac:70b3d5e05001c6f3`. +The DevEUI urn will also be used as Subject Alternative Name (SAN) in the certificate. +Any fields added as will be appended to the subject (not the SAN), so you can use something like + + cert self-signed C=DE,O=Lobaro,L=Hamburg + +Subject must be comma separated (without blanks) and not be surrounded by quotes (see example). +When the cert creation is successful, the certificate will be stored in the device's flash memory and +printed to the console. + +The device must have a DevEUI set to create a self-signed certificate (and a private key, but that one is +generated during boot, if it is missing). + +### Certificate Signing Requests +Devices can create a Certificate Signing Request (CSR) to be signed by a CA. This is done over the Shell, using the command + + cert csr + +It works the same as `self-signed`, but the certificate is not created, only the CSR. The CSR will be printed to the console. +It must be signed by the provisioning computer that runs the shell (or by hand), using an intermediate CA that is in +turn signed by our Device Root CA. + +### Writing Certificates from CSR +After the CSR has been signed externally, the certificate can be written to the device using the command + + cert own + +It is a multi-input command, where you input the certificate in PEM format, one line at a time ('\n' terminated). +You need to include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines in the input. You must also +include an intermediate CA certificate; this can be done by inputting the device's certificate first and then +the intermediate CA certificate after it (without a newline in between). Sending an empty line will finish the input; +the certificate chain will then be written to the device's flash memory. You can cancel the input by sending +`exit` as a single line. Longer certificate chains are possible; the limitation is around 4 kiB of space for +the both, the device's certificate chain and the trusted CA certificates together (in DER format). + +### Trusted CA Certificates +The device can store multiple trusted server CA certificates or server certificates directly. Those are entered +using the shell command + + cert ca + +The handling is the same as with `cert own`, only that you do not provide a chain, but a list of trusted CA +certificates. Size is limited by a shared 4 kiB space with the device's certificate chain (in DER format). + +### Certificate Revocation +There is no support for certificate revocation in the device. + +### Certificate Signing +Signing (when not self-singed) must be done externally by the provisioning computer in the provisioning tool. +A development variant of the certificate chains exists under https://github.com/lobaro/development-certificates.