Criar certificados de demonstração para testar recursos do dispositivo do IoT Edge

Artigo
06/03/2024

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Os dispositivos do IoT Edge exigem certificados para comunicação segura entre o tempo de execução, os módulos e os dispositivos downstream. Se você não tiver uma autoridade de certificação para criar os certificados necessários, poderá usar os certificados de demonstração para experimentar os recursos do IoT Edge em seu ambiente de teste. Este artigo descreve a funcionalidade dos scripts de geração de certificado que o IoT Edge fornece para teste.

Aviso

Esses certificados expiram em 30 dias e não devem ser usados em nenhum cenário de produção.

Você pode criar certificados em qualquer computador e copiá-los para seu dispositivo do IoT Edge ou gerar os certificados diretamente no dispositivo do IoT Edge.

Pré-requisitos

Um computador de desenvolvimento com o Git instalado.

Baixar scripts de certificado de teste e configurar o diretório de trabalho

O repositório IoT Edge no GitHub inclui scripts de geração de certificado que você pode usar para criar certificados de demonstração. Esta seção fornece instruções para preparar os scripts para execução no computador, seja no Windows ou no Linux.

Windows
Linux

Para criar certificados de demonstração em um dispositivo Windows, você precisa instalar o OpenSSL e então clonar os scripts de geração e configurá-los para serem executados localmente no PowerShell.

Instalar o OpenSSL

Instale o OpenSSL para Windows no computador que você está usando para gerar os certificados. Se já tiver o OpenSSL instalado em seu dispositivo Windows, você pode ignorar esta etapa, mas verifique se openssl.exe está disponível na variável de ambiente PATH.

Há várias maneiras de instalar o OpenSSL, incluindo as seguintes opções:

Fácil: Faça o download e instale todos os binários do OpenSSL de terceiros, por exemplo, OpenSSL no SourceForge. Adicione o caminho completo para openssl.exe à variável de ambiente PATH.
Recomendado: Faça o download do código-fonte do OpenSSL e construa os binários em sua máquina sozinho ou por meio do vcpkg. As instruções a seguir usam vcpkg para baixar o código-fonte, compilação e instalar o OpenSSL em seu computador Windows com etapas simples.
1. Navegue para um diretório onde você deseja instalar vcpkg. Siga as instruções para fazer o download e instalar o vcpkg.
2. Quando o vcpkg estiver instalado, em um prompt do PowerShell, execute o seguinte comando para instalar o pacote OpenSSL para Windows x64. Normalmente, a instalação leva cerca de 5 minutos para concluir.
```
.\vcpkg install openssl:x64-windows
```
3. Adicione <vcpkg path>\installed\x64-windows\tools\openssl à variável de ambiente PATH para que o arquivo openssl.exe fique disponível para invocação.

Preparar scripts no PowerShell

O repositório do Git do dispositivo do Azure IoT Edge contém scripts que você pode usar para gerar certificados de teste. Nesta seção, você clonará o repositório de IoT Edge e executará os scripts.

Abra uma janela do PowerShell no modo de administrador.
Clone o repositório Git do IoT Edge, que contém scripts para gerar certificados de demonstração. Use o comando git clone ou faça o download do ZIP.
```
git clone https://github.com/Azure/iotedge.git
```
Crie um diretório no qual você deseja trabalhar e copie nele os scripts de certificado. Todos os arquivos de certificado e de chave serão criados nesse diretório.
```
mkdir wrkdir
cd .\wrkdir\
cp ..\iotedge\tools\CACertificates\*.cnf .
cp ..\iotedge\tools\CACertificates\ca-certs.ps1 .
```
Se você fez o download do repositório como ZIP, o nome da pasta será iotedge-master e o restante do caminho será o mesmo.

Habilite o PowerShell para executar os scripts.

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Coloque as funções, usadas por scripts, no namespace global do PowerShell.
```
. .\ca-certs.ps1
```
A janela do PowerShell exibirá um aviso de que os certificados gerados por esse script são apenas para fins de teste e não devem ser usados em cenários de produção.
Verifique se o OpenSSL foi instalado corretamente e certifique-se de não haver colisões de nome com certificados existentes. Se houver problemas, o script deve descrever como corrigi-los em seu sistema.
```
Test-CACertsPrerequisites
```

Para criar certificados de demonstração em um dispositivo Linux, você precisará clonar os scripts de geração e configurá-los para serem executados localmente no Bash.

Clone o repositório Git do IoT Edge, que contém scripts para gerar certificados de demonstração.
```
git clone https://github.com/Azure/iotedge.git
```
Crie um diretório no qual você deseja trabalhar e copie nele os scripts de certificado. Todos os arquivos de certificado e de chave serão criados nesse diretório.
```
mkdir wrkdir
cd wrkdir
cp ../iotedge/tools/CACertificates/*.cnf .
cp ../iotedge/tools/CACertificates/certGen.sh .
```

Criar um certificado de AC raiz

Execute esse script para gerar uma AC raiz necessária para cada etapa neste artigo.

O certificado de autoridade de certificação raiz é usado para fazer todos os outros certificados de demonstração para testar um cenário de IoT Edge. Você pode continuar usando o mesmo certificado de AC raiz para criar certificados de demonstração para vários dispositivos IoT Edge ou downstream.

Se você já tiver um certificado de AC raiz em sua pasta de trabalho, não crie um novo. O novo certificado de AC raiz substituirá o antigo e todos os certificados downstream criados a partir do antigo deixarão de funcionar. Se você quiser vários certificados de AC raiz, certifique-se de gerenciá-los em pastas separadas.

Windows
Linux

Navegue até o diretório de trabalho wrkdir em que você colocou os scripts de geração de certificado.
Crie o Certificado de AC do proprietário e faça com que assine um certificado intermediário. Os certificados são colocados em seu diretório de trabalho.
```
New-CACertsCertChain rsa
```
Esse comando de script cria vários arquivos de certificado e de chave, mas quando os artigos solicitam o certificado de AC raiz, use o seguinte arquivo:

certs\azure-iot-test-only.root.ca.cert.pem

Navegue até o diretório de trabalho wrkdir em que você colocou os scripts de geração de certificado.
Crie o Certificado de AC raiz e um certificado intermediário.
```
./certGen.sh create_root_and_intermediate
```
Esse comando de script cria vários arquivos de certificado e de chave, mas quando os artigos solicitam o certificado de AC raiz, use o seguinte arquivo:

certs/azure-iot-test-only.root.ca.cert.pem

Esse certificado é necessário antes que você possa criar mais certificados para seus dispositivos do IoT Edge e dispositivos downstream, conforme descrito nas próximas seções.

Criar certificado de identidade para o dispositivo do IoT Edge

Certificados de identidade do dispositivo IoT Edge são usados para provisionar dispositivos IoT Edge se você optar por usar a autenticação de certificado X. 509. Se você usar a chave simétrica para autenticar no Hub IoT ou DPS, esses certificados não serão necessários e você pode ignorar esta seção.

Esses certificados funcionam se você usa provisionamento manual ou provisionamento automático por meio do DPS (Serviço de Provisionamento de Dispositivos) no Hub IoT do Azure.

Os certificados de identidade do dispositivo entram na seção Provisionamento do arquivo de configuração no dispositivo IoT Edge.

Windows
Linux

Navegue até o diretório de trabalho wrkdir que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie uma chave privada e o certificado de identidade de dispositivo IoT Edge com o comando a seguir:
```
New-CACertsEdgeDeviceIdentity "<device-id>"
```
O nome que você passa para esse comando é a ID do dispositivo para o dispositivo do IoT Edge no Hub IoT.

O novo comando de identidade do dispositivo cria vários arquivos de certificado e chave:

Tipo	Arquivo	Descrição
Certificado de Identidade do dispositivo	`certs\iot-edge-device-identity-<device-id>.cert.pem`	Assinado pelo certificado intermediário gerado anteriormente. Contém apenas o certificado de identidade. Especifique no arquivo de configuração para registro individual do DPS ou provisionamento de Hub IoT.
Certificados de cadeia completa	`certs\iot-edge-device-identity-<device-id>-full-chain.cert.pem`	Contém a cadeia completa do certificado, incluindo o certificado intermediário. Especifique no arquivo de configuração para o IoT Edge apresentar ao DPS para provisionamento de registro de grupo.
Chave privada	`private\iot-edge-device-identity-<device-id>.key.pem`	Chave privada associada ao certificado de identidade do dispositivo. Deve ser especificado no arquivo de configuração desde que você esteja usando algum tipo de autenticação de certificado (impressão digital ou AC) para DPS ou Hub IoT.

Navegue até o diretório de trabalho wrkdir que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie uma chave privada e o certificado de identidade de dispositivo IoT Edge com o comando a seguir:
```
./certGen.sh create_edge_device_identity_certificate "<device-id>"
```
O nome que você passa para esse comando é a ID do dispositivo para o dispositivo do IoT Edge no Hub IoT.

O script cria vários arquivos de certificado e chave, incluindo três que você usará ao criar um registro individual no DPS e instalar o runtime do IoT Edge:

Tipo	Arquivo	Descrição
Certificado de Identidade do dispositivo	`certs/iot-edge-device-identity-<device-id>.cert.pem`	Assinado pelo certificado intermediário gerado anteriormente. Contém apenas o certificado de identidade. Especifique no arquivo de configuração para registro individual do DPS ou provisionamento de Hub IoT.
Certificados de cadeia completa	`certs/iot-edge-device-identity-<device-id>-full-chain.cert.pem`	Contém a cadeia completa do certificado, incluindo o certificado intermediário. Especifique no arquivo de configuração para o IoT Edge apresentar ao DPS para provisionamento de registro de grupo.
Chave privada	`private/iot-edge-device-identity-<device-id>.key.pem`	Chave privada associada ao certificado de identidade do dispositivo. Deve ser especificado no arquivo de configuração desde que você esteja usando algum tipo de autenticação de certificado (impressão digital ou AC) para DPS ou Hub IoT.

Crie certificados de assinatura do Edge

Estes certificados são necessários para cenários de gateway, pois o certificado de assinatura do Edge é como o dispositivo de IoT Edge verifica sua identidade para dispositivos downstream. Você pode ignorar esta seção se não estiver conectando nenhum dispositivo downstream ao IoT Edge.

O certificado de CA do Edge também é responsável por criar certificados para módulos em execução no dispositivo, mas o runtime do IoT Edge poderá criar um certificado temporário se o CA do Edge não estiver configurada. Os certificados de AC de borda entram na seção AC de borda do arquivo config.toml no dispositivo IoT Edge. Para saber mais, confira Entender como o Azure IoT Edge usa certificados.

Windows
Linux

Navegue até o diretório de trabalho wrkdir que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie uma chave privada e o Certificado de AC de IoT Edge com o comando a seguir. Fornecer um nome para certificado de AC. O nome passado para o comando New-CACertsEdgeDevice não deve ser o mesmo que o parâmetro hostname no arquivo de configuração ou a ID do dispositivo no Hub IoT.
```
New-CACertsEdgeDevice "<CA cert name>"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificado e par de chaves precisam ser copiados para um dispositivo do IoT Edge e referenciados no arquivo de configuração:
- certs\iot-edge-device-<CA cert name>-full-chain.cert.pem
- private\iot-edge-device-<CA cert name>.key.pem

Navegue até o diretório de trabalho que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie uma chave privada e o Certificado de AC de IoT Edge com o comando a seguir. Fornecer um nome para certificado de AC. O nome passado para o comando create_edge_device_ca_certificate não deve ser o mesmo que o parâmetro hostname no arquivo de configuração ou a ID do dispositivo no Hub IoT.
```
./certGen.sh create_edge_device_ca_certificate "<CA cert name>"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificado e par de chaves precisam ser copiados para um dispositivo do IoT Edge e referenciados no arquivo de configuração:
- certs/iot-edge-device-ca-<CA cert name>-full-chain.cert.pem
- private/iot-edge-device-ca-<CA cert name>.key.pem

Criar certificados de dispositivo downstream

Esses certificados são necessários para configurar um dispositivo IoT downstream para um cenário de gateway e deseje usar a autenticação X.509 com o Hub IoT ou DPS. Se você quiser usar a autenticação de chave simétrica, você não precisará criar certificados para o dispositivo downstream e poderá ignorar esta seção.

Há duas maneiras de autenticar um dispositivo IoT usando certificados X. 509: usando certificados autoassinados ou usando certificados assinados pela autoridade de certificação (AC).

Para a autenticação autoassinada X.509, às vezes conhecida como autenticação de impressão digital, você precisa criar certificados para serem colocados em seu dispositivo IoT. Esses certificados têm uma impressão digital neles que você compartilha com o Hub IoT para autenticação.
Para uma autenticação assinada por AC (autoridade de certificado) X.509, você precisa de um certificado AC raiz registrado no Hub IoT ou DPS que você use para assinar certificados para seu dispositivo IoT. Qualquer dispositivo que use um certificado emitido pelo certificado AC raiz ou qualquer um dos respectivos certificados intermediários poderá autenticar desde que a cadeia completa seja apresentada pelo dispositivo.

Os scripts de geração de certificado podem ajudá-lo a fazer certificados de demonstração para testar qualquer um desses cenários de autenticação.

Certificados autoassinados

Ao autenticar um dispositivo IoT com certificados autoassinados, você precisa criar certificados de dispositivo com base no certificado AC raiz para sua solução. Em seguida, você recupera uma "impressão digital" hexadecimal dos certificados para fornecer ao Hub IoT. O dispositivo IoT também precisa de uma cópia de seus certificados de dispositivo para que ele possa ser autenticado com o Hub IoT.

Windows
Linux

Navegue até o diretório de trabalho wrkdir que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie dois certificados de dispositivo (primário e secundário) para o dispositivo downstream. Uma convenção de nomenclatura fácil de usar é criar os certificados com o nome do dispositivo IoT e, em seguida, o rótulo primário ou secundário. Por exemplo:
```
New-CACertsDevice "<device ID>-primary"
New-CACertsDevice "<device ID>-secondary"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificados e pares de chaves precisam ser copiados para o dispositivo IoT downstream e referenciados nos aplicativos que se conectam ao Hub IoT:
- certs\iot-device-<device ID>-primary-full-chain.cert.pem
- certs\iot-device-<device ID>-secondary-full-chain.cert.pem
- certs\iot-device-<device ID>-primary.cert.pem
- certs\iot-device-<device ID>-secondary.cert.pem
- certs\iot-device-<device ID>-primary.cert.pfx
- certs\iot-device-<device ID>-secondary.cert.pfx
- private\iot-device-<device ID>-primary.key.pem
- private\iot-device-<device ID>-secondary.key.pem
Recupere a impressão digital SHA-1 (chamada de impressão digital nos contextos do Hub IoT) de cada certificado. A impressão digital é uma cadeia hexadecimal de 40 caracteres. Use o comando openssl a seguir para exibir o certificado e encontrar a impressão digital:
```
Write-Host (Get-Pfxcertificate -FilePath certs\iot-device-<device name>-primary.cert.pem).Thumbprint
```
Execute este comando duas vezes, uma vez para o certificado primário e uma vez para o certificado secundário. Você fornece impressões digitais para ambos os certificados ao registrar um novo dispositivo IoT usando certificados X.509 autoassinados.

Navegue até o diretório de trabalho que tem os scripts de geração de certificado e o certificado de AC raiz.
Crie dois certificados de dispositivo (primário e secundário) para o dispositivo downstream. Uma convenção de nomenclatura fácil de usar é criar os certificados com o nome do dispositivo IoT e, em seguida, o rótulo primário ou secundário. Por exemplo:
```
./certGen.sh create_device_certificate "<device name>-primary"
./certGen.sh create_device_certificate "<device name>-secondary"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificados e pares de chaves precisam ser copiados para o dispositivo IoT downstream e referenciados nos aplicativos que se conectam ao Hub IoT:
- certs/iot-device-<device name>-primary-full-chain.cert.pem
- certs/iot-device-<device name>-secondary-full-chain.cert.pem
- certs/iot-device-<device name>-primary.cert.pem
- certs/iot-device-<device name>-secondary.cert.pem
- certs/iot-device-<device name>-primary.cert.pfx
- certs/iot-device-<device name>-secondary.cert.pfx
- private/iot-device-<device name>-primary.key.pem
- private/iot-device-<device name>-secondary.key.pem
Recupere a impressão digital SHA-1 (chamada de impressão digital nos contextos do Hub IoT) de cada certificado. A impressão digital é uma cadeia hexadecimal de 40 caracteres. Use o comando openssl a seguir para exibir o certificado e encontrar a impressão digital:
```
openssl x509 -in certs/iot-device-<device name>-primary.cert.pem -text -thumbprint | sed 's/[:]//g'
```
Você fornece as impressões digitais primárias e secundárias ao registrar um novo dispositivo IoT usando certificados X.509 autoassinados.

Certificados AC autoassinados

Ao autenticar um dispositivo IoT com certificados assinados por autoridade de certificação, você precisa criar certificados de dispositivo com base no certificado AC raiz para sua solução no Hub IoT. Use o mesmo certificado de AC raiz para criar certificados de dispositivo a serem colocados em seu dispositivo IoT para que ele possa ser autenticado com o Hub IoT.

Os certificados nesta seção são para as etapas na série de tutoriais de certificado X.509 do Hub IoT. Confira Noções básicas sobre a criptografia por chave pública e a infraestrutura de chave pública X.509 para a introdução desta série.

Windows
Linux

Carregue o arquivo de certificado de autoridade de certificação raiz do seu diretório de trabalho, certs\azure-iot-test-only.root.ca.cert.pem, para o Hub IoT.
Se a verificação automática não estiver selecionada, use o código fornecido no portal do Azure para verificar se você possui esse certificado de AC raiz.
```
New-CACertsVerificationCert "<verification code>"
```
Crie uma cadeia de certificados para seu dispositivo downstream. Use a mesma ID de dispositivo com a qual o dispositivo está registrado no Hub IoT.
```
New-CACertsDevice "<device id>"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificados e pares de chaves precisam ser copiados para o dispositivo IoT downstream e referenciados nos aplicativos que se conectam ao Hub IoT:
- certs\iot-device-<device id>.cert.pem
- certs\iot-device-<device id>.cert.pfx
- certs\iot-device-<device id>-full-chain.cert.pem
- private\iot-device-<device id>.key.pem

Carregue o arquivo de certificado de autoridade de certificação raiz do seu diretório de trabalho, certs\azure-iot-test-only.root.ca.cert.pem, para o Hub IoT.
Se a verificação automática não estiver selecionada, use o código fornecido no portal do Azure para verificar se você possui esse certificado de AC raiz.
```
./certGen.sh create_verification_certificate "<verification code>"
```
Crie uma cadeia de certificados para seu dispositivo downstream. Use a mesma ID de dispositivo com a qual o dispositivo está registrado no Hub IoT.
```
./certGen.sh create_device_certificate "<device id>"
```
Esse comando cria vários arquivos de certificado e chave. Os seguintes certificados e pares de chaves precisam ser copiados para o dispositivo IoT downstream e referenciados nos aplicativos que se conectam ao Hub IoT:
- certs/iot-device-<device id>.cert.pem
- certs/iot-device-<device id>.cert.pfx
- certs/iot-device-<device id>-full-chain.cert.pem
- private/iot-device-<device id>.key.pem

Compartilhar via