×

Please give details of the problem

Docs

Find

Using CoAP with RunMyProcess

The Constrained Application Protocol (CoAP) is a specialised web transfer protocol for use with constrained nodes and constrained networks in the Internet of Things.

This document discusses how to establish communication between applications running on RunMyProcess and sensors ('things') over CoAP.

1 Overview

With the rapid advancement of the Internet of Things comes an increasing need to communicate with sensors and constrained devices. The RunMyProcess platform facilitates this communication by allowing you to both connect to Constrained Devices and to receive messages from such devices.

All communication is achieved using the Constrained Application Protocol (CoAP), this is a specialized web transfer protocol for use with constrained nodes and constrained networks in the Internet of Things.

To communicate with external systems, RunMyProcess uses connectors. The same concept applies when communicating with devices; connectors are used to enable the communication over CoAP.

To receive information from sensors a Composite API is called over CoAP, this Composite API takes the information from the sensor and handles the necessary event processing.

Overview

This document discusses how applications built on the platform can interact with sensors (outbound communication) and how the platform can be configured to process events that are triggered by sensors (inbound communication).

2 Outbound Communication (RunMyProcess to Device)

Communication to a device from a RunMyProcess application is facilitated by the use of a Connector. Connectors are used by RunMyProcess to offer a pre-configured way for applications to communicate with systems. They can be imported from the library into your project or you can create your own.

Outbound

There are two parts to configuring a connector; you must first configure a provider and then the connector itself.

2.1 Configuring the provider

A provider is a means of grouping connectors that are available from the same web address. A CoAP provider is a remote CoAP server, which could also be a device.

You can create a new Provider by choosing My Connectors from the Toolbox, choosing the Providers Tab and clicking on New Provider.

NewProvider

This will open the New Provider page. From here you can choose secure CoAP (coaps://) or standard CoAP (coap://) from the drop down list of possible protocols.

Protocols

Further information on configuring a provider can be found here.

2.1.1 Standard CoAP

As opposed to secure CoAP (coaps://), standard CoAP (coap://) has no authentication scheme, standard CoAP is unencrypted and as such vulnerable - this protocol should only be used for testing purposes.

The default port for standard CoAP is 5683.

StandardCoAP

2.1.2 DTLS-enabled CoAP

The Datagram Transport Layer Security (DTLS) is the UDP-based version of TLS, designed to provide end-to-end security.

DTLS-enabled CoAP(coaps://) provides an encrypted connection and a choice of two authentication schemes, the schemes have their own impact on the way the connector communicates with the target server:

Authentication Schemes
No Authentication In this case the connector will choose a certificate-based encryption scheme.
Identity / Key In this case the connector will use a Pre-Shared Key (PSK) encryption scheme. You will be prompted for the Identity and Key when configuring the provider.

Please refer to the Encryption section for further details on both these schemes.

The default port for coaps:// is 5684.

SecureCoAP

2.2 Configuring the Connector

The connector is essentially the CoAP message. You can create a new connector by choosing My Connectors from the Toolbox, choosing the Connectors Tab and clicking on New Connector.

Connectors

2.2.1 Standard Parameters

The CoAP connector has the same options as connectors using other protocols (e.g. HTTP). Information on these parameters can be found here

ConnectorConfiguration

2.2.2 Advanced Parameters

Additional CoAP Parameters can be entered via the 'Advanced Parameters' section. There are three additional parameters, which are optional:

AdditionalParameters

Parameter Name Explanation
message-typePossible Values are:

  • CON (Confirmable)
  • NON (Non-Confirmable)
  • ACK (Acknowledgment)
  • RST (Reject)
proxi-URIThis parameter is relevant when talking to a CoAP-proxy server. A CoAP-proxy will route all requests to this address.
timeoutYou can specify a custom timeout in milliseconds. The default and maximum value is 30.000 (ms)

Please refer to the CoAP specification ( https://tools.ietf.org/html/rfc7252 ) for further details.

3 Inbound Communication (Device to RunMyProcess)

RunMyProcess provides the ability for CoAP devices to call a Composite API hosted on the RunMyProcess platform.

Inbound

CoAP messages should be sent to:

coaps://coap.runmyprocess.com:5684/coap2http

coap://coap.runmyprocess.com:5683/coap2http

The message will include the URI of the Composite API as a message parameter.

Please note that standard coap (coap://) is unencrypted and as such vulnerable. This protocol should only be used for testing purposes.

3.1 Message Options

CoAP requests and responses can include one or more parameters, the following ones should be set:

message-type

The CoAP message-type parameter should be set to CON (Confirmable). A Confirmable message is retransmitted using a default timeout until the recipient sends an Acknowledgement message (ACK) with the same Message ID.

proxy-URI

It is essential that the URL of your Composite API is specified in this option, you will have been given this URL when deploying your Composite API. Please see the Composite API chapter for details.

In addition, the proxy-URI requires an additional parameter that has to be added to the Composite API URI - the AuthToken. The AuthToken is the Base64-encoded string of your RunMyProcess credentials, token = Base64(username:password).

The token can be generated using CLI tools such as base64, openssl base64 on Linux or CygWin on Windows. There are also online services for this such as http://decodebase64.com/ but please note that online services aren't necessarily secure.

Example for the use of base64:

> echo -n 'hello:world' | base64

aGVsbG86d29ybGQK

The resulting proxy-URI parameter would look similar to this:

https://live.runmyprocess.com/live/aaaa/host/bbbb/service/cccc?P_mode=TEST&AuthToken=aGVsbG86d29ybGQK

It is possible to send the usual GET, PUT, POST and DELETE methods, content-types and character-sets of a Composite API.

3.2 Encryption

Secure CoAP (coaps://) offers two methods of encryption:

  • Certificate-based encryption
  • Pre-shared Key (PSK) Encryption

Please refer to the Encryption section for further details on both these schemes.

4 Encryption

DTLS-enabled CoAP(coaps:// ) provides an encrypted connection and a choice of two authentication schemes:

4.1 Certificate-based encryption scheme

A cipher will need to be specified as part of the DTLS handshake process; the handshake process will be initiated either by the connector in outbound messages from RunMyProcess or by the device in incoming messages to RunMyProcess. The cipher specifies which encryption algorithms to use and should be specified as TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.

RunMyProcess uses certificates signed by Comodo. It is essential that the Comodo root CA certificate is stored in the client's truststore to enable the connection to succeed.

4.2 Pre-Shared Key (PSK) Encryption

PSK encryption works on the concept of a secret which has previously been shared between the two parties.

The correct cipher for use with PSK Encryption is TLS_PSK_WITH_AES_128_CCM_8.

When choosing PSK transport encryption, the following credentials should be used:

identity: RunMyProcess user name key: SHA256 hash of the RunMyProcess password

The SHA256-hashed RunMyProcess password can be generated by downloading a software package from:

http://com.runmyprocess.jenkins.artifacts.coaproxy.s3-eu-west-1.amazonaws.com/PSKKey-jar-with-dependencies.jar

and executing the following command line tool:

java -jar PSKKey-jar-with-dependencies.jar rmppassword

Please note that the PSK mode is currently in beta. If you experience problems, please contact our support team with details.

5 Security

Security is provided via DTLS which is a variation of TLS/SSL optimized for small devices. The DTLS layer is fully transparent to the embedded CoAP communication.

DTLS/TLS encrypts the communication. Optionally it can authenticate a client via pre-shared keys (essentially credentials) but this information is kept in the DTLS layer only. The authentication is fully transparent to the CoAP layer where the business logic resides so the credentials are not accessible for http-forwarding purposes.

DTLS encrypts the total payload of the CoAP requests including the previously mentioned proxy-URI. Therefore the proxy-URI can be enriched with a BasicAuth token (key=XXX in the illustration below) which can in turn be used by the cross proxy to authenticate the request towards the RMP server.

Security

If Secure CoAP (coaps://) is not used the AuthToken will not be encrypted (just like the payload of the request). Thus it is recommended that Standard CoAP (coap://) is used only for testing/development purposes.