Gestire i certificati in app di alto livelloManage certificates in high-level applications

L'API CertStore consente a un'applicazione di alto livello di gestire i certificati da usare nell'autenticazione della rete.The CertStore API lets a high-level application manage certificates for use in network authentication. Il certificato del dispositivo azsphere consente di gestire i certificati dalla riga di comando.The azsphere device certificate lets you manage certificates from the command line.

I certificati sono archiviati nell'archiviazione non volatile nel dispositivo Azure Sphere.Certificates are stored in nonvolatile storage on the Azure Sphere device. L' archivio certificati può contenere fino a 24 KiB di certificati.The certificate store , or cert store, can hold up to 24 KiB of certificates. Le dimensioni massime per un certificato sono 8 KiB.The maximum size for a certificate is 8 KiB. I certificati CA radice presentano in genere dimensioni più elevate rispetto ai certificati client.Root CA certificates are typically larger than client certificates. Oltre a usare l'archivio certificati, è anche possibile accedere al certificato client gestito da Microsoft.In addition to using the cert store, you can also access the Microsoft-managed client certificate. Il certificato client gestito da Microsoft sarà disponibile per l'uso solo quando il dispositivo è connesso a Internet almeno una volta ogni 24 ore.The Microsoft-managed client certificate will only be available for use when the device is connected to the internet at least once every 24 hours.

Usare il certificato client gestito da MicrosoftUse the Microsoft-managed client certificate

Utilizzare queste due funzioni per ottenere un certificato client e determinare se è pronto per l'utilizzo.Use these two functions to obtain a client certificate and determine whether it is ready for use.

  • DeviceAuth_GetCertificatePath restituisce un percorso di file a un certificato client gestito dal sistema operativo.DeviceAuth_GetCertificatePath returns a file path to a client certificate managed by the OS. Questo percorso di file è richiesto da alcune librerie per caricare un certificato per le comunicazioni TLS.This file path is required by some libraries to load a certificate for TLS communications.

  • Application_IsDeviceAuthReady per verificare se l'autenticazione del dispositivo per l'applicazione corrente è pronta.Application_IsDeviceAuthReady to verify whether device authentication for the current application is ready.

Requisiti di CertStoreCertStore requirements

Le applicazioni che usano l'API CertStore devono includere i file di intestazione appropriati e aggiungere la funzionalità CertStore al manifesto dell'applicazione.Applications that use the CertStore API must include the appropriate header files and add the CertStore capability to the application manifest.

File di intestazioneHeader files

Includere l'intestazione CertStore nel progetto:Include the CertStore header in your project:

 #include <applibs\certstore.h>

Impostazioni del manifesto dell'applicazioneApplication manifest settings

Per usare le API dell'archivio certificati, è necessario aggiungere la funzionalità dell'applicazione CertStore al manifesto dell'applicazione e quindi impostare il valore su true.To use the certificate store APIs, you must add the CertStore application capability to the application manifest and set the value to true. Nell'argomento Manifesto dell'applicazione di Azure Sphere sono disponibili informazioni più dettagliate sul manifesto dell'applicazione.The Azure Sphere application manifest topic has more details about the application manifest.

