Gerenciar certificados em aplicativos de alto nível

Artigo
08/09/2023

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

Os certificados são armazenados no armazenamento não involatile no dispositivo do Azure Sphere. O repositório de certificados, ou repositório de certificados, pode conter até 24 kib de certificados. O tamanho máximo de um certificado é 8 KiB. Certificados de AC raiz normalmente são maiores que certificados de 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 é necessário por algumas bibliotecas para carregar um certificado para comunicações TLS.
Application_IsDeviceAuthReady verificar se a autenticação do dispositivo para o aplicativo atual está pronta.

Requisitos do CertStore

Os aplicativos que usam a API do 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 do manifesto do aplicativo

Para usar as APIs do repositório 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 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 está associado a uma ID (identificador de certificado). A 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', hifen (-). e sublinhado (_). Cada ID de certificado deve ser exclusiva 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 do azsphere. Consequentemente, se você carregar um certificado da linha de comando, todos os aplicativos que consultam, movem ou excluem esse certificado devem usar a mesma ID. Da mesma forma, se um aplicativo carregar o certificado, todos os comandos do azsphere que manipulam o certificado devem usar a mesma ID. Se você instalar um novo certificado com a mesma ID que um certificado existente de qualquer tipo, o novo certificado substituirá o existente.

Cuidado

Como as IDs de certificado são em todo o sistema para certificados de ca raiz e 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 chamada de função anterior, potencialmente causando falhas de conexão de rede. Recomendamos que você desenvolva procedimentos claros de atualização de certificado e escolha as IDs de certificado cuidadosamente.

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 de cliente, que consiste em um certificado público e uma chave privada
CertStore_InstallRootCACertificate instala um certificado de AC 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 do 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 por índice e podem ser recuperados por índice. O intervalo de valores de índice é executado 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, mover ou excluir o certificado e usar um certificado para autenticação.

Obter informações de certificado

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

CertStore_GetCertificateNotBefore obtém o tempo em que o certificado se torna válido
CertStore_GetCertificateNotAfter obtém o tempo 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

Os tempos não anteriores e não posteriores 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 repositório de certificados contiver MyCert e YourCert, mover MyCert para YourCert resulta em um único certificado com ID YourCert, que contém os dados do antigo 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 repositório de certificados, você precisa fazer 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á o 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 do 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.