SDK 없이 HTTPS를 통해 대칭 키를 사용하는 방법

아티클
06/01/2023

이 방법 문서에서는 Azure IoT DPS 디바이스 SDK 없이 HTTPS를 통해 대칭 키를 사용하여 디바이스를 프로비저닝합니다. 대부분의 언어는 HTTP 요청을 보내는 라이브러리를 제공하지만, 이 문서에서는 특정 언어에 초점을 맞추지 않고 cURL 명령줄 도구를 사용하여 HTTPS를 통해 요청을 보내고 받습니다.

Linux 또는 Windows 머신에서 이 문서의 단계를 수행할 수 있습니다. WSL(Linux용 Windows 하위 시스템)에서 실행 중이거나 Linux 머신에서 실행 중인 경우 로컬 시스템의 Bash 프롬프트에서 모든 명령을 입력할 수 있습니다. Windows에서 실행 중인 경우 로컬 시스템의 GitBash 프롬프트에서 모든 명령을 입력합니다.

이 문서에서는 선택하는 등록 항목의 유형에 따라 여러 경로를 사용합니다. 필수 구성 요소를 설치한 후 계속하기 전에 개요를 꼭 읽어야 합니다.

필수 조건

Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Azure Portal에서 IoT Hub Device Provisioning Service 설정의 단계를 완료합니다.
머신에 Python 3.7 이상이 설치되어 있는지 확인합니다. python --version을 실행하여 Python 버전을 확인할 수 있습니다.
Windows에서 실행 중인 경우 최신 버전의 Git을 설치합니다. Git이 명령 창에 액세스할 수 있는 환경 변수에 추가되었는지 확인합니다. 설치할 git 도구의 최신 버전은 Software Freedom Conservancy의 Git 클라이언트 도구를 참조하세요. 여기에는 로컬 Git 리포지토리와 상호 작용하는 데 사용할 수 있는 명령줄 앱인 Git Bash가 포함됩니다. Windows에서는 로컬 시스템의 GitBash 프롬프트에서 모든 명령을 입력합니다.
Azure CLI 이 문서에서는 Azure CLI 명령을 실행하는 두 가지 옵션이 있습니다.
- 브라우저에서 CLI 명령을 실행하는 대화형 셸인 Azure Cloud Shell을 사용합니다. 이 옵션은 아무 것도 설치할 필요가 없으므로 권장됩니다. 처음으로 Cloud Shell을 사용하는 경우 Azure Portal에 로그인합니다. Cloud Shell 빠른 시작의 단계를 따라 Cloud Shell을 시작하고 Bash 환경을 선택합니다.
- 선택적으로 로컬 컴퓨터에서 Azure CLI를 실행합니다. Azure CLI가 이미 설치된 경우 az upgrade를 실행하여 CLI 및 확장을 현재 버전으로 업그레이드합니다. Azure CLI를 설치하는 방법은 Azure CLI 2.0 설치를 참조하세요.
Linux 또는 WSL 환경에서 실행 중인 경우 Bash 프롬프트를 열고 로컬로 명령을 실행합니다. Windows 환경에서 실행 중인 경우 GitBash 프롬프트를 엽니다.

개요

이 문서에서는 개별 등록 또는 등록 그룹을 사용하여 DPS를 통해 프로비저닝할 수 있습니다.

개별 등록의 경우 개별 등록 사용을 완료합니다.
등록 그룹의 경우 등록 그룹 사용을 완료합니다.

개별 등록 또는 등록 그룹 항목을 만든 후에는 계속해서 SAS 토큰 만들기 및 DPS에 디바이스 등록을 진행합니다.

개별 등록 사용

이 문서에 사용할 새 개별 등록을 만들려면 az iot dps enrollment create 명령을 사용하여 대칭 키 증명에 사용할 개별 등록을 만들 수 있습니다.

다음 명령은 DPS 인스턴스에 대한 기본 할당 정책을 사용하여 등록 항목을 만들고 DPS가 디바이스의 기본 키 및 보조 키를 할당할 수 있도록 합니다.

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

