Ferramenta de provisionamento do OpenWeave Factory

Ver o código-fonte no GitHub

A ferramenta de provisionamento de fábrica do OpenWeave é um meio conveniente de provisionar informações de configuração persistentes por dispositivo em dispositivos compatíveis com o Weave. A ferramenta de provisionamento de fábrica foi desenvolvida para ser usada como parte de um processo de linha de fabricação que carimba dispositivos individuais com informações exclusivas de identidade e credencial antes do envio aos clientes. Ele também pode ser usado por desenvolvedores para personalizar o hardware de pré-produção usado durante o processo de desenvolvimento.

Teoria da operação

O objetivo da ferramenta de provisionamento de fábrica do OpenWeave é injetar informações de configuração selecionadas no repositório de configuração persistente de um dispositivo, onde elas podem ser coletadas e usadas no momento da execução pelo firmware do dispositivo. A configuração persistente do dispositivo geralmente é armazenada no flash interno do dispositivo, embora os detalhes de como exatamente os dados são armazenados e em que formato variem de plataforma para plataforma. A própria Factory Provisioning Tool é independente do formato de armazenamento final e depende do código no firmware do dispositivo para gravar os dados da maneira correta. A interface do usuário da ferramenta também é independente do tipo de hardware que está sendo configurado, o que significa que processos de fabricação semelhantes podem ser usados em linhas de produtos com base em diferentes plataformas de hardware.

A ferramenta de provisionamento de fábrica foi projetada para ser executada em uma máquina host conectada a um dispositivo de destino por alguma forma de depuração ou interface de controle, por exemplo, uma porta JTAG ou SWD. A ferramenta injeta informações de provisionamento na RAM do dispositivo em um formato codificado especial. O dispositivo é então instruído a reiniciar. Nesse ponto, o código integrado ao firmware do dispositivo localiza os dados codificados, valida a integridade deles e grava os valores contidas no armazenamento permanente em um formato adequado para a plataforma.

O código no dispositivo que detecta e processa os dados de provisionamento injetados é integrado à camada do dispositivo do OpenWeave e pode ser ativado em qualquer plataforma com suporte. Depois de ativado, o código é executado automaticamente sempre que o dispositivo é inicializado, no início do processo de inicialização. O código opera lendo uma região específica da RAM da plataforma. Em plataformas com quantidades modestas de memória (por exemplo, <1M), a verificação abrange toda a RAM disponível.

Quando colocados na RAM, os dados de provisionamento são codificados com um prefixo facilmente identificável, o que permite que eles sejam encontrados rapidamente durante o processo de verificação. Um valor de verificação de integridade baseado em um hash criptográfico é usado para confirmar a validade dos dados antes do processamento.

Por padrão, a ferramenta de provisionamento seleciona o local da RAM em que os dados de provisionamento serão injetados com base na plataforma do dispositivo de destino. Essa escolha pode ser substituída por um argumento para a ferramenta. Em geral, não é necessário que o firmware do dispositivo reserve um local de RAM especificamente para receber dados de provisionamento. Normalmente, os dados de provisionamento são gravados em um local de RAM alocado para outros fins, mas geralmente não são usados no início do processo de inicialização do dispositivo. As opções comuns são o topo da pilha inicial do sistema ou a extremidade de uma arena de heap.

A ferramenta de provisionamento de fábrica depende de um conjunto de ferramentas de desenvolvimento externas para se conectar ao dispositivo de destino. As ferramentas utilizadas dependem do tipo de dispositivo de destino. No momento, há suporte para duas interfaces de dispositivo:

  • uma sonda de depuração SEGGER J-Link conectada à porta JTAG ou SWD de um dispositivo
  • uma porta serial USB conectada a um Espressif ESP32

A interface J-Link depende da ferramenta SEGGER J-Link Commander (JLinkExe), que precisa ser instalada separadamente na máquina host.

A interface ESP32 depende do comando esptool.py da Espressif, que é fornecido como parte do SDK ESP-IDF da Espressif.

Tipos de informações que podem ser provisionadas

A ferramenta de provisionamento de fábrica do OpenWeave é capaz de provisionar os seguintes tipos de informações:

  • Número de série do dispositivo
  • ID do dispositivo Weave atribuído pelo fabricante
  • Certificado e chave privada do Weave atribuídos pelo fabricante
  • Código de pareamento do Weave
  • Número de revisão do produto
  • Data de fabricação

Geralmente, um dispositivo precisa de todas as informações acima para funcionar corretamente, mas não é necessário provisionar todas elas ao mesmo tempo. Assim, o provisionamento de diferentes tipos de informações pode acontecer em pontos distintos do processo de fabricação. Além disso, é possível substituir valores provisionados anteriormente por novos valores em uma etapa de provisionamento posterior.

Fontes de informações de provisionamento

As informações de provisionamento do dispositivo podem ser fornecidas à ferramenta de provisionamento de fábrica das seguintes maneiras:

  • Argumentos de linha de comando A
  • Como usar um arquivo CSV de provisionamento
  • Buscando valores de um servidor de provisionamento do Nest

Linha de comando

Na forma mais simples, as informações de provisionamento do dispositivo são especificadas diretamente na linha de comando para a ferramenta de provisionamento da fábrica do OpenWeave. Exemplo:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --pairing-code NESTUS --mfg-date 2019/04/01

Os valores de dados binários, como o certificado e a chave privada do Weave, podem ser especificados como strings base-64 ou como os nomes de arquivos que contêm os dados desejados em formato bruto (binário).

Confira abaixo uma lista completa de argumentos de linha de comando disponíveis.

Arquivo CSV de provisionamento

Para acomodar o provisionamento em massa de dispositivos, a ferramenta de provisionamento de fábrica também pode ler dados de provisionamento de um arquivo de dados de provisionamento formatado em CSV. As colunas deste arquivo devem corresponder a tipos de dados de provisionamento específicos, ou seja, Serial_Num, Certificate, Private_Key etc. As linhas no arquivo fornecem valores individuais para dispositivos específicos, indexados pelo ID do dispositivo Weave (Device_Id). O ID do dispositivo específico a ser provisionado precisa ser especificado na linha de comando. Exemplo:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-csv-file ./dev-provisioning-data.csv

As seguintes colunas CSV são compatíveis:

Nome Formato Descrição
Device_Id 16 dígitos hexadecimais ID do dispositivo do Weave. Precisa estar presente.
Serial_Num string Número de série do dispositivo.
Certificate string de base64 Certificado do dispositivo Weave atribuído pelo fabricante.
Private_Key string de base64 Chave privada do Weave atribuída pelo fabricante.
Pairing_Code string Código de pareamento do Weave.
Product_Rev número inteiro Número da revisão do produto.
Mfg_Date AAAA/MM/DD Data de fabricação do dispositivo.

As colunas podem aparecer no arquivo CSV em qualquer ordem. Todas as colunas são opcionais, exceto Device_Id. Os valores não presentes no arquivo CSV simplesmente não são provisionados no dispositivo.

O usuário pode especificar valores de provisionamento individuais na linha de comando, além do arquivo CSV. Nesse caso, o valor da linha de comando tem precedência sobre os valores no arquivo.

O suporte ao formato de arquivo CSV pela ferramenta de provisionamento de fábrica é compatível com a saída do comando gen-provisioning-data da ferramenta weave.

Servidor de provisionamento do Nest

A ferramenta de provisionamento de fábrica oferece suporte para buscar informações de provisionamento selecionadas de um servidor de provisionamento Nest usando um protocolo baseado em HTTPS. O protocolo do servidor de provisionamento pode ser usado para buscar o certificado do dispositivo Weave atribuído pelo fabricante, a chave privada correspondente e o código de pareamento do Weave do servidor de provisionamento.

O local da rede do servidor de provisionamento é especificado fornecendo um URL de base na linha de comando da ferramenta de provisionamento. As informações de provisionamento desejadas são selecionadas especificando o ID do dispositivo Weave na linha de comando. Exemplo:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-server https://192.168.172.2:8000/

O usuário pode especificar valores de provisionamento individuais na linha de comando, além do URL do servidor de provisionamento. Nesse caso, os valores fornecidos na linha de comando têm precedência em relação aos valores retornados pelo servidor.

Como ativar / desativar o suporte ao provisionamento de fábrica

O suporte ao provisionamento de fábrica do OpenWeave no firmware do dispositivo é controlado pela opção de configuração WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING no momento da compilação. Essa opção é ativada por padrão. O recurso pode ser desativado substituindo a opção no arquivo WeaveProjectConfig.h do aplicativo. Exemplo:

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

Em geral, é seguro ativar o provisionamento de fábrica no firmware do dispositivo de produção desde que a interface de depuração do dispositivo esteja desativada corretamente nos dispositivos de produção. Isso pode ser feito por meio de hardware (por exemplo, queimando fusíveis no SoC) ou em software (por exemplo, usando um bootloader seguro que bloqueia o acesso de depuração como parte do processo de inicialização).

Como executar a ferramenta Factory Provisioning

A ferramenta de provisionamento da fábrica do OpenWeave oferece suporte às seguintes opções de linha de comando:

Opção Descrição
--target <string> Tipo de dispositivo de destino. As opções são: nrf52840, esp32
--load-addr <hex-digits> Endereço na memória do dispositivo em que os dados de provisionamento serão gravados.
--detalhado, -v Ajusta o nível de detalhamento da saída. Use vários argumentos para aumentar a quantidade de detalhes.
--serial-num <string> Defina o número de série do dispositivo.
--device-id <hex-digits> Defina o ID do dispositivo atribuído pelo fabricante.
--device-cert <base-64> | <file-name> Defina o certificado do dispositivo Weave atribuído pelo fabricante.
--device-key <base-64> | <file-name> Defina a chave privada do dispositivo Weave atribuída pelo fabricante.
--pairing-code <string> Defina o código de pareamento do dispositivo.
--product-rev <integer> Defina a revisão do produto para o dispositivo.
--mfg-date <YYYY/MM/DD> | today | now Defina a data de fabricação do dispositivo.
--jlink-cmd <path-name> Caminho para o comando JLink. O padrão é "JLinkExe".
--jlink-if SWD | JTAG Tipo de interface J-Link. O padrão é SWD.
--jlink-speed <integer> | adaptive | auto Velocidade da interface J-Link.
--jlink-sn <string> Número de série da sondagem J-Link.
--esptool-cmd <path-name> Caminho para o comando esptool. O padrão é "esptool.py".
--port <path-name> Nome do dispositivo da porta COM para ESP32. O padrão é /tty/USB0.
--speed <integer> Taxa de Baud para a porta COM. O padrão é 115200.
--prov-csv-file <file-name> Ler dados de provisionamento de dispositivos de um arquivo CSV de provisionamento.
--prov-server <url> Ler dados de provisionamento de dispositivos de um servidor de provisionamento.
--disable-server-validation Ao usar HTTPS, desative a validação do certificado apresentado pelo servidor de provisionamento.

Exemplos

O comando a seguir define o ID do dispositivo, o número de série, a revisão do produto e o código de pareamento como valores específicos. A data de fabricação é definida como a data atual. Além disso, o certificado do dispositivo e a chave privada são definidos para testar valores fornecidos em um arquivo CSV fornecido com o repositório de origem openweave-core.

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
    --serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
    --prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv