Guia de início rápido: provisionar um dispositivo simulado de certificado X.509

  • Artigo

Neste início rápido, você cria um dispositivo simulado em sua máquina Windows. O dispositivo simulado está configurado para usar o atestado de certificado X.509 para autenticação. Depois de configurar o dispositivo, provisione-o para o hub IoT usando o Serviço de Provisionamento de Dispositivo do Hub IoT do Azure.

Se você não estiver familiarizado com o processo de provisionamento, revise a visão geral do provisionamento . Certifique-se também de que executa os passos descritos em Configurar o Serviço de Aprovisionamento de Dispositivos no Hub IoT com o portal do Azure antes de continuar.

Este guia de início rápido demonstra uma solução para uma estação de trabalho baseada no Windows. No entanto, você também pode executar os procedimentos no Linux. Para obter um exemplo de Linux, consulte Tutorial: Provisão para latência geográfica.

Pré-requisitos

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

  • Instale o Visual Studio 2022 com a carga de trabalho 'Desenvolvimento de área de trabalho com C++' habilitada. Visual Studio 2015, Visual Studio 2017 e Visual Studio 19 também são suportados. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

  • Instale o sistema de compilação CMake mais recente. Certifique-se de marcar a opção que adiciona o executável CMake ao seu caminho.

    Importante

    Confirme se os pré-requisitos do Visual Studio (Visual Studio e a carga de trabalho 'Desenvolvimento de área de trabalho com C++') estão instalados em sua máquina, antes de iniciar a CMake instalação. Depois de os pré-requisitos estarem assegurados e a transferência verificada, instale o sistema de compilação CMake. Além disso, esteja ciente de que versões mais antigas do sistema de compilação CMake não conseguem gerar o arquivo de solução usado neste artigo. Certifique-se de usar a versão mais recente do CMake.

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

  • Instale o .NET SDK 6.0 ou posterior em sua máquina baseada no Windows. Você pode usar o seguinte comando para verificar sua versão.

    dotnet --info

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows.

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

  • Instale a versão mais recente do Git. Certifique-se de que o Git é adicionado às variáveis de ambiente acessíveis à janela de comando. Consulte as ferramentas de cliente Git da Software Freedom Conservancy para obter a versão mais recente das ferramentas a serem instaladas, que inclui o Git Bash, o aplicativo de linha de git comando que você pode usar para interagir com seu repositório Git local.

  • Certifique-se de que o OpenSSL está instalado na sua máquina. No Windows, sua instalação do Git inclui uma instalação do OpenSSL. Você pode acessar o OpenSSL a partir do prompt do Git Bash. Para verificar se o OpenSSL está instalado, abra um prompt do Git Bash e digite openssl version.

    Nota

    A menos que você esteja familiarizado com o OpenSSL e já o tenha instalado em sua máquina Windows, recomendamos usar o OpenSSL no prompt do Git Bash. Como alternativa, você pode optar por baixar o código-fonte e construir OpenSSL. Para saber mais, consulte a página Downloads do OpenSSL. Ou, você pode baixar OpenSSL pré-construído de terceiros. Para saber mais, consulte o wiki do OpenSSL. A Microsoft não garante a validade de pacotes baixados de terceiros. Se você optar por construir ou baixar o OpenSSL, certifique-se de que o binário OpenSSL esteja acessível em seu caminho e que a OPENSSL_CNF variável de ambiente esteja definida como o caminho do arquivo openssl.cnf .

  • Abra um prompt de comando do Windows e um prompt do Git Bash.

    As etapas neste início rápido pressupõem que você esteja usando uma máquina Windows e a instalação do OpenSSL instalada como parte do Git. Você usa o prompt do Git Bash para emitir comandos OpenSSL e o prompt de comando do Windows para todo o resto. Se você estiver usando Linux, você pode emitir todos os comandos a partir de um shell Bash.

Preparar o ambiente de desenvolvimento

Nesta seção, você prepara um ambiente de desenvolvimento usado para criar o SDK do Azure IoT C. O código de exemplo tenta provisionar o dispositivo, durante a sequência de inicialização do dispositivo.

  1. Abra um navegador da Web e vá para a página Lançamento do SDK do Azure IoT C.

  2. Selecione a guia Tags na parte superior da página.

  3. Copie o nome da marca para a versão mais recente do Azure IoT C SDK.

  4. No prompt de comando do Windows, execute os seguintes comandos para clonar a versão mais recente do SDK do Dispositivo IoT do Azure para o repositório C GitHub. Substitua <release-tag> pela tag copiada na etapa anterior, por exemplo: lts_01_2023.

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

    Esta operação pode levar vários minutos para ser concluída.

  5. Quando a operação estiver concluída, execute os seguintes comandos a azure-iot-sdk-c partir do diretório:

    mkdir cmake