리소스 그룹 및 DPS 인스턴스 이름을 바꿉니다.
등록 ID는 디바이스의 등록 ID입니다. 등록 ID는 영숫자 문자의 대/소문자를 구분하지 않는 문자열(최대 128자 길이)과 특수 문자인 '-', '.', '_', ':'입니다. 마지막 문자는 영숫자 또는 대시('-')여야 합니다. 명령에서 사용하는 등록 ID는 이 형식을 준수해야 합니다.

할당된 대칭 키는 응답의 증명 속성에 반환됩니다.


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

  ...

}

개별 등록 항목의 기본 키 및 등록 ID(등록 ID)를 적어둡니다. 이 문서의 뒷부분에서 필요합니다.

이 문서에 기존 개별 등록을 사용하려는 경우 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

등록 그룹 사용

이 문서에 사용할 새 등록 그룹을 만들려면 az iot dps enrollment-group create 명령을 사용하여 대칭 키 증명에 사용할 등록 그룹을 만들 수 있습니다.

다음 명령은 DPS 인스턴스에 대한 기본 할당 정책을 사용하여 등록 그룹 항목을 만들고 DPS가 등록 그룹의 기본 키 및 보조 키를 할당할 수 있도록 합니다.

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

리소스 그룹 및 DPS 인스턴스 이름을 바꿉니다.
등록 ID는 영숫자 문자의 대/소문자를 구분하지 않는 문자열(최대 128자 길이)과 특수 문자인 '-', '.', '_', ':'입니다. 마지막 문자는 영숫자 또는 대시('-')여야 합니다. 등록 그룹에 사용하도록 선택하는 이름일 수 있습니다.

할당된 대칭 키는 응답의 증명 속성에 반환됩니다.


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

  ...

}

기본 키를 적어둡니다.

이 문서에 기존 개별 등록을 사용하려는 경우 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

디바이스 키 파생

그룹 등록과 함께 대칭 키 증명을 사용할 때는 등록 그룹 키를 직접 사용하지 않습니다. 대신 등록 그룹 키에서 각 디바이스의 고유 키를 파생합니다. 자세한 내용은 대칭 키를 사용하여 그룹 등록을 참조하세요.

이 섹션에서는 등록 그룹 기본 키에서 디바이스 키를 생성하여 디바이스에 대한 고유한 등록 ID의 HMAC-SHA256을 컴퓨팅합니다. 결과는 Base64 형식으로 변환됩니다.

openssl을 사용하여 고유 키를 생성합니다. 다음 Bash 셸 스크립트를 사용합니다. {primary-key}를 앞에서 복사한 등록 그룹의 기본 키로 바꾸고 {contoso-simdevice}를 디바이스에 사용할 등록 ID로 바꿉니다. 등록 ID는 영숫자 문자의 대/소문자를 구분하지 않는 문자열(최대 128자 길이)과 특수 문자인 '-', '.', '_', ':'입니다. 마지막 문자는 영숫자 또는 대시('-')여야 합니다.
```
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
```
이 스크립트는 다음 키와 비슷한 내용을 출력합니다.
```
p3w2DQr9WqEGBLUSlFi1jPQ7UWQL4siAGy75HFTFbf8=
```

파생된 디바이스 키와 이 키를 생성하는 데 사용한 등록 ID를 적어둡니다. 다음 섹션에서 필요합니다.

Azure CLI 또는 PowerShell을 사용하여 디바이스 키를 파생할 수도 있습니다. 자세한 내용은 디바이스 키 파생을 참조하세요.

SAS 토큰 만들기

대칭 키 증명을 사용하는 경우 디바이스는 SAS(공유 액세스 서명) 토큰을 사용하여 DPS에 인증합니다. 개별 등록을 통한 디바이스 프로비저닝의 경우 토큰은 등록 항목의 기본 또는 보조 키 세트를 사용하여 서명됩니다. 등록 그룹을 통한 디바이스 프로비저닝의 경우 토큰은 파생된 디바이스 키를 사용하여 서명되며, 이 키는 등록 그룹 항목의 기본 또는 보조 키 세트를 사용하여 생성된 것입니다. 토큰은 만료 시간 및 대상 리소스 URI를 지정합니다.

다음 Python 스크립트를 사용하여 SAS 토큰을 생성할 수 있습니다.

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))

여기서

