Protocols and Checksum

When using Carriots control panel, data integrity is granted by our panels logic. When REST API is used, checksum with HMAC can be useful to automatically check data integrity and re-authenticate each request.

Streams envelope

As detailed in our Streams creation API documentation for posting data and status streams some fields are required along with the data to be sent. This fields are the stream "envelope" and they are:

  • protocol: To know how the checksum field will be used
  • device: The device that sends the stream
  • at: Stream timestamp or "now" string for automatic timestamping
  • checksum: The checksum token depending on the protocol specified

Example:

How it works? Depending on the protocol, the checksum is calculated including message content and a secret key. This enables checking data integrity and the secret key offers an extra authentication method. This secret key is defined as a device property. This documentation covers the different protocols available at this moment and how to create checksum tokens.

Carriots protocols

Carriots has 3 protocols to be used between external devices or applications and Carriots:

  • v1: Used for internal purposes, do not use
  • v2: Without checksum validation, checksum field is ignored. May be good for simple devices
  • v3: Checksum authentication with HMAC-SHA1

Checksum calculation with Protocol v3 (HMAC-SHA1)

Using protocol version v3 the checksum token is generated by the sender and included in the envelope.

HMAC stands for Hash-based Message Authentication Code and provides more complexity and security in authentication code than classic SHA or MD5 methods. The algorithm is defined in RFC 2104 http://tools.ietf.org/html/rfc2104.

HMAC algorithm (from RFC 2104):

  • H(·) be a cryptographic hash function
  • K be a secret key padded to the right with extra zeros to the input block size of the hash function, or the hash of the original key if its longer than that block size
  • m be the message to be authenticated
  • || denote concatenation
  • ? denote exclusive or (XOR)
  • opad be the outer padding (0x5c5c5c…5c5c, one-block-long hexadecimal constant)
  • ipad be the inner padding (0x363636…3636, one-block-long hexadecimal constant)

Then HMAC(K,m) is mathematically defined by:

HMAC(K,m) = H((K ? opad) || H((K ? ipad) || m))

Carriots use SHA1 as cryptographic hash function and 64k blocksize. The message string to be "hashed" is composed by the "at" and "data" fields contents.

Algorithm pseudo-code:

Example:

HMAC has been generated with the following parameters:

  • Hash function: SHA1
  • Sender secret key: FGHDOMO453453KUN45DFPOUASA
  • Message string: 1356390000{"light": "ON"}
  • HMAC: 9aef92625a701af7dd71e3030f77207f9d9e95bd