Securing CoAP

1. Overview

This section gives examples of how to get and set various security options that are available to CoAP servers. These security options only apply when "security-mode" is set to "raw-public-key" and the client is connecting over UDP/IP. Currently accessing CoAP over MUP1 is considered trusted, and therefor by passes the security layer.

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.

When "RawPublicKey" mode is configured then CoAP is accessible after proving authorization over DTLS which is available on UDP port 5684. Initially this mode has no authorized users, and therefor must be provision to recognize the administrator. After provisioning then the administrator can access all CoAP servers through DTLS. See below for more information about provisioning.

When "NoSec" (no security) mode is configured then CoAP servers are accessible directly on UDP port 5683. In this mode no authorization or encryption is performed.

2. Security Modes

By default VelocitySP is configured for "raw-public-key" mode. To verify this perform the following request.

2.1. Get Security Mode

FETCH request message

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

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config/security-mode"
  : raw-public-key

2.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

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

FETCH request message

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

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config/security-mode"
  : no-sec

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/security-mode"

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config/security-mode"
  : no-sec

At this point the security layer (DTLS) has been disabled, and all coap servers are accessible on UDP port 5683. Any attempt to authorize a client through DTLS on UDP port 5684 is now blocked.

2.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

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

FETCH request message

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

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config/security-mode"
  : raw-public-key

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.

FETCH request message

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

FETCH response message

- ? "/mchp-velocitysp-system:coap-server/config/security-mode"
  : raw-public-key

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

3. Authentication

Assuming that the security mode is set to 'raw-public-key' then all client access to CoAP must be authenticated. VelocitySP maintains a short list of authorized client keys.

However, at first startup there are no authorized client keys listed. You can check this with the following command.

FETCH request message

- "/ietf-system:system/authentication"

FETCH response message

- ? "/ietf-system:system/authentication"
  : user: []

3.1. Provisioning

As you can see, initially, there are no authorized users, and VelocitySP is considered non-provisioned. In this state, all secured CoAP servers are blocked until after the provisioning process has been completed.

Before we continue, lets review the current state. Security mode is set to 'raw-public-key' which means direct to CoAP on UDP port 5683 is blocked, and DTLS to CoAP is enabled on UDP port 5684. Also VelocitySP is in the 'non-provisioned' state which means normal CoAP server URI_PATHs (such as '/c') are blocked. And only the provisioning URI_PATH is enabled at '/p'. Additionally, in this 'non-provisioned' state authentication checks are disabled. Which means any client may provision itself as the admin client. But this can only be done once. After VelocitySP has the admin client key, then it is 'provisioned', authentication checking is enabled in DTLS, and normal CoAP server URI_PATHs are enabled.

Now lets proceed to provision the device. This is done by simply issuing a CoAPS GET request on '/p', through DTLS on UDP port 5684. You can do this using openssl and libcoap’s coap_client tool.

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 the following.

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

If successful you should see the content returned is "PROVISIONED"

During the DTLS handshake, the client key is stored, and when CoAP processes the get request on '/p' it saves the client key as the admin key.

To verify the new admin key is saved issue the following request

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: rKpMtVOxomldA11CKrVJtEAh0Pc1ztYugYfpe0lFf0kzk29u10whRF5SU/E2ztXMqUp8SXXbONYJstAFTcmMqg==
        access-control:
          cc-rights: read-write
          startup-config-rights: read-write
          fw-rights: read-write
          dbg-rights: read-write
          well-known-rights: read-write

Obviously your key-data will be different, but notice the admin key has read-write access to all CoAP servers. Therefor you can now use admin_keys.pem with your coap_client to access all available servers.

For example, to get the full runtime config in cbor do the following.

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

3.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: rKpMtVOxomldA11CKrVJtEAh0Pc1ztYugYfpe0lFf0kzk29u10whRF5SU/E2ztXMqUp8SXXbONYJstAFTcmMqg==
        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.