{
  "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 certificatoCertificate IDs

Ogni certificato è associato a un identificatore (ID) del certificato.Every certificate is associated with a certificate identifier (ID). L'ID certificato è una stringa con una lunghezza compresa tra 1 e 16 caratteri che identifica in modo univoco il certificato nel dispositivo.The certificate ID is a string of 1-16 characters that uniquely identifies the certificate on the device. I caratteri validi sono 'a'-'z', 'A'-'Z', '0'-'9', trattino (-)Valid characters are 'a'-'z', 'A'-'Z', '0'-'9', hyphen (-). e carattere di sottolineatura ().and underscore (). Ogni ID certificato deve essere univoco all'interno del dispositivo, indipendentemente dal tipo di certificato che identifica.Every certificate ID must be unique across the device, regardless of the type of certificate that it identifies.

Ogni identificatore del certificato viene salvato nell'archivio certificati e viene usato a livello di dispositivo: dall'API CertStore, dall'API WifiConfig e dall'interfaccia della riga di comando azsphere.Each certificate's identifier is saved in the certificate store and is used device-wide: by the CertStore API, the WifiConfig API, and the azsphere CLI. Di conseguenza, se si carica un certificato dalla riga di comando, le eventuali applicazioni che eseguono query, spostano o eliminano il certificato devono usare lo stesso ID.Consequently, if you load a certificate from the command line, any applications that query, move, or delete that certificate must use the same ID. Allo stesso modo, se un'app carica il certificato, qualsiasi comando di azsphere che modifica il certificato deve usare lo stesso ID.Similarly, if an app loads the certificate, any azsphere commands that manipulate the certificate must use the same ID. Se si installa un nuovo certificato con lo stesso ID di un certificato esistente di qualsiasi tipo, il nuovo certificato sovrascriverà quello esistente.If you install a new certificate with the same ID as an existing certificate of any type, the new certificate will overwrite the existing one.

Attenzione

Poiché gli ID certificato sono a livello di sistema sia per il certificato client che per il certificato CA radice, un comando azsphere o una chiamata di funzione che aggiunge un nuovo certificato può sovrascrivere un certificato aggiunto da un comando o una chiamata di funzione precedente, generando possibilmente errori di connessione di rete.Because certificate IDs are system-wide for both client and Root CA certificates, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. È consigliabile sviluppare procedure ben definite per l'aggiornamento dei certificati e scegliere con attenzione gli ID certificato.We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

Aggiungere un nuovo certificato all'archivio certificatiAdd a certificate to the certificate store

Per aggiungere un certificato all'archivio certificati, un'app chiama una delle funzioni seguenti:To add a certificate to the certificate store, an app calls one of the following functions:

  • CertStore_InstallClientCertificate installa un certificato client costituito da un certificato pubblico e da una chiave privataCertStore_InstallClientCertificate installs a client certificate, which consists of a public certificate and a private key
  • CertStore_InstallRootCACertificate installa un certificato CA radice che è costituito da un certificato pubblicoCertStore_InstallRootCACertificate installs a Root CA certificate, which consists of a public certificate

Il certificato deve essere presente nel dispositivo prima che l'app possa installarlo.The certificate must be present on the device before the app can install it. Per caricare i certificati nel dispositivo Azure Sphere, è necessario che siano in formato PEM con sintassi PKCS1 o PKCS8.Certificates must be in PKCS1 or PKCS8 syntax and the .pem format to load onto the Azure Sphere device. Per informazioni sull'acquisizione dei certificati e sul caricamento in un dispositivo, vedere Acquisire e distribuire i certificati per le reti EAP-TLS.Acquire and deploy certificates for EAP-TLS networks describes how to acquire certificates and load them onto a device. Microsoft non fornisce certificati.Microsoft does not supply certificates.

L'installazione di un certificato lo aggiunge all'archivio certificati e lo rende disponibile per l'uso nell'autenticazione.Installing a certificate adds it to the certificate store and makes it available for use in authentication. All'interno dell'archivio certificati, i certificati vengono gestiti dall'indice e possono essere recuperati in base all'indice.Within the certificate store, certificates are managed by index and can be retrieved by index. L'intervallo dei valori di indice è compreso tra 0 e (CertStore_GetCertificateCount - 1).The range of index values runs from 0 to (CertStore_GetCertificateCount - 1).

Un'app può ottenere l'ID del certificato in corrispondenza di un indice specifico chiamando la funzione CertStore_GetCertificateIdentifierAt.An app can get the ID of the certificate at a particular index by calling the CertStore_GetCertificateIdentifierAt function. Può quindi usare l'ID certificato nelle chiamate per ottenere informazioni sul certificato, per spostare o eliminare il certificato e per usare un certificato per l'autenticazione.It can then use the certificate ID in calls to get information about the certificate, to move or delete the certificate, and to use a certificate for authentication.

Ottenere le informazioni sul certificatoGet certificate information

L'API CertStore include numerose funzioni che restituiscono informazioni su un certificato archiviato:The CertStore API includes several functions that return information about a stored certificate:

Gli orari per not-before e not-after sono utili per la gestione della durata e degli aggiornamenti dei certificati.The not-before and not-after times are useful in managing certificate lifetime and updates. Per informazioni dettagliate, vedere Ciclo di vita e rinnovo dei certificati.See Certificate life cycle and renewal for details.

Rinominare o eliminare un certificatoRename or delete a certificate

Per rinominare o eliminare un certificato, un'app chiama CertStore_MoveCertificate o CertStore_DeleteCertificate.To rename or delete a certificate, an app calls CertStore_MoveCertificate or CertStore_DeleteCertificate.

CertStore_MoveCertificate rinomina un certificato modificando il relativo ID certificato.CertStore_MoveCertificate renames a certificate by changing its certificate ID. Poiché gli ID certificato devono essere univoci in un dispositivo, la ridenominazione di un certificato assegnando a tale certificato lo stesso ID di un altro certificato comporta l'eliminazione del certificato.Because certificate IDs must be unique across a device, renaming a certificate by giving it the same ID as another certificate deletes that certificate. Se, ad esempio, l'archivio certificati contiene MyCert e YourCert, lo spostamento di MyCert in YourCert genera un singolo certificato con l'ID YourCert, che contiene i dati del certificato MyCert precedente.For example, if the certificate store contains MyCert and YourCert, moving MyCert to YourCert results in a single certificate with ID YourCert, which contains the data from the former MyCert. Non viene restituito alcun errore.No error is returned.

CertStore_DeleteCertificate elimina un singolo certificato.CertStore_DeleteCertificate deletes a single certificate. L'eliminazione di un certificato causa la reindicizzazione dei certificati rimanenti, a partire da 0.Deleting a certificate causes the remaining certificates to be reindexed, starting at 0. Di conseguenza, per eliminare tutti i certificati nell'archivio certificati, è necessario eseguire un ciclo in base al numero di certificati, ma eliminare il certificato in corrispondenza dell'indice 0 in ogni iterazione.Therefore, to delete all the certificates in the certificate store, you need to loop based on the number of certificates but delete the certificate at index 0 in each iteration. Se si tenta di eliminare un certificato in un indice non più in uso, CertStore_GetCertificateIdentifierAt restituisce ERANGE.If you try to delete a certificate at an index that is no longer in use, CertStore_GetCertificateIdentifierAt returns ERANGE.

Il metodo seguente funziona correttamente:The following method works correctly:

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 della reteUse a certificate for network authentication

L'API WifiConfig fornisce funzioni che impostano e restituiscono i certificati abilitati per una configurazione Wi-Fi specifica.The WifiConfig API provides functions that set and return the certificates that are enabled for a particular Wi-Fi configuration. Vedere Configurare la rete EAP-TLS in un'app per informazioni dettagliate sul modo in cui un'applicazione di alto livello può configurare una rete EAP-TLS che usa certificati per l'autenticazione.See Set up EAP-TLS network in an app for details about how a high-level application can set up an EAP-TLS network that uses certificates for authentication.

Esempio di certificatoCertificate sample

L'applicazione di esempio Certificates illustra come usare le funzioni CertStore in un'applicazione.The Certificates sample application shows how an application can use the CertStore functions.