Criar programaticamente um registro individual do Serviço de Provisionamento de Dispositivos para atestado do TPM

  • Artigo

Este artigo mostra como criar de modo programático um registro individual para um dispositivo TPM no Serviço de Provisionamento de Dispositivos no Hub IoT do Azure usando o SDK do serviço de DPS no Azure IoT Hub e um aplicativo de exemplo. Depois de criar o registro individual, você pode, opcionalmente, inscrever um dispositivo TPM simulado no serviço de provisionamento por meio dessa entrada de registro.

Embora essas etapas funcionem em computadores Windows e Linux, este artigo usa um computador de desenvolvimento do Windows.

Pré-requisitos

  • 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

  • (Opcional) Caso deseje registrar um dispositivo simulado ao final deste artigo, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso para o dispositivo. Salve a chave Endosso, como você usá-lo mais adiante neste artigo.

    Observação

    Não siga as etapas para criar um registro individual usando o portal do Azure.

  • Instale o Node.js v4.0+.

  • (Opcional) Caso deseje registrar um dispositivo simulado ao final deste guia de início rápido, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso e ID de registro para o dispositivo. Salve a chave de endosso e a ID de registro, conforme você usá-las posteriormente neste artigo.

    Observação

    Não siga as etapas para criar um registro individual usando o portal do Azure.

  • Instale o Java SE Development Kit 8. Este artigo instala o Java Service SDK posteriormente no artigo. Ele funciona no Windows e no Linux. Este artigo usa Windows.

  • Instale o Maven 3.

  • Instale o Git e certifique-se de que o caminho é adicionado à variável PATHde ambiente .

  • (Opcional) Caso deseje registrar um dispositivo simulado ao final deste artigo, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso para o dispositivo. Observe a chave de endosso e a ID de registro, conforme você as usa posteriormente neste artigo.

    Observação

    Não siga as etapas para criar um registro individual usando o portal do Azure.

Obter a chave de endosso do TPM (opcional)

Você pode seguir as etapas neste artigo para criar um registro individual de exemplo. Nesse caso, você poderá exibir a entrada de registro no DPS, mas não poderá usá-la para provisionar um dispositivo.

As etapas neste artigo também podem ser seguidas para criar um registro individual e registrar um dispositivo TPM simulado. Caso deseje registrar um dispositivo simulado ao final deste artigo, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso para o dispositivo. Salve a chave Endosso, como você usá-lo mais adiante neste artigo.

Observação

Não siga as etapas para criar um registro individual usando o portal do Azure.

As etapas neste artigo também podem ser seguidas para criar um registro individual e registrar um dispositivo TPM simulado. Caso deseje registrar um dispositivo simulado ao final deste guia de início rápido, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso e ID de registro para o dispositivo. Salve a chave de endosso e a ID de registro, conforme você usá-las posteriormente neste artigo.

Observação

Não siga as etapas para criar um registro individual usando o portal do Azure.

As etapas neste artigo também podem ser seguidas para criar um registro individual e registrar um dispositivo TPM simulado. Caso deseje registrar um dispositivo simulado ao final deste artigo, siga o procedimento descrito em Criar e provisionar um dispositivo TPM simulado até a etapa em que você obtém uma chave de endosso para o dispositivo. Observe a chave de endosso e a ID de registro, conforme você as usa posteriormente neste artigo.

Observação

Não siga as etapas para criar um registro individual usando o portal do Azure.

Obter a cadeia de conexão do serviço de provisionamento

Para o exemplo neste artigo, você precisará copiar a cadeia de conexão do serviço de provisionamento.

  1. Entre 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 Configurações, selecione Políticas de acesso compartilhado.

  5. Selecione a política de acesso que você deseja usar.

  6. No painel Política de Acesso, copie e salve a cadeia de conexão da chave primária.

    Get provisioning service connection string from the portal.

Criar o exemplo de registro individual