cd cmake

  6. O exemplo de código utiliza um certificado X.509 para fornecer um atestado através da autenticação X.509. Execute o comando a seguir para criar uma versão do SDK específica para sua plataforma de desenvolvimento que inclua o cliente de provisionamento de dispositivo. Uma solução do Visual Studio para o dispositivo simulado cmake é gerada no diretório.

    Ao especificar o caminho usado com -Dhsm_custom_lib o comando a seguir, certifique-se de usar o caminho absoluto para a biblioteca no cmake diretório criado anteriormente. O caminho mostrado pressupõe que você clonou o C SDK no diretório raiz da unidade C. Se você usou outro diretório, ajuste o caminho de acordo.

    cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..

Gorjeta

Se cmake não encontrar seu compilador C++, você pode obter erros de compilação ao executar o comando acima. Se isso acontecer, tente executar o comando no prompt de comando do Visual Studio.

  1. Quando a compilação é bem-sucedida, as últimas linhas de saída são semelhantes à seguinte saída:

    -- Building for: Visual Studio 17 2022
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
-- The C compiler identification is MSVC 19.32.31329.0
-- The CXX compiler identification is MSVC 19.32.31329.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

No prompt de comando do Windows, clone o repositório GitHub do SDK do Azure IoT para C# usando o seguinte comando:

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

No prompt de comando do Windows, clone o SDK do Azure IoT para Node.js repositório GitHub usando o seguinte comando:

git clone https://github.com/Azure/azure-iot-sdk-node.git

No prompt de comando do Windows, clone o SDK do Dispositivo IoT do Azure para o repositório GitHub do Python usando o seguinte comando:

git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

Nota

Os exemplos usados neste tutorial estão na ramificação v2 do repositório azure-iot-sdk-python. V3 do Python SDK está disponível para uso em beta.

  1. No prompt de comando do Windows, clone o repositório Azure IoT Samples for Java GitHub usando o seguinte comando:

    git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive

  2. Vá para o diretório raiz azure-iot-sdk-java e construa o projeto para baixar todos os pacotes necessários.

    cd azure-iot-sdk-java
mvn install -DskipTests=true

Criar um certificado de dispositivo X.509 autoassinado

Nesta seção, você usa OpenSSL para criar um certificado X.509 auto-assinado e uma chave privada. Esse certificado é carregado na instância do serviço de provisionamento e verificado pelo serviço.

Atenção

Use certificados criados com OpenSSL neste início rápido apenas para testes de desenvolvimento. Não utilize estes certificados na produção. Esses certificados expiram após 30 dias e podem conter senhas codificadas, como 1234. Para saber mais sobre como obter certificados adequados para uso em produção, consulte Como obter um certificado de CA X.509 na documentação do Hub IoT do Azure.

Execute as etapas nesta seção no prompt do Git Bash.

  1. No prompt do Git Bash, navegue até um diretório onde você gostaria de criar seus certificados.

  2. Execute o seguinte comando:

    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"

    Importante

    A barra extra dada para o nome do assunto (//CN=my-x509-device) só é necessária para escapar da cadeia de caracteres com o Git em plataformas Windows.

  3. Quando lhe for pedido para introduzir a frase secreta PEM:, utilize a frase 1234secreta .

  4. Quando lhe for perguntado Verificar - Introduza a frase secreta PEM:, utilize novamente a frase 1234 secreta.

    Um arquivo de certificado de chave pública (device-cert.pem) e um arquivo de chave privada (device-key.pem) agora devem ser gerados no diretório onde você executou o openssl comando.

    O arquivo de certificado tem seu nome comum de assunto (CN) definido como my-x509-device. Para inscrições baseadas em X.509, a ID de Registro é definida como o nome comum. O ID de registo é uma cadeia de carateres alfanuméricos que não diferencia maiúsculas de minúsculas mais os carateres especiais: '-', '.', '_', ':'. O último caractere deve ser alfanumérico ou traço ('-'). O nome comum deve aderir a este formato. O DPS suporta IDs de registro de até 128 caracteres; no entanto, o comprimento máximo do nome comum da entidade em um certificado X.509 é de 64 caracteres. O ID de registro, portanto, é limitado a 64 caracteres ao usar certificados X.509.

  5. O arquivo de certificado é codificado em Base 64. Para exibir o nome comum da entidade (CN) e outras propriedades do arquivo de certificado, digite o seguinte comando:

    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

  1. O código de exemplo requer uma chave privada que não está encriptada. Execute o seguinte comando para criar uma chave privada não encriptada:

    winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

  2. Quando solicitado a inserir a frase secreta para device-key.pem:, use a mesma frase secreta que você fez anteriormente, 1234.

Mantenha o prompt do Git Bash aberto. Você precisa dele mais tarde neste início rápido.

O código de exemplo C# é configurado para usar certificados X.509 armazenados em um arquivo formatado PKCS#12 protegido por senha (certificate.pfx). Você ainda precisa do arquivo de certificado de chave pública formatado PEM (device-cert.pem) que acabou de criar para criar uma entrada de registro individual posteriormente neste início rápido.

  1. Para gerar o arquivo formatado PKCS12 esperado pelo exemplo, digite o seguinte comando:

    winpty openssl pkcs12 -inkey device-key.pem -in device-cert.pem -export -out certificate.pfx

  2. Quando solicitado a inserir a frase secreta para device-key.pem:, use a mesma frase secreta que você fez anteriormente, 1234.

  3. Quando lhe for pedido para introduzir a palavra-passe de exportação:, utilize a palavra-passe 1234.

  4. Quando solicitado Verificando - Digite Exportar senha:, use a senha 1234 novamente.

    Um arquivo de certificado formatado PKCS12 (certificate.pfx) agora deve ser gerado no diretório onde você executou o openssl comando.

  5. Copie o arquivo de certificado formatado PKCS12 para o diretório do projeto para o exemplo de provisionamento de dispositivo X.509. O caminho fornecido é relativo ao local onde você baixou o repositório de exemplo.

    cp certificate.pfx ./azure-iot-sdk-csharp/provisioning/device/samples/"Getting Started"/X509Sample

Você não precisa do prompt do Git Bash para o resto deste início rápido. No entanto, você pode querer mantê-lo aberto para verificar seu certificado se tiver problemas em etapas posteriores.

  1. O código de exemplo requer uma chave privada que não está encriptada. Execute o seguinte comando para criar uma chave privada não encriptada:

    winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

  2. Quando solicitado a inserir a frase secreta para device-key.pem:, use a mesma frase secreta que você fez anteriormente, 1234.

  3. Copie o certificado do dispositivo e a chave privada não criptografada para o diretório do projeto para o exemplo de provisionamento de dispositivo X.509. O caminho fornecido é relativo ao local onde você baixou o SDK.

    cp device-cert.pem ./azure-iot-sdk-node/provisioning/device/samples
cp unencrypted-device-key.pem ./azure-iot-sdk-node/provisioning/device/samples

Você não precisa do prompt do Git Bash para o resto deste início rápido. No entanto, você pode querer mantê-lo aberto para verificar seu certificado se tiver problemas em etapas posteriores.

  1. Copie o certificado do dispositivo e a chave privada para o diretório do projeto para o exemplo de provisionamento de dispositivo X.509. O caminho fornecido é relativo ao local onde você baixou o SDK.

    cp device-cert.pem ./azure-iot-sdk-python/samples/async-hub-scenarios
cp device-key.pem ./azure-iot-sdk-python/samples/async-hub-scenarios

Você não precisa do prompt do Git Bash para o resto deste início rápido. No entanto, você pode querer mantê-lo aberto para verificar seu certificado se tiver problemas em etapas posteriores.

  1. O código de exemplo Java requer uma chave privada que não está criptografada. Execute o seguinte comando para criar uma chave privada não encriptada:

    winpty openssl pkey -in device-key.pem -out unencrypted-device-key.pem

  2. Quando solicitado a inserir a frase secreta para device-key.pem:, use a mesma frase secreta que você fez anteriormente, 1234.

Mantenha o prompt do Git Bash aberto. Você precisa dele mais tarde neste início rápido.

Criar um registro de dispositivo

O Serviço Aprovisionamento de Dispositivos no IoT do Azure suporta dois tipos de inscrição:

Este artigo demonstra um registro individual para um único dispositivo a ser provisionado com um hub IoT.

  1. Entre no portal do Azure e navegue até sua instância do Serviço de Provisionamento de Dispositivo.

  2. Selecione Gerenciar inscrições na seção Configurações do menu de navegação.

  3. Selecione a guia Inscrições individuais e, em seguida, selecione Adicionar inscrição individual.

    Captura de tela que mostra a opção adicionar inscrição individual.

  4. Na página Registro + provisionamento da página Adicionar registro, forneça as seguintes informações para configurar os detalhes do registro:

    Campo Descrição
    Atestado Selecione certificados de cliente X.509 como o mecanismo de atestado.
    Configurações de certificado X.509 Carregue um ou dois certificados que serão usados para verificar o dispositivo para este registro.
    Status de provisionamento Marque a caixa Habilitar este registro se quiser que esse registro esteja disponível para provisionar seu dispositivo. Desmarque esta caixa se quiser que a inscrição seja desativada. Você pode alterar essa configuração mais tarde.
    Política de reaprovisionamento Escolha uma política de reprovisionamento que reflita como você deseja que o DPS manipule dispositivos que solicitam reprovisionamento. Para obter mais informações, consulte Políticas de reprovisionamento.

  5. Selecione Next: Hubs IoT.

  6. Na guia Hubs IoT da página Adicionar registro, forneça as seguintes informações para determinar para quais hubs IoT o registro pode provisionar dispositivos:

    Campo Descrição
    Hubs IoT de destino Selecione um ou mais hubs IoT vinculados ou adicione um novo link a um hub IoT. Para saber mais sobre como vincular hubs IoT à sua instância DPS, consulte Como vincular e gerenciar hubs IoT.
    Política de afetação Se você selecionou mais de um hub IoT vinculado, selecione como deseja atribuir dispositivos aos diferentes hubs. Para saber mais sobre políticas de alocação, consulte Como usar políticas de alocação.

    Se você selecionou apenas um hub IoT vinculado, recomendamos usar a política de distribuição ponderada uniformemente.

  7. Selecione Next: Configurações do dispositivo

  8. Na guia Configurações do dispositivo da página Adicionar registro, forneça as seguintes informações para definir como os dispositivos recém-provisionados serão configurados:

    Campo Descrição
    ID do Dispositivo Forneça um ID de dispositivo que será atribuído ao dispositivo provisionado no Hub IoT. Se não fornecer um ID de dispositivo, o ID de registo será utilizado.
    IoT Edge Verifique a opção Habilitar o IoT Edge em dispositivos provisionados se o dispositivo provisionado executará o Azure IoT Edge. Desmarque esta caixa se este registro for para um dispositivo não habilitado para IoT Edge.
    Tags de dispositivo Use esta caixa de texto para fornecer as tags que você deseja aplicar ao gêmeo de dispositivo do dispositivo provisionado.
    Propriedades desejadas Use esta caixa de texto para fornecer as propriedades desejadas que você deseja aplicar ao gêmeo de dispositivo do dispositivo provisionado.

    Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

  9. Selecione Seguinte: Rever + criar.

  10. No separador Rever + criar, verifique todos os seus valores e, em seguida, selecione Criar.

Preparar e executar o código de provisionamento do dispositivo

Nesta seção, você atualiza o código de exemplo para enviar a sequência de inicialização do dispositivo para sua instância do Serviço de Provisionamento de Dispositivo. Essa sequência de inicialização faz com que o dispositivo seja reconhecido e atribuído a um hub IoT vinculado à instância do DPS.

Nesta seção, você usa o prompt do Git Bash e o IDE do Visual Studio.

Configurar o código do dispositivo de provisionamento

Nesta seção, você atualiza o código de exemplo com as informações da instância do Serviço de Provisionamento de Dispositivo.

  1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo.

  2. Copie o valor ID Scope .

    Captura de ecrã do âmbito do ID no portal do Azure.

  3. Inicie o Visual Studio e abra o novo arquivo de solução que foi criado no cmake diretório criado na raiz do repositório git azure-iot-sdk-c. O arquivo de solução é chamado azure_iot_sdks.sln.

  4. No Gerenciador de Soluções para Visual Studio, navegue até Provision_Samples > prov_dev_client_sample Arquivos de > Origem e abra prov_dev_client_sample.c.

  5. Localize a id_scope constante e substitua o valor pelo valor do Escopo de ID copiado na etapa 2.

    static const char* id_scope = "0ne00000A0A";

  6. Localize a definição da função main() no mesmo ficheiro. Verifique se a hsm_type variável está definida como SECURE_DEVICE_TYPE_X509.

    SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
hsm_type = SECURE_DEVICE_TYPE_X509;
//hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

  7. Guardar as suas alterações.

  8. Clique com o botão direito do mouse no projeto prov_dev_client_sample e selecione Definir como projeto de inicialização.

Configurar o código de stub HSM personalizado

As especificidades da interação com o armazenamento seguro real baseado em hardware variam dependendo do hardware. Como resultado, o certificado e a chave privada usados pelo dispositivo simulado neste início rápido são codificados no código de stub personalizado do HSM (Hardware Security Module).

Para atualizar o código de stub HSM personalizado para simular a identidade do dispositivo com ID my-x509-device:

  1. No Gerenciador de Soluções para Visual Studio, navegue até Provision_Samples > custom_hsm_example > Arquivos de Origem e abra o custom_hsm_example.c.

  2. Atualize o valor da cadeia de caracteres constante COMMON_NAME usando o nome comum usado ao gerar o certificado do dispositivo, my-x509-device.

    static const char* const COMMON_NAME = "my-x509-device";

  3. Atualize o valor da cadeia de caracteres constante usando o certificado de CERTIFICATE dispositivo, device-cert.pem, que você gerou anteriormente.

    A sintaxe do texto do certificado no exemplo deve seguir o seguinte padrão sem espaços extras ou análise feita pelo Visual Studio.

    static const char* const CERTIFICATE = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----";

    Atualizar esse valor de cadeia de caracteres manualmente pode ser propenso a erros. Para gerar a sintaxe adequada, você pode copiar e colar o seguinte comando no prompt do Git Bash e pressionar ENTER. Este comando gera a sintaxe para o valor da CERTIFICATE constante de cadeia de caracteres e grava-a na saída.

    sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' device-cert.pem

    Copie e cole o texto do certificado de saída para o valor constante.

  4. Atualize o valor da cadeia de caracteres da PRIVATE_KEY constante com a chave privada não criptografada para o certificado do dispositivo, unencrypted-device-key.pem.

    A sintaxe do texto da chave privada deve seguir o seguinte padrão sem espaços extras ou análise feita pelo Visual Studio.

    static const char* const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n"
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n"
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n"
"-----END RSA PRIVATE KEY-----";

    Atualizar esse valor de cadeia de caracteres manualmente pode ser propenso a erros. Para gerar a sintaxe adequada, você pode copiar e colar o seguinte comando no prompt do Git Bash e pressionar ENTER. Este comando gera a sintaxe para o valor da PRIVATE_KEY constante de cadeia de caracteres e grava-a na saída.

    sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' unencrypted-device-key.pem

    Copie e cole o texto da chave privada de saída para o valor constante.

  5. Guardar as suas alterações.

  6. Clique com o botão direito do mouse no projeto custom_hsm_-_example e selecione Construir.

    Importante

    Você deve criar o projeto custom_hsm_example antes de criar o restante da solução na próxima seção.

Executar o exemplo

  1. No menu do Visual Studio, selecione Debug (Depurar) >Start without debugging (Iniciar sem depuração) para executar a solução. Se você for solicitado a reconstruir o projeto, selecione Sim para reconstruir o projeto antes de executá-lo.

    A saída a seguir é um exemplo do dispositivo my-x509-device simulado inicializando com êxito e conectando-se ao serviço de provisionamento. O dispositivo é atribuído a um hub IoT e registrado:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-iot-hub-2.azure-devices.net, deviceId: my-x509-device
Press enter key to exit:

Nesta seção, você usa o prompt de comando do Windows.

  1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo.

  2. Copie o valor ID Scope .

    Captura de ecrã do âmbito do ID no portal do Azure.

  3. No prompt de comando do Windows, mude para o diretório X509Sample. Este diretório está localizado no diretório .\azure-iot-sdk-csharp\provisioning\device\samples\getting started\X509Sample fora do diretório onde você clonou os exemplos no seu computador.

  4. Digite o seguinte comando para criar e executar o exemplo de provisionamento de dispositivo X.509 (substitua o <IDScope> valor pelo Escopo de ID que você copiou na seção anterior. O arquivo de certificado assume como padrão ./certificate.pfx e solicita a senha .pfx.

    dotnet run -- -s <IDScope>

    Se você quiser passar o certificado e a senha como parâmetro, você pode usar o seguinte formato.

    Nota

    Parâmetros adicionais podem ser passados durante a execução do aplicativo para alterar o TransportType (-t) e o GlobalDeviceEndpoint (-g).

    dotnet run -- -s 0ne00000A0A -c certificate.pfx -p 1234

  5. O dispositivo se conecta ao DPS e é atribuído a um hub IoT. Em seguida, o dispositivo envia uma mensagem de telemetria para o hub IoT.

    Loading the certificate...
Enter the PFX password for certificate.pfx:
****
Found certificate: A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device; PrivateKey: True
Using certificate A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device
Initializing the device provisioning client...
Initialized for registration Id my-x509-device.
Registering with the device provisioning service...
Registration status: Assigned.
Device my-x509-device registered to MyExampleHub.azure-devices.net.
Creating X509 authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

Nesta seção, você usa o prompt de comando do Windows.

  1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo.

  2. Copie o valor ID Scope .

    Captura de ecrã do âmbito do ID no portal do Azure.

  3. No prompt de comando do Windows, vá para o diretório de exemplo e instale os pacotes necessários para o exemplo. O caminho mostrado é relativo ao local onde você clonou o SDK.

    cd .\azure-iot-sdk-node\provisioning\device\samples
npm install

    O exemplo usa cinco variáveis de ambiente para autenticar e provisionar um dispositivo IoT usando DPS. Estas variáveis de ambiente são:

    Nome da variável Description
    PROVISIONING_HOST O ponto de extremidade a ser usado para se conectar à sua instância DPS. Para este início rápido, use o ponto de extremidade global, global.azure-devices-provisioning.net.
    PROVISIONING_IDSCOPE O escopo de ID para sua instância DPS.
    PROVISIONING_REGISTRATION_ID O ID de registo do seu dispositivo. Ele deve corresponder ao nome comum da entidade no certificado do dispositivo.
    CERTIFICATE_FILE O caminho para o arquivo de certificado do dispositivo.
    KEY_FILE O caminho para o arquivo de chave privada do dispositivo.

  4. Adicione variáveis de ambiente para o ponto de extremidade do dispositivo global e o escopo de ID. Substitua <id-scope> pelo valor copiado na etapa 2.

    set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<id-scope>

  5. Defina a variável de ambiente para o ID de registro do dispositivo. A ID de registro do dispositivo IoT deve corresponder ao nome comum da entidade no certificado do dispositivo. Se você seguiu as etapas neste início rápido para gerar um certificado de teste autoassinado, my-x509-device é o nome do assunto e o ID de registro do dispositivo.

    set PROVISIONING_REGISTRATION_ID=my-x509-device

  6. Defina as variáveis de ambiente para o certificado do dispositivo e os arquivos de chave privada do dispositivo (não criptografados).

    set CERTIFICATE_FILE=.\device-cert.pem
set KEY_FILE=.\unencrypted-device-key.pem

  7. Execute o exemplo e verifique se o dispositivo foi provisionado com êxito.

    node register_x509.js

    Você deve ver uma saída semelhante ao exemplo a seguir:

    registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=my-x509-device
Client connected
send status: MessageEnqueued

Nesta seção, você usa o prompt de comando do Windows.

  1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo.

  2. Copie os valores de ID Scope e Global device endpoint .

    Captura de ecrã do âmbito do ID e do ponto de extremidade do dispositivo global no portal do Azure.

  3. No prompt de comando do Windows, vá para o diretório do exemplo de provision_x509.py . O caminho mostrado é relativo ao local onde você clonou o SDK.

    cd ./azure-iot-sdk-python/samples/async-hub-scenarios

    Este exemplo usa seis variáveis de ambiente para autenticar e provisionar um dispositivo IoT usando DPS. Estas variáveis de ambiente são:

    Nome da variável Description
    PROVISIONING_HOST O ponto de extremidade global usado para se conectar à sua instância DPS.
    PROVISIONING_IDSCOPE O escopo de ID para sua instância DPS.
    DPS_X509_REGISTRATION_ID O ID de registo do seu dispositivo. Ele também deve corresponder ao nome do assunto no certificado do dispositivo.
    X509_CERT_FILE O caminho para o arquivo de certificado do dispositivo.
    X509_KEY_FILE O caminho para o arquivo de chave privada do certificado do dispositivo.
    PASS_PHRASE A frase secreta usada para criptografar o certificado e o arquivo de chave privada (1234).

  4. Adicione as variáveis de ambiente para o ponto de extremidade do dispositivo global e o Escopo do ID.

    set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>

  5. Defina a variável de ambiente para a ID de registro. O ID de registro do dispositivo IoT deve corresponder ao nome do assunto no certificado do dispositivo. Se você seguiu as etapas neste início rápido para gerar um certificado de teste autoassinado, my-x509-device é o nome do assunto e o ID de registro do dispositivo.

    set DPS_X509_REGISTRATION_ID=my-x509-device

  6. Defina as variáveis de ambiente para o arquivo de certificado, arquivo de chave privada e frase secreta.

    set X509_CERT_FILE=./device-cert.pem
set X509_KEY_FILE=./device-key.pem
set PASS_PHRASE=1234

  7. Revise o código para provision_x509.py. Se você não estiver usando o Python versão 3.7 ou posterior, faça a alteração de código mencionada aqui para substituir asyncio.run(main()) e salvar suas alterações.

  8. Execute o exemplo. O exemplo se conecta ao DPS, que provisiona o dispositivo para um hub IoT. Depois que o dispositivo é provisionado, o exemplo envia algumas mensagens de teste para o hub IoT.

    $ python azure-iot-sdk-python/samples/async-hub-scenarios/provision_x509.py
RegistrationStage(RequestAndResponseOperation): Op will transition into polling after interval 2.  Setting timer.
The complete registration result is
my-x509-device
TestHub12345.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #4
sending message #7
sending message #2
sending message #8
sending message #5
sending message #9
sending message #1
sending message #6
sending message #10
sending message #3
done sending message #4
done sending message #7
done sending message #2
done sending message #8
done sending message #5
done sending message #9
done sending message #1
done sending message #6
done sending message #10
done sending message #3

Nesta seção, você usa o prompt de comando do Windows e o prompt do Git Bash.

  1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo.

  2. Copie os valores de ID Scope e Global device endpoint .

    Captura de ecrã do âmbito do ID e do ponto de extremidade do dispositivo global no portal do Azure.

  3. No prompt de comando do Windows, navegue até a pasta de projeto de exemplo. O caminho mostrado é relativo ao local onde você clonou o SDK

    cd .\azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-X509-sample

  4. Insira o serviço de provisionamento e as informações de identidade X.509 no código de exemplo. Essas informações são usadas durante o provisionamento, para atestado do dispositivo simulado, antes do registro do dispositivo.

    1. Abra o arquivo .\src\main\java\samples\com\microsoft\azure\sdk\iot\ProvisioningX509Sample.java em seu editor favorito.

    2. Atualize os valores a seguir com o ID Scope and Provisioning Service Global Endpoint que você copiou anteriormente.

      private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;

    3. Atualize o leafPublicPem valor da cadeia de caracteres constante com o valor do seu certificado, device-cert.pem.

      A sintaxe do texto do certificado deve seguir o seguinte padrão, sem espaços ou caracteres extras.

      private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
"-----END CERTIFICATE-----";

      Atualizar esse valor de cadeia de caracteres manualmente pode ser propenso a erros. Para gerar a sintaxe adequada, você pode copiar e colar o seguinte comando no prompt do Git Bash e pressionar ENTER. Este comando gera a sintaxe para o valor da leafPublicPem constante de cadeia de caracteres e grava-a na saída.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' device-cert.pem

      Copie e cole o texto do certificado de saída para o valor constante.

    4. Atualize o valor da cadeia de caracteres da leafPrivateKey constante com a chave privada não criptografada para o certificado do dispositivo, unencrypted-device-key.pem.

      A sintaxe do texto da chave privada deve seguir o seguinte padrão, sem espaços ou caracteres extras.

      private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n" +
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n" +
"-----END PRIVATE KEY-----";

      Atualizar esse valor de cadeia de caracteres manualmente pode ser propenso a erros. Para gerar a sintaxe adequada, você pode copiar e colar o seguinte comando no prompt do Git Bash e pressionar ENTER. Este comando gera a sintaxe para o valor da leafPrivateKey constante de cadeia de caracteres e grava-a na saída.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' unencrypted-device-key.pem

      Copie e cole o texto da chave privada de saída para o valor constante.

    5. Guardar as suas alterações.

  5. Crie o exemplo e, em seguida, vá para a target pasta.

    mvn clean install
cd target

  6. A compilação produz .jar arquivo na target pasta com o seguinte formato de arquivo: provisioning-x509-sample-{version}-with-deps.jar; por exemplo: provisioning-x509-sample-1.8.1-with-deps.jar. Execute o arquivo .jar. Talvez seja necessário substituir a versão no comando a seguir.

    java -jar ./provisioning-x509-sample-1.8.1-with-deps.jar

    O exemplo se conecta ao DPS, que provisiona o dispositivo para um hub IoT. Depois que o dispositivo é provisionado, o exemplo envia algumas mensagens de teste para o hub IoT.

    Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-05-11 09:42:05,025 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.0
2022-05-11 09:42:05,027 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-05-11 09:42:05,030 INFO (global.azure-devices-provisioning.net-6255a8ba-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-05-11 09:42:05,252 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-05-11 09:42:05,286 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using x509 certificates
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
Waiting for Provisioning Service to register
2022-05-11 09:42:15,685 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : MyExampleHub.azure-devices.net
Device ID : java-device-01
2022-05-11 09:42:25,057 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,080 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,087 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.0.3
2022-05-11 09:42:25,129 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-05-11 09:42:25,150 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-05-11 09:42:25,982 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-05-11 09:42:25,983 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/#
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/# was acknowledged
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-05-11 09:42:26,070 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-05-11 09:42:26,073 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-05-11 09:42:26,074 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-05-11 09:42:26,075 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-05-11 09:42:26,077 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
Press any key to exit...
2022-05-11 09:42:26,079 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
2022-05-11 09:42:26,422 DEBUG (MQTT Call: java-device-01) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
2022-05-11 09:42:26,425 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] ) with status OK
Message sent!

Confirme o registro de provisionamento do dispositivo

Para ver para qual hub IoT seu dispositivo foi provisionado, examine os detalhes de registro do registro individual criado anteriormente:

  1. No portal do Azure, vá para o seu Serviço de Provisionamento de Dispositivo.

  2. No menu Configurações, selecione Gerenciar inscrições.

  3. Selecione Inscrições individuais. A entrada de inscrição X.509 que você criou anteriormente, my-x509-device, deve aparecer na lista.

  4. Selecione a entrada de inscrição. O hub IoT ao qual seu dispositivo foi atribuído e sua ID de dispositivo aparecem em Status de registro.

Para verificar o dispositivo no seu hub IoT:

  1. No portal do Azure, vá para o hub IoT ao qual seu dispositivo foi atribuído.

  2. No menu Gerenciamento de dispositivos, selecione Dispositivos.

  3. Se o dispositivo tiver sido provisionado com êxito, o ID do dispositivo, my-x509-device, deverá aparecer na lista, com Status definido como habilitado. Se não vir o dispositivo, selecione Atualizar.

    Captura de ecrã que mostra que o dispositivo está registado no hub IoT no portal do Azure.

Importante

Se tiver alterado o estado inicial do dispositivo duplo face ao valor predefinido na entrada de inscrição do seu dispositivo, este pode extrair o estado pretendido do dispositivo duplo a partir do hub e agir em conformidade. Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT)

