Использование сертификатов X.509 по протоколу HTTPS без пакета SDK

  • Статья

В этой статье описано, как подготовить устройство с помощью сертификатов x.509 по протоколу HTTPS без использования пакета SDK для устройств Azure IoT DPS. Большинство языков предоставляют библиотеки для отправки HTTP-запросов, но вместо того, чтобы сосредоточиться на определенном языке, в этой статье вы будете использовать средство командной строки cURL для отправки и получения по протоколу HTTPS.

Действия, описанные в этой статье, можно выполнить на компьютере Под управлением Linux или Windows. Если вы работаете на подсистема Windows для Linux (WSL) или работаете на компьютере Linux, вы можете ввести все команды в локальной системе в командной строке Bash. Если вы работаете в Windows, введите все команды в локальной системе в командной строке GitBash.

В этой статье существует несколько путей в зависимости от типа записи регистрации и сертификатов X.509, которые вы хотите использовать. После установки необходимых компонентов перед продолжением работы ознакомьтесь с обзором.

Необходимые компоненты

  • Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

  • Выполните инструкции по настройке Службы подготовки устройств к добавлению в Центр Интернета вещей на портале Microsoft Azure.

  • Убедитесь, что на компьютере установлен Python 3.7 или более поздней версии. Вы можете проверка версию Python, выполнив python --version или python3 --version.

  • Если вы работаете в Windows, установите последнюю версию Git. Обязательно добавьте GIT в переменные среды, доступные в командном окне. Последнюю версию средств git для установки, которая включает Git Bash (приложение командной строки для взаимодействия с локальным репозиторием GIT), можно найти на этой странице. В Windows вы введете все команды в локальной системе в командной строке GitBash.

  • Azure CLI. В этой статье описано два варианта выполнения команд Azure CLI:

    • Azure Cloud Shell — интерактивная оболочка CLI, которая работает в браузере. Этот вариант предпочтителен, так как не нужно ничего устанавливать. Если вы впервые используете Cloud Shell, войдите на портал Azure. Выполните действия, описанные в кратком руководстве Cloud Shell, чтобы запустить Cloud Shell и выбрать среду Bash.
    • Azure CLI также можно запустить на локальном компьютере. Если интерфейс командной строки Azure уже установлен, запустите az upgrade, чтобы обновить интерфейс командной строки и расширения до текущей версии. Чтобы установить Azure CLI, ознакомьтесь с разделом Установка Azure CLI.

  • Если вы работаете в среде Linux или WSL, откройте строку Bash для локального выполнения команд. Если вы работаете в среде Windows, откройте запрос GitBash.

Обзор

Существует три сценария, описанные в этой статье, и начальные шаги, которые вы будете выполнять, будут отличаться для каждого из них. Если вы хотите:

Завершив действия для выбранного сценария, вы можете продолжить регистрацию устройства и отправить сообщение телеметрии.

Создание сертификата устройства

В этой статье вы будете использовать сертификат X.509 для проверки подлинности с помощью DPS с помощью отдельной регистрации или группы регистрации.

Если вы используете отдельную регистрацию, вы можете использовать самозаверяющий сертификат X.509 или цепочку сертификатов, состоящую из сертификата устройства плюс один или несколько сертификатов подписи. Если вы используете группу регистрации, необходимо использовать цепочку сертификатов.

Важно!

Для проверки подлинности регистрации X.509 имя субъекта (CN) сертификата устройства используется в качестве идентификатора регистрации для устройства. Идентификатор регистрации — это строка без учета регистра буквенно-цифровых символов, а также специальные символы: '-', '.', '_'. ':' Последний символ должен быть буквенно-цифровым или дефисом ('-'). DPS поддерживает идентификаторы регистрации до 128 символов; Однако общее имя субъекта сертификата X.509 ограничено 64 символами. Если изменить общее имя субъекта для сертификата устройства на следующих шагах, убедитесь, что он соответствует этому формату.

Использование самозаверяющего сертификата

