Soracom

Users

ドキュメント
Home ドキュメント SORACOM Beam そのほかの使いかた

転送先サーバーで SORACOM Beam からのリクエストであることを検証する

デバイスから送信されたデータを Beam でデータを転送する際、Beam からのリクエストであることを転送先のサーバーで検証するための署名を挿入できます。

この署名は、SORACOM プラットフォームで計算され、リクエストに挿入されます。データ転送先のサーバーで、同じデータ、および同じアルゴリズムを利用して署名を計算し、リクエストに挿入された署名と一致した場合は、送信元が Beam であることを確認できる仕組みです。転送先のサーバーで署名を検証することを推奨します。

「事前共有鍵」には推測されにくい任意の文字列を指定してください。「事前共有鍵」には 4096 文字までの英文字・数字・記号を利用できます。

署名の検証は、以下の流れで行います。特に、「事前共有鍵」は事前に共有すること、また、Beam からお客様サーバーには送信されないことに注意してください。

  1. 事前に「SORACOM プラットフォーム」と「転送先のサーバー」に、「事前共有鍵」と呼ばれる文字列を登録します (①)。

    • SORACOM プラットフォームでは、認証情報ストア に 事前共有鍵 を登録してください。

      さらに、Beam のグループ設定で [署名ヘッダ付与] をオンにし、手順 1 で登録した「事前共有鍵」を [事前共有鍵] で選択します。

    • 転送先のサーバーでは、署名を計算する際に「事前共有鍵」を利用してください。

  2. デバイスから Beam のエントリポイントにデータを送信します (②)。

    Beam に送信されたデータや送信元のデバイスの情報を元に署名が計算され (③)、転送先サーバーに送信されます (④)。

    なお、署名の計算アルゴリズムは、エントリポイントごとに設定が異なります。

    エントリポイント署名の計算アルゴリズム
    HTTP エントリポイントHTTP/HTTPS 用アルゴリズム
    Web サイトエントリポイントHTTP/HTTPS 用アルゴリズム
    MQTT エントリポイント(署名ヘッダーを付与できません)
    TCP → TCP/TCPS エントリポイントTCP/TCPS 用アルゴリズム
    TCP → HTTP/HTTPS エントリポイントHTTP/HTTPS 用アルゴリズム
    UDP → HTTP/HTTPS エントリポイントHTTP/HTTPS 用アルゴリズム
    SMS → HTTP/HTTPS エントリポイントHTTP/HTTPS 用アルゴリズム
    USSD → HTTP/HTTPS エントリポイントHTTP/HTTPS 用アルゴリズム
    LoRaWAN → HTTP/HTTPS エントリポイントLoRaWAN 用アルゴリズム
    Sigfox → HTTP/HTTPS エントリポイントSigfox 用アルゴリズム
    Inventory → HTTP/HTTPS エントリポイントInventory 用アルゴリズム

  3. 転送先サーバーは、Beam から送信されたデータから「事前共有鍵」以外の情報を取り出し、手順 1 で登録した「事前共有鍵」を利用して、既定された署名の計算アルゴリズムで、署名を計算します (⑤)。

  4. 転送先サーバーは、Beam から送信されたデータに含まれる署名と、転送先サーバーで計算した署名が一致していることを確認します (⑥)。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。

HTTP/HTTPS 用アルゴリズム

[SORACOM Beam 設定] で HTTP/HTTPS 用アルゴリズムを利用するエントリポイントを追加し、エントリポイントの設定で [署名 ヘッダ 付与] をオンにすると、転送先サーバーへの HTTP リクエストに 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}

  • ${事前共有鍵} には、[SORACOM Beam 設定] のエントリポイントの設定で [事前共有鍵] に設定した認証情報の [事前共有鍵] に設定した値が含まれます。

  • x-soracom-imei=${IMEI} は、[SORACOM Beam 設定] のエントリポイントの設定で [IMEI ヘッダ] をオンにしたときのみ含まれます。

    接続中の通信キャリアが対応していないなどの理由で IMEI が取得できなかった場合は、x-soracom-imei=${IMEI} は含まれません。

  • x-soracom-imsi=${IMSI} は、[SORACOM Beam 設定] のエントリポイントの設定で [IMSI ヘッダ] をオンにしたときのみ含まれます。

  • x-soracom-msisdn=${MSISDN} は、[SORACOM Beam 設定] のエントリポイントの設定で [MSISDN ヘッダ] をオンにしたときのみ含まれます。

  • x-soracom-sim-id=${SIM_ID} は、[SORACOM Beam 設定] のエントリポイントの設定で [SIM ID ヘッダ] をオンにしたときのみ含まれます。

  • x-soracom-timestamp=${TIMESTAMP} は、常に含まれます。

署名の計算例

[SORACOM Beam 設定] のエントリポイントの設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。

[SORACOM Beam 設定] のエントリポイントの設定の例:

項目値
[IMSI ヘッダ]オン
[SIM ID ヘッダ]オフ
[MSISDN ヘッダ]オフ
[IMEI ヘッダ]オン
[署名ヘッダ付与]オン
[事前共有鍵]「認証情報ストアで [事前共有鍵] に topsecret を設定した認証情報」を選択

IoT SIM の情報の例:

項目値
IMSI295012345678901
SIM ID (*1)8942123456789012345
MSISDN (*1)423612345678
IMEI867612345678901
  • (*1) [SORACOM Beam 設定] で [SIM ID ヘッダ] および [MSISDN ヘッダ] をオフにしているため、署名の生成では利用されません。

データ送信時に付与されるタイムスタンプの例:

項目値
タイムスタンプ1640962800000

計算例:

  1. 転送先のサーバーで受信した HTTP ヘッダーから、以下の文字列を作成します。

    topsecretx-soracom-imei=867612345678901x-soracom-imsi=295012345678901x-soracom-timestamp=1640962800000

  2. 手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。

    83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba

    この値が、計算した署名です。

  3. 手順 2 で計算した署名と、x-soracom-signature: ${signature} の ${signature} の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。

テストサーバーの署名検証機能