Clean up resources (Limpar recursos)

Se você planeja continuar trabalhando e explorando o exemplo de cliente de dispositivo, não limpe os recursos criados neste início rápido. Se você não planeja continuar, use as etapas a seguir para excluir todos os recursos criados por este início rápido.

Excluir o registro do dispositivo

  1. Feche a janela da saída do exemplo de dispositivo cliente no seu computador.

  2. No menu à esquerda no portal do Azure, selecione Todos os recursos.

  3. Selecione o Serviço de Provisionamento de Dispositivo.

  4. No menu Configurações, selecione Gerenciar inscrições.

  5. Selecione a guia Inscrições individuais.

  6. Marque a caixa de seleção ao lado da ID de registro do dispositivo que você inscreveu neste início rápido.

  7. Na parte superior da página, selecione Eliminar.

Excluir o registro do dispositivo do Hub IoT

  1. No menu à esquerda no portal do Azure, selecione Todos os recursos.

  2. Selecione seu hub IoT.

  3. No menu Explorers, selecione dispositivos IoT.

  4. Marque a caixa de seleção ao lado da ID do dispositivo que você registrou neste início rápido.

  5. Na parte superior da página, selecione Eliminar.

Próximos passos

Neste início rápido, você provisionou um único dispositivo para seu hub IoT usando um registro individual. Em seguida, saiba como provisionar vários dispositivos em vários hubs.

Tutorial: Gerenciar atribuição de hub IoT com políticas de alocação personalizadas