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

Artigo
10/25/2024

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

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.
Conclua as etapas em Configurar o Serviço de Provisionamento de Dispositivos no Hub IoT com o portal do Azure.

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 de endosso, conforme você a utiliza 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, pois você as usará mais adiante 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 SDK do Serviço Java 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 tenha sido adicionado à variável de ambiente PATH.
(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. Anote a Chave de endosso e a ID de registro, pois você as usará 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 de endosso, pois você a usará 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, pois você as usará 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 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. Anote a Chave de endosso e a ID de registro, pois você as usará 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.

Entre no portal do Azure.
No menu à esquerda ou na página do portal, selecione Todos os recursos.
Selecione o seu Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Políticas de acesso compartilhado.
Selecione a política de acesso que você deseja usar.
No painel Política de Acesso, copie e salve a cadeia de conexão da chave primária.

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.

Abra o prompt de comando do Windows e acesse a pasta na qual o aplicativo será criado.
Para criar um projeto de console, execute o comando a seguir:
```
dotnet new console --framework net6.0 --use-program-main 
```
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.
Abra o arquivo Program.cs em um editor.
Substitua as instruções de namespace na parte superior do arquivo pelo seguinte:
```
namespace CreateIndividualEnrollment;
```
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;
```

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.

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

    }
}

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();
}

Salve suas alterações.

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.

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));
  }
});

Salve o arquivo.

Abra um prompt de comando do Windows.
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
```

Acesse a pasta da amostra:

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

Abra o arquivo \src\main\java\samples\com\microsoft\azure\sdk\iot\ServiceEnrollmentSample.java em um editor.
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]";
```
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".
Para registros individuais, você pode optar por definir uma ID de dispositivo que o DPS atribui ao dispositivo quando ele o provisiona no Hub IoT. Se você não atribuir uma ID do dispositivo, o DPS usará a ID de registro como a ID do 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);
```
O exemplo permite que você defina um hub IoT no registro individual para o qual o dispositivo será provisionado. Este 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 com distribuição uniformemente ponderada. Comente a seguinte instrução no arquivo:
```
individualEnrollment.setIotHubHostName(IOTHUB_HOST_NAME);
```

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);

Salve suas alterações.

Executar o exemplo de registro individual

Execute o exemplo:
```
dotnet run
```
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 copiado 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==

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>"
```
Após uma criação bem-sucedida, a janela de comandos exibirá as propriedades do novo registro.

Na pasta azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-sample no prompt de comando, execute o seguinte comando para compilar 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.
Alterne para a pasta de destino e execute o exemplo. A compilação na etapa anterior gera o arquivo .jar na pasta de destino com o seguinte formato de arquivo: service-enrollment-sample-{version}-with-deps.jar; por exemplo, service-enrollment-sample-1.8.1-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
```
Após uma criação bem-sucedida, a janela de comandos exibirá as propriedades do novo registro.

Para verificar se o registro individual foi criado:

No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Gerenciar registros.
Selecione a guia Registros individuais. Você deverá ver uma nova entrada de registro que corresponde à ID de registro usada no exemplo.

Captura de tela que mostra a verificação do registro de um dispositivo individual em C# no portal.

Captura de tela que mostra a verificação do registro de um dispositivo individual Node.js no portal.

Captura de tela que mostra a verificação do registro de um dispositivo individual Java no 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.

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.

No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Gerenciar registros.
Selecione a guia Registros individuais.
Marque a caixa de seleção ao lado da ID de registro da entrada de registro que você criou neste artigo.
Na parte superior da página, selecione Excluir.

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.

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.

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:

Para obter mais informações sobre o atestado do TPM com o DPS, consulte atestado do TPM.
Para obter um exemplo de ponta a ponta de um provisionamento de um dispositivo por meio de um registro individual usando o atestado do TPM, consulte o guia de início rápido Provisionar um dispositivo simulado do TPM.
Para saber mais sobre como gerenciar registros individuais e grupos de registro usando portal do Azure, consulte Como gerenciar registros de dispositivo com o portal do Azure.

Compartilhar via

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

Pré-requisitos

Obter a chave de endosso do TPM (opcional)

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

Criar o exemplo de registro individual

Executar o exemplo de registro individual

Registrar um dispositivo simulado (opcional)

Limpar os recursos

Próximas etapas

Comentários

Recursos adicionais