Esta seção mostra como criar um aplicativo de console .NET Core que adiciona um registro individual de um dispositivo TPM ao serviço de provisionamento.

  1. Abra o prompt de comando do Windows e acesse a pasta na qual o aplicativo será criado.

  2. Para criar um projeto de console, execute o comando a seguir:

    dotnet new console --framework net6.0 --use-program-main

  3. Para adicionar uma referência ao SDK do serviço de DPS, execute o seguinte comando:

    dotnet add package Microsoft.Azure.Devices.Provisioning.Service

    Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do cliente do serviço DPS em IoT do Azure e suas dependências. Esse pacote inclui os binários do SDK do serviço .NET.

  4. Abra o arquivo Program.cs em um editor.

  5. Substitua as instruções de namespace na parte superior do arquivo pelo seguinte:

    namespace CreateIndividualEnrollment;

  6. Adicione as instruções using a seguir à parte superior do arquivo acima da instrução namespace:

    using System.Threading.Tasks;
using Microsoft.Azure.Devices.Provisioning.Service;

  7. Adicione os campos a seguir à classe Program 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;

    • Substitua o valor de espaço reservado ProvisioningServiceConnectionString pela cadeia de conexão do serviço de provisionamento que você copiou na seção anterior.

    • Caso esteja usando este artigo junto com o guia de início rápido Criar e provisionar um dispositivo TPM simulado para provisionar um dispositivo simulado, substitua a chave de endosso pelo valor que você anotou no guia de início rápido anterior. É possível substituir a identidade do dispositivo e a identidade do registro pelos valores sugeridos nesse início rápido. Para isso, use seus próprios valores ou os valores padrão nesta amostra.

  8. Adicione o método a seguir à classe Program. Esse código cria uma entrada de registro individual e, em seguida, chama o método CreateOrUpdateIndividualEnrollmentAsync no ProvisioningServiceClient para adicionar o registro individual ao serviço de provisionamento.

    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 object...");
        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 the individualEnrollment to the provisioning service...");
        IndividualEnrollment individualEnrollmentResult =
            await provisioningServiceClient.CreateOrUpdateIndividualEnrollmentAsync(individualEnrollment).ConfigureAwait(false);
        Console.WriteLine("\nIndividualEnrollment created with success.");
        Console.WriteLine(individualEnrollmentResult);
        #endregion

    }
}

  9. Por fim, substitua o método Main pelas seguintes linhas:

    static async Task Main(string[] args)
{
    await RunSample();
    Console.WriteLine("\nHit <Enter> to exit ...");
    Console.ReadLine();
}

  10. Salve suas alterações.

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

    npm install azure-iot-provisioning-service

    Esta etapa baixa, instala e adiciona uma referência ao pacote do cliente do serviço DPS em IoT do Azure e suas dependências. Esse pacote inclui os binários do SDK do serviço Node.js.

  2. Usando um editor de texto, crie um arquivo create_individual_enrollment.js em sua pasta de trabalho. Adicione o seguinte código ao arquivo :

    '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. Salve o arquivo.

  1. Abra um prompt de comando do Windows.

  2. Clone o repositório GitHub de SDKs da Internet das Coisas do Microsoft Azure para Java:

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

  3. Acesse a pasta da amostra:

    cd azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-sample

  4. Abra o arquivo \src\main\java\samples\com\microsoft\azure\sdk\iot\ServiceEnrollmentSample.java em um editor.

  5. Substitua [Provisioning Connection String] pela cadeia de conexão que você copiou em Obter a cadeia de conexão do serviço de provisionamento.

    private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";

  6. Adicione os detalhes do dispositivo TPM. Substitua as instruções [RegistrationId] e [TPM Endorsement Key] a seguir pela chave de endosso e pela ID de registro.

    private static final String REGISTRATION_ID = "[RegistrationId]";
