2.1. SORACOM Beam (Basic) - soracom/handson GitHub Wiki

Objective

In this tutorial, you will learn how to send data from your device to backend servers or cloud services in a simple and secure fashion without your device encrypting the data.

Preparation

  • RPi connected with SORACOM Air

What is SORACOM Beam

SORACOM Beam (“Beam”) translates lightweight device friendly protocols like HTTP, MQTT, TCP or UDP into secure protocols like HTTPS, MQTTS or TCPS. Because SSL/TLS adds extra 100s of bytes overhead to each data upload, you end up saving approximately 40 to 60% of data transfer in typical IoT use cases. Beam also helps simple sensors or microcontrollers with no encryption capabilities to connect to cloud services like AWS IoT requiring HTTPS or MQTTS. First, your data will be sent to Beam end point via 3G/LTE network to SORACOM Platform. Your data will then be encrypted by SORACOM and be forwarded to the destination of your choice.

Currently, Beam supports the following protocol combinations.

Original Protocol Translated Protocol
HTTP HTTP(S)
MQTT MQTT(S)
TCP TCP(S)
TCP HTTP(S)
UDP HTTP(S)

To use Beam, you need to create a group, configure Beam parameter and move your SIM into the group you configured Beam with.

Create a Group

Click "Menu" in top left corner, and select "Groups". In the "Groups" screen, create a group by clicking "+ Add" button. You give it a name and hit “Create”

Configure Group

  1. Click the group name in the list to open group detail.
  2. Expand "SORACOM Beam" section.
  3. Click on "+" button choose HTTP entry point from protocol list
  4. Fill in the information below when "SORACOM Beam - HTTP configuration" dialog comes up
  • Configuration name: You can give an arbitrary name. For this workshop, name "HTTP to HTTPS
  • Entry point -> Path: specify ""
  • Destination -> Host name: specify "beamtest.soracom.io" (this is preconfigured HTTPS endpoint for this worksop)
  • Destination -> Port number: leave it blank or specify "443" (You can skip "Port number" if you use default port for HTTPS, which is 44/tcp)
  • Destination -> Path: specify "/"

Scroll down to the bottom and click "Save".

Change group in your SIM management page

  1. Click "Menu" and go back to "SIM Management" and search for the SIM name.
  2. Check the box next to your SIM name and click "Actions" -> "Change group".
  3. Click on ▼ and choose the group you created.

4.Click "Update" to apply.

Test the connection from Raspberry Pi

Login to the Raspberry Pi and type the following command.

Command

curl https://beamtest.soracom.io
curl http://beam.soracom.io:8888

Result

pi@raspberrypi:~ $ curl https://beamtest.soracom.io
Hello Unknown Client...

== HTTP Headers ==


pi@raspberrypi:~ $ curl http://beam.soracom.io:8888
Hello Unknown Client...

== HTTP Headers ==

You will see the same output for both commands although the first command is accessing the endpoint over HTTP. This means the HTTP request was translated into HTTPS and was forwarded to test server as an HTTPS request.

Append SIM info

As SORACOM identifies the SIM by its unique IDs, SORACOM Beam can append SIM information when forwarding the data to your endpoint. Please follow the step below to append Pre-Shared Key for your device to access restricted backend applications.

  1. Go back to "Group" setting by clicking the group name on your SIM and expand SORACOM Beam configuration section.
  2. Click "..." button on the right.
  3. You will see "Header manipulations" at the bottom. Turn on "IMSI header", "IMEI header", and "Signature header".
  4. Press [+] button next to "Pre-Shared Key".
  5. You can give any arbitrary name, but for this workshop, type in "topsecret" in "Pre-Shared Key". "topsecret" is the password already configured in Beam test server for signature matching example in this workshop.

  1. Click "Register" to get back to "HTTP configuration" and click "Save" to apply the setting.
  2. Execute the following command on your Raspberry Pi.

Command

curl http://beam.soracom.io:8888

Result

pi@raspberrypi:~ $ curl http://beam.soracom.io:8888
Hello SORACOM Beam Client 89423xxxxxxxxxx !

== HTTP Headers ==
HTTP_X_SORACOM_IMEI = 35636xxxxxxxxxx
HTTP_X_SORACOM_IMSI = 89423xxxxxxxxxx
HTTP_X_SORACOM_SIGNATURE = ccafbf350fffd01f5f4fd0dac0b34da80870864b54c621c97c1125ba30f1e4a7
HTTP_X_SORACOM_SIGNATURE_VERSION = 20151001
HTTP_X_SORACOM_TIMESTAMP = 1494662049112

= Signature Verification =
Pre shared key = topsecret

stringToSign:
x-soracom-imei=35636xxxxxxxxxxx-soracom-imsi=89423xxxxxxxxxxx-soracom-timestamp=1494662049112

calculated_signature:
SHA256('topsecret'+stringToSign) = ccafbf350fffd01f5f4fd0dac0b34da80870864b54c621c97c1125ba30f1e4a7

provided_signature:
ccafbf350fffd01f5f4fd0dac0b34da80870864b54c621c97c1125ba30f1e4a7

signature:
Match!

The output should look different now. Beam test server identifies this request coming from the SIM card with IMSI(89423xxxxxxxxxx). Beam test server understands this information from HTTP_X_SORACOM_IMSI header.

To prevent unauthorized accesses, you should also check the request signature. Beam test server can calculate it from "Pre-Shared Key", “IMSI”, “IMEI” and its timestamp. If the signature matches, you can prove that this access is from the SIM card on your IoT device.

TCP to HTTPS translation

If your device is not capable of handling HTTP or HTTPS, Beam can even translate TCP into HTTPS for secure data transmission. Let's try TCP to HTTPS translation in this section.

Configure Group

  1. Click “Menu” -> "Groups" and click the group name.
  2. Expand "SORACOM Beam"
  3. Click on "+" button and select "TCP to HTTP/HTTPS" entry point.
  4. When "SORACOM Beam - TCP to HTTP/HTTPS configuration" dialog comes up, please fill in the information below
  • Configuration name: Any arbitrary name but let's give "TCP to HTTPS"
  • Host name: specify "beamtest.soracom.io" (this is our test HTTPS endpoint for this workshop)
  • Port number: keep it blank or specify "443" (You can leave "Port number" blank if you use default TCP:443)
  • Path: specify "/"
  • Header manipulations: IMSI header/IMEI header/Signature header -> ON
  • Header manipulations -> Pre-Shared Key: choose the same key which you created in the previous HTTP to HTTPS section.

Test the connection from Raspberry Pi

You can use nc(netcat) command to send data into raw TCP socket. Please specify beam endpoint and port number in your command parameter.

Command

nc beam.soracom.io 23080
foobar (or anything you want to submit)
(Ctrl+C to exit)

Result

pi@raspberrypi:~ $ nc beam.soracom.io 23080
foobar
200 Access Authorized: {"payload"=>"Zm9vYmFyCg=="} => foobar

The server authenticated your SIM by checking the signature and accepted your data in base64 encoded format. If you decode this string, it will match the original string you sent over Beam. This will end the advanced scenario.

Thank you so much for reaching this far.

If you have any questions regarding your IoT project, please come to soracom.io and use “contact us” form to get to us