How to use checksum validation

This tutorial will show you how to use checksum validation to ensure data integrity and message authentication. To know more about checksum and protocols please read protocols and checksum documetation.

Introduction

Carriots has three different protocols, but if you want to use checksum validation, is necessary prococol:v3 in the stream envelope.

A correct stream with checkum validation will be something like:

But, how is it constructed?

Building the example

If youre registered in Carriots, you have a default device already created for you.
Check your control panel and see what it looks like.
Basically you need the device id_developer that might be something like defaultDevice@myusername.

We will assume we have the test@carriots device for this tutorial.

Now, go to your control panel “My account menu” and check your Apikey.
Its a big alphanumeric token like 98346673a6377ef1fde2357ebdcb0da582b150b00cabcd5a0d83045425407ab4.

The next step is to define the secret key as a property in the device. To do this, go to the control panel “Hierarchy” → “Devices” menu and edit your device.

In checksum field type your secret key.

  • Secret key - checksum

Finally we need a REST client, for this example we will use Poster. This client can be whatever you want that can create full HTTP request including headers, verbs and so on.

Follow these steps:

  • Install Poster for Firefox https://addons.mozilla.org/en-us/firefox/addon/poster/
  • Once installed, open it (Ctrl+Alt+P)
  • In the url section, type -> https://api.carriots.com/streams/
  • Click the "Content to Send" tab and type your payload. Example:
    {
    "protocol":"v3",
    "checksum":"",
    "device":"test@carriots",
    "at":"now",
    "data":{"test":"ok"}
    }
  • Click the "headers" tab and type your carriots.apikey
  • Click post button

You should have something like this:

  • Response - Not authorized

But, Why the response is wrong?

The answer is very simple. If we specify protocol:v3, is mandatory complete the checksum encoded with our secret key. If it isn't specified or if you specify an incorrect checksum, the request will receive "Not authorized", because Carriots can not verify the message integrity.

To build the correct checksum with our example values, you can use your preferred programming language, but in this case we will use an online tool. For example hmac-generator

Write these values:

  • Copy-paste the message here: now{"test":"ok"}
  • Secret Key: Your Secret Key
  • Select a message digest algorithm: SHA1
  • Click COMPUTE HMAC

You should have something like this:

  • hmac - generator

Copy the hexadecimal result value in your stream checksum field and try to send again. Now the response is correct.

  • Response - Ok

It's easy, isn't it?. Enjoy Carriots!