Quickstart: Inscreva o dispositivo individual no Serviço de Provisionamento de Dispositivos IoT Hub utilizando atestado TPM

Este artigo mostra-lhe como criar programáticamente uma inscrição individual para um dispositivo TPM no Serviço de Provisionamento de Dispositivos IoT IoT Azure, utilizando o Microsoft Azure IoT SDK e uma aplicação de amostra. Pode inscrever opcionalmente um dispositivo TPM simulado para o serviço de fornecimento utilizando esta entrada individual de inscrição.

Embora estes passos funcionem em computadores Windows e Linux, este artigo utiliza um Windows computador de desenvolvimento.

Pré-requisitos

Se não tiver uma subscrição do Azure,crie uma conta gratuita antes de começar.

  • Instale Visual Studio 2019.

  • Instale .NET Core 3.1 SDK ou mais tarde ou mais tarde na sua máquina baseada em Windows. Pode utilizar o seguinte comando para verificar a sua versão.

    dotnet --info
    
  • (Opcional) Se pretender inscrever um dispositivo simulado no final deste arranque rápido, siga o procedimento na Criação e provisa um dispositivo TPM simulado até ao passo em que obtém uma chave de endosso para o dispositivo. Guarde a chave de endosso, iD de registo e, opcionalmente, o ID do dispositivo.

  • Transfira e instale o Python 2.x ou 3.x. Certifique-se de que utiliza a instalação de 32 ou 64 bits, conforme exigido pela sua configuração. Quando lhe for pedido durante a instalação, confirme que adiciona Python às variáveis de ambiente específicas da sua plataforma.

  • Instale pip,se não estiver incluído com a sua distribuição de Python.

Importante

Este artigo aplica-se apenas ao V1 Python SDK precedido. Os clientes de dispositivos e serviços do Serviço de Provisionamento de Dispositivos IoT Hub ainda não estão disponíveis em V2. A equipa está neste momento a trabalhar arduamente para trazer a V2 para apresentar paridade.

Nota

Não siga os passos para criar uma inscrição individual utilizando o portal Azure.

Preparar o ambiente de desenvolvimento

Copiar chaves de inscrição simétrica e TPM

Este arranque rápido demonstra tanto as inscrições simétricas como as matrículas de TPM. Terá de criar a sua própria ou utilizar as chaves de teste fornecidas:

Para as inscrições de chaves simétricas simuladas, precisa de uma chave primária e secundária para o seu dispositivo. Se não tiver uma chave simétrica válida, pode utilizar as seguintes teclas de teste para este exemplo:

Chave simétrica primária

UmorGiEVPNIQuaWGXXbe8v9gWayS7XtOZmNMo6DEaEXP65GvhuK3OeRf8RVZ9BymBCHxNg3oRTey0pUHUwwYKQ==

Chave simétrica secundária

Zx8/eE7PUBmnouB1qlNQxI7fcQ2HbJX+y96F1uCVQvDj88jFL+q6L9YWLLi4jqTmkRPOulHlSbSv2uFgj4vKtw==

Preparar o ambiente de desenvolvimento

Configurar as variáveis de ambiente

Para configurar variáveis ambientais:

  1. A variável PATH deve incluir o caminho completo para o diretório jdk1.8.x\bin. Se esta for a primeira instalação de Java do seu computador, crie uma nova variável de ambiente com o nome JAVA_HOME e aponte-a para o caminho completo para o diretório jdk1.8.x. Num computador Windows, este diretório encontra-se na pasta C:\Programas\Java\ e pode criar ou editar variáveis de ambiente, procurando Editar as variáveis de ambiente do sistema no Painel de controlo do seu computador Windows.

    Pode verificar se a Java está configurada com sucesso na sua máquina, executando o seguinte comando na janela de comando:

    java -version
    
  2. Edite a variável ambiente PATH para apontar para a pasta apache-maven-3.x.x \ bin dentro da pasta onde Maven foi extraída. Pode confirmar se o Maven é instalado com êxito ao executar este comando na janela de comando:

    mvn --version
    
  3. Certifique-se de que o git está instalado no computador e é adicionado à variável de ambiente PATH.

Repositório de Clone Git para Azure IoT Java SDK

Para clonar o Azure IoT Java SDK:

  1. Abra uma linha de comandos.

  2. Clone o GitHub repo para a amostra de código de inscrição do dispositivo utilizando o Java Service SDK:

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

