Использование сертификатов 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, создайте бесплатную учетную запись, прежде чем приступить к работе.

  • Выполните шаги из руководства по быстрому началу работы: настройка службы подготовки устройств концентраторов IoT с использованием портала Azure.

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

  • Если вы работаете в Windows, установите последнюю версию Git. Обязательно добавьте GIT в переменные среды, доступные в командном окне. На клиентских инструментах Git от Software Freedom Conservancy можно найти последнюю версию git инструментов для установки, которая включает Git Bash — приложение командной строки, используемое для взаимодействия с вашим локальным репозиторием Git. В Windows введите все команды в локальной системе в командной строке Git Bash.

  • 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". Для этой статьи требуется только одно устройство, поэтому после создания закрытого ключа и цепочки сертификатов для первого устройства можно остановиться.

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

Сертификат Файл Описание
сертификат корневого ЦС. 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, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Снимок экрана: кнопка отправки файла в 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, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Снимок экрана: кнопка отправки файла в 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, вы можете использовать кнопку отправки для отправки файла сертификата на облачный диск перед выполнением команды.

Снимок экрана: кнопка отправки файла в 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— это, возможно, длительная операция, поэтому она выполняется асинхронно. Как правило, вы проверяете состояние с помощью 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

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

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' сообщает IoT Hub, какую кодировку мы используем для нашего сообщения. Задайте правильное значение для операционной системы или клиента; однако обычно это 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] на идентификатор устройства, который был назначен при регистрации устройства. Для устройств, которые настраиваются через группы регистрации, идентификатор устройства — это идентификатор регистрации. Для индивидуальных регистраций можно, при желании, указать 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

Дальнейшие шаги

  • Last updated on