Signature Verification

When enabling the Signature header option, a SHA-256 hash will be calculated using a pre-shared key that you define, and will be appended to the HTTP request header or TCP packet. You can then independently re-calculate the SHA-256 hash on your server application in order to verify the connection request.

Air for Cellular

To use the Signature header option, you must also enable one or more of the IMEI Header, IMSI Header, MSISDN Header, or SIM ID Header options, as well as create or select 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:

Then simply calculate the SHA-256 value of the unique string:

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

You can then check the resulting hash against the signature value that was appened to the request:


Air for Sigfox and Air for LoRaWAN

To use the Signature header option, you must create or select a Pre-shared key. The Sigfox or LoRa Device ID will automatically be used when calculating the SHA-256 signature.

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

Air for Sigfox and Air for LoRaWAN

This information is used to generate one the following unique strings:

Then simply calculate the SHA-256 value of the unique string:

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

You can then check the resulting hash against the signature value that was appened to the request:


Example

Signature Generation

For example, given the following:

When a Beam HTTP/HTTPS endpoint is configured, the unique string will be formatted as:

mysecretkeyx-soracom-imei=860000012345678x-soracom-imsi=295000012345678x-soracom-timestamp=1445587157992

Then the signature header value is calculated using the unique string:

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 SHA-256 calculation—excluding the Pre-shared key—will also be included as part of the HTTP/HTTPS request:

You can then combine the values from the headers together with your secret pre-shared key, using the either the HTTP/HTTPs 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!