Securing CoAP

1. Overview

This section gives examples of how to get and set various security options that are available to CoAP servers.

Section 9 of RFC7252 explains various methods of securing or not securing CoAP. VelocitySP supports modes "NoSec" and "RawPublicKey" with "RawPublicKey" being set by default.

There are three security options and default values are set as follows.

- "/mchp-velocitysp-system:coap-server/config":
    security-mode: raw-public-key
    mup1-dtls-enable: true
    ip-dtls-enable: true

The following table shows how "security-mode" and "mup1-dtls-enable" control access to CoAP over MUP1.

security-mode

mup1-dtls-enable

direct to CoAP using MUP1 type 'c'

DTLS to CoAP using MUP1 type 'd'

raw-public-key

true

blocked

allowed

raw-public-key

false

allowed

blocked

no-sec

don’t care

allowed

blocked

The following table shows how "security-mode" and "ip-dtls-enable" control access to CoAP over UDP/IP.

security-mode

ip-dtls-enable

direct to CoAP using UDP/IP port 5683

DTLS to CoAP using UDP/IP port 5684

raw-public-key

true

blocked

allowed

raw-public-key

false

allowed

blocked

no-sec

don’t care

allowed

blocked

Anytime you change any of these security modes, before they take effect you must save your runtime config, and reboot the device.

2. Authentication

By default DTLS is enabled on both MUP1 and UDP/IP, and the device is in the non-provisioned state. This applies to newly manufactured devices, devices which have been reset to factory defaults, or devices where the entire NOR flash has been re-programmed.

It is possible to change this behavioral by providing other settings in the Factory Defaults.

When the device is in the non-provisioned state, no authentication is performed, but also access to all secured CoAP servers are blocked. The only URI path that is available for a GET operation is "/p". This path is used with the GET method to provision the device. The first client to provision the device will be considered the administrator and given full access to all CoAP servers. After the device is provisioned the "/p" path will be blocked, and only the administrator can grant access to other clients.

2.1. Provisioning

Before any authentication is performed the device must be provisioned. Provisioning tells the device who the administrator is, and then future connections will authenticate all clients.

To provision the device, first generate your admin client key using openssl.

openssl ecparam -name prime256v1 -genkey -noout -out admin_keys.pem

Then using your new admin key, initiate the provisioning with one of the following steps.

Provision Over UDP/IP using libcoap’s coap-client tool.

coap-client -m get -M admin_keys.pem coaps://<device_ip_address>/p

Or provision over MUP1 using mup1ct.

mup1ct -k admin_keys.pem coaps get /p

If successful, the response code will be 2.05 and payload will contain "PROVISIONED"

If something goes wrong, then it is always possible to press-and-hold the reset bottom on the EVB to reset the board to Factory Defaults.

Provisioning using URI_PATH "/p" causes the client public key, as well as the server public and private keys to be saved to the flash. This way, when the device is rebooted, it will remain provisioned.

If you would like to provision with out saving to flash replace URI_PATH "/p" with "/pdry". Using "/pdry" will allow you to see the effects of provisioning with out saving to the flash. This way, when the device is rebooted, it will revert back to the unprovisioned state.

At this point the client, using admin_keys.pem, will have access to all CoAP servers using DTLS to CoAP over UDP/IP port 5684, or MUP1 type 'd'.

If you access over UDP/IP using libcoap’s coap-client tool, make sure to use "-M" option to specify your admin_keys.pem file, and also use "coaps" as the URL scheme

If you access over MUP1 using mup1ct or mup1cc, make sure to use "-k" option to specify your admin_keys.pem file.

To verify the new admin key is saved issue the following request using one of the DTLS to CoAP pathways.

'FETCH' request message

- "/ietf-system:system/authentication"

FETCH response message

- ? "/ietf-system:system/authentication"
  : user:
    - name: admin
      mchp-velocitysp-system:coap-authorized-key:
      - name: admin
        key-data: "/iR5KXnZESIONhXpRaUhaK2dC5+f3XAlwYpGymd+ySsFd4yncth6mGAhQ7UlZg1jgaG0VaNHVC5Ctgw0rhzwCA=="
        access-control:
          cc-rights: read-write
          startup-config-rights: read-write
          fw-rights: read-write
          dbg-rights: read-write
          well-known-rights: read-write

2.2. Add a New Authorized User Key

VelocitySP maintains a short list of authorized users and keys. Currently it is limited to 2 users, with 2 keys per user.

If you would like to add a new user and key that has limited access rights you can issue the following iPatch request.

IPATCH request message

- ? "/ietf-system:system/authentication/user"
  : name: ccreader
    mchp-velocitysp-system:coap-authorized-key:
    - name: ccreader
      key-data: XYa1F+fUzIM1xVfqHzeWFxE/NVYiTAFA1GdZ4LYfgzo6mzedPGaRsFADNs7cvdRp7EsxBZxlHS1LkAK8k22TTA==
      access-control:
        cc-rights: read-only

Note that key-data is the base64 encoding of the public x key concatinated with the public y key. And make sure this base64 encoded data does not include any new line "\n" characters, as some base64 encoders will add new lines to long strings.

You can confirm this change by getting the user key list again.

FETCH request message

- "/ietf-system:system/authentication"

FETCH response message

- ? "/ietf-system:system/authentication"
  : user:
    - name: admin
      mchp-velocitysp-system:coap-authorized-key:
      - name: admin
        key-data: "/iR5KXnZESIONhXpRaUhaK2dC5+f3XAlwYpGymd+ySsFd4yncth6mGAhQ7UlZg1jgaG0VaNHVC5Ctgw0rhzwCA=="
        access-control:
          cc-rights: read-write
          startup-config-rights: read-write
          fw-rights: read-write
          dbg-rights: read-write
          well-known-rights: read-write
    - name: ccreader
      mchp-velocitysp-system:coap-authorized-key:
      - name: ccreader
        key-data: XYa1F+fUzIM1xVfqHzeWFxE/NVYiTAFA1GdZ4LYfgzo6mzedPGaRsFADNs7cvdRp7EsxBZxlHS1LkAK8k22TTA==
        access-control:
          cc-rights: read-only
          startup-config-rights: no-access
          fw-rights: no-access
          dbg-rights: no-access
          well-known-rights: no-access

As you can see there are now two users, each with one key. The admin user was created by provisioning, and has read-write access to all servers. The ccreader was created with read-only access to the cc (CORECONF) server. Notice in the IPATCH request above, we did not specify the access rights of other servers, and therefor they have defaulted to no-access.

3. Security Modes

By default VelocitySP is configured for "raw-public-key" mode, and both MUP1 and UDP/IP pathways are enabled for DTLS.

To verify this perform the following request.

3.1. Get Security Mode

FETCH request message

- "/mchp-velocitysp-system:coap-server/config"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: raw-public-key
    mup1-dtls-enable: true
    ip-dtls-enable: true

3.2. Set Security Mode to 'no-sec' (no security)

You can disable the security layer by following these steps.

IPATCH request message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: no-sec
    mup1-dtls-enable: false
    ip-dtls-enable: false

You can verify that 'no-sec" was configure by getting the security mode.

FETCH request message

- "/mchp-velocitysp-system:coap-server/config"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: no-sec
    mup1-dtls-enable: false
    ip-dtls-enable: false

Before this mode takes effect you need to save the runtime config to the startup config, and reboot the device.

Save to startup config with

POST request message

- ? "/mchp-velocitysp-system:save-config"
  :

Now reboot the device and it will start in "no-sec" mode.

After restarting the device verify "no-sec" mode by getting security mode again.

FETCH request message

- "/mchp-velocitysp-system:coap-server/config"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: no-sec
    mup1-dtls-enable: false
    ip-dtls-enable: false

At this point the security layer (DTLS) has been disabled, and all coap servers are accessible on UDP port 5683, or MUP1 type 'c'. Any attempt to access the server through DTLS on UDP port 5684 or MUP1 type 'd' is now blocked.

3.3. Set Security Mode to 'raw-public-key'

If the security layer is disabled, you can re-enable it by following these steps

IPATCH request message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: raw-public-key
    mup1-dtls-enable: true
    ip-dtls-enable: true

You can verify that "raw-public-key" was configured by getting the security mode.

FETCH request message

- "/mchp-velocitysp-system:coap-server/config"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: raw-public-key
    mup1-dtls-enable: true
    ip-dtls-enable: true

Before this mode takes effect you need to save the runtime config to the startup config, and reboot the device.

Save to startup config with

POST request message

- ? "/mchp-velocitysp-system:save-config"
  :

Now reboot the device and it will start in "raw-public-key" mode.

After restarting the device verify "raw-public-key" mode by getting security mode again.

previously configured authorized users are still in effect. Therefor access using appropriate key over one of the DTLS pathways.

FETCH request message

- "/mchp-velocitysp-system:coap-server/config"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config"
  : security-mode: raw-public-key
    mup1-dtls-enable: true
    ip-dtls-enable: true

At this point the security layer (DTLS) has been enabled, and all coap servers are accessible after authorization through DTLS on UDP port 5684, or MUP1 type 'd'. Direct to CoAP access on UDP port 5683 of MUP1 type 'c' is now blocked.