Чтобы создать самозаверяющий сертификат для использования с отдельной регистрацией, перейдите в каталог, в котором нужно создать сертификат, и выполните следующие действия.

  1. Выполните следующую команду:

    winpty openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "//CN=my-x509-device"

    Важно!

    Добавлять к имени субъекта (//CN=my-x509-device) дополнительную косую черту нужно только для того, чтобы строка экранировалась с помощью Git на платформах Windows.

  2. При появлении запроса на ввод парольной фразы PEM используйте 1234.

  3. При запросе на ввод парольной фразы PEM для проверки повторно используйте парольную фразу 1234.

    Теперь файл сертификата открытого ключа (device-cert.pem) и файл закрытого ключа (device-key.pem) должен быть создан в каталоге, где вы выполнили openssl команду.

    Файл сертификата имеет общее имя субъекта (CN).my-x509-device

    Файл закрытого ключа защищен парольной фразой: 1234

  4. Файл сертификата закодирован в кодировке Base64. Чтобы просмотреть общее имя субъекта (CN) и другие свойства файла сертификата, введите следующую команду:

    winpty openssl x509 -in device-cert.pem -text -noout

    Certificate:
Data:
    Version: 3 (0x2)
    Serial Number:
        77:3e:1d:e4:7e:c8:40:14:08:c6:09:75:50:9c:1a:35:6e:19:52:e2
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: CN = my-x509-device
    Validity
        Not Before: May  5 21:41:42 2022 GMT
        Not After : Jun  4 21:41:42 2022 GMT
    Subject: CN = my-x509-device
    Subject Public Key Info:
        Public Key Algorithm: rsaEncryption
            RSA Public-Key: (4096 bit)
            Modulus:
                00:d2:94:37:d6:1b:f7:43:b4:21:c6:08:1a:d6:d7:
                e6:40:44:4e:4d:24:41:6c:3e:8c:b2:2c:b0:23:29:
                ...
                23:6e:58:76:45:18:03:dc:2e:9d:3f:ac:a3:5c:1f:
                9f:66:b0:05:d5:1c:fe:69:de:a9:09:13:28:c6:85:
                0e:cd:53
            Exponent: 65537 (0x10001)
    X509v3 extensions:
        X509v3 Basic Constraints:
            CA:FALSE
        Netscape Comment:
            OpenSSL Generated Certificate
        X509v3 Subject Key Identifier:
            63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18
        X509v3 Authority Key Identifier:
            keyid:63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18

        X509v3 Extended Key Usage:
            TLS Web Client Authentication
Signature Algorithm: sha256WithRSAEncryption
     82:8a:98:f8:47:00:85:be:21:15:64:b9:22:b0:13:cc:9e:9a:
     ed:f5:93:b9:4b:57:0f:79:85:9d:89:47:69:95:65:5e:b3:b1:
     ...
     cc:b2:20:9a:b7:f2:5e:6b:81:a1:04:93:e9:2b:92:62:e0:1c:
     ac:d2:49:b9:36:d2:b0:21

Использование цепочки сертификатов

Если вы используете группу регистрации, необходимо пройти проверку подлинности с помощью цепочки сертификатов. С помощью отдельной регистрации можно использовать цепочку сертификатов или самозаверяющий сертификат.

Чтобы создать цепочку сертификатов, следуйте инструкциям в статье "Создание цепочки сертификатов X.509". Для этой статьи требуется только одно устройство, поэтому после создания закрытого ключа и цепочки сертификатов для первого устройства можно остановиться.

По завершении у вас должны быть следующие файлы:

Сертификат Файл Description
сертификат корневого ЦС. certs/azure-iot-test-only.root.ca.cert.pem Будет отправлено в DPS и проверено.
промежуточный сертификат ЦС certs/azure-iot-test-only.intermediate.cert.pem Будет использоваться для создания группы регистрации в DPS.
закрытый ключ device-01 private/device-01.key.pem Используется устройством для проверки владения сертификатом устройства во время проверки подлинности с помощью DPS.
сертификат device-01 certs/device-01.cert.pem Используется для создания отдельной записи регистрации с помощью DPS.
Сертификат полной цепочки device-01 certs/device-01-full-chain.cert.pem Представлено устройством для проверки подлинности и регистрации в DPS.

Использование отдельной регистрации

Чтобы создать отдельную регистрацию, используемую для этой статьи, используйте команду az iot dps enrollment create .

Следующая команда создает отдельную запись регистрации с политикой выделения по умолчанию для экземпляра DPS с помощью указанного сертификата устройства.

az iot dps enrollment create -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --attestation-type x509 --certificate-path {path to your certificate}

  • Замените имя группы ресурсов и экземпляра DPS.

  • Идентификатор регистрации — это идентификатор регистрации для устройства, и для регистрации X.509 должен соответствовать общему имени субъекта (CN) сертификата устройства.

  • Путь к сертификату — это путь к сертификату устройства.

Примечание.

Если вы используете Cloud Shell для выполнения команд Azure CLI, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Screenshot that shows the upload file button in Azure Cloud Shell.

Использование группы регистрации

Чтобы создать группу регистрации, используемую для этой статьи, используйте команду az iot dps enrollment-group create .

Следующая команда создает запись группы регистрации с политикой выделения по умолчанию для экземпляра DPS с помощью промежуточного сертификата ЦС:

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

  • Замените имя группы ресурсов и экземпляра DPS.

  • Идентификатор регистрации — это строка без учета регистра буквенно-цифровых символов, а также специальные символы: '-', '.', '_'. ':' Последний символ должен быть буквенно-цифровым или дефисом ('-'). Это может быть любое имя, используемое для группы регистрации.

  • Путь к сертификату — это путь к промежуточному сертификату. Если вы выполнили инструкции по использованию цепочки сертификатов, имя файла — certs/azure-iot-test-only.intermediate.cert.pem.

Примечание.

Если вы используете Cloud Shell для выполнения команд Azure CLI, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Screenshot that shows the upload file button in Azure Cloud Shell.

Примечание.

Если вы предпочитаете, можно создать группу регистрации на основе сертификата подписи, который ранее был отправлен и проверен с помощью DPS (см. следующий раздел). Для этого укажите имя сертификата и --ca-name опустите --certificate-path параметр в команде az iot dps enrollment-group create .

Отправка и проверка сертификата подписи

Если вы используете цепочку сертификатов для отдельной регистрации или группы регистрации, необходимо отправить и проверить по крайней мере один сертификат в цепочке подписывания сертификата устройства в DPS.

  • Для отдельной регистрации это может быть любой сертификат подписи в цепочке сертификатов устройства.

  • Для группы регистрации это может быть сертификат группы регистрации или любой сертификат в цепочке подписывания до корневого сертификата ЦС.

Чтобы отправить и проверить сертификат, используйте команду az iot dps certificate create :

az iot dps certificate create -g {resource_group_name} --dps-name {dps_name} --certificate-name {friendly_name_for_your_certificate} --path {path_to_your_certificate} --verified true

  • Замените имя группы ресурсов и экземпляра DPS.

  • Путь к сертификату для подписи — это путь к сертификату подписи. В этой статье рекомендуется отправить корневой сертификат ЦС. Если вы выполнили инструкции по использованию цепочки сертификатов, имя файла — certs/azure-iot-test-only.root.ca.cert.pem.

  • Имя сертификата может содержать только буквенно-цифровые символы или следующие специальные символы: -._ Пробелы не разрешены. Например, azure-iot-test-only-root.

Примечание.

Если вы используете Cloud Shell для выполнения команд Azure CLI, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Screenshot that shows the upload file button in Azure Cloud Shell.

Примечание.

Действия, описанные в этом разделе, автоматически проверили сертификат при отправке. Вы также можете выполнить ручную проверку сертификата. Дополнительные сведения см. в руководстве по проверке промежуточного или корневого ЦС вручную.

Зарегистрировать устройство

Вы вызываете REST API регистрации устройств для подготовки устройства с помощью DPS.

Используйте следующую команду curl:

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

Где:

  • -L сообщает curl, чтобы следовать перенаправлениям HTTP.

  • –i указывает curl включить заголовки протокола в выходные данные. Эти заголовки не являются строго необходимыми, но они могут быть полезны.

  • -X PUT сообщает curl, что это команда HTTP PUT. Требуется для этого вызова API.

  • --cert [path_to_your_device_cert] сообщает curl, где найти сертификат X.509 устройства. Если закрытый ключ устройства защищен секретной фразой, можно добавить парольную фразу после пути сертификата, предшествовав двоеточию, например: --cert my-device.pem:1234

    • Если вы используете самозаверяющий сертификат, файл сертификата устройства будет содержать только один сертификат X.509. Если вы выполнили инструкции по использованию самозаверяющего сертификата, имя файла — device-cert.pem, а фраза передачи закрытого ключа — 1234используйте.--cert device-cert.pem:1234

    • Если вы используете цепочку сертификатов, например при проверке подлинности через группу регистрации, файл сертификата устройства должен содержать допустимую цепочку сертификатов. Цепочка сертификатов должна включать сертификат устройства и все сертификаты подписи вплоть до проверенного сертификата. Если вы выполнили инструкции по созданию цепочки сертификатов, файловый путь — certs/device-01-full-chain.cert.pem, поэтому используйте --cert certs/device-01-full-chain.cert.pem.

  • --key [path_to_your_device_private_key] сообщает curl, где найти закрытый ключ устройства.

  • -H 'Content-Type: application/json' сообщает DPS, что мы публикуем содержимое JSON и должны быть "application/json"

  • -H 'Content-Encoding: utf-8' сообщает DPS кодировке, которую мы используем для нашего текста сообщения. Задайте правильное значение для операционной системы или клиента; однако обычно это utf-8.

  • -d '{"registrationId": "[registration_id]"}'–d Параметр — это "данные" или текст сообщения, которое мы публикуем. Он должен быть JSON в виде "{"registrationId":"[registration_id"}". Обратите внимание, что для curl он упакован в одинарные кавычки; в противном случае необходимо экранировать двойные кавычки в формате JSON. Для регистрации X.509 идентификатор регистрации — это общее имя субъекта (CN) сертификата устройства.

  • Наконец, последний параметр — это 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 --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "my-x509-device"}' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/register?api-version=2021-06-01

  • Если вы выполнили инструкции по использованию цепочки сертификатов:

    curl -L -i -X PUT --cert certs/device-01-full-chain.cert.pem --key private/device-01.key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "device-01"}' https://global.azure-devices-provisioning.net/0ne00111111/registrations/device-01/register?api-version=2021-06-01