[resource_uri]는 이 토큰으로 액세스하려는 리소스의 URI입니다. DPS의 경우 [dps_id_scope]/registrations/[dps_registration_id]형식입니다. 여기서 [dps_id_scope]는 DPS 인스턴스의 ID 범위이고, [dps_registration_id]는 디바이스에 사용한 등록 ID입니다.

Azure Portal의 인스턴스 개요 창에서 또는 az iot dps show Azure CLI 명령을 사용하여(자리 표시자를 해당 리소스 그룹 및 DPS 인스턴스 이름으로 대체) DPS 인스턴스의 ID 범위를 가져올 수 있습니다.
```
az iot dps show -g {resource_group_name} --name {dps_name}
```
[device_key]는 디바이스와 연결된 디바이스 키입니다. 이 키는 개별 등록에서 사용자가 지정하거나 자동으로 생성된 키 또는 그룹 등록에 대해 파생된 키입니다.
- 개별 등록을 사용하는 경우 개별 등록 사용에서 저장한 기본 키를 사용합니다.
- 등록 그룹을 사용하는 경우 등록 그룹 사용에서 생성한 파생 디바이스 키를 사용합니다.
[expiry_in_seconds]는 이 SAS 토큰의 유효 기간(초)입니다.
[policy]는 디바이스 키가 연결된 정책입니다. DPS 디바이스 등록의 경우 정책은 '등록'으로 하드 코딩됩니다.

다음은 유효 기간이 30일인 my-symkey-device라는 디바이스의 입력 예제입니다.

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

디바이스 및 DPS 인스턴스에 대한 스크립트를 수정하고 Python 파일로 저장합니다(예: generate_token.py). 스크립트를 실행합니다(예: python generate_token.py). 다음과 유사한 SAS 토큰이 출력될 것입니다.

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

SharedAccessSignature로 시작하는 전체 줄을 복사하여 저장합니다. 이 줄은 SAS 토큰입니다. 다음 섹션에서 필요합니다.

DPS 및 해당 구조에 SAS 토큰을 사용하는 방법에 대한 자세한 내용은 SAS를 사용하여 DPS에 대한 액세스 제어를 참조하세요.

디바이스 등록

디바이스 등록 REST API를 호출하여 DPS를 통해 디바이스를 프로비저닝합니다.

다음 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

여기서

-L은 HTTP 리디렉션을 따르도록 curl에 지시합니다.
–i는 프로토콜 헤더를 출력에 포함하도록 curl에 지시합니다. 이러한 헤더는 꼭 필요한 것은 아니지만 유용할 수 있습니다.
-X PUT은 이 명령이 HTTP PUT 명령이라는 것을 curl에 알려줍니다. 이 API 호출에 필요합니다.
-H 'Content-Type: application/json'은 JSON 콘텐츠를 게시하고 있으며 'application/json'이어야 한다고 DPS에 알려줍니다.
-H 'Content-Encoding: utf-8'은 메시지 본문에 사용 중인 인코딩을 DPS에 알려줍니다. OS/클라이언트에 적절한 값으로 설정하세요. 하지만 일반적으로 utf-8입니다.
-H 'Authorization: [sas_token]'은 SAS 토큰을 사용하여 인증하도록 DPS에 지시합니다. [sas_token]을 SAS 토큰 만들기에서 생성한 토큰으로 바꿉니다.
-d '{"registrationId": "[registration_id]"}'에서 –d 매개 변수는 게시 중인 메시지의 '데이터' 또는 본문입니다. '{"registrationId":"[registration_id"}' 형식의 JSON이어야 합니다. curl인 경우 작은따옴표로 묶입니다. curl이 아닌 경우 JSON에서 큰따옴표를 이스케이프해야 합니다.
마지막 매개 변수는 게시할 URL입니다. "일반"(즉, 온-프레미스가 아님) DPS의 경우 전역 DPS 엔드포인트인 global.azure-devices-provisioning.net이 사용됩니다(예: https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/register?api-version=2019-03-31). [dps_scope_id] 및 [registration_id]를 적절한 값으로 바꿔야 합니다.

예시:

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

호출이 성공하면 다음과 비슷한 응답이 반환됩니다.

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"}

응답에는 작업 ID 및 상태가 포함됩니다. 이 예제의 상태는 assigning으로 설정되어 있습니다. DPS 등록은 잠재적으로 장기 실행 작업이므로 비동기적으로 수행됩니다. 일반적으로 작업 상태 조회 REST API를 사용하여 상태를 폴링하여 디바이스가 할당된 시기 또는 오류 발생 여부를 확인합니다.

