Gerenciar certificados em aplicativos de alto nível

Artigo
10/23/2024

Importante

Esta é a documentação do Azure Sphere (Legado). O Azure Sphere (Legado) 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 certificado de dispositivo azsphere permite gerenciar certificados a partir da linha de comando.

Os certificados são armazenados em armazenamento não volátil no dispositivo Azure Sphere. O armazenamento de certificados, ou armazenamento de certificados, pode armazenar até 24 KiB de certificados. O tamanho máximo de um certificado é de 8 KiB. Os certificados de autoridade de certificação raiz geralmente são maiores do que os certificados de cliente. Além de usar o armazenamento 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 verificar se a autenticação de dispositivo para o aplicativo atual está pronta.

Requisitos do CertStore

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

Arquivos de cabeçalho

Inclua o cabeçalho CertStore em seu projeto:

 #include <applibs\certstore.h>

Configurações de manifesto do aplicativo

Para usar as APIs de armazenamento de certificados, você deve adicionar o recurso do CertStore aplicativo ao manifesto do aplicativo e definir o valor como true. O tópico de manifesto do aplicativo 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 do certificado

Cada certificado é associado a um identificador de certificado (ID). O ID 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'-'z', 'A'-'Z', '0'-'9', hífen (-). e sublinhado (_). Cada ID de certificado deve ser exclusivo em todo o dispositivo, independentemente do tipo de certificado que ele identifica.

O identificador de cada certificado é salvo no armazenamento 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 consultarem, moverem ou excluirem esse certificado deverão usar a mesma ID. Da mesma forma, se um aplicativo carregar o certificado, todos os comandos azsphere que manipularem o certificado deverão usar a mesma ID. Se você instalar um novo certificado com a mesma ID de um certificado existente de qualquer tipo, o novo certificado substituirá o existente.

Atenção

Como os IDs de certificado são de todo o sistema para certificados de CA de cliente e raiz, 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 chamada de função anterior, potencialmente causando falhas de conexão de rede. É altamente recomendável que você desenvolva procedimentos claros de atualização de certificado e escolha cuidadosamente os IDs de certificado.

Adicionar um certificado ao armazenamento de certificados

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

CertStore_InstallClientCertificate instala um certificado de cliente, que consiste em um certificado público e uma chave privada
CertStore_InstallRootCACertificate instala um certificado de autoridade de certificação raiz, que consiste em um certificado público

O certificado deve estar presente no dispositivo antes que o aplicativo possa instalá-lo. Os certificados devem estar na 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 adiciona-o ao armazenamento de certificados e torna-o disponível para utilização na autenticação. No armazenamento de certificados, os certificados são gerenciados por índice e podem ser recuperados por índice. O intervalo de valores de índice vai de 0 a (CertStore_GetCertificateCount - 1).

Um aplicativo pode obter a ID do certificado em um determinado índice chamando a função CertStore_GetCertificateIdentifierAt. Em seguida, ele pode usar a ID 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 do certificado

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

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

Os tempos não antes e não depois são úteis no gerenciamento do tempo de vida e das atualizações do certificado. Consulte 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 sua ID de certificado. Como as IDs de certificado devem ser exclusivas em um dispositivo, renomear um certificado dando-lhe a mesma ID que outro certificado exclui esse certificado. Por exemplo, se o armazenamento de certificados contiver MyCert e YourCert, mover MyCert para YourCert resultará em um único certificado com ID YourCert, que contém os dados do primeiro MyCert. Nenhum erro é retornado.

CertStore_DeleteCertificate exclui um único certificado. A exclusão de um certificado faz com que os certificados restantes sejam reindexados, começando em 0. Portanto, para excluir todos os certificados no armazenamento de certificados, você precisa fazer um loop com base no número de certificados, mas excluir o certificado no índice 0 em cada iteração. Se você tentar excluir um certificado em um índice que não está 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 Wi-Fi específica. Consulte 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 Certificados mostra como um aplicativo pode usar as funções CertStore.

Partilhar via