Успешный вызов будет иметь ответ, аналогичный следующему:

HTTP/1.1 202 Accepted
Date: Sat, 27 Aug 2022 17:53:18 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Location: https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/register
Retry-After: 3
x-ms-request-id: 05cdec07-c0c7-48f3-b3cd-30cfe27cbe57
Strict-Transport-Security: max-age=31536000; includeSubDomains

{"operationId":"5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a","status":"assigning"}

Ответ содержит идентификатор операции и состояние. В этом случае для состояния задано assigningзначение . Регистрация DPS— это, возможно, длительная операция, поэтому она выполняется асинхронно. Как правило, вы будете опрашивать состояние с помощью REST API поиска состояния операции, чтобы определить, было ли назначено устройство или произошла ли сбой.

Допустимые значения состояния для DPS:

  • assigned: возвращаемое значение из вызова состояния указывает, что Центр Интернета вещей устройство было назначено.

  • assigning: операция по-прежнему выполняется.

  • disabled: запись регистрации отключена в DPS, поэтому устройство не может быть назначено.

  • failed: сбой назначения. В ответе будет errorCode возвращен и errorMessage возвращен registrationState в записи, чтобы указать, что не удалось.

  • unassigned

Чтобы вызвать API подстановки состояния операции, используйте следующую команду curl:

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