Obter a cadeia de ligação para o serviço de aprovisionamento

Para a amostra neste arranque rápido, terá de copiar a cadeia de ligação para o seu serviço de fornecimento.

  1. Inicie sessão no portal do Azure.

  2. No menu à esquerda ou na página do portal, selecione Todos os recursos.

  3. Selecione o seu serviço de provisionamento de dispositivos.

  4. No menu Definições, selecione Políticas de acesso partilhado.

  5. Selecione a política de acesso que pretende utilizar.

  6. No painel 'Política de Acesso', copie e guarde a cadeia de ligação da chave primária.

    Obtenha o fio de ligação de serviço de fornecimento do portal.

Criar o exemplo de inscrição individual

Esta secção mostra-lhe como criar uma aplicação de consola .NET Core que adiciona uma inscrição individual para um dispositivo TPM ao seu serviço de fornecimento. Com algumas modificações, também pode seguir estes passos para criar uma aplicação de consola Windows IoT Core para adicionar à inscrição individual. Para saber mais sobre o desenvolvimento com o IoT Core, consulte Windows documentação do desenvolvedor do IoT Core.

  1. Abra Visual Studio e selecione Criar um novo projeto.

  2. No Criar um novo painel de projeto, selecione *Aplicação da consola.

  3. Selecione Seguinte.

  4. Para Project nome, escreva CreateEnrollmentGroup.

  5. Selecione Seguinte. Mantenha o quadro-alvo predefinido.

  6. Selecione Criar.

  7. Depois de a solução abrir, no painel Solution Explorer, clique com a direita no projeto CreateEnrollmentGroup e, em seguida, selecione Gerir pacotes NuGet.

  8. Em NuGet Gestor de Pacotes, selecione Procurar.

  9. Digite e selecione Microsoft.Azure.Devices.Provisioning.Service.

  10. Selecione Instalar.

    Janela Gestor de Pacote NuGet

    Este passo descarrega, instala e adiciona uma referência ao pacote SDK NuGet do Serviço de Provisionamento Azure IoT e suas dependências.

  11. Adicione as using seguintes declarações após as outras using declarações no topo Program.cs de:

    using System.Threading.Tasks;
    using Microsoft.Azure.Devices.Provisioning.Service;
    
  12. Adicione os seguintes campos à Program classe e faça as alterações listadas.

    private static string ProvisioningConnectionString = "{ProvisioningServiceConnectionString}";
    private const string RegistrationId = "sample-registrationid-csharp";
    private const string TpmEndorsementKey =
        "AToAAQALAAMAsgAgg3GXZ0SEs/gakMyNRqXXJP1S124GUgtk8qHaGzMUaaoABgCAAEMAEAgAAAAAAAEAxsj2gUS" +
        "cTk1UjuioeTlfGYZrrimExB+bScH75adUMRIi2UOMxG1kw4y+9RW/IVoMl4e620VxZad0ARX2gUqVjYO7KPVt3d" +
        "yKhZS3dkcvfBisBhP1XH9B33VqHG9SHnbnQXdBUaCgKAfxome8UmBKfe+naTsE5fkvjb/do3/dD6l4sGBwFCnKR" +
        "dln4XpM03zLpoHFao8zOwt8l/uP3qUIxmCYv9A7m69Ms+5/pCkTu/rK4mRDsfhZ0QLfbzVI6zQFOKF/rwsfBtFe" +
        "WlWtcuJMKlXdD8TXWElTzgh7JS4qhFzreL0c1mI0GCj+Aws0usZh7dLIVPnlgZcBhgy1SSDQMQ==";
    
    // Optional parameters
    private const string OptionalDeviceId = "myCSharpDevice";
    private const ProvisioningStatus OptionalProvisioningStatus = ProvisioningStatus.Enabled;
    
  13. Substitua o ProvisioningServiceConnectionString valor do espaço reservado pela cadeia de ligação do serviço de fornecimento que copiou na secção anterior.

  14. Se estiver a utilizar este quickstart juntamente com o Create e providenciar um dispositivo TPM simulado para obter um dispositivo simulado, substitua a chave de endosso e o ID de registo pelos valores que observou nesse arranque rápido. Pode substituir o ID do dispositivo pelo valor sugerido nesse arranque rápido, utilizar o seu próprio valor ou utilizar o valor predefinido nesta amostra.

  15. Adicione o seguinte método à Program classe. Este código cria a entrada individual de inscrição e, em seguida, chama o CreateOrUpdateIndividualEnrollmentAsync método para adicionar a ProvisioningServiceClient inscrição individual ao serviço de fornecimento.

    public static async Task RunSample()
    {
        Console.WriteLine("Starting sample...");
    
        using (ProvisioningServiceClient provisioningServiceClient =
                ProvisioningServiceClient.CreateFromConnectionString(ProvisioningConnectionString))
        {
            #region Create a new individualEnrollment config
            Console.WriteLine("\nCreating a new individualEnrollment...");
            Attestation attestation = new TpmAttestation(TpmEndorsementKey);
            IndividualEnrollment individualEnrollment =
                    new IndividualEnrollment(
                            RegistrationId,
                            attestation);
    
            // The following parameters are optional. Remove them if you don't need them.
            individualEnrollment.DeviceId = OptionalDeviceId;
            individualEnrollment.ProvisioningStatus = OptionalProvisioningStatus;
            #endregion
    
            #region Create the individualEnrollment
            Console.WriteLine("\nAdding new individualEnrollment...");
            IndividualEnrollment individualEnrollmentResult =
                await provisioningServiceClient.CreateOrUpdateIndividualEnrollmentAsync(individualEnrollment).ConfigureAwait(false);
            Console.WriteLine("\nIndividualEnrollment created with success.");
            Console.WriteLine(individualEnrollmentResult);
            #endregion
    
        }
    }
    
  16. Por último, substitua o Main método pelas seguintes linhas:

    static async Task Main(string[] args)
    {
        await RunSample();
        Console.WriteLine("\nHit <Enter> to exit ...");
        Console.ReadLine();
    }
    
  17. Compilar a solução.

  1. A partir de uma janela de comando na sua pasta de trabalho, execute:

    npm install azure-iot-provisioning-service
    
  2. Com um editor de texto, crie um ficheiro create_individual_enrollment.js na sua pasta de trabalho. Adicione o seguinte código ao ficheiro:

    'use strict';
    
    var provisioningServiceClient = require('azure-iot-provisioning-service').ProvisioningServiceClient;
    
    var serviceClient = provisioningServiceClient.fromConnectionString(process.argv[2]);
    var endorsementKey = process.argv[3];
    
    var enrollment = {
      registrationId: 'first',
      attestation: {
        type: 'tpm',
        tpm: {
          endorsementKey: endorsementKey
        }
      }
    };
    
    serviceClient.createOrUpdateIndividualEnrollment(enrollment, function(err, enrollmentResponse) {
      if (err) {
        console.log('error creating the individual enrollment: ' + err);
      } else {
        console.log("enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
      }
    });
    
  3. Guarde o ficheiro.

  1. Utilizando um editor de texto, crie um novo ficheiro Enrollment.py.

  2. Adicione as import seguintes declarações e variáveis no início do ficheiro Enrollment.py (substituído pela cadeia {dpsConnectionString} de ligação que copiou anteriormente, o titular do certificado com o certificado criado nas teclas de inscrição de Copy simétrica e TPM, e {registrationid} por um exclusivo que consiste registrationid apenas em alfanuméricos e hífenes de caixa inferior):

    from provisioningserviceclient import ProvisioningServiceClient
    from provisioningserviceclient.models import IndividualEnrollment, AttestationMechanism
    from provisioningserviceclient.protocol.models import SymmetricKeyAttestation
    
    CONNECTION_STRING = "Enter your DPS connection string"
    PRIMARY_KEY = "Add a valid key"
    SECONDARY_KEY = "Add a valid key"
    REGISTRATION_ID = "Enter a registration ID"
    
  3. Adicione o seguinte código Python para implementar a criação da inscrição individual:

    def main():
        print ( "Starting individual enrollment..." )
    
        psc = ProvisioningServiceClient.create_from_connection_string(CONNECTION_STRING)
    
        symAtt = SymmetricKeyAttestation(primary_key=PRIMARY_KEY, secondary_key=SECONDARY_KEY)
        att = AttestationMechanism(type="symmetricKey", symmetric_key=symAtt)
        ie = IndividualEnrollment.create(REGISTRATION_ID, att)
    
        ie = psc.create_or_update(ie)
    
        print ( "Individual enrollment successful." )
    
    if __name__ == '__main__':
        main()
    
  4. Guarde e feche o ficheiro Enrollment.py.

  1. No código fonte transferido, navegue até à pasta de exemplo azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-sample. Abra o ficheiro /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentSample.java.

  2. [Provisioning Connection String]Substitua-a pela cadeia de ligação que copiou em Obter a cadeia de ligação para o seu serviço de provisionamento.

    private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";
    
    1. Adicione os detalhes do dispositivo TPM:
      1. Obtenha o ID de Registo e a chave de endossamento de TPM para uma simulação de dispositivo TPM, seguindo os passos que levam à secção Simular dispositivo TPM.

      2. Utilize o ID de Registo e a Chave de endossamento da saída do passo anterior, para substituir o [RegistrationId] e [TPM Endorsement Key] no ficheiro de código de exemplo ServiceEnrollmentSample.java:

        private static final String REGISTRATION_ID = "[RegistrationId]";
        private static final String TPM_ENDORSEMENT_KEY = "[TPM Endorsement Key]";
        
  3. Para configurar o seu serviço de fornecimento a partir do código de amostra, proceda ao passo seguinte. Se não quiser configurá-lo, certifique-se de comentar ou apagar as seguintes declarações no ficheiro ServiceEnrollmentSample.java:

    / / The following parameters are optional. Remove it if you don't need.
    individualEnrollment.setDeviceId(DEVICE_ID);
    individualEnrollment.setIotHubHostName(IOTHUB_HOST_NAME);
    individualEnrollment.setProvisioningStatus(PROVISIONING_STATUS);
    
  4. Este passo mostra-lhe como configurar o seu serviço de fornecimento no código de amostra.

    1. Aceda ao Portal do Azure.

    2. No menu à esquerda ou na página do portal, selecione Todos os recursos.

    3. Selecione o seu serviço de provisionamento de dispositivos.

    4. No painel 'Visão Geral', copie o nome de anfitrião do ponto final de Serviço. Na amostra de código fonte, [Host name] substitua-a pelo nome de hospedeiro copiado.

    private static final String IOTHUB_HOST_NAME = "[Host name].azure-devices.net";
    
  5. Estude o código de exemplo. Esta cria, atualiza, consulta e elimina uma inscrição de dispositivo TPM individual. Para verificar a inscrição com êxito no portal, comente temporariamente as seguintes linhas de código no final do ficheiro ServiceEnrollmentSample.java:

    // *********************************** Delete info of individualEnrollment ************************************
    System.out.println("\nDelete the individualEnrollment...");
    provisioningServiceClient.deleteIndividualEnrollment(REGISTRATION_ID);
    
  6. Guarde o ficheiro ServiceEnrollmentSample.java.

Executar o exemplo de inscrição individual

  1. Executar a amostra em Visual Studio para criar a inscrição. Aparecerá uma janela de comando e apresentará mensagens de confirmação.

  2. Após a criação bem sucedida, a janela de comando exibe as propriedades da nova inscrição.

Para executar a amostra, você precisará da cadeia de ligação para o seu serviço de fornecimento que copiou na secção anterior, bem como a chave de endosso para o dispositivo. Se seguiu o Create e forte um dispositivo simulado de arranque rápido para criar um dispositivo TPM simulado, utilize a chave criada para esse dispositivo. Caso contrário, para criar uma amostra de inscrição individual, pode utilizar a seguinte chave de endosso fornecida com o serviço deNode.js SDK:

AToAAQALAAMAsgAgg3GXZ0SEs/gakMyNRqXXJP1S124GUgtk8qHaGzMUaaoABgCAAEMAEAgAAAAAAAEAxsj2gUScTk1UjuioeTlfGYZrrimExB+bScH75adUMRIi2UOMxG1kw4y+9RW/IVoMl4e620VxZad0ARX2gUqVjYO7KPVt3dyKhZS3dkcvfBisBhP1XH9B33VqHG9SHnbnQXdBUaCgKAfxome8UmBKfe+naTsE5fkvjb/do3/dD6l4sGBwFCnKRdln4XpM03zLpoHFao8zOwt8l/uP3qUIxmCYv9A7m69Ms+5/pCkTu/rK4mRDsfhZ0QLfbzVI6zQFOKF/rwsfBtFeWlWtcuJMKlXdD8TXWElTzgh7JS4qhFzreL0c1mI0GCj+Aws0usZh7dLIVPnlgZcBhgy1SSDQMQ==
  1. Para criar uma inscrição individual para o seu dispositivo TPM, execute o seguinte comando (inclua as aspas à volta dos argumentos do comando):

    node create_individual_enrollment.js "<the connection string for your provisioning service>" "<endorsement key>"
    
  2. Após a criação bem sucedida, a janela de comando exibe as propriedades da nova inscrição.

  1. Abra um pedido de comando e execute o seguinte script.

    python Enrollment.py
    
  2. Após a criação bem sucedida, a janela de comando exibe as propriedades da nova inscrição.

  1. Abra uma janela de comando no modo administrador e vá para a pasta azure-iot-sdk-java/provisioning/provisioning-samples/service-registration-group-sample.

  2. Na solicitação de comando, utilize este comando:

    mvn install -DskipTests
    

    Este comando descarrega o pacote Maven com.microsoft.azure.sdk.iot.provisioning.service para a sua máquina. Este pacote inclui os binários para o SDK do serviço Java, que o código de exemplo precisa de compilar. Se tiver executado a ferramenta X.509 certificate generator na secção anterior, este pacote já estará transferido no seu computador.

  3. Na solicitação de comando, execute o guião:

    cd target
    java -jar ./service-enrollment-group-sample-{version}-with-deps.jar
    
  4. Após a criação bem sucedida, a janela de comando exibe as propriedades da nova inscrição.

Para verificar se o grupo de inscrições foi criado:

  1. No portal Azure, selecione o seu Serviço de Provisionamento de Dispositivos.

  2. No menu Definições, selecione Gerir as inscrições.

  3. Selecione Inscrições Individuais. Deverá ver uma nova inscrição que corresponda ao ID de inscrição que utilizou na amostra.

Verifique a inscrição para o dispositivo individual C# no portal.

Verifique a inscrição para Node.js dispositivo individual no portal.

Verifique a inscrição para dispositivo individual Python no portal.

Verifique a inscrição para dispositivo individual java no portal.

Limpar os recursos

Se planeia explorar os tutoriais do Serviço de Fornecimento de Dispositivos Azure IoT Hub,não limpe os recursos criados neste arranque rápido. Caso contrário, utilize os seguintes passos para eliminar todos os recursos criados por este arranque rápido.

  1. Feche a janela de saída da amostra no seu computador.

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

  3. Selecione o seu serviço de provisionamento de dispositivos.

  4. No menu Definições, selecione Gerir as inscrições.

  5. Selecione o separador Inscrições Individuais.

  6. Selecione a caixa de verificação ao lado do ID de registo do dispositivo que inscreveu neste arranque rápido.

  7. No topo da página, selecione Delete.

  8. A partir do seu Serviço de Provisionamento de Dispositivos no portal Azure, selecione Certificados.

  9. Selecione o certificado que carregou para este arranque rápido.

  10. No topo dos Detalhes do Certificado, selecione Delete.

  11. Se seguiu os passos na Criação e providenciar um dispositivo TPM simulado para criar um dispositivo TPM simulado, faça os seguintes passos:

    1. Feche a janela do simulador TPM e a janela de saída de exemplo para o dispositivo simulado.

    2. No portal do Azure, navegue para o Hub IoT onde o seu dispositivo foi aprovisionado.

    3. No menu em Explorers, selecione dispositivos IoT.

    4. Selecione a caixa de verificação ao lado do ID do dispositivo que registou neste arranque rápido.

    5. Na parte superior do painel, selecione Delete.

Passos seguintes

Neste arranque rápido, criou programáticamente uma entrada individual de inscrição para um dispositivo TPM. Opcionalmente, criou um dispositivo simulado TPM no seu computador e forte-o para o seu hub IoT utilizando o Serviço de Provisionamento de Dispositivos Azure IoT Hub. Para ficar a conhecer aprofundadamente o aprovisionamento de dispositivos, prossiga no tutorial para a configuração do Serviço Aprovisionamento de Dispositivos no portal do Azure.

Azure IoT Hub Device Provisioning Service tutorials (Tutoriais do Serviço Aprovisionamento de Dispositivos no Hub IoT do Azure)