Início Rápido: Provisionar um dispositivo simulado de certificado X.509

  • Artigo

Neste início rápido, você cria um dispositivo simulado no seu computador Windows. O dispositivo simulado está configurado para usar o mecanismo de atestado do certificado X.509 para autenticação. Depois de configurar seu dispositivo, você o provisiona no seu hub IoT usando o Serviço de Provisionamento de Dispositivos no Hub IoT do Azure.

Se você não estiver familiarizado com o processo de provisionamento, examine a visão geral de provisionamento. Não se esqueça de concluir as etapas em Configurar o Serviço de Provisionamento 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 em Windows. No entanto, também é possível executar os procedimentos no Linux. Para obter um exemplo de Linux, confira 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, confira a seção apropriada em Preparar seu ambiente de desenvolvimento na documentação do SDK.

  • Instale o Visual Studio 2022 com a carga de trabalho "Desenvolvimento para desktop com C++" habilitada. Também há suporte para o Visual Studio 2015, Visual Studio 2017 e o Visual Studio 19. Para Linux ou macOS, confira a seção apropriada em Preparar seu ambiente de desenvolvimento na documentação do SDK.

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

    Importante

    Confirme que os pré-requisitos do Visual Studio (Visual Studio e a carga de trabalho de 'Desenvolvimento para Desktop com C++') estão instalados no computador antes de iniciar a instalação de CMake. Após a instalação dos pré-requisitos e verificação do download, instale o sistema de compilação CMake. Além disso, esteja ciente de que as versões mais antigas do sistema de build CMake não geram o arquivo de solução usado neste artigo. Use 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, confira a seção apropriada em Preparar seu ambiente de desenvolvimento na documentação do SDK.

  • Instale o SDK do .NET 6.0 ou posterior no computador baseado no Windows. Use o comando a seguir para verificar a versão.

    dotnet --info

Os pré-requisitos a seguir são para um ambiente de desenvolvimento do Windows. Para Linux ou macOS, confira a seção apropriada em Preparar seu ambiente de desenvolvimento 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, confira a seção apropriada em Preparar seu ambiente de desenvolvimento na documentação do SDK.

  • Instale a versão mais recente do Git. Verifique se o Git foi adicionado às variáveis de ambiente que podem ser acessadas pela janela de comando. Confira Ferramentas de cliente Git do Software Freedom Conservancy para obter a versão mais recente das ferramentas git a serem instaladas, que inclui o Git Bash, o aplicativo de linha de comando que você pode usar para interagir com seu repositório Git local.

  • Verifique se o OpenSSL está instalado no computador. No Windows, a instalação do Git inclui uma instalação do OpenSSL. É possível acessar o OpenSSL no prompt do Git Bash. Para verificar se o OpenSSL está instalado, abra um prompt do Git Bash e insira openssl version.

    Observação

    A menos que você esteja familiarizado com o OpenSSL e já o tenha instalado em seu computador Windows, recomendamos usar o OpenSSL no prompt do Git Bash. Como alternativa, você pode optar por baixar o código-fonte e compilar o OpenSSL. Para saber mais, consulte a página Downloads do OpenSSL. Ou então, você pode baixar o OpenSSL pré-criado de terceiros. Para saber mais, consulte o wiki do OpenSSL. A Microsoft não garante a validade dos pacotes baixados de terceiros. Se você optar por compilar ou baixar o OpenSSL, verifique se o binário OpenSSL está acessível no seu caminho e se a variável de ambiente OPENSSL_CNF está 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 um computador Windows e a instalação do OpenSSL feita 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 o Linux, poderá emitir todos os comandos de um shell do Bash.

Preparar seu ambiente de desenvolvimento

Nesta seção, você prepara um ambiente de desenvolvimento usado para compilar o SDK de C do IoT do Azure. 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 acesse a página de versão do SDK do Azure IoT para C.

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

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

  4. No prompt de comando do Windows, execute os seguintes comandos para clonar a última versão do repositório GitHub do SDK do Dispositivo IoT do Azure para C. Substitua <release-tag> pela marca que você copiou 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

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

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

    mkdir cmake
cd cmake

  6. O exemplo de código usa um certificado X.509 para fornecer comprovação por meio 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 inclui o cliente de provisionamento de dispositivos. Uma solução do Visual Studio para o dispositivo simulado é gerada no diretório cmake.

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

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

Dica

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

  1. Quando o build tiver êxito, as últimas linhas da saída terão aparência semelhante à 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 do GitHub do SDK da IoT do Azure 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 repositório GitHub SDK da Internet das Coisas do Azure para Node.js usando o seguinte comando:

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

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

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

Observação

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

  1. No prompt de comando do Windows, clone o repositório GitHub Exemplos da Internet das Coisas do Azure para Java usando o seguinte comando:

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

  2. Acesse o diretório azure-iot-sdk-java raiz e crie 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 o OpenSSL para criar um certificado X.509 auto-assinado e uma chave privada. Esse certificado é enviado para sua instância do serviço de provisionamento e verificado pelo serviço.

Cuidado

Use certificados criados com o OpenSSL neste início rápido somente para testes de desenvolvimento. Não use esses certificados em produção. Esses certificados expiram após 30 dias e podem conter senhas embutidas em código, como 1234. Para obter informações sobre como obter certificados adequados para o uso de produção, confira Como obter um certificado de Autoridade de Certificação 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 em que você deseja criar seus certificados.

  2. Execute o comando a seguir:

    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 fornecida para o nome da entidade (//CN=my-x509-device) só é necessária para escapar a cadeia de caracteres com o Git em plataformas Windows.

  3. Quando receber a solicitação Insira a frase secreta de PEM: , use a frase secreta 1234.

  4. Quando receber a solicitação Verificando – Insira a frase secreta de PEM: , use a frase secreta 1234 novamente.

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

    O arquivo de certificado tem seu CN (nome comum da entidade) definido como my-x509-device. Para registros baseados em X.509, a ID de registro é definida como o nome comum. A ID de registro é uma cadeia de caracteres alfanuméricos que não diferencia maiúsculas de minúsculas e caracteres especiais: '-', '.', '_' e ':'. O último caractere deve ser alfanumérico ou um traço ('-'). O nome comum deve aderir a esse formato. O DPS dá suporte a IDs de registro com até 128 caracteres; no entanto, o comprimento máximo do nome comum da entidade em um certificado X.509 é 64 caracteres. Portanto, a ID de registro é limitada a 64 caracteres ao usar certificados X.509.

  5. O arquivo de certificado é codificado em Base64. Para exibir o CN (nome comum) da entidade e outras propriedades do arquivo de certificado, insira 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 seja criptografada. Execute o seguinte comando para criar uma chave privada não criptografada:

    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ê precisará dele mais tarde neste início rápido.

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

  1. Para gerar o arquivo formatado PKCS12 esperado pelo exemplo, insira 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 solicitado a Inserir a senha de exportação:, use a senha 1234.

  4. Quando solicitado a Verificar – Inserir a senha de exportação:, use a senha 1234 novamente.

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

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

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

Você não precisará do prompt do Git Bash para o resto deste início rápido. No entanto, talvez você queira 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 seja criptografada. Execute o seguinte comando para criar uma chave privada não criptografada:

    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 em que 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 precisará do prompt do Git Bash para o resto deste início rápido. No entanto, talvez você queira 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 no exemplo de provisionamento de dispositivo X.509. O caminho fornecido é relativo ao local em que 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 precisará do prompt do Git Bash para o resto deste início rápido. No entanto, talvez você queira 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 seja criptografada. Execute o seguinte comando para criar uma chave privada não criptografada:

    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ê precisará dele mais tarde neste início rápido.

Criar um registro do dispositivo

O Serviço de Provisionamento de Dispositivos de IoT do Azure dá suporte a dois tipos de registros:

Este artigo demonstra um registro individual de um único dispositivo a ser provisionado com um Hub IoT.

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

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

  3. Selecione a guia Registros individuais e, em seguida, selecione Adicionar registro individual.

    Screenshot that shows the add individual enrollment option.

  4. Na guia 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 do certificado X.509 Carregue um ou dois certificados que serão usados para verificar o dispositivo para esse registro.
    Satus do provisionamento Marque a caixa Habilitar este registro se quiser que esse registro esteja disponível para provisionar seu dispositivo. Desmarque essa caixa se quiser que o registro seja desabilitado. Você poderá alterar essa configuração mais tarde.
    Reprovisionar política Escolha uma política de reprovisionamento que reflita como você deseja que o DPS manipule os dispositivos que solicitam o reprovisionamento. Para obter mais informações, confira Reprovisionar políticas.

  5. Selecione Próximo: 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 dos hubs IoT vinculados ou adicione um novo link a um hub IoT. Para saber mais sobre como vincular hubs IoT à instância do DPS, confira Como vincular e gerenciar hubs IoT.
    Política de alocaçã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, confira Como usar políticas de alocação.

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

  7. Selecione Avançar: 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 provisionados recentemente serão configurados:

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

    Para saber mais, veja Noções básicas e uso de dispositivos gêmeos no Hub IoT.

  9. Selecione Avançar: Revisar + criar.

  10. Na guia Examinar + criar, verifique todos os valores e selecione Criar.

Preparar e executar o código de provisionamento de dispositivos

Nesta seção, você atualiza o código de exemplo para enviar a sequência de inicialização do dispositivo para a instância do Serviço de Provisionamento de Dispositivos. 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ê atualizará o código de exemplo com informações da instância do Serviço de Provisionamento de Dispositivos.

  1. No portal do Azure, selecione a guia Visão Geral do seu serviço de Provisionamento de Dispositivos.

  2. Copie o valor de Escopo da ID.

    Screenshot of the ID scope on Azure portal.

  3. Inicie o Visual Studio e abra o arquivo de solução criado no diretório cmake que você criou 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, acesse Provisioning_Samples > prov_dev_client_sample > Arquivos de Origem e abra prov_dev_client_sample.c.

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

    static const char* id_scope = "0ne00000A0A";

  6. Encontre a definição da função main() no mesmo arquivo. Certifique-se de que a variável hsm_type esteja 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. Salve suas alterações.

  8. Clique com 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 do HSM personalizado

As especificidades de interação com o armazenamento baseado em hardware seguro real variam conforme o 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 Módulo de Segurança de Hardware (HSM).

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

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

  2. Atualize o valor da cadeia de caracteres da constante da cadeia de caracteres COMMON_NAME com 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 da constante CERTIFICATE usando o certificado do dispositivo, device-cert.pem, que você gerou anteriormente.

    A sintaxe do texto do certificado no exemplo precisa seguir o padrão a seguir 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 da 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. Esse comando vai gerar a sintaxe para o valor da constante da cadeia de caracteres CERTIFICATE e gravá-la 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 da constante.

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

    A sintaxe do texto da chave privada precisa seguir o padrão a seguir 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 da 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. Esse comando vai gerar a sintaxe para o valor da constante da cadeia de caracteres PRIVATE_KEY e gravá-la 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 da constante.

  5. Salve suas alterações.

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

    Importante

    Compile o projeto custom_hsm_example antes de compilar o restante da solução na próxima seção.

Execute o exemplo

  1. No menu do Visual Studio, selecione Depurar>Iniciar sem depuração para executar a solução. Se a recompilação do projeto for solicitada, selecione Sim para recompilar o projeto antes da execução.

    A saída a seguir é um exemplo da inicialização bem-sucedida do dispositivo simulado my-x509-device e da conexão dele com o serviço de provisionamento. O dispositivo foi 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ê pode usar o prompt de comando do Windows.

  1. No portal do Azure, selecione a guia Visão Geral do seu serviço de Provisionamento de Dispositivos.

  2. Copie o valor de Escopo da ID.

    Screenshot of the ID scope on Azure portal.

  3. No prompt de comando do Windows, altere para o diretório X509Sample. Esse diretório está localizado no diretório .\azure-iot-sdk-csharp\provisioning\device\samples\Getting Started\X509Sample fora do diretório em que você clonou os exemplos no seu computador.

  4. Insira o comando a seguir para compilar e executar o exemplo de provisionamento de dispositivos X.509 (substitua o valor <IDScope> pelo Escopo da ID que você copiou na seção anterior). O arquivo do certificado tem como padrão ./certificate.pfx e solicita a senha .pfx.

    dotnet run -- -s <IDScope>

    Se desejar transmitir o certificado e a senha como um parâmetro, use o formato a seguir.

    Observação

    Parâmetros adicionais podem ser passados ao executar o aplicativo para alterar o TransportType (-t) e o GlobalDeviceEndpoint (-g).

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

  5. O dispositivo se conectará ao DPS e receberá um Hub IoT. Depois, o dispositivo enviará uma mensagem de telemetria ao 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ê pode usar o prompt de comando do Windows.

  1. No portal do Azure, selecione a guia Visão Geral do seu serviço de Provisionamento de Dispositivos.

  2. Copie o valor de Escopo da ID.

    Screenshot of the ID scope on Azure portal.

  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 em que 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 o DPS. Essas variáveis de ambiente são:

    Nome da variável Descrição
    PROVISIONING_HOST O ponto de extremidade a ser usado para se conectar à instância do DPS. Para este início rápido, use o ponto de extremidade global, global.azure-devices-provisioning.net.
    PROVISIONING_IDSCOPE O escopo da ID da instância do DPS.
    PROVISIONING_REGISTRATION_ID A ID do registro do dispositivo. Ele precisa 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 as variáveis de ambiente para o ponto de extremidade de dispositivo global e o escopo da 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 a ID de registro do dispositivo. A ID de registro do dispositivo IoT precisa corresponder ao nome comum da entidade no respectivo certificado de dispositivo. Se você seguiu as etapas deste início rápido para gerar um certificado de teste autoassinado, my-x509-device será o nome da entidade e a 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ê deverá ver uma saída semelhante ao seguinte exemplo:

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

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

  1. No portal do Azure, selecione a guia Visão Geral do seu serviço de Provisionamento de Dispositivos.

  2. Copie os valores Escopo da ID e Ponto de extremidade de dispositivo global.

    Screenshot of the ID scope and global device endpoint on Azure portal.

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

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

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

    Nome da variável Descrição
    PROVISIONING_HOST O ponto de extremidade global usado para se conectar à instância do DPS.
    PROVISIONING_IDSCOPE O escopo da ID da instância do DPS.
    DPS_X509_REGISTRATION_ID A ID do registro do dispositivo. Ele também precisa corresponder ao nome da entidade no certificado de 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 de dispositivo global e o Escopo da 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. A ID de registro do dispositivo IoT precisa corresponder ao nome da entidade no respectivo certificado de dispositivo. Se você seguiu as etapas deste início rápido para gerar um certificado de teste autoassinado, my-x509-device será o nome da entidade e a 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, o arquivo de chave privada e a frase secreta.

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

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

  8. Execute o exemplo. A amostra se conecta ao DPS, que provisiona o dispositivo a um hub IoT. Depois que o dispositivo for provisionado, o exemplo enviará 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 Dispositivos.

  2. Copie os valores Escopo da ID e Ponto de extremidade de dispositivo global.

    Screenshot of the ID scope and global device endpoint on Azure portal.

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

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

  4. Insira as informações de identidade de X.509 e do serviço de provisionamento no código de exemplo. A informação é usada durante o provisionamento, para comprovação do dispositivo simulado, antes do registro do dispositivo.

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

    2. Atualize os valores a seguir com o Escopo da ID e o Ponto de Extremidade Global do Serviço de Provisionamento 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 valor da leafPublicPemcadeia de caracteres da constante com o valor do certificado, device-cert.pem.

      A sintaxe do texto do certificado precisa seguir o padrão a seguir sem espaços extras nem caracteres.

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

      Atualizar esse valor da 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. Esse comando vai gerar a sintaxe para o valor da constante da cadeia de caracteres leafPublicPem e gravá-la na saída.

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

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

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

      A sintaxe do texto da chave privada precisa seguir o padrão a seguir sem espaços extras nem caracteres.

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

      Atualizar esse valor da 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. Esse comando vai gerar a sintaxe para o valor da constante da cadeia de caracteres leafPrivateKey e gravá-la 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 da constante.

    5. Salve suas alterações.

  5. Compile o exemplo e acesse a pasta target.

    mvn clean install
cd target

  6. A compilação gera o arquivo .jar na pasta target 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

    A amostra se conecta ao DPS, que provisiona o dispositivo a um hub IoT. Depois que o dispositivo for provisionado, o exemplo enviará 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!

Confirmar o registro de provisionamento de dispositivos

Para ver para qual hub IoT seu dispositivo foi provisionado, examine os detalhes do registro individual que você criou anteriormente:

  1. No portal do Azure, acesse o Serviço de Provisionamento de Dispositivos.

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

  3. Selecione Registros Individuais. A entrada do registro X.509 que você criou anteriormente, my-x509-device, deve aparecer na lista.

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

Para verificar o dispositivo no hub IoT:

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

  2. No menu Gerenciamento de dispositivo, selecione Dispositivos.

  3. Se o dispositivo foi provisionado com êxito, a ID do dispositivo, my-x509-device, deve aparecer na lista, com o Status definido como habilitado. Se você não encontrar seu dispositivo, selecione Atualizar.

    Screenshot that shows the device is registered with the IoT hub in Azure portal.

Importante

Se você tiver alterado o estado de dispositivo gêmeo inicial do valor padrão na entrada de registro para o seu dispositivo, pode receber o estado desejado duas do hub e agir de acordo. Para saber mais, veja Noções básicas e uso de dispositivos gêmeos no Hub IoT

Limpar os recursos

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

Excluir o registro do dispositivo

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

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

  3. Selecione o seu Serviço de Provisionamento de Dispositivos.

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

  5. Selecione a guia Registros individuais.

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

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

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 Gerenciadores, selecione Dispositivos IoT.

  4. Marque a caixa de seleção ao lado da ID do dispositivo do dispositivo inscrito neste guia de início rápido.

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

Próximas etapas

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

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