Вы будете использовать тот же идентификатор область, идентификатор регистрации и сертификат и ключ, что и в запросе на регистрацию устройства. Используйте идентификатор операции, возвращенный в ответе регистрации устройства .

Например, следующая команда предназначена для самозаверяющего сертификата, созданного при использовании самозаверяющего сертификата. (Необходимо изменить идентификатор область и идентификатор операции.)

curl -L -i -X GET --cert ./device-certPUT --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/operations/5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a?api-version=2021-06-01

В следующих выходных данных показан ответ на устройство, которое было успешно назначено. Обратите внимание, что это свойство и registrationState.assignedHub что status свойство assigned задано в Центре Интернета вещей, где было подготовлено устройство.

HTTP/1.1 200 OK
Date: Sat, 27 Aug 2022 18:10:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
x-ms-request-id: 8f211bc5-3ed8-4c8b-9a79-e003e756e9e4
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
   "operationId":"5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a",
   "status":"assigned",
   "registrationState":{
      "x509":{
         
      },
      "registrationId":"my-x509-device",
      "createdDateTimeUtc":"2022-08-27T17:53:19.5143497Z",
      "assignedHub":"MyExampleHub.azure-devices.net",
      "deviceId":"my-x509-device",
      "status":"assigned",
      "substatus":"initialAssignment",
      "lastUpdatedDateTimeUtc":"2022-08-27T17:53:19.7519141Z",
      "etag":"IjEyMDA4NmYyLTAwMDAtMDMwMC0wMDAwLTYzMGE1YTBmMDAwMCI="
   }
}

Запишите идентификатор устройства и назначенный Центр Интернета вещей. Вы будете использовать их для отправки сообщения телеметрии в следующем разделе.

Отправка сообщения телеметрии

Вызовите REST API событий устройства Центр Интернета вещей для отправки телеметрии на устройство.

Используйте следующую команду curl:

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

Где:

  • -X POST сообщает curl, что это команда HTTP POST. Требуется для этого вызова API.

  • --cert [path_to_your_device_cert] сообщает curl, где найти сертификат X.509 устройства. Если закрытый ключ устройства защищен секретной фразой, можно добавить парольную фразу после пути сертификата, предшествовав двоеточию, например: --cert my-device.pem:1234

    • Если вы используете самозаверяющий сертификат, файл сертификата устройства будет содержать только один сертификат X.509. Если вы выполнили инструкции по использованию самозаверяющего сертификата, имя файла — device-cert.pem, а фраза передачи закрытого ключа — 1234используйте.--cert device-cert.pem:1234

    • Если вы используете цепочку сертификатов, файл сертификата устройства должен содержать допустимую цепочку сертификатов. Если вы выполнили инструкции по созданию цепочки сертификатов, файловый путь — certs/device-01-full-chain.cert.pem, поэтому используйте --cert certs/device-01-full-chain.cert.pem.

  • --key [path_to_your_device_private_key] сообщает curl, где найти закрытый ключ устройства.

  • -H 'Content-Type: application/json'сообщает Центр Интернета вещей, что мы публикуем содержимое JSON и должны быть "application/json".

  • -H 'Content-Encoding: utf-8'сообщает Центр Интернета вещей кодировку, которую мы используем для нашего текста сообщения. Задайте правильное значение для операционной системы или клиента; однако обычно это utf-8.

  • -d '{"temperature": 30}'–d Параметр — это "данные" или текст сообщения, которое мы публикуем. В этой статье мы публикуем одну точку данных температуры. Тип контента был указан как application/json, поэтому для этого запроса текст — JSON. Обратите внимание, что для curl он упакован в одинарные кавычки; в противном случае необходимо экранировать двойные кавычки в формате JSON.

  • Последним параметром является URL-адрес для публикации. Для API событий отправки устройства URL-адрес: https://[assigned_iot_hub_name].azure-devices.net/devices/[device_id]/messages/events?api-version=2020-03-13

    • Замените [assigned_iot_hub_name] именем Центра Интернета вещей, которому было назначено ваше устройство.

    • Замените [device_id] идентификатор устройства, назначенный при регистрации устройства. Для устройств, подготавливающих через группы регистрации, идентификатор устройства будет идентификатором регистрации. Для отдельных регистраций можно указать идентификатор устройства, отличный от идентификатора регистрации в записи регистрации.

Например:

  • Если вы выполнили инструкции по использованию самозаверяющего сертификата:

    curl -L -i -X POST --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"temperature": 30}' https://MyExampleHub.azure-devices.net/devices/my-x509-device/messages/events?api-version=2020-03-13

  • Если вы выполнили инструкции по использованию цепочки сертификатов:

    curl -L -i -X POST --cert certs/device-01-full-chain.cert.pem --key private/device-01.key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"temperature": 30}' https://MyExampleHub.azure-devices.net/devices/my-x509-device/messages/events?api-version=2020-03-13

Успешный вызов будет иметь ответ, аналогичный следующему:

HTTP/1.1 204 No Content
Content-Length: 0
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: aa58c075-20d9-4565-8058-de6dc8524f14
Date: Wed, 31 Aug 2022 18:34:44 GMT

Дальнейшие действия