Gerir certificados em aplicações de alto nível

Artigo
08/09/2023

A API CertStore permite que uma aplicação de alto nível faça a gestão de certificados para utilização na autenticação de rede. O certificado de dispositivo az sphere permite-lhe gerir certificados a partir da linha de comandos.

Os certificados são armazenados num armazenamento não complicado no dispositivo do Azure Sphere. O arquivo de certificados, ou arquivo de certificados, pode conter até 24 KiB de certificados. O tamanho máximo de um certificado é 8 KiB. Normalmente, os certificados de AC de raiz são maiores do que os certificados de cliente. Além de utilizar o arquivo de certificados, também pode aceder ao certificado de cliente gerido pela Microsoft. O certificado de cliente gerido pela Microsoft só estará disponível para utilização quando o dispositivo estiver ligado à Internet pelo menos uma vez a cada 24 horas.

Utilizar o certificado de cliente gerido pela Microsoft

Utilize estas duas funções para obter um certificado de cliente e determinar se está pronto para ser utilizado.

DeviceAuth_GetCertificatePath devolve um caminho de ficheiro para um certificado de cliente gerido pelo SO. Este caminho de ficheiro é exigido por algumas bibliotecas para carregar um certificado para comunicações TLS.
Application_IsDeviceAuthReady para verificar se a autenticação do dispositivo para a aplicação atual está pronta.

Requisitos do CertStore

As aplicações que utilizam a API CertStore têm de incluir os ficheiros de cabeçalho adequados e adicionar a capacidade CertStore ao manifesto da aplicação.

Ficheiros de cabeçalho

Inclua o cabeçalho CertStore no projeto:

 #include <applibs\certstore.h>

Definições do manifesto da aplicação

Para utilizar as APIs do arquivo de certificados, tem de adicionar a capacidade de aplicação CertStore ao manifesto da aplicação e definir o valor como true. O tópico de manifesto da aplicação do Azure Sphere tem mais detalhes sobre o manifesto da aplicação.

{
  "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 um identificador de certificado (ID). O ID do certificado é uma cadeia de 1 a 16 carateres que identifica exclusivamente o certificado no dispositivo. Os carateres válidos são 'a'-'z', 'A'-'Z', '0'-'9', hífen (-). e caráter de sublinhado (_). Cada ID de certificado tem de ser exclusivo em todo o dispositivo, independentemente do tipo de certificado que identificar.

O identificador de cada certificado é guardado no arquivo de certificados e é utilizado em todo o dispositivo: pela API CertStore , pela API WifiConfig e pela extensão da CLI do Azure. Consequentemente, se carregar um certificado a partir da linha de comandos, todas as aplicações que consultam, movem ou eliminam esse certificado têm de utilizar o mesmo ID. Da mesma forma, se uma aplicação carregar o certificado, todos az sphere os comandos que manipulam o certificado têm de utilizar o mesmo ID. Se instalar um novo certificado com o mesmo ID que um certificado existente de qualquer tipo, o novo certificado substituirá o existente.

Atenção

Uma vez que os IDs de certificado são ao nível do sistema para certificados de AC de cliente e de raiz, um comando az sphere ou uma chamada de função que adiciona um novo certificado pode substituir um certificado que foi adicionado por uma chamada de comando ou função anterior, potencialmente causando falhas de ligação de rede. Recomendamos vivamente que desenvolva procedimentos de atualização de certificados claros e escolha cuidadosamente os IDs de certificado.

Adicionar um certificado ao arquivo de certificados

Para adicionar um certificado ao arquivo de certificados, uma aplicação chama uma das seguintes funções:

CertStore_InstallClientCertificate instala um certificado de cliente, que consiste num certificado público e numa chave privada
CertStore_InstallRootCACertificate instala um certificado de AC de Raiz, que consiste num certificado público

O certificado tem de estar presente no dispositivo antes de a aplicação poder instalá-lo. Os certificados têm de estar na sintaxe PKCS1 ou PKCS8 e no formato .pem para carregar para o dispositivo do Azure Sphere. Adquirir e implementar certificados para redes EAP-TLS descreve como adquirir certificados e carregá-los num dispositivo. A Microsoft não fornece certificados.

Instalar um certificado adiciona-o ao arquivo de certificados e disponibiliza-o para utilização na autenticação. No arquivo de certificados, os certificados são geridos por índice e podem ser obtidos por índice. O intervalo de valores de índice é executado de 0 a (CertStore_GetCertificateCount - 1).

Uma aplicação pode obter o ID do certificado num determinado índice ao chamar a função CertStore_GetCertificateIdentifierAt. Em seguida, pode utilizar o ID do certificado em chamadas para obter informações sobre o certificado, mover ou eliminar o certificado e utilizar um certificado para autenticação.

Obter informações do certificado

A API CertStore inclui várias funções que devolvem 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 requerente do certificado; ou seja, o que o certificado protege

Os tempos não anteriores e não posteriores são úteis na gestão da duração do certificado e das atualizações. Veja Ciclo de vida e renovação do certificado para obter detalhes.

Mudar o nome ou eliminar um certificado

Para mudar o nome ou eliminar um certificado, uma aplicação chama CertStore_MoveCertificate ou CertStore_DeleteCertificate.

CertStore_MoveCertificate muda o nome de um certificado ao alterar o respetivo ID de certificado. Uma vez que os IDs de certificado têm de ser exclusivos num dispositivo, mudar o nome de um certificado ao atribuir-lhe o mesmo ID que outro certificado elimina esse certificado. Por exemplo, se o arquivo de certificados MyCert contiver e YourCert, mover MyCert para YourCert resulta num único certificado com o ID YourCert, que contém os dados do anterior MyCert. Não é devolvido nenhum erro.

CertStore_DeleteCertificate elimina um único certificado. A eliminação de um certificado faz com que os restantes certificados sejam reindexados, a partir de 0. Por conseguinte, para eliminar todos os certificados no arquivo de certificados, tem de repetir o ciclo com base no número de certificados, mas eliminar o certificado no índice 0 em cada iteração. Se tentar eliminar um certificado num índice que já não está a ser utilizado, CertStore_GetCertificateIdentifierAt devolve 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);
}

Utilizar um certificado para autenticação de rede

A API WifiConfig fornece funções que definem e devolvem os certificados que estão ativados para uma configuração Wi-Fi específica. Veja Configurar a rede EAP-TLS numa aplicação para obter detalhes sobre como uma aplicação de alto nível pode configurar uma rede EAP-TLS que utiliza certificados para autenticação.

Exemplo de certificado

A aplicação de exemplo Certificados mostra como uma aplicação pode utilizar as funções CertStore.

Partilhar via