[SORACOM Beam 設定] で HTTP エントリポイント を選択して以下のように設定し、デバイスから Beam の HTTP エントリポイント (http://beam.soracom.io:8888/) にデータを送信すると、テストサーバー (https://beamtest.soracom.io:443/) によって署名が検証されて「Match!」と返されます。

設定例:

項目説明
[設定名]任意の文字列
[有効]オン
[エントリポイント]

デバイスからの HTTP リクエストを受け付けるエントリポイントを設定します。

項目説明
[パス]/
[転送先]

このエントリポイントで受け付けたリクエストの転送先を設定します。

項目説明
[プロトコル]「HTTPS」を選択
[ホスト名]beamtest.soracom.io
[ポート番号]443
[パス]/
[ヘッダ操作]

転送先へのリクエストに追加するヘッダーを指定します。スイッチをオンにしたときに追加されるヘッダーは以下のとおりです。

項目説明
[IMSI ヘッダ]オン
[SIM ID ヘッダ]オフ
[MSISDN ヘッダ]オフ
[IMEI ヘッダ]オン
[署名 ヘッダ 付与]オン
[事前共有鍵][＋認証情報を追加] をクリックして、[認証情報 ID] に任意の文字列を入力し、[事前共有鍵] に topsecret を入力して、[登録] をクリック
[カスタムヘッダ]空欄

レスポンスの例:

$ 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!

テストサーバーの署名検証機能は、Beam から送信された署名をテストサーバーで検証して、検証結果に応じて「Does not match...」や「Match!」、「Access Authorized」などを表示する機能です。

  • テストサーバーの署名検証機能では、[事前共有鍵] を topsecret 以外に設定した場合は、「Does not match...」と表示されます。

  • 任意のサーバーからテストサーバーに対して、正しいヘッダーと正しい署名を付与したデータを送信しても「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 用アルゴリズム

[SORACOM Beam 設定] で TCP/TCPS 用アルゴリズムを利用するエントリポイントを追加し、エントリポイントの設定で [署名 ヘッダ 付与] をオンにすると、転送先サーバーに送信されるデータに signature=${signature} が追加されます。この ${signature} が署名です。

TCP/TCPS 用アルゴリズムの署名の計算方法

以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。

${事前共有鍵}imei=${IMEI} imsi=${IMSI} msisdn=${MSISDN} simId=${SIM_ID} timestamp=${TIMESTAMP}

  • ${事前共有鍵} には、[SORACOM Beam 設定] のエントリポイントの設定で [事前共有鍵] に設定した認証情報の [事前共有鍵] に設定した値が含まれます。

  • imei=${IMEI} は、[SORACOM Beam 設定] のエントリポイントの設定で [IMEI ヘッダ] をオンにしたときのみ含まれます。

    接続中の通信キャリアが対応していないなどの理由で IMEI が取得できなかった場合は、imei=undefined が含まれます。

  • imsi=${IMSI} は、[SORACOM Beam 設定] のエントリポイントの設定で [IMSI ヘッダ] をオンにしたときのみ含まれます。

  • msisdn=${MSISDN} は、[SORACOM Beam 設定] のエントリポイントの設定で [MSISDN ヘッダ] をオンにしたときのみ含まれます。

  • simId=${SIM_ID} は、[SORACOM Beam 設定] のエントリポイントの設定で [SIM ID ヘッダ] をオンにしたときのみ含まれます。

  • timestamp=${TIMESTAMP} は、常に含まれます。

署名の計算例

グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。

グループ設定の例:

項目値
[IMSI ヘッダ]オン
[SIM ID ヘッダ]オフ
[MSISDN ヘッダ]オフ
[IMEI ヘッダ]オン
[署名ヘッダ付与]オン
[事前共有鍵]「認証情報ストアで [事前共有鍵] に topsecret を設定した認証情報」を選択

IoT SIM の情報の例:

項目値
IMSI (*1)295012345678901
SIM ID8942123456789012345
MSISDN (*1)423612345678
IMEI取得不可
  • (*1) グループ設定で [IMSI ヘッダ] および [MSISDN ヘッダ] をオフにしているため、署名の生成では利用されません。

データ送信時に付与されるタイムスタンプの例:

項目値
タイムスタンプ1640962800000

計算例:

  1. 事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。

    topsecretimei=undefined simId=8942123456789012345 timestamp=1640962800000

  2. 手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。

    83341a7b3fa0b264e029c338acf83ac07cc416789efe9ace4275a537924aecba

    この値が、計算した署名です。

  3. 手順 2 で計算した署名と、signature=${signature} の ${signature} の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。

テストサーバーの署名検証機能

[SORACOM Beam 設定] で TCP → TCP/TCPS エントリポイント を選択して以下のように設定し、デバイスから Beam の TCP → TCP/TCPS エントリポイント (tcp://beam.soracom.io:8023/) にデータを送信すると、テストサーバー (tcps://beamtest.soracom.io:1234/) によって署名が検証されて「Match!」と返されます。

設定例:

項目説明
[設定名]任意の文字列
[有効]オン
[転送先]

このエントリポイントで受け付けたリクエストの転送先を設定します。

項目説明
[プロトコル]「TCPS」を選択
[ホスト名]beamtest.soracom.io
[ポート番号]1234
[ヘッダ操作]

転送先へのリクエストに追加するヘッダーを指定します。スイッチをオンにしたときに追加されるヘッダーは以下のとおりです。

項目説明
[IMSI ヘッダ]オン
[SIM ID ヘッダ]オフ
[MSISDN ヘッダ]オフ
[IMEI ヘッダ]オン
[署名 ヘッダ 付与]オン
[事前共有鍵][＋認証情報を追加] をクリックして、[認証情報 ID] に任意の文字列を入力し、[事前共有鍵] に topsecret を入力して、[登録] をクリック

レスポンスの例:

$ 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

テストサーバーの署名検証機能は、Beam から送信された署名をテストサーバーで検証して、検証結果に応じて「ERROR: The request signature we calculated does not match the signature you provided.」や「Hello Authorized Soracom Beam Client!」などを表示する機能です。

  • テストサーバーの署名検証機能では、[事前共有鍵] を topsecret 以外に設定した場合は、「ERROR: The request signature we calculated does not match the signature you provided.」と表示されます。

  • 任意のサーバーからテストサーバーに対して、正しいヘッダーと正しい署名を付与したデータを送信しても「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})

  • ${事前共有鍵} には、[SORACOM Beam 設定] のエントリポイントの設定で [事前共有鍵] に設定した認証情報の [事前共有鍵] に設定した値が含まれます。
  • x-soracom-lora-device-id=${LoRa device id} は、[SORACOM Beam 設定] のエントリポイントの設定で [デバイス ID 付与] をオンにしたときのみ含まれます。
  • x-soracom-timestamp=${timestamp} は、常に含まれます。

署名の計算例

グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。

グループ設定の例:

項目値
[デバイス ID 付与]オン
[署名ヘッダ付与]オン
[事前共有鍵]「認証情報ストアで [事前共有鍵] に topsecret を設定した認証情報」を選択

LoRaWAN デバイスの情報の例:

項目値
LoRa device id000b78fffe000001

データ送信時に付与されるタイムスタンプの例:

項目値
タイムスタンプ1492414740191

計算例:

  1. 事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。

    topsecretx-soracom-lora-device-id=000b78fffe000001x-soracom-timestamp=1492414740191

  2. 手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。

    cbf1a4c8c835eb7c8b12ce3e884da2be1845365f36ba633adcf444f17b41f295

    この値が、計算した署名です。

  3. 手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。

Sigfox 用アルゴリズム

Sigfox で通信している場合も、署名は同様に計算されます。なお、署名は x-soracom-signature としてリクエストに付与されます。

Sigfox 用アルゴリズムの署名の計算方法

以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。

${事前共有鍵}x-soracom-sigfox-device-id=${Sigfox device id}x-soracom-timestamp=${timestamp}

  • ${事前共有鍵} には、[SORACOM Beam 設定] のエントリポイントの設定で [事前共有鍵] に設定した認証情報の [事前共有鍵] に設定した値が含まれます。
  • x-soracom-sigfox-device-id=${Sigfox device id} は、[SORACOM Beam 設定] のエントリポイントの設定で [デバイス ID 付与] をオンにしたときのみ含まれます。
  • x-soracom-timestamp=${timestamp} は、常に含まれます。

署名の計算例

グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。

グループ設定の例:

項目値
[デバイス ID 付与]オン
[署名ヘッダ付与]オン
[事前共有鍵]「認証情報ストアで [事前共有鍵] に topsecret を設定した認証情報」を選択

Sigfox デバイスの情報の例:

項目値
Sigfox device id000b78fffe000001

データ送信時に付与されるタイムスタンプの例:

項目値
タイムスタンプ1492414740191

計算例:

  1. 事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。

    topsecretx-soracom-sigfox-device-id=000b78fffe000001x-soracom-timestamp=1492414740191

  2. 手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。

    34be7efde2ba2d78ca0dff588a4b087e953a65c4fc0a90be6179eb12806273d2

    この値が、計算した署名です。

  3. 手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。

Inventory 用アルゴリズム

Inventory で通信している場合も、署名は同様に計算されます。なお、署名は x-soracom-signature としてリクエストに付与されます。

Inventory 用アルゴリズムの署名の計算方法

以下の文字列を作成したうえで、この文字列の SHA-256 ハッシュ値を計算します。その SHA-256 ハッシュ値が、署名です。

${事前共有鍵}x-soracom-device-id=${Inventory device id}x-soracom-timestamp=${timestamp}

  • ${事前共有鍵} には、[SORACOM Beam 設定] のエントリポイントの設定で [事前共有鍵] に設定した認証情報の [事前共有鍵] に設定した値が含まれます。
  • x-soracom-device-id=${Inventory device id} は、[SORACOM Beam 設定] のエントリポイントの設定で [デバイス ID 付与] をオンにしたときのみ含まれます。
  • x-soracom-timestamp=${timestamp} は、常に含まれます。

署名の計算例

グループ設定、IoT SIM の情報、データ送信時に付与されるタイムスタンプが以下の場合に、署名の計算方法と計算結果を紹介します。

グループ設定の例:

項目値
[デバイス ID 付与]オン
[署名ヘッダ付与]オン
[事前共有鍵]「認証情報ストアで [事前共有鍵] に topsecret を設定した認証情報」を選択

Inventory デバイスの情報の例:

項目値
Inventory device id000b78fffe000001

データ送信時に付与されるタイムスタンプの例:

項目値
タイムスタンプ1492414740191

計算例:

  1. 事前共有鍵と転送先のサーバーで受信したデータから、以下の文字列を作成します。

    topsecretx-soracom-device-id=d-1234567890abcdefghijx-soracom-timestamp=1492414740191

  2. 手順 1 で作成した文字列の SHA-256 ハッシュ値を計算します。

    414c01c97fc8a7fa880e81f75447c2fade81d49d3bce3a3f7bb10ba94ed1e6fd

    この値が、計算した署名です。

  3. 手順 2 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
© 2015-2023 SORACOM
最終更新日: 2023-08-08
そのほかの使いかた : レスポンスのデータ終端バイト列を設定する
そのほかの使いかた : Virtual Private Gateway (VPG) を利用してよりセキュアにデータを転送する
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog