Signature Verification

When enabling the Signature header option, a SHA256 hash will be appended to the HTTP request header or TCP packet for use in verifying the connection request.

Signature header requires IMSI header or IMEI header to be enabled (or both), in addition to selecting a Pre-Shared Key.

When Beam receives data from your device, it will use the following information to generate a secure hash:

This information is used to generate one of the following unique strings, based on which headers have been enabled:

The SHA256 of the string is then calculated:

SHA256(unique-string)
= abcdef...12345678

And the resulting hash appended to the HTTP request as a header: X-Soracom-Signature: abcdef...12345678.


Signature Generation

For example, given the following:

The Signature header content is calculated using:

SHA256('mysecretkeyx-soracom-imei=860000012345678x-soracom-imsi=295000012345678x-soracom-timestamp=1445587157992')
= 95c8e34d68e2bd76502c1e403108dc1bd7008964c31081d0415adb9f21a721a5

Signature Verification

When Beam sends data to the forwarding destination, the corresponding headers used in the SHA256 calculation—excluding the Pre-Shared Key—will also be included:

You can then combine the data from the headers together with the secret Pre-Shared Key, using the format above, to independently verify the authenticity of the data.


Test Server

When using the HTTPS Beam test server with the Signature header option enabled, you can test the signature calculation behavior.

Configure Beam for HTTP entry point using the following Destination parameters:

Then simply make an HTTP request from the device to beam.soracom.io:8888:

curl beam.soracom.io:8888
>Hello SORACOM Beam Client 295000012345678 !
>
>== HTTP Headers ==
>HTTP_X_SORACOM_IMEI = 860000012345678
>HTTP_X_SORACOM_IMSI = 295000012345678
>HTTP_X_SORACOM_SIGNATURE = 95c8e34d68e2bd76502c1e403108dc1bd7008964c31081d0415adb9f21a721a5
>HTTP_X_SORACOM_SIGNATURE_VERSION = 20151001
>HTTP_X_SORACOM_TIMESTAMP = 1445587157992
>
>= Signature Verification =
>Pre shared key = mysecretkey
>
>stringToSign:
>x-soracom-imei=860000012345678x-soracom-imsi=295000012345678x-soracom-timestamp=1445587157992
>
>calculated_signature:
>SHA256('mysecretkey'+stringToSign) = 95c8e34d68e2bd76502c1e403108dc1bd7008964c31081d0415adb9f21a721a5
>
>provided_signature:
>95c8e34d68e2bd76502c1e403108dc1bd7008964c31081d0415adb9f21a721a5
>
>signature:
>Match!