private static final String TPM_ENDORSEMENT_KEY = "[TPM Endorsement Key]";

    • Caso esteja usando este artigo junto com o guia de início rápido Criar e provisionar um dispositivo TPM simulado para provisionar um dispositivo simulado, use os valores da ID de registro e sa Chave de endosso que você anotou no guia de início rápido anterior.

    • Se você estiver usando este artigo apenas para criar um registro individual de exemplo e não pretende usá-lo para registrar um dispositivo, o seguinte valor poderá ser usado para uma chave de endosso:

      private static final String TPM_ENDORSEMENT_KEY = "AToAAQALAAMAsgAgg3GXZ0SEs/gakMyNRqXXJP1S124GUgtk8qHaGzMUaaoABgCAAEMAEAgAAAAAAAEAxsj2gUScTk1UjuioeTlfGYZrrimExB+bScH75adUMRIi2UOMxG1kw4y+9RW/IVoMl4e620VxZad0ARX2gUqVjYO7KPVt3dyKhZS3dkcvfBisBhP1XH9B33VqHG9SHnbnQXdBUaCgKAfxome8UmBKfe+naTsE5fkvjb/do3/dD6l4sGBwFCnKRdln4XpM03zLpoHFao8zOwt8l/uP3qUIxmCYv9A7m69Ms+5/pCkTu/rK4mRDsfhZ0QLfbzVI6zQFOKF/rwsfBtFeWlWtcuJMKlXdD8TXWElTzgh7JS4qhFzreL0c1mI0GCj+Aws0usZh7dLIVPnefZcBhgy1SSDQMQ==";

      Insira seu próprio valor para a identificação de registro, por exemplo, "myJavaDevice".

  7. Para registros individuais, você pode optar por definir uma ID de dispositivo que o DPS atribui ao dispositivo quando o provisiona para o Hub IoT. Se você não atribuir uma ID de dispositivo, o DPS usará a ID de registro como a ID de dispositivo. Por padrão, este exemplo atribui "myJavaDevice" como a identificação do dispositivo. Se você quiser alterar a identificação do dispositivo, modifique a seguinte instrução:

        private static final String DEVICE_ID = "myJavaDevice";

    Se você não quiser atribuir uma identificação do dispositivo específica, comente a seguinte instrução:

    individualEnrollment.setDeviceId(DEVICE_ID);

  8. O exemplo permite que você defina um hub IoT no registro individual para o qual o dispositivo será provisionado. Esse hub IoT deve ser um que tenha sido vinculado anteriormente ao serviço de provisionamento. Para este artigo, permitimos que o DPS escolha entre os hubs vinculados de acordo com a política de alocação padrão, distribuição ponderada uniformemente. Comente a seguinte instrução no arquivo:

    individualEnrollment.setIotHubHostName(IOTHUB_HOST_NAME);

  9. A amostra cria, atualiza, consulta e exclui um registro de dispositivo TPM individual. Para verificar o registro bem-sucedido no portal, comente temporariamente as seguintes linhas de código no fim do arquivo:

    // *********************************** Delete info of individualEnrollment ************************************
System.out.println("\nDelete the individualEnrollment...");
provisioningServiceClient.deleteIndividualEnrollment(REGISTRATION_ID);

  10. Salve suas alterações.

Executar o exemplo de registro individual

  1. Execute o exemplo:

    dotnet run

  2. Após uma criação bem-sucedida, a janela de comandos exibirá as propriedades do novo registro.

Para executar o exemplo, você precisa da cadeia de conexão para o serviço de provisionamento que você copiou na seção anterior e da chave de endosso para o dispositivo. Se você seguiu o guia de início rápido Criar e provisionar um dispositivo simulado para criar um dispositivo TPM simulado, use a chave de endosso criada para esse dispositivo. Caso contrário, para criar um registro individual de exemplo, use a seguinte chave de endosso fornecida com o SDK do Serviço Node.js:

AToAAQALAAMAsgAgg3GXZ0SEs/gakMyNRqXXJP1S124GUgtk8qHaGzMUaaoABgCAAEMAEAgAAAAAAAEAxsj2gUScTk1UjuioeTlfGYZrrimExB+bScH75adUMRIi2UOMxG1kw4y+9RW/IVoMl4e620VxZad0ARX2gUqVjYO7KPVt3dyKhZS3dkcvfBisBhP1XH9B33VqHG9SHnbnQXdBUaCgKAfxome8UmBKfe+naTsE5fkvjb/do3/dD6l4sGBwFCnKRdln4XpM03zLpoHFao8zOwt8l/uP3qUIxmCYv9A7m69Ms+5/pCkTu/rK4mRDsfhZ0QLfbzVI6zQFOKF/rwsfBtFeWlWtcuJMKlXdD8TXWElTzgh7JS4qhFzreL0c1mI0GCj+Aws0usZh7dLIVPnlgZcBhgy1SSDQMQ==

  1. Para criar um registro individual para seu dispositivo TPM, execute o seguinte comando (inclua aspas nos argumentos do comando):

    node create_individual_enrollment.js "<the connection string for your provisioning service>" "<endorsement key>"

  2. Após uma criação bem-sucedida, a janela de comandos exibirá as propriedades do novo registro.

  1. Na pasta azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-sample no prompt de comando, execute o seguinte comando para criar o exemplo:

    mvn install -DskipTests

    Esse comando baixa o pacote Maven do cliente do serviço DPS em IoT do Azure para seu computador e compila o exemplo. Esse pacote inclui os binários do SDK do serviço Java.

  2. Alterne para a pasta de destino e execute o exemplo. A compilação na etapa anterior gera .jar arquivo na pasta de destino com o seguinte formato de arquivo: ; por exemplo: service-enrollment-sample-1.8.1-with-deps.jarservice-enrollment-sample-{version}-with-deps.jar. Talvez seja necessário substituir a versão no comando a seguir.

    cd target
java -jar ./service-enrollment-sample-1.8.1-with-deps.jar

  3. Após uma criação bem-sucedida, a janela de comandos exibirá as propriedades do novo registro.

Para verificar se a inscrição individual foi criada:

  1. No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivo.

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

  3. Selecione a guia Inscrições individuais. Você verá uma nova entrada de registro que corresponde à ID de registro usada no exemplo.

Screenshot that shows verifying enrollment for a C# individual device in the portal.

Screenshot that shows verifying enrollment for a Node.js individual device in the portal.

Screenshot that shows verifying enrollment for a Java individual device in the portal.

Registrar um dispositivo simulado (opcional)

Se você estiver seguindo as etapas no início rápido Criar e provisionar um dispositivo simulado do TPM para provisionar um dispositivo simulado, retome o início rápido em Registrar o dispositivo.

Se você estiver seguindo as etapas no início rápido Criar e provisionar um dispositivo simulado do TPM para provisionar um dispositivo simulado, retome o início rápido em Registrar o dispositivo.

Se você estiver seguindo as etapas no início rápido Criar e provisionar um dispositivo simulado do TPM para provisionar um dispositivo simulado, retome o início rápido em Registrar o dispositivo.

Limpar os recursos

Se pretende explorar os tutoriais do DPS, não limpe os recursos criados neste artigo. Caso contrário, use as seguintes etapas para excluir todos os recursos criados por este artigo.

  1. No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivo.

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

  3. Selecione a guia Registros individuais.

  4. Marque a caixa de seleção ao lado da ID de registro da entrada de registro criada neste artigo.

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

  1. Caso tenha seguido as etapas de Criar e provisionar um dispositivo TPM simulado para criar um dispositivo TPM simulado, execute as seguintes etapas:

    1. No portal do Azure, navegue até o Hub IoT em que o dispositivo foi provisionado.

    2. No menu à esquerda, em Gerenciamento de dispositivos, selecione Dispositivos.

    3. Marque a caixa de seleção ao lado da ID do dispositivo do dispositivo registrado neste artigo.

    4. Na parte superior do painel, selecione Excluir.

  1. Caso tenha seguido as etapas de Criar e provisionar um dispositivo TPM simulado para criar um dispositivo TPM simulado, execute as seguintes etapas:

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

    2. No portal do Azure, navegue até o Hub IoT em que o dispositivo foi provisionado.

    3. No menu à esquerda, em Gerenciamento de dispositivos, selecione Dispositivos.

    4. Marque a caixa de seleção ao lado da ID do dispositivo que você registrou neste artigo.

    5. Na parte superior do painel, selecione Excluir.

  1. Caso tenha seguido as etapas de Criar e provisionar um dispositivo TPM simulado para criar um dispositivo TPM simulado, execute as seguintes etapas:

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

    2. No portal do Azure, navegue até o Hub IoT em que o dispositivo foi provisionado.

    3. No menu à esquerda, em Gerenciamento de dispositivos, selecione Dispositivos.

    4. Marque a caixa de seleção ao lado da ID do dispositivo que você registrou neste artigo.

    5. Na parte superior do painel, selecione Excluir.

Próximas etapas

Neste artigo, você criou de forma programática uma entrada de registro individual para um dispositivo TPM. Opcionalmente, você criou um dispositivo simulado TPM no computador e o provisionou no hub IoT usando o Serviço de Provisionamento de Dispositivos no Hub IoT do Azure. Para explorar mais, confira os links a seguir: