Gerenciar certificados em aplicativos de alto nível

Artigo
11/05/2024

Importante

Esta é a documentação do Azure Sphere (herdado). O Azure Sphere (herdado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).

A API CertStore permite que um aplicativo de alto nível gerencie certificados para uso na autenticação de rede. O azsphere device certificate permite gerenciar certificados na linha de comando.

Os certificados são armazenados no armazenamento não volátil no dispositivo Azure Sphere. O repositório de certificados pode armazenar até 24 KiB de certificados. O tamanho máximo de um certificado é 8 KiB. Os certificados de Autoridade de Certificação raiz normalmente são maiores que os certificados do cliente. Além de usar o repositório de certificados, você também pode acessar o certificado de cliente gerenciado pela Microsoft. O certificado de cliente gerenciado pela Microsoft só estará disponível para uso quando o dispositivo estiver conectado à Internet pelo menos uma vez a cada 24 horas.

Usar o certificado de cliente gerenciado pela Microsoft

Use essas duas funções para obter um certificado de cliente e determinar se ele está pronto para uso.

DeviceAuth_GetCertificatePath retorna um caminho de arquivo para um certificado de cliente gerenciado pelo sistema operacional. Esse caminho de arquivo é exigido por algumas bibliotecas para carregar um certificado para comunicações TLS.
Application_IsDeviceAuthReady para verificar se a autenticação do dispositivo para o aplicativo atual está pronta.

Requisitos CertStore

Os aplicativos que usam a API CertStore devem incluir os arquivos de cabeçalho apropriados e adicionar a funcionalidade CertStore ao manifesto do aplicativo.

Arquivos de cabeçalho

Inclua o cabeçalho CertStore em seu projeto:

 #include <applibs\certstore.h>

Configurações do manifesto do aplicativo

Para usar as APIs do repositório de certificados, você deve adicionar a funcionalidade do aplicativo CertStore ao manifesto do aplicativo e definir o valor como true. O tópico Manifesto de aplicativo do Azure Sphere tem mais detalhes sobre o manifesto do aplicativo.

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App3",
  "ComponentId" : "bb267cbd-4d2a-4937-8dd8-3603f48cb8f6",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "CertStore" : true,
    "Gpio": [],
    "Uart": [],
    "EnterpriseWifiConfig": true,
    "WifiConfig": true,
    "NetworkConfig": false,
    "SystemTime": true
  }
}

IDs de certificado

Cada certificado é associado a uma ID (identificador) do certificado. O identificador do certificado é uma cadeia de caracteres de 1 a 16 caracteres que identifica exclusivamente o certificado no dispositivo. Os caracteres válidos são “a” a ”z”, “A” a “Z”, “0” a “9”, hífen (-). e sublinhado (_). Cada identificador do certificado deve ser exclusivo em todo o dispositivo, independentemente do tipo de certificado que ele identifica.

O identificador de cada certificado é salvo no repositório de certificados e é usado em todo o dispositivo: pela API CertStore , pela API WifiConfig e pela CLI azsphere. Consequentemente, se você carregar um certificado da linha de comando, todos os aplicativos que consultam, movem ou excluem esse certificado deverão usar o mesmo identificador. Da mesma forma, se um aplicativo carregar o certificado, comandos azsphere que manipularem o certificado deverão usar o mesmo identificador. Se você instalar um novo certificado com o mesmo identificador que um certificado existente de qualquer tipo, o novo certificado substituirá o existente.

Cuidado

Como as IDs do certificado são aplicadas a todo o sistema nos Certificados de Autoridade de Certificação raiz e nos certificados do cliente, um comando azsphere ou uma chamada de função que adiciona um novo certificado pode substituir um certificado que foi adicionado por um comando ou uma chamada de função anterior, potencialmente causando falhas de conexão de rede. Recomendamos que você desenvolva procedimentos de atualização de certificado bem definidos e escolha IDs de certificado com cuidado.

Adicionar um certificado ao repositório de certificados

Para adicionar um certificado ao repositório de certificados, um aplicativo chama uma das seguintes funções:

CertStore_InstallClientCertificate instala um certificado do cliente, que é composto por um certificado público e uma chave privada
CertStore_InstallRootCACertificate instala um Certificado de Autoridade de Certificação raiz, composto por um certificado público

O certificado deve estar presente no dispositivo para que o aplicativo possa instalá-lo. Os certificados devem estar em sintaxe PKCS1 ou PKCS8 e no formato .pem para serem carregados no dispositivo Azure Sphere. Adquirir e implantar certificados para redes EAP-TLS descreve como adquirir certificados e carregá-los em um dispositivo. A Microsoft não fornece certificados.

A instalação de um certificado o adiciona ao repositório de certificados e o disponibiliza para uso na autenticação. No repositório de certificados, os certificados são gerenciados pelo índice e podem ser recuperados por índice. O intervalo de valores de índice é executado de 0 a (CertStore_GetCertificateCount – 1).

Um aplicativo pode obter o identificador do certificado em um índice específico chamando a função CertStore_GetCertificateIdentifierAt. Em seguida, ele pode usar o identificador do certificado em chamadas para obter informações sobre o certificado, para mover ou excluir o certificado e para usar um certificado para autenticação.

Obter informações de certificado

A API CertStore inclui várias funções que retornam informações sobre um certificado armazenado:

CertStore_GetCertificateNotBefore obtém a hora em que o certificado se torna válido
CertStore_GetCertificateNotAfter obtém a hora em que o certificado expira
CertStore_GetCertificateIssuerName obtém o nome do emissor do certificado
CertStore_GetCertificateSubjectName obtém o nome da entidade do certificado, ou seja, o que o certificado protege

As horas “não antes de” e “não depois de” são úteis para gerenciar o tempo de vida e as atualizações do certificado. Confira Ciclo de vida e renovação do certificado para obter detalhes.

Renomear ou excluir um certificado

Para renomear ou excluir um certificado, um aplicativo chama CertStore_MoveCertificate ou CertStore_DeleteCertificate.

CertStore_MoveCertificate renomeia um certificado alterando o identificador do certificado dele. Como as IDs do certificado devem ser exclusivas em um dispositivo, a renomeação de um certificado fornecendo a mesma ID que outro certificado exclui esse certificado. Por exemplo, se o repositório de certificados contiver MyCert e YourCert, mover MyCert para YourCert resulta em um certificado com a ID YourCert, que contém os dados do MyCert anterior. Nenhum erro é retornado.

CertStore_DeleteCertificate exclui um certificado. A exclusão de um certificado faz os certificados restantes serem reindexados, começando em 0. Portanto, para excluir todos os certificados no repositório de certificados, você precisa criar um loop com base no número de certificados, mas exclua o certificado no índice 0 em cada iteração. Se você tentar excluir um certificado em um índice que não esteja mais em uso, CertStore_GetCertificateIdentifierAt retornará ERANGE.

O seguinte método funciona corretamente:

for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
    struct CertStore_Identifier id;
    result = CertStore_GetCertificateIdentifierAt(0, &id);
    CertStore_DeleteCertificate(id.identifier);
}

Usar um certificado para autenticação de rede

A API WifiConfig fornece funções que definem e retornam os certificados habilitados para uma configuração de Wi-Fi específica. Confira Configurar a rede EAP-TLS em um aplicativo para obter detalhes sobre como um aplicativo de alto nível pode configurar uma rede EAP-TLS que usa certificados para autenticação.

Exemplo de certificado

O aplicativo de exemplo de certificados mostra como um aplicativo pode usar as funções CertStore.

Compartilhar via