Gestire i certificati nelle applicazioni di alto livello
L'API CertStore consente a un'applicazione di alto livello di gestire i certificati da usare nell'autenticazione di rete. Il certificato dispositivo sfera az consente di gestire i certificati dalla riga di comando.
I certificati vengono archiviati in memoria nonvolatile nel dispositivo Azure Sphere. L'archivio certificati, o archivio certificati, può contenere fino a 24 KiB di certificati. La dimensione massima per un certificato è 8 KiB. I certificati CA radice sono in genere più grandi dei certificati client. Oltre a usare l'archivio certificati, è anche possibile accedere al certificato client gestito da Microsoft. Il certificato client gestito da Microsoft sarà disponibile per l'uso solo quando il dispositivo è connesso a Internet almeno una volta ogni 24 ore.
Usare il certificato client gestito da Microsoft
Usare queste due funzioni per ottenere un certificato client e determinare se è pronto per l'uso.
DeviceAuth_GetCertificatePath restituisce un percorso file a un certificato client gestito dal sistema operativo. Questo percorso di file è necessario per alcune librerie per caricare un certificato per le comunicazioni TLS.
Application_IsDeviceAuthReady per verificare se l'autenticazione del dispositivo per l'applicazione corrente è pronta.
Requisiti di CertStore
Le applicazioni che utilizzano l'API CertStore devono includere i file di intestazione appropriati e aggiungere la funzionalità CertStore al manifesto dell'applicazione.
File di intestazione
Includere l'intestazione CertStore nel progetto:
#include <applibs\certstore.h>
Impostazioni del manifesto dell'applicazione
Per utilizzare le API dell'archivio certificati, è necessario aggiungere la funzionalità dell'applicazione CertStore al manifesto dell'applicazione e impostare il valore truesu . L'argomento manifesto dell'applicazione Azure Sphere contiene ulteriori dettagli sul manifesto dell'applicazione.
{
"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
}
}
ID certificato
Ogni certificato è associato a un identificatore (ID) del certificato. L'ID certificato è una stringa di 1-16 caratteri che identifica in modo univoco il certificato nel dispositivo. I caratteri validi sono 'a'-'z', 'A'-'Z', '0'-'9', segno meno (-). e carattere di sottolineatura (_). Ogni ID certificato deve essere univoco nel dispositivo, indipendentemente dal tipo di certificato identificato.
L'identificatore di ogni certificato viene salvato nell'archivio certificati e viene usato a livello di dispositivo: dall'API CertStore , dall'API WifiConfig e dall'estensione CLI di Azure. Di conseguenza, se si carica un certificato dalla riga di comando, tutte le applicazioni che ese necessario eseguire query, spostare o eliminare il certificato devono usare lo stesso ID. Analogamente, se un'app carica il certificato, tutti az sphere i comandi che manipolano il certificato devono usare lo stesso ID. Se si installa un nuovo certificato con lo stesso ID di un certificato esistente di qualsiasi tipo, il nuovo certificato sovrascriverà quello esistente.
Attenzione
Poiché gli ID certificato sono a livello di sistema sia per i certificati client che per i certificati CA radice, un comando az sphere o una chiamata funzione che aggiunge un nuovo certificato può sovrascrivere un certificato aggiunto da una chiamata di comando o funzione precedente, causando potenzialmente errori di connessione di rete. È consigliabile sviluppare procedure di aggiornamento dei certificati chiare e scegliere con attenzione gli ID certificato.
Aggiungere un certificato all'archivio certificati
Per aggiungere un certificato all'archivio certificati, un'app chiama una delle funzioni seguenti:
- CertStore_InstallClientCertificate installa un certificato client costituito da un certificato pubblico e da una chiave privata
- CertStore_InstallRootCACertificate installa un certificato CA radice costituito da un certificato pubblico
Il certificato deve essere presente nel dispositivo prima che l'app possa installarlo. I certificati devono essere in sintassi PKCS1 o PKCS8 e nel formato .pem per essere caricati nel dispositivo Azure Sphere. L'acquisizione e la distribuzione di certificati per le reti EAP-TLS descrive come acquisire certificati e caricarli in un dispositivo. Microsoft non fornisce certificati.
L'installazione di un certificato lo aggiunge all'archivio certificati e lo rende disponibile per l'uso nell'autenticazione. All'interno dell'archivio certificati, i certificati vengono gestiti dall'indice e possono essere recuperati dall'indice. L'intervallo di valori di indice viene eseguito da 0 a (CertStore_GetCertificateCount - 1).
Un'app può ottenere l'ID del certificato in corrispondenza di un determinato indice chiamando la funzione CertStore_GetCertificateIdentifierAt. Può quindi usare l'ID certificato nelle chiamate per ottenere informazioni sul certificato, spostarlo o eliminarlo e usare un certificato per l'autenticazione.
Ottenere informazioni sul certificato
L'API CertStore include diverse funzioni che restituiscono informazioni su un certificato archiviato:
- CertStore_GetCertificateNotBefore ottiene l'ora in cui il certificato diventa valido
- CertStore_GetCertificateNotAfter ottiene l'ora di scadenza del certificato
- CertStore_GetCertificateIssuerName ottiene il nome dell'emittente del certificato
- CertStore_GetCertificateSubjectName ottiene il nome dell'oggetto del certificato; vale a dire ciò che protegge il certificato
I tempi non precedenti e non successivi sono utili per gestire la durata e gli aggiornamenti dei certificati. Per informazioni dettagliate, vedere Ciclo di vita e rinnovo dei certificati.
Rinominare o eliminare un certificato
Per rinominare o eliminare un certificato, un'app chiama CertStore_MoveCertificate o CertStore_DeleteCertificate.
CertStore_MoveCertificate rinomina un certificato modificandone l'ID certificato. Poiché gli ID certificato devono essere univoci in un dispositivo, la ridenominazione di un certificato assegnandovi lo stesso ID di un altro certificato comporta l'eliminazione del certificato. Ad esempio, se l'archivio certificati contiene e , passando MyCert ai YourCert risultati in un singolo certificato con ID YourCert, che contiene i dati della prima MyCert.YourCertMyCert Non viene restituito alcun errore.
CertStore_DeleteCertificate elimina un singolo certificato. L'eliminazione di un certificato comporta la reindicizzazione dei certificati rimanenti, a partire da 0. Pertanto, per eliminare tutti i certificati nell'archivio certificati, è necessario eseguire un ciclo in base al numero di certificati, ma eliminare il certificato all'indice 0 in ogni iterazione. Se si prova a eliminare un certificato in corrispondenza di un indice non più in uso, CertStore_GetCertificateIdentifierAt restituisce ERANGE.
Il metodo seguente funziona correttamente:
for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
struct CertStore_Identifier id;
result = CertStore_GetCertificateIdentifierAt(0, &id);
CertStore_DeleteCertificate(id.identifier);
}
Usare un certificato per l'autenticazione di rete
L'API WifiConfig fornisce funzioni che impostano e restituiscono i certificati abilitati per una particolare configurazione Wi-Fi. Vedere Configurare la rete EAP-TLS in un'app per informazioni dettagliate su come un'applicazione di livello elevato può configurare una rete EAP-TLS che usa i certificati per l'autenticazione.
Esempio di certificato
L'applicazione di esempio Certificati mostra come un'applicazione può usare le funzioni CertStore.