DPS의 유효한 상태 값은 다음과 같습니다.

assigned: 상태 호출의 반환 값은 디바이스가 할당된 IoT Hub를 나타냅니다.
assigning: 작업이 아직 진행 중입니다.
disabled: DPS에서 등록 레코드를 사용하지 않으므로 디바이스를 할당할 수 없습니다.
failed: 할당이 실패했습니다. 무엇이 실패했는지 나타내기 위해 응답의 registrationState 레코드에 errorCode 및 errorMessage가 반환됩니다.
unassigned

작업 상태 조회 API를 호출하려면 다음 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

디바이스 등록 요청에서 사용한 것과 동일한 ID 범위, 등록 ID 및 SAS 토큰을 사용합니다. 디바이스 등록 응답에서 반환된 작업 ID를 사용합니다.

예시:

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

다음 출력은 성공적으로 할당된 디바이스에 대한 응답을 보여줍니다. status 속성은 assigned이고 registrationState.assignedHub 속성은 디바이스가 프로비저닝된 IoT Hub로 설정되었습니다.

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="
   }
}

원격 분석 메시지 보내기

원격 분석 메시지를 보내려면 디바이스가 할당된 IoT 허브에 대한 SAS 토큰을 만들어야 합니다. DPS 인스턴스에 대한 SAS 토큰에 서명하는 데 사용한 것과 동일한 기본 키 또는 파생 디바이스 키를 사용하여 이 토큰에 서명합니다.

IoT 허브에 대한 SAS 토큰 만들기

SAS 토큰을 만들려면 DPS 인스턴스에 대한 토큰을 만들 때 사용한 것과 동일한 코드를 다음과 같이 변경하여 실행하면 됩니다.

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

여기서

[resource_uri]는 이 토큰으로 액세스하려는 리소스의 URI입니다. IoT 허브에 메시지를 보내는 디바이스의 경우 [iot-hub-host-name]/devices/[device-id]형식입니다.
- [iot-hub-host-name]의 경우 이전 섹션의 assignedHub 속성에서 반환된 IoT Hub 호스트 이름을 사용합니다.
- [device-id]의 경우 이전 섹션의 deviceId 속성에서 반환된 디바이스 ID를 사용합니다.
[device_key]는 디바이스와 연결된 디바이스 키입니다. 이 키는 개별 등록에서 사용자가 지정하거나 자동으로 생성된 키 또는 그룹 등록에 대해 파생된 키입니다. (이전에 DPS용 토큰을 만드는 데 사용한 것과 동일한 키입니다.)
- 개별 등록을 사용하는 경우 개별 등록 사용에서 저장한 기본 키를 사용합니다.
- 등록 그룹을 사용하는 경우 등록 그룹 사용에서 생성한 파생 디바이스 키를 사용합니다.
[expiry_in_seconds]는 이 SAS 토큰의 유효 기간(초)입니다.
policy=None IoT 허브에 원격 분석 데이터를 보내는 디바이스에 대한 정책이 필요 없으므로 이 매개 변수는 None으로 설정됩니다.

다음은 토큰 유효 기간이 1시간이고 MyExampleHub라는 IoT Hub에 데이터를 보내는 my-symkey-device라는 디바이스의 입력 예제입니다.

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

다음 출력은 이러한 입력의 샘플 SAS 토큰을 보여줍니다.

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

다른 프로그래밍 언어의 예제 코드를 포함하여 IoT Hub에 대한 SAS 토큰을 만드는 방법에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조하세요.

참고 항목

편의상 Azure CLI az iot hub generate-sas-token 명령을 사용하여 IoT 허브에 등록된 디바이스의 SAS 토큰을 가져올 수 있습니다. 예를 들어 다음 명령은 기간이 1시간인 SAS 토큰을 생성합니다. {iothub_name}의 경우 호스트 이름의 첫 번째 부분(예: MyExampleHub)만 필요합니다.

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

IoT 허브에 데이터 보내기

IoT Hub 디바이스 이벤트 보내기 REST API를 호출하여 디바이스에 원격 분석 데이터를 보냅니다.