デバイスから送信されたデータを Beam でデータを転送する際、Beam からのリクエストであることを転送先のサーバーで検証するための署名を挿入できます。
この署名は、SORACOM プラットフォームで計算され、リクエストに挿入されます。データ転送先のサーバーで、同じデータ、および同じアルゴリズムを利用して署名を計算し、リクエストに挿入された署名と一致した場合は、送信元が Beam であることを確認できる仕組みです。転送先のサーバーで署名を検証することを推奨します。
「事前共有鍵」には推測されにくい任意の文字列を指定してください。「事前共有鍵」には 4096 文字までの英文字・数字・記号を利用できます。
署名の検証は、以下の流れで行います。特に、「事前共有鍵」は事前に共有すること、また、Beam からお客様サーバーには送信されないことに注意してください。
事前に「SORACOM プラットフォーム」と「転送先のサーバー」に、「事前共有鍵」と呼ばれる文字列を登録します (①)。
デバイスから Beam のエントリポイントにデータを送信します (②)。
Beam に送信されたデータや送信元のデバイスの情報を元に署名が計算され (③)、転送先サーバーに送信されます (④)。
なお、署名の計算アルゴリズムは、エントリポイントごとに設定が異なります。
転送先サーバーは、Beam から送信されたデータから「事前共有鍵」以外の情報を取り出し、手順 1 で登録した「事前共有鍵」を利用して、既定された署名の計算アルゴリズムで、署名を計算します (⑤)。
転送先サーバーは、Beam から送信されたデータに含まれる署名と、転送先サーバーで計算した署名が一致していることを確認します (⑥)。
- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
HTTP/HTTPS 用アルゴリズム
x-soracom-signature: ${signature}
ヘッダーが追加されます。この ${signature}
が署名です。
HTTP/HTTPS 用アルゴリズムの署名の計算方法
以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。
${事前共有鍵}x-soracom-imei=${IMEI}x-soracom-imsi=${IMSI}x-soracom-msisdn=${MSISDN}x-soracom-sim-id=${SIM_ID}x-soracom-timestamp=${TIMESTAMP}
${事前共有鍵}
には、 のエントリポイントの設定で に設定した認証情報の に設定した値が含まれます。x-soracom-imei=${IMEI}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。接続中の通信キャリアが対応していないなどの理由で IMEI が取得できなかった場合は、
x-soracom-imei=${IMEI}
は含まれません。x-soracom-imsi=${IMSI}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-msisdn=${MSISDN}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-sim-id=${SIM_ID}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-timestamp=${TIMESTAMP}
は、常に含まれます。
署名の計算例
のエントリポイントの設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。
のエントリポイントの設定の例:
項目 | 値 |
---|---|
オン | |
オフ | |
オフ | |
オン | |
オン | |
「認証情報ストアで topsecret を設定した認証情報」を選択 | に
IoT SIM の情報の例:
項目 | 値 |
---|---|
IMSI | 295012345678901 |
SIM ID (*1) | 8942123456789012345 |
MSISDN (*1) | 423612345678 |
IMEI | 867612345678901 |
- (*1) で および をオフにしているため、署名の生成では利用されません。
データ送信時に付与されるタイムスタンプの例:
項目 | 値 |
---|---|
タイムスタンプ | 1640962800000 |
計算例:
転送先のサーバーで受信した HTTP ヘッダーから、以下の文字列を作成します。
topsecretx-soracom-imei=867612345678901x-soracom-imsi=295012345678901x-soracom-timestamp=1640962800000
手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。
83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba
この値が、計算した署名です。
手順 2 で計算した署名と、
x-soracom-signature: ${signature}
の${signature}
の値が一致していることを確認します。- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
HTTPS テストサーバーの署名検証機能
HTTP エントリポイント を選択して以下のように設定し、デバイスから Beam の HTTP エントリポイント (http://beam.soracom.io:8888/
) にデータを送信すると、テストサーバー (https://beamtest.soracom.io:443/
) によって署名が検証されて「Match!」と返されます。
設定例:
項目 | 説明 | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
任意の文字列 | |||||||||||||||||
オン | |||||||||||||||||
デバイスからの HTTP リクエストを受け付けるエントリポイントを設定します。
| |||||||||||||||||
このエントリポイントで受け付けたリクエストの転送先を設定します。
| |||||||||||||||||
転送先へのリクエストに追加するヘッダーを指定します。
|
レスポンスの例:
$ curl beam.soracom.io:8888
Hello SORACOM Beam Client IMSI:295012345678901 IMEI:867612345678901 !
== HTTP Headers ==
HTTP_X_SORACOM_SIGNATURE_VERSION = 20151001
HTTP_X_SORACOM_SIGNATURE = 83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba
HTTP_X_SORACOM_TIMESTAMP = 1640962800000
HTTP_X_SORACOM_IMEI = 867612345678901
HTTP_X_SORACOM_IMSI = 295012345678901
= Signature Verification =
Pre shared key = topsecret
stringToSign:
x-soracom-imei=867612345678901x-soracom-imsi=295012345678901x-soracom-timestamp=1640962800000
calculated_signature:
SHA256('topsecret'+stringToSign) = 83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba
provided_signature:
83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba
signature:
Match!
HTTPS テストサーバーの署名検証機能は、Beam から送信された署名を HTTPS テストサーバーで検証して、検証結果に応じて「Does not match...」や「Match!」、「Access Authorized」などを表示する機能です。
HTTPS テストサーバーの署名検証機能では、
をtopsecret
以外に設定した場合は、「Does not match...」と表示されます。任意のサーバーから HTTPS テストサーバーに対して、正しいヘッダーと正しい署名を付与したデータを送信しても「Match!」と返されます。
呼び出し例:
$ curl https://beamtest.soracom.io:443/ \ -H "x-soracom-signature-version: 20151001" \ -H "x-soracom-signature: 83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba" \ -H "x-soracom-timestamp: 1640962800000" \ -H "x-soracom-imei: 867612345678901" \ -H "x-soracom-imsi: 295012345678901"
レスポンス例:
Hello SORACOM Beam Client IMSI:295012345678901 IMEI:867612345678901 ! : signature: Match!
なお、以下のように HTTP リクエストボディを追加すると、「Access Authorized」と返されます。
呼び出し例:
$ curl https://beamtest.soracom.io:443/ \ -H "x-soracom-signature-version: 20151001" \ -H "x-soracom-signature: 83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba" \ -H "x-soracom-timestamp: 1640962800000" \ -H "x-soracom-imei: 867612345678901" \ -H "x-soracom-imsi: 295012345678901" \ -H "Content-Type:application/json" \ -d '{ "key": "value" }'
レスポンス例:
Access Authorized: {"key"=>"value"}
TCP/TCPS 用アルゴリズム
signature=${signature}
が追加されます。この ${signature}
が署名です。
TCP/TCPS 用アルゴリズムの署名の計算方法
以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。
${事前共有鍵}imei=${IMEI} imsi=${IMSI} msisdn=${MSISDN} simId=${SIM_ID} timestamp=${TIMESTAMP}
${事前共有鍵}
には、 のエントリポイントの設定で に設定した認証情報の に設定した値が含まれます。imei=${IMEI}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。接続中の通信キャリアが対応していないなどの理由で IMEI が取得できなかった場合は、
imei=undefined
が含まれます。imsi=${IMSI}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。msisdn=${MSISDN}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。simId=${SIM_ID}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。timestamp=${TIMESTAMP}
は、常に含まれます。
署名の計算例
グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。
グループ設定の例:
項目 | 値 |
---|---|
オン | |
オフ | |
オフ | |
オン | |
オン | |
「認証情報ストアで topsecret を設定した認証情報」を選択 | に
IoT SIM の情報の例:
項目 | 値 |
---|---|
IMSI (*1) | 295012345678901 |
SIM ID | 8942123456789012345 |
MSISDN (*1) | 423612345678 |
IMEI | 取得不可 |
- (*1) グループ設定で および をオフにしているため、署名の生成では利用されません。
データ送信時に付与されるタイムスタンプの例:
項目 | 値 |
---|---|
タイムスタンプ | 1640962800000 |
計算例:
事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。
topsecretimei=undefined simId=8942123456789012345 timestamp=1640962800000
手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。
83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba
この値が、計算した署名です。
手順 2 で計算した署名と、
signature=${signature}
の${signature}
の値が一致していることを確認します。- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
TCPS テストサーバーの署名検証機能
TCP → TCP/TCPS エントリポイント を選択して以下のように設定し、デバイスから Beam の TCP → TCP/TCPS エントリポイント (tcp://beam.soracom.io:8023/
) にデータを送信すると、TCPS テストサーバー (tcps://beamtest.soracom.io:1234/
) によって署名が検証されて「Match!」と返されます。
設定例:
項目 | 説明 | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
任意の文字列 | |||||||||||||||
オン | |||||||||||||||
このエントリポイントで受け付けたリクエストの転送先を設定します。
| |||||||||||||||
転送先へのリクエストに追加するヘッダーを指定します。
|
レスポンスの例:
$ nc beam.soracom.io 8023
--- SIGNATURE VERIFICATION
imei=undefined imsi=295012345678901 timestamp=1640962800000;signature=a1c2b406c2caba9c4ca1eee490621bf8b9bd825793d6a76aeb89bb77acfbf8e0 version=20151001
string_to_sign: imei=undefined imsi=295012345678901 timestamp=1640962800000
calculated_signature: sha256(string_to_sign) = a1c2b406c2caba9c4ca1eee490621bf8b9bd825793d6a76aeb89bb77acfbf8e0
provided_signature: a1c2b406c2caba9c4ca1eee490621bf8b9bd825793d6a76aeb89bb77acfbf8e0
---
Hello Authorized Soracom Beam Client! :imei=undefined imsi=295012345678901 timestamp=1640962800000
TCPS テストサーバーの署名検証機能は、Beam から送信された署名を TCPS テストサーバーで検証して、検証結果に応じて「ERROR: The request signature we calculated does not match the signature you provided.」や「Hello Authorized Soracom Beam Client!」などを表示する機能です。
TCPS テストサーバーの署名検証機能では、
をtopsecret
以外に設定した場合は、「ERROR: The request signature we calculated does not match the signature you provided.」と表示されます。任意のサーバーから TCPS テストサーバーに対して、正しいヘッダーと正しい署名を付与したデータを送信しても「Hello Authorized Soracom Beam Client!」と返されます。
呼び出し例:
$ ncat --ssl beamtest.soracom.io 1234 imei=undefined imsi=295012345678901 timestamp=1640962800000;signature=a1c2b406c2caba9c4ca1eee490621bf8b9bd825793d6a76aeb89bb77acfbf8e0 version=20151001
レスポンス例:
--- SIGNATURE VERIFICATION : --- Hello Authorized Soracom Beam Client! :imei=undefined imsi=295012345678901 timestamp=1640962800000
LoRaWAN 用アルゴリズム
LoRaWAN で通信している場合も、署名は同様に計算されます。なお、署名は x-soracom-signature
としてリクエストに付与されます。
LoRaWAN 用アルゴリズムの署名の計算方法
以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。
${事前共有鍵}x-soracom-lora-device-id=${LoRa device id}x-soracom-timestamp=${timestamp})
${事前共有鍵}
には、 のエントリポイントの設定で に設定した認証情報の に設定した値が含まれます。x-soracom-lora-device-id=${LoRa device id}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-timestamp=${timestamp}
は、常に含まれます。
署名の計算例
グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。
グループ設定の例:
項目 | 値 |
---|---|
オン | |
オン | |
「認証情報ストアで topsecret を設定した認証情報」を選択 | に
LoRaWAN デバイスの情報の例:
項目 | 値 |
---|---|
LoRa device id | 000b78fffe000001 |
データ送信時に付与されるタイムスタンプの例:
項目 | 値 |
---|---|
タイムスタンプ | 1492414740191 |
計算例:
事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。
topsecretx-soracom-lora-device-id=000b78fffe000001x-soracom-timestamp=1492414740191
手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。
cbf1a4c8c835eb7c8b12ce3e884da2be1845365f36ba633adcf444f17b41f295
この値が、計算した署名です。
手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。
- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
Sigfox 用アルゴリズム
Sigfox で通信している場合も、署名は同様に計算されます。なお、署名は x-soracom-signature
としてリクエストに付与されます。
Sigfox 用アルゴリズムの署名の計算方法
以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。
${事前共有鍵}x-soracom-sigfox-device-id=${Sigfox device id}x-soracom-timestamp=${timestamp}
${事前共有鍵}
には、 のエントリポイントの設定で に設定した認証情報の に設定した値が含まれます。x-soracom-sigfox-device-id=${Sigfox device id}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-timestamp=${timestamp}
は、常に含まれます。
署名の計算例
グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。
グループ設定の例:
項目 | 値 |
---|---|
オン | |
オン | |
「認証情報ストアで topsecret を設定した認証情報」を選択 | に
Sigfox デバイスの情報の例:
項目 | 値 |
---|---|
Sigfox device id | 000b78fffe000001 |
データ送信時に付与されるタイムスタンプの例:
項目 | 値 |
---|---|
タイムスタンプ | 1492414740191 |
計算例:
事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。
topsecretx-soracom-sigfox-device-id=000b78fffe000001x-soracom-timestamp=1492414740191
手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。
34be7efde2ba2d78ca0dff588a4b087e953a65c4fc0a90be6179eb12806273d2
この値が、計算した署名です。
手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。
- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
Inventory 用アルゴリズム
Inventory で通信している場合も、署名は同様に計算されます。なお、署名は x-soracom-signature
としてリクエストに付与されます。
Inventory 用アルゴリズムの署名の計算方法
以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。
${事前共有鍵}x-soracom-device-id=${Inventory device id}x-soracom-timestamp=${timestamp}
${事前共有鍵}
には、 のエントリポイントの設定で に設定した認証情報の に設定した値が含まれます。x-soracom-device-id=${Inventory device id}
は、 のエントリポイントの設定で をオンにしたときのみ含まれます。x-soracom-timestamp=${timestamp}
は、常に含まれます。
署名の計算例
グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。
グループ設定の例:
項目 | 値 |
---|---|
オン | |
オン | |
「認証情報ストアで topsecret を設定した認証情報」を選択 | に
Inventory デバイスの情報の例:
項目 | 値 |
---|---|
Inventory device id | 000b78fffe000001 |
データ送信時に付与されるタイムスタンプの例:
項目 | 値 |
---|---|
タイムスタンプ | 1492414740191 |
計算例:
事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。
topsecretx-soracom-device-id=d-1234567890abcdefghijx-soracom-timestamp=1492414740191
手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。
414c01c97fc8a7fa880e81f75447c2fade81d49d3bce3a3f7bb10ba94ed1e6fd
この値が、計算した署名です。
手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。
- 署名が一致したときは、データを利用できます。
- 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。