Ligar um dispositivo a jusante a um gateway do Azure IoT Edge

Aplica-se a: IoT Edge 1.5

Importante

O IoT Edge 1.5 LTS é a versão suportada. O IoT Edge 1.4 LTS está em fim de vida útil a partir de 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

Este artigo fornece instruções para configurar uma conexão confiável entre dispositivos downstream e gateways transparentes do IoT Edge. Em um cenário de gateway transparente, um ou mais dispositivos enviam mensagens por meio de um único dispositivo de gateway que mantém a conexão com o Hub IoT. Neste artigo, os termos gateway e gateway IoT Edge significam um dispositivo IoT Edge configurado como um gateway transparente.

Nota

Um dispositivo downstream envia dados diretamente para a Internet ou para dispositivos de gateway (habilitado para IoT Edge ou não). Um dispositivo filho pode ser um dispositivo downstream ou um dispositivo gateway em uma topologia aninhada.

Você configura uma conexão de gateway transparente em três etapas. Este artigo explica o terceiro passo.

1. Configure o dispositivo de gateway como um servidor para que os dispositivos downstream possam se conectar a ele com segurança. Configure o gateway para receber mensagens de dispositivos downstream e encaminhá-las para o destino certo. Para essas etapas, consulte Configurar um dispositivo IoT Edge para atuar como um gateway transparente.

2. Crie uma identidade de dispositivo para o dispositivo downstream para que ele possa se autenticar com o Hub IoT. Configure o dispositivo downstream para enviar mensagens através do dispositivo de gateway. Para essas etapas, consulte Autenticar um dispositivo downstream no Hub IoT do Azure.

3. Conecte o dispositivo downstream ao dispositivo de gateway e comece a enviar mensagens.

Este artigo explica os componentes de conexão de dispositivo downstream, como:

• Segurança da camada de transporte (TLS) e fundamentos de certificado
• Bibliotecas TLS que funcionam em diferentes sistemas operacionais e lidam com certificados de forma diferente

Você percorre exemplos do Azure IoT em seu idioma preferido para fazer com que seu dispositivo envie mensagens para o gateway.

Pré-requisitos

Adquira o seguinte para preparar o seu dispositivo a jusante:

• Um dispositivo a jusante.

  Este dispositivo pode ser qualquer aplicativo ou plataforma com uma identidade criada no Hub IoT do Azure. Em muitos casos, os aplicativos usam o SDK do dispositivo IoT do Azure. Um dispositivo downstream também pode ser um aplicativo em execução no dispositivo de gateway IoT Edge.

  Mais tarde, este artigo mostra como conectar um dispositivo IoT como um dispositivo downstream. Se você quiser usar um dispositivo IoT Edge como um dispositivo downstream, consulte Conectar dispositivos IoT Edge do Azure juntos para criar uma hierarquia (borda aninhada).

• Um arquivo de certificado de autoridade de certificação raiz.

  Este ficheiro é usado para gerar o certificado CA do Edge em Configurar um dispositivo IoT Edge para atuar como um gateway transparente e está disponível no seu dispositivo downstream.

  Seu dispositivo downstream usa esse certificado para verificar a identidade do dispositivo de gateway. Este certificado de confiança garante as conexões de segurança da camada de transporte (TLS) com o dispositivo de gateway. Para obter informações sobre uso, consulte Fornecimento do certificado de autoridade de certificação raiz.

• Uma cadeia de conexão modificada que aponta para o dispositivo de gateway.

  Para saber como alterar sua cadeia de conexão, consulte Autenticar um dispositivo downstream no Hub IoT do Azure.

Nota

Os dispositivos IoT registrados no Hub IoT podem usar gêmeos de módulo para isolar diferentes processos, hardware ou funções em um único dispositivo. Os gateways IoT Edge suportam conexões de módulo downstream usando autenticação de chave simétrica, mas não autenticação de certificado X.509.

Compreender os fundamentos do TLS e do certificado

A conexão segura de dispositivos downstream ao IoT Edge é semelhante a outras comunicações seguras de cliente e servidor pela Internet. Um cliente e um servidor se comunicam com segurança pela Internet usando a segurança da camada de transporte (TLS). O TLS usa construções padrão de infraestrutura de chave pública (PKI) chamadas certificados. TLS é uma especificação detalhada que abrange muitos tópicos relacionados à proteção de dois pontos de extremidade. Esta seção resume os conceitos necessários para conectar dispositivos com segurança a um gateway IoT Edge.

Quando um cliente se conecta a um servidor, o servidor apresenta uma cadeia de certificados chamada cadeia de certificados do servidor. Uma cadeia de certificados geralmente tem um certificado de autoridade de certificação (CA) raiz, um ou mais certificados de CA intermediários e o certificado do servidor. O cliente confia no servidor verificando criptograficamente toda a cadeia de certificados do servidor. Esse processo é chamado de validação da cadeia de servidores. O cliente também desafia o servidor a provar que tem a chave privada para o certificado do servidor, chamado de prova de posse. Juntas, a validação da cadeia de servidores e a prova de posse são chamadas de autenticação de servidor. Para validar uma cadeia de certificados de servidor, o cliente precisa de uma cópia do certificado de autoridade de certificação raiz usado para emitir o certificado do servidor. Ao conectar-se a websites, os navegadores vêm pré-configurados com certificados de Autoridades de Certificação comuns, para que o processo cliente seja sem falhas.

Quando um dispositivo se conecta ao Hub IoT do Azure, o dispositivo é o cliente e o serviço de nuvem do Hub IoT é o servidor. O serviço de nuvem do Hub IoT usa um certificado de CA raiz chamado Baltimore CyberTrust Root, que está disponível publicamente e é amplamente utilizado. Como o certificado de CA do Hub IoT já está instalado na maioria dos dispositivos, muitas implementações TLS (OpenSSL, Schannel, LibreSSL) o usam automaticamente durante a validação do certificado do servidor. No entanto, um dispositivo que se conecta ao Hub IoT pode ter problemas ao se conectar a um gateway IoT Edge.

Quando um dispositivo se conecta a um gateway IoT Edge, o dispositivo downstream é o cliente e o dispositivo de gateway é o servidor. O Azure IoT Edge permite criar cadeias de certificados de gateway conforme necessário. Você pode usar um certificado de autoridade de certificação pública, como Baltimore, ou um certificado de autoridade de certificação raiz autoassinado (ou interno). Os certificados de autoridade de certificação pública geralmente têm um custo, por isso geralmente são usados em cenários de produção. Os certificados de CA autoassinados são preferidos para desenvolvimento e teste. Os certificados de demonstração são certificados de CA raiz autoassinados.

Ao usar um certificado de autoridade de certificação raiz autoassinado para um gateway IoT Edge, você precisa instalá-lo ou fornecê-lo a todos os dispositivos downstream que se conectam ao gateway.

Para saber mais sobre certificados do IoT Edge e implicações de produção, consulte Detalhes de uso do certificado do IoT Edge.

Fornecer o certificado de autoridade de certificação raiz

Para verificar os certificados do dispositivo gateway, o dispositivo downstream precisa de sua própria cópia do certificado da autoridade de certificação raiz. Se você usar os scripts no repositório git do IoT Edge para criar certificados de teste, o certificado de CA raiz será chamado azure-iot-test-only.root.ca.cert.pem.

Se ainda não o fez, mova este ficheiro de certificado para qualquer diretório no seu dispositivo a jusante. Mova o arquivo instalando o certificado da autoridade de certificação no armazenamento de certificados do sistema operacional ou fazendo referência ao certificado em aplicativos que usam os SDKs do Azure IoT.

Use um serviço como o Azure Key Vault ou uma ferramenta como o protocolo de cópia segura para mover o arquivo de certificado.

Instalar certificados no SO

Depois de copiar o certificado de autoridade de certificação raiz para o dispositivo downstream, verifique se os aplicativos que se conectam ao gateway podem acessar o certificado.

Instale o certificado de autoridade de certificação raiz no armazenamento de certificados do sistema operacional para que a maioria dos aplicativos possa usá-lo. Alguns aplicativos, como Node.js, não usam o armazenamento de certificados do sistema operacional e, em vez disso, usam o armazenamento de certificados interno do tempo de execução do Node. Se não for possível instalar o certificado no nível do sistema operacional, vá para a seção Usar certificados com SDKs do Azure IoT .

Instale o certificado de CA raiz no Ubuntu ou Windows.

Ubuntu

Use os seguintes comandos para instalar um certificado CA em um host Ubuntu. Este exemplo usa o certificado azure-iot-test-only.root.ca.cert.pem dos artigos de pré-requisitos e pressupõe que você copiou o certificado para um local no dispositivo downstream.

sudo cp <file path>/azure-iot-test-only.root.ca.cert.pem /usr/local/share/ca-certificates/azure-iot-test-only.root.ca.cert.pem.crt

sudo update-ca-certificates

Quando terminar, você verá um Atualizando certificados em /etc/ssl/certs... 1 adicionado, 0 removido; mensagem concluída .

Mac OS

Siga estas etapas para instalar um certificado de autoridade de certificação em um host Windows. Este exemplo usa o certificado azure-iot-test-only.root.ca.cert.pem dos artigos de pré-requisitos e pressupõe que você copiou o certificado para um local no dispositivo downstream.

Instale certificados usando o Import-Certificate do PowerShell como administrador:

import-certificate  <file path>\azure-iot-test-only.root.ca.cert.pem -certstorelocation cert:\LocalMachine\root

Você também pode instalar certificados com o utilitário certlm :

1. No menu Iniciar, procure e selecione Gerenciar certificados de computador. O utilitário certlm é aberto.
2. Vá para Certificados - Computador Local>Autoridades de Certificação Raiz Confiáveis.
3. Clique com o botão direito do rato em Certificados e, em seguida, selecione Todas as Tarefas>de Importação. O assistente de importação de certificados abre.
4. Siga as etapas para importar o arquivo de <file path>/azure-iot-test-only.root.ca.cert.pemcertificado . Quando terminar, você verá uma mensagem importada com êxito .

Instale certificados programaticamente com APIs .NET, conforme mostrado no exemplo .NET mais adiante neste artigo.

A maioria dos aplicativos usa a pilha TLS fornecida pelo Windows chamada Schannel para se conectar por TLS. O Schannel requer que os certificados sejam instalados no armazenamento de certificados do Windows antes de estabelecer uma conexão TLS.

Usar certificados com SDKs do Azure IoT

Os SDKs do Azure IoT se conectam a um dispositivo IoT Edge usando aplicativos de exemplo simples. O objetivo dos exemplos é conectar o cliente do dispositivo e enviar mensagens de telemetria do dispositivo para o gateway, fechar a conexão e sair.

Antes de usar os exemplos no nível do aplicativo, obtenha os seguintes itens:

• Sua cadeia de conexão do Hub IoT, do seu dispositivo downstream, modificada para apontar para o dispositivo de gateway.

• Todos os certificados necessários para autenticar seu dispositivo downstream no Hub IoT. Para obter mais informações, consulte Autenticar um dispositivo downstream no Hub IoT do Azure.

• O caminho completo para o certificado de autoridade de certificação raiz que você copiou e salvou em algum lugar em seu dispositivo downstream.

  Por exemplo: <file path>/azure-iot-test-only.root.ca.cert.pem.

Agora você está pronto para usar certificados com uma amostra no idioma de sua escolha:

NodeJS

Esta seção fornece um aplicativo de exemplo para conectar um cliente de dispositivo do Azure IoT Node.js a um gateway IoT Edge. Para aplicativos Node.js, você deve instalar o certificado de autoridade de certificação raiz no nível do aplicativo, conforme mostrado aqui. Node.js aplicativos não usam o armazenamento de certificados do sistema.

1. Obtenha o exemplo para edge_downstream_device.js do SDK do dispositivo IoT do Azure para Node.js repositório de exemplos.
2. Certifique-se de que você tem todos os pré-requisitos para executar o exemplo, revisando o arquivo readme.md .
3. No arquivo edge_downstream_device.js, atualize as variáveis connectionString e edge_ca_cert_path .
4. Consulte a documentação do SDK para obter instruções sobre como executar o exemplo no seu dispositivo.

Para entender o exemplo que você está executando, o trecho de código a seguir é como o SDK do cliente lê o arquivo de certificado e o usa para estabelecer uma conexão TLS segura:

// Provide the Azure IoT device client via setOptions with the X509
// Edge root CA certificate that was used to setup the Edge runtime
var options = {
    ca : fs.readFileSync(edge_ca_cert_path, 'utf-8'),
};

.NET

Esta seção apresenta um aplicativo de exemplo para conectar um cliente de dispositivo do Azure IoT .NET a um gateway do IoT Edge. No entanto, os aplicativos .NET são automaticamente capazes de usar quaisquer certificados instalados no armazenamento de certificados do sistema em hosts Linux e Windows.

1. Obtenha o exemplo para EdgeDownstreamDevice da pasta de exemplos do IoT Edge .NET.
2. Certifique-se de que você tem todos os pré-requisitos para executar o exemplo, revisando o arquivo readme.md .
3. No arquivo Propriedades / launchSettings.json, atualize as variáveis DEVICE_CONNECTION_STRING e CA_CERTIFICATE_PATH. Se você quiser usar o certificado instalado no armazenamento de certificados confiáveis no sistema host, deixe essa variável em branco.
4. Consulte a documentação do SDK para obter instruções sobre como executar o exemplo no seu dispositivo.

Para instalar programaticamente um certificado confiável no armazenamento de certificados por meio de um aplicativo .NET, consulte a função InstallCACert() no arquivo EdgeDownstreamDevice / Program.cs . Esta operação é idempotente, por isso pode ser executada várias vezes com os mesmos valores sem efeito extra.

C

Esta seção apresenta um aplicativo de exemplo para conectar um cliente de dispositivo do Azure IoT C a um gateway do IoT Edge. O C SDK pode operar com muitas bibliotecas TLS, incluindo OpenSSL, WolfSSL e Schannel. Para obter mais informações, consulte o SDK do Azure IoT C.

1. Obtenha o aplicativo iotedge_downstream_device_sample dos exemplos do SDK do dispositivo IoT do Azure para C.
2. Certifique-se de que você tem todos os pré-requisitos para executar o exemplo, revisando o arquivo readme.md .
3. No arquivo iotedge_downstream_device_sample.c, atualize as variáveis connectionString e edge_ca_cert_path .
4. Consulte a documentação do SDK para obter instruções sobre como executar o exemplo no seu dispositivo.

O SDK do dispositivo IoT do Azure para C fornece uma opção para registrar um certificado de CA ao configurar o cliente. Esta operação não instala o certificado em nenhum lugar, mas usa um formato de cadeia de caracteres do certificado na memória. O certificado salvo é fornecido à pilha TLS subjacente ao estabelecer uma conexão.

(void)IoTHubDeviceClient_SetOption(device_handle, OPTION_TRUSTED_CERT, cert_string);

Nota

O método para registrar um certificado de autoridade de certificação ao configurar o cliente pode mudar se estiver usando um pacote gerenciado ou biblioteca. Por exemplo, a biblioteca baseada em IDE do Arduino requer a adição do certificado CA a uma matriz de certificados definida em um arquivo certs.c global, em vez de usar a IoTHubDeviceClient_LL_SetOption operação.

Em hosts Windows, se você não estiver usando OpenSSL ou outra biblioteca TLS, o SDK padrão para usar Schannel. Para que o Schannel funcione, o certificado de CA raiz do IoT Edge deve ser instalado no repositório de certificados do Windows, não definido usando a IoTHubDeviceClient_SetOption operação.

Java

Esta seção apresenta um aplicativo de exemplo para conectar um cliente de dispositivo Java do Azure IoT a um gateway do IoT Edge.

1. Obtenha o exemplo de evento de envio dos exemplos do SDK do dispositivo IoT do Azure para Java.
2. Certifique-se de que você tem todos os pré-requisitos para executar o exemplo, revisando o arquivo readme.md .
3. Consulte a documentação do SDK para obter instruções sobre como executar o exemplo no seu dispositivo.

Píton

Esta seção apresenta um aplicativo de exemplo para conectar um cliente de dispositivo Python do Azure IoT a um gateway do IoT Edge.

1. Obtenha o exemplo para send_message_downstream dos exemplos do SDK do dispositivo IoT do Azure para Python.
2. Defina as IOTHUB_DEVICE_CONNECTION_STRING variáveis e IOTEDGE_ROOT_CA_CERT_PATH de ambiente conforme especificado nos comentários do script Python.
3. Consulte a documentação do SDK para obter mais instruções sobre como executar o exemplo no seu dispositivo.

Testar a conexão do gateway

Execute este comando de exemplo no dispositivo downstream para testar se ele pode se conectar ao dispositivo gateway:

openssl s_client -connect mygateway.contoso.com:8883 -CAfile <CERTDIR>/certs/azure-iot-test-only.root.ca.cert.pem -showcerts

Este comando verifica a conexão através do MQTTS (porta 8883). Se você usar um protocolo diferente, ajuste o comando para AMQPS (5671) ou HTTPS (443).

A saída deste comando pode ser longa e inclui informações sobre todos os certificados na cadeia. Se a conexão for bem-sucedida, você verá uma linha como Verification: OK ou Verify return code: 0 (ok).

Solucionar problemas de conexão de gateway

Se a conexão do dispositivo downstream com o dispositivo gateway estiver instável, considere estas perguntas para ajudar a corrigir o problema.

• O nome do host do gateway na cadeia de conexão é o mesmo que o valor do nome do host no arquivo de configuração do IoT Edge no dispositivo do gateway?
• O hostname do gateway pode ser resolvido para um endereço IP? Corrija conexões intermitentes usando DNS ou adicionando uma entrada de arquivo host no dispositivo downstream.
• As portas de comunicação estão abertas no seu firewall? Verifique se as portas de protocolo necessárias (MQTTS:8883, AMQPS:5671, HTTPS:433) estão abertas entre o dispositivo downstream e o dispositivo IoT Edge transparente.

Próximos passos

Saiba como o IoT Edge estende os recursos offline para dispositivos downstream.