Jak používat symetrické klíče přes HTTPS bez sady SDK

  • Článek

V tomto článku s postupy zřídíte zařízení pomocí symetrických klíčů přes HTTPS bez použití sady SDK pro zařízení Azure IoT DPS. Většina jazyků poskytuje knihovny pro odesílání požadavků HTTP, ale místo toho, abyste se v tomto článku zaměřili na konkrétní jazyk, použijete nástroj příkazového řádku cURL k odesílání a přijímání přes PROTOKOL HTTPS.

Postup najdete v tomto článku na počítači s Linuxem nebo Windows. Pokud používáte Subsystém Windows pro Linux (WSL) nebo používáte na počítači s Linuxem, můžete do příkazového řádku Bash zadat všechny příkazy v místním systému. Pokud používáte Windows, zadejte všechny příkazy v místním systému do příkazového řádku GitBash.

Tento článek obsahuje různé cesty v závislosti na typu položky registrace, kterou se rozhodnete použít. Po instalaci požadavků si před pokračováním přečtěte přehled .

Požadavky

Přehled

Pro účely tohoto článku můžete ke zřízení prostřednictvím DPS použít individuální registraci nebo skupinu registrací.

Po vytvoření jednotlivé registrace nebo položky skupiny registrací pokračujte vytvořením tokenu SAS a zaregistrujte zařízení ve službě DPS.

Použití jednotlivé registrace

Pokud chcete vytvořit novou jednotlivou registraci, kterou chcete použít pro tento článek, můžete pomocí příkazu az iot dps enrollment create vytvořit jednotlivou registraci pro ověření symetrického klíče.

Následující příkaz vytvoří položku registrace s výchozí zásadou přidělování pro vaši instanci DPS a umožní službě DPS přiřadit primární a sekundární klíče pro vaše zařízení:

az iot dps enrollment create -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --attestation-type symmetrickey

  • Nahraďte název vaší skupiny prostředků a instance DPS.

  • ID registrace je ID registrace pro vaše zařízení. ID registrace je řetězec nerozlišující velká a malá písmena (maximálně 128 znaků dlouhý) alfanumerických znaků a speciálních znaků: '-', '.', '_', ':'. Poslední znak musí být alfanumerický nebo pomlčka ('-'). Ujistěte se, že ID registrace, které používáte v příkazu, dodržuje tento formát.

Přiřazené symetrické klíče se vrátí ve vlastnosti ověření identity v odpovědi:


{
  "allocationPolicy": null,
  "attestation": {
    "symmetricKey": {
      "primaryKey": "G3vn0IZH9oK3d4wsxFpWBtd2KUrtjI+39dZVRf26To8w9OX0LaFV9yZ93ELXY7voqHEUsNhnb9bt717UP87KxA==",
      "secondaryKey": "4lNxgD3lUAOEOied5/xOocyiUSCAgS+4b9OvXLDi8ug46/CJzIn/3rN6Ys6gW8SMDDxMQDaMRnIoSd1HJ5qn/g=="
    },
    "tpm": null,
    "type": "symmetricKey",
    "x509": null
  },

  ...

}

Poznamenejte si primární klíč a ID registrace (ID registrace) pro vaši jednotlivou položku registrace, použijete je dále v tomto článku.

Pokud chcete použít existující individuální registraci pro tento článek, můžete primární klíč získat pomocí příkazu az iot dps enrollment show :

az iot dps enrollment show -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --show-keys true

Použití skupiny registrací

Pokud chcete pro účely tohoto článku vytvořit novou skupinu registrací, můžete k vytvoření skupiny registrací pro ověření symetrického klíče použít příkaz az iot dps enrollment-group create .

Následující příkaz vytvoří položku skupiny registrací s výchozí zásadou přidělování pro vaši instanci DPS a umožní službě DPS přiřadit primární a sekundární klíče pro skupinu registrací:

az iot dps enrollment-group create -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id}

  • Nahraďte název vaší skupiny prostředků a instance DPS.

  • ID registrace je řetězec nerozlišující velká a malá písmena (maximálně 128 znaků dlouhý) alfanumerických znaků a speciálních znaků: '-', '.''_', ':'. Poslední znak musí být alfanumerický nebo pomlčka ('-'). Může se jednat o libovolný název, který se rozhodnete použít pro skupinu registrací.

Přiřazené symetrické klíče se vrátí ve vlastnosti ověření identity v odpovědi:


{
  "allocationPolicy": null,
  "attestation": {
    "symmetricKey": {
      "primaryKey": "G3vn0IZH9oK3d4wsxFpWBtd2KUrtjI+39dZVRf26To8w9OX0LaFV9yZ93ELXY7voqHEUsNhnb9bt717UP87KxA==",
      "secondaryKey": "4lNxgD3lUAOEOied5/xOocyiUSCAgS+4b9OvXLDi8ug46/CJzIn/3rN6Ys6gW8SMDDxMQDaMRnIoSd1HJ5qn/g=="
    },
    "tpm": null,
    "type": "symmetricKey",
    "x509": null
  },

  ...

}

Poznamenejte si primární klíč.

Pokud chcete pro tento článek použít existující individuální registraci, můžete primární klíč získat pomocí příkazu az iot dps enrollment-group show :

az iot dps enrollment-group show -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --show-keys true

Odvození klíče zařízení

Při použití ověření symetrického klíče s registracemi skupin nepoužíváte klíče skupiny registrací přímo. Místo toho odvozujete jedinečný klíč pro každé zařízení z klíče skupiny registrací. Další informace najdete v tématu Skupinové registrace se symetrickými klíči.

V této části vygenerujete klíč zařízení z primárního klíče skupiny registrací pro výpočet HMAC-SHA256 jedinečného ID registrace zařízení. Výsledek se pak převede do formátu Base64.

  1. Vygenerujte jedinečný klíč pomocí openssl. Použijete následující skript prostředí Bash. Nahraďte {primary-key} primárním klíčem skupiny registrací, který jste zkopírovali dříve, a nahraďte {contoso-simdevice}ID registrace, které chcete pro zařízení použít. ID registrace je řetězec nerozlišující velká a malá písmena (maximálně 128 znaků dlouhý) alfanumerických znaků a speciálních znaků: '-', '.', '_', ':'. Poslední znak musí být alfanumerický nebo pomlčka ('-').

    KEY={primary-key}
REG_ID={contoso-simdevice}

keybytes=$(echo $KEY | base64 --decode | xxd -p -u -c 1000)
echo -n $REG_ID | openssl sha256 -mac HMAC -macopt hexkey:$keybytes -binary | base64

  2. Skript zobrazí výstup podobný následujícímu klíči:

    p3w2DQr9WqEGBLUSlFi1jPQ7UWQL4siAGy75HFTFbf8=

Poznamenejte si odvozený klíč zařízení a ID registrace, které jste použili k jeho vygenerování, a použijete ho v další části.

Klíč zařízení můžete odvodit také pomocí Azure CLI nebo PowerShellu. Další informace najdete v tématu Odvození klíče zařízení.

Vytvoření tokenu SAS

Při použití ověření symetrického klíče se zařízení ověřují pomocí DPS pomocí tokenu sdíleného přístupového podpisu (SAS). U zařízení, která se zřizují prostřednictvím jednotlivé registrace, je token podepsaný buď pomocí primárního nebo sekundárního klíče nastaveného v položce registrace. Pro zřizování zařízení prostřednictvím skupiny registrací je token podepsaný pomocí odvozeného klíče zařízení, který se následně vygeneroval pomocí primárního nebo sekundárního klíče nastaveného v položce skupiny registrací. Token určuje dobu vypršení platnosti a identifikátor URI cílového prostředku.

K vygenerování tokenu SAS je možné použít následující skript Pythonu:

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib.parse import quote_plus, urlencode
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600):
     ttl = time() + expiry
     sign_key = "%s\n%d" % ((quote_plus(uri)), int(ttl))
     print(sign_key)
     signature = b64encode(HMAC(b64decode(key), sign_key.encode('utf-8'), sha256).digest())

     rawtoken = {
         'sr' :  uri,
         'sig': signature,
         'se' : str(int(ttl))
     }

     if policy_name is not None:
         rawtoken['skn'] = policy_name

     return 'SharedAccessSignature ' + urlencode(rawtoken)

uri = '[resource_uri]'
key = '[device_key]'
expiry = [expiry_in_seconds]
policy= '[policy]'

print(generate_sas_token(uri, key, policy, expiry))

Kde:

  • [resource_uri] je identifikátor URI prostředku, ke kterému se pokoušíte získat přístup pomocí tohoto tokenu. V případě DPS se jedná o formulář [dps_id_scope]/registrations/[dps_registration_id], kde [dps_id_scope] je rozsah ID vaší instance DPS a [dps_registration_id] jedná se o ID registrace, které jste použili pro vaše zařízení.

    Obor ID pro vaši instanci DPS můžete získat z podokna Přehled instance na webu Azure Portal nebo můžete použít příkaz az iot dps show Azure CLI (zástupné symboly nahraďte názvem vaší skupiny prostředků a instance DPS):

    az iot dps show -g {resource_group_name} --name {dps_name}

  • [device_key] je klíč zařízení přidružený k vašemu zařízení. Tento klíč je buď zadaný, nebo automaticky vygenerovaný pro vás v individuální registraci, nebo odvozený klíč pro registraci skupiny.

    • Pokud používáte jednotlivou registraci, použijte primární klíč, který jste uložili v části Použití jednotlivé registrace.

    • Pokud používáte skupinu registrací, použijte odvozený klíč zařízení, který jste vygenerovali ve skupině registrace.

  • [expiry_in_seconds] je doba platnosti tohoto tokenu SAS v sekundách.

  • [policy] je zásada, ke které je klíč zařízení přidružený. U registrace zařízení DPS je zásada pevně zakódovaná na "registraci".

Příklad sady vstupů pro zařízení volaný my-symkey-device s dobou platnosti 30 dnů může vypadat takto.

uri = '0ne00111111/registrations/my-symkey-device'
key = '18RQk/hOPJR9EbsJlk2j8WA6vWaj/yi+oaYg7zmxfQNdOyMSu+SJ8O7TSlZhDJCYmn4rzEiVKIzNiVAWjLxrGA=='
expiry = 2592000
policy='registration'

Upravte skript pro vaše zařízení a instanci DPS a uložte ho jako soubor Pythonu; například generate_token.py. Spusťte skript, například python generate_token.py. Měl by vygenerovat token SAS podobný následujícímu:

0ne00111111%2Fregistrations%2Fmy-symkey-device
1663952627
SharedAccessSignature sr=0ne00111111%2Fregistrations%2Fmy-symkey-device&sig=eNwg52xQdFTNf7bgPAlAJBCIcONivq%2Fck1lf3wtxI4A%3D&se=1663952627&skn=registration

Zkopírujte a uložte celý řádek, který začíná SharedAccessSignature. Tento řádek je token SAS. Budete ho potřebovat v následujících částech.

Další informace o používání tokenů SAS se službou DPS a jejich struktuře najdete v tématu Řízení přístupu k DPS pomocí SAS.

Registrace zařízení

Zavoláte rozhraní REST API pro registraci zařízení a zřídíte ho prostřednictvím DPS.

Použijte následující příkaz curl:

curl -L -i -X PUT -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: [sas_token]' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/register?api-version=2019-03-31

Kde:

  • -L říká curl, aby sledoval přesměrování HTTP.

  • –i říká curl, aby ve výstupu zahrnovala hlavičky protokolu. Tyto hlavičky nejsou nezbytně nutné, ale můžou být užitečné.

  • -X PUT říká curl, že se jedná o příkaz HTTP PUT. Vyžaduje se pro toto volání rozhraní API.

  • -H 'Content-Type: application/json' říká DPS, že publikujeme obsah JSON a musí být application/json.

  • -H 'Content-Encoding: utf-8' informuje DPS o kódování, které používáme pro text zprávy. Nastavte správnou hodnotu pro váš operační systém nebo klienta; je to ale obecně utf-8.

  • -H 'Authorization: [sas_token]' říká službě DPS, aby se ověřila pomocí tokenu SAS. Nahraďte [sas_token] tokenem, který jste vygenerovali v části Vytvoření tokenu SAS.

  • -d '{"registrationId": "[registration_id]"}', parametr –d je "data" nebo text zprávy, kterou publikujeme. Musí to být JSON ve tvaru {"registrationId":"[registration_id"}". Všimněte si, že pro curl je zabalena do jednoduchých uvozovek; v opačném případě je nutné uvozovky ve formátu JSON uvozovek uvozovat.

  • Poslední parametr je adresa URL, do které se má publikovat. Pro "regular" (tj. místní) DPS se používá globální koncový bod DPS global.azure-devices-provisioning.net: https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/register?api-version=2019-03-31. Všimněte si, že je nutné nahradit [dps_scope_id] příslušné hodnoty a [registration_id] za odpovídající hodnoty.

Příklad:

curl -L -i -X PUT -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: SharedAccessSignature sr=0ne00111111%2Fregistrations%2Fmy-symkey-device&sig=eNwg52xQdFTNf7bgPAlAJBCIcONivq%2Fck1lf3wtxI4A%3D&se=1663952627&skn=registration' -d '{"registrationId": "my-symkey-device"}' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-symkey-device/register?api-version=2021-06-01

Úspěšné volání bude mít odpověď podobnou této:

HTTP/1.1 202 Accepted
Date: Wed, 31 Aug 2022 22:02:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Location: https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-symkey-device/register
Retry-After: 3
x-ms-request-id: a021814f-0cf6-4ce9-a1e9-ead7eb5118d9
Strict-Transport-Security: max-age=31536000; includeSubDomains

{"operationId":"5.316aac5bdc130deb.b1e02da8-c3a0-4ff2-a121-7ea7a6b7f550","status":"assigning"}

Odpověď obsahuje ID operace a stav. V tomto případě je stav nastaven na assigninghodnotu . Registrace DPS je potenciálně dlouhotrvající operace, takže se provádí asynchronně. Obvykle se pomocí rozhraní REST API pro vyhledávání stavu operace dotazujete na stav a určíte, kdy je vaše zařízení přiřazené nebo jestli došlo k selhání.

Platné hodnoty stavu pro DPS jsou:

  • assigned: Návratová hodnota ze stavového volání bude indikovat, k čemu bylo zařízení přiřazeno.

  • assigning: Operace je stále spuštěná.

  • disabled: Záznam registrace je v DPS zakázaný, takže zařízení se nedá přiřadit.

  • failed: Přiřazení se nezdařilo. V odpovědi bude errorCode errorMessage vrácen registrationState záznam, který indikuje, co se nezdařilo.

  • unassigned

Pokud chcete volat rozhraní API pro vyhledávání stavu operace, použijte následující příkaz curl:

curl -L -i -X GET -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: [sas_token]' https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/operations/[operation_id]?api-version=2019-03-31

Použijete stejný obor ID, ID registrace a token SAS, jako jste to udělali v žádosti o registraci zařízení . Použijte ID operace, které bylo vráceno v odpovědi Zaregistrovat zařízení .

Příklad:

curl -L -i -X GET -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: SharedAccessSignature sr=0ne00111111%2Fregistrations%2Fmy-symkey-device&sig=eNwg52xQdFTNf7bgPAlAJBCIcONivq%2Fck1lf3wtxI4A%3D&se=1663952627&skn=registration' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-symkey-device/operations/5.316aac5bdc130deb.f4f1828c-4dab-4ca9-98b2-dfc63b5835d6?api-version=2021-06-01

Následující výstup ukazuje odpověď na zařízení, které bylo úspěšně přiřazeno. Všimněte si, že status vlastnost je assigned a že registrationState.assignedHub je vlastnost nastavená na IoT Hub, ve kterém bylo zařízení zřízeno.

HTTP/1.1 200 OK
Date: Wed, 31 Aug 2022 22:05:23 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
x-ms-request-id: ffb98d42-023e-4e75-afb0-1807ff091cbb
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-c3a0-4ff2-a121-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "registrationId":"my-symkey-device",
      "createdDateTimeUtc":"2022-08-31T22:02:50.5163352Z",
      "assignedHub":"MyExampleHub.azure-devices.net",
      "deviceId":"my-symkey-device",
      "status":"assigned",
      "substatus":"initialAssignment",
      "lastUpdatedDateTimeUtc":"2022-08-31T22:02:50.7370676Z",
      "etag":"IjY5MDAzNTUyLTAwMDAtMDMwMC0wMDAwLTYzMGZkYThhMDAwMCI="
   }
}

Odeslání zprávy telemetrie

Než budete moct odeslat zprávu telemetrie, musíte vytvořit token SAS pro centrum IoT, ke kterému bylo zařízení přiřazeno. Tento token podepíšete pomocí stejného primárního klíče nebo odvozeného klíče zařízení, který jste použili k podepsání tokenu SAS pro vaši instanci DPS.

Vytvoření tokenu SAS pro centrum IoT

Pokud chcete vytvořit token SAS, můžete spustit stejný kód, který jste udělali k vytvoření tokenu pro instanci DPS, s následujícími změnami:

uri = '[resource_uri]'
key = '[device_key]'
expiry = [expiry_in_seconds]
policy= None

Kde:

  • [resource_uri] je identifikátor URI prostředku, ke kterému se pokoušíte získat přístup pomocí tohoto tokenu. V případě zařízení, které odesílá zprávy do centra IoT, je ve formuláři [iot-hub-host-name]/devices/[device-id].

    • Pro [iot-hub-host-name]použití názvu hostitele služby IoT Hub vrácený ve assignedHub vlastnosti v předchozí části.

    • Pro [device-id]použití ID zařízení vráceného deviceId ve vlastnosti v předchozí části.

  • [device_key] je klíč zařízení přidružený k vašemu zařízení. Tento klíč je buď zadaný, nebo automaticky vygenerovaný pro vás v individuální registraci, nebo odvozený klíč pro registraci skupiny. (Je to stejný klíč, který jste použili dříve k vytvoření tokenu pro DPS.)

    • Pokud používáte jednotlivou registraci, použijte primární klíč, který jste uložili v části Použití jednotlivé registrace.

    • Pokud používáte skupinu registrací, použijte odvozený klíč zařízení, který jste vygenerovali ve skupině registrace.

  • [expiry_in_seconds] je doba platnosti tohoto tokenu SAS v sekundách.

  • policy=None Pro zařízení odesílající telemetrii do centra IoT se nevyžadují žádné zásady, takže tento parametr je nastavený na None.

Příklad sady vstupů pro zařízení, které se říká my-symkey-device odesílání do ioT Hubu MyExampleHub s dobou platnosti tokenu 1 hodinu, může vypadat takto:

uri = 'MyExampleHub.azure-devices.net/devices/my-symkey-device'
key = '18RQk/hOPJR9EbsJlk2j8WA6vWaj/yi+oaYg7zmxfQNdOyMSu+SJ8O7TSlZhDJCYmn4rzEiVKIzNiVAWjLxrGA=='
expiry = 3600
policy= None

Následující výstup ukazuje ukázkový token SAS pro tyto vstupy:

SharedAccessSignature sr=MyExampleHub.azure-devices.net%2Fdevices%2Fmy-symkey-device&sig=f%2BwW8XOKeJOtiPc9Iwjc4OpExvPM7NlhM9qxN2a1aAM%3D&se=1663119026

Další informace o vytváření tokenů SAS pro IoT Hub, včetně ukázkového kódu v jiných programovacích jazycích, najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Poznámka:

Jako pohodlí můžete pomocí azure CLI az iot hub generate-sas-token získat token SAS pro zařízení zaregistrované ve službě IoT Hub. Například následující příkaz vygeneruje token SAS s dobou trvání jedné hodiny. {iothub_name}Pro , potřebujete pouze první část hostitelské hame, MyExampleHubnapříklad .

az iot hub generate-sas-token -d {device_id} -n {iothub_name}

Odeslání dat do centra IoT

Zavoláte rozhraní REST API pro odesílání událostí zařízení do služby IoT Hub, které do zařízení odesílá telemetrii.

Použijte následující příkaz curl:

curl -L -i -X POST -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: [sas_token]' -d '{"temperature": 30}' https://[assigned_iot_hub_name].azure-devices.net/devices/[device_id]/messages/events?api-version=2020-03-13

Kde:

  • -X POST říká curl, že se jedná o příkaz HTTP POST. Vyžaduje se pro toto volání rozhraní API.

  • -H 'Content-Type: application/json' říká službě IoT Hub, že publikujeme obsah JSON a musí být application/json.

  • -H 'Content-Encoding: utf-8' Říká ioT Hubu, že kódování, které používáme pro text zprávy. Nastavte správnou hodnotu pro váš operační systém nebo klienta; je to ale obecně utf-8.

  • -H 'Authorization: [sas_token]' Říká službě IoT Hub, aby se ověřila pomocí vašeho tokenu SAS. Nahraďte [sas_token] tokenem, který jste vygenerovali pro přiřazené centrum IoT.

  • -d '{"temperature": 30}', parametr –d je "data" nebo text zprávy, kterou publikujeme. V tomto článku zveřejňujeme jeden datový bod teploty. Typ obsahu byl zadán jako application/json, takže pro tento požadavek je text JSON. Všimněte si, že pro curl je zabalena do jednoduchých uvozovek; v opačném případě je nutné uvozovky ve formátu JSON uvozovek uvozovat.

  • Posledním parametrem je adresa URL, do které se má publikovat. Pro rozhraní API událostí odesílání zařízení je adresa URL: https://[assigned_iot_hub_name].azure-devices.net/devices/[device_id]/messages/events?api-version=2020-03-13.

    • Nahraďte [assigned_iot_hub_name] názvem centra IoT, ke kterému bylo vaše zařízení přiřazeno.

    • Nahraďte [device_id] ID zařízení, které bylo přiřazeno při registraci zařízení. Pro zařízení, která se zřizují prostřednictvím skupin registrací, bude ID registrace. U jednotlivých registrací můžete volitelně zadat ID zařízení, které se liší od ID registrace v položce registrace.

Například pro zařízení s ID zařízení odesílajícího my-symkey-device telemetrický datový bod do centra IoT s názvem MyExampleHub:

curl -L -i -X POST -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: SharedAccessSignature sr=MyExampleHub.azure-devices.net%2Fdevices%2Fmy-symkey-device&sig=f%2BwW8XOKeJOtiPc9Iwjc4OpExvPM7NlhM9qxN2a1aAM%3D&se=1663119026' -d '{"temperature": 30}' https://MyExampleHub.azure-devices.net/devices/my-symkey-device/messages/events?api-version=2020-03-13

Úspěšné volání bude mít odpověď podobnou této:

HTTP/1.1 204 No Content
Content-Length: 0
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: 9e278582-3561-417b-b807-76426195920f
Date: Wed, 14 Sep 2022 00:32:53 GMT

Další kroky