Soracom

Users

ドキュメント

署名ヘッダーと事前共有鍵を使って送信元を検証する

デバイスから送信されたデータを 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 で計算した署名と、転送先のサーバーで受信した署名の値が一致していることを確認します。

    • 署名が一致したときは、データを利用できます。
    • 署名が一致しないときは、第三者がデータを送信してきたとみなして、破棄してください。
Copyright © 2015-2022 SORACOM, INC.
最終更新日: 2022-08-19
エントリポイントリファレンス : Inventory → HTTP/HTTPS エントリポイント
そのほかの使い方 : レスポンスのステータスコードを省略する
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog