origin/786-update-CoAP-documentation
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.
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.
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.
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.
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.
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.
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.
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
2.2.2 Advanced Parameters
Additional CoAP Parameters can be entered via the 'Advanced Parameters' section. There are three additional parameters, which are optional:
| Parameter Name | Explanation |
|---|---|
| message-type | Possible Values are:
|
| proxi-URI | This parameter is relevant when talking to a CoAP-proxy server. A CoAP-proxy will route all requests to this address. |
| timeout | You 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.
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.
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.