Verwalten von Zertifikaten in allgemeinen Anwendungen
Die CertStore-API ermöglicht es einer allgemeinen Anwendung, Zertifikate für die Verwendung bei der Netzwerkauthentifizierung zu verwalten. Mit dem azsphere device certificate können Sie Zertifikate über die Befehlszeile verwalten.
Zertifikate werden im nicht flüchtigen Speicher auf dem Azure Sphere-Gerät gespeichert. Der Zertifikatspeicher oder Zertifikatspeicher kann bis zu 24 KiB Zertifikate enthalten. Die maximale Größe für ein Zertifikat beträgt 8 KiB. Stammzertifizierungsstellenzertifikate sind in der Regel größer als Clientzertifikate. Zusätzlich zur Verwendung des Zertifikatspeichers können Sie auch auf das von Microsoft verwaltete Clientzertifikat zugreifen. Das von Microsoft verwaltete Clientzertifikat steht nur zur Verwendung zur Verfügung, wenn das Gerät mindestens einmal alle 24 Stunden mit dem Internet verbunden ist.
Verwenden des von Microsoft verwalteten Clientzertifikats
Verwenden Sie diese beiden Funktionen, um ein Clientzertifikat abzurufen und zu bestimmen, ob es einsatzbereit ist.
DeviceAuth_GetCertificatePath gibt einen Dateipfad zu einem Clientzertifikat zurück, das vom Betriebssystem verwaltet wird. Dieser Dateipfad ist für einige Bibliotheken erforderlich, um ein Zertifikat für die TLS-Kommunikation zu laden.
Application_IsDeviceAuthReady , um zu überprüfen, ob die Geräteauthentifizierung für die aktuelle Anwendung bereit ist.
CertStore-Anforderungen
Anwendungen, die die CertStore-API verwenden, müssen die entsprechenden Headerdateien enthalten und dem Anwendungsmanifest die CertStore-Funktion hinzufügen.
Headerdateien
Fügen Sie den CertStore-Header in Ihr Projekt ein:
#include <applibs\certstore.h>
Anwendungsmanifesteinstellungen
Um die Zertifikatspeicher-APIs verwenden zu können, müssen Sie die CertStore Anwendungsfunktion zum Anwendungsmanifest hinzufügen und den Wert auf truefestlegen. Das Thema Azure Sphere-Anwendungsmanifest enthält weitere Details zum Anwendungsmanifest.
{
"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
}
}
Zertifikat-IDs
Jedes Zertifikat ist einem Zertifikatbezeichner (ID) zugeordnet. Die Zertifikat-ID ist eine Zeichenfolge von 1 bis 16 Zeichen, die das Zertifikat auf dem Gerät eindeutig identifiziert. Gültige Zeichen sind 'a'-'z', 'A'-'Z', '0'-'9', Bindestrich (-). und Unterstrich (_). Jede Zertifikat-ID muss unabhängig vom Typ des identifizierten Zertifikats auf dem gesamten Gerät eindeutig sein.
Der Bezeichner jedes Zertifikats wird im Zertifikatspeicher gespeichert und geräteweit verwendet: von der CertStore-API , der WifiConfig-API und der azsphere CLI. Wenn Sie also ein Zertifikat über die Befehlszeile laden, müssen alle Anwendungen, die dieses Zertifikat abfragen, verschieben oder löschen, dieselbe ID verwenden. Wenn eine App das Zertifikat lädt, müssen alle azsphere-Befehle, die das Zertifikat bearbeiten, dieselbe ID verwenden. Wenn Sie ein neues Zertifikat mit der gleichen ID wie ein vorhandenes Zertifikat eines beliebigen Typs installieren, überschreibt das neue Zertifikat das vorhandene Zertifikat.
Vorsicht
Da Zertifikat-IDs sowohl für Client- als auch für Stammzertifizierungsstellenzertifikate systemweit sind, kann ein azsphere-Befehl oder ein Funktionsaufruf, der ein neues Zertifikat hinzufügt, ein Zertifikat überschreiben, das von einem früheren Befehl oder Funktionsaufruf hinzugefügt wurde, was zu Netzwerkverbindungsfehlern führen kann. Es wird dringend empfohlen, eindeutige Prozeduren für die Zertifikataktualisierung zu entwickeln und Zertifikat-IDs sorgfältig auszuwählen.
Hinzufügen eines Zertifikats zum Zertifikatspeicher
Um dem Zertifikatspeicher ein Zertifikat hinzuzufügen, ruft eine App eine der folgenden Funktionen auf:
- CertStore_InstallClientCertificate installiert ein Clientzertifikat, das aus einem öffentlichen Zertifikat und einem privaten Schlüssel besteht.
- CertStore_InstallRootCACertificate installiert ein Zertifikat der Stammzertifizierungsstelle, das aus einem öffentlichen Zertifikat besteht.
Das Zertifikat muss auf dem Gerät vorhanden sein, bevor es von der App installiert werden kann. Zertifikate müssen in der PKCS1- oder PKCS8-Syntax und im PEM-Format vorliegen, damit sie auf das Azure Sphere-Gerät geladen werden können. Unter Abrufen und Bereitstellen von Zertifikaten für EAP-TLS-Netzwerke wird beschrieben, wie Zertifikate abgerufen und auf ein Gerät geladen werden. Microsoft stellt keine Zertifikate bereit.
Durch die Installation eines Zertifikats wird es dem Zertifikatspeicher hinzugefügt und zur Verwendung bei der Authentifizierung verfügbar. Innerhalb des Zertifikatspeichers werden Zertifikate nach Index verwaltet und können nach Index abgerufen werden. Der Bereich der Indexwerte wird von 0 bis (CertStore_GetCertificateCount - 1) ausgeführt.
Eine App kann die ID des Zertifikats an einem bestimmten Index abrufen, indem sie die CertStore_GetCertificateIdentifierAt-Funktion aufruft. Anschließend kann die Zertifikat-ID in Aufrufen verwendet werden, um Informationen zum Zertifikat abzurufen, das Zertifikat zu verschieben oder zu löschen und ein Zertifikat für die Authentifizierung zu verwenden.
Abrufen von Zertifikatinformationen
Die CertStore-API enthält mehrere Funktionen, die Informationen zu einem gespeicherten Zertifikat zurückgeben:
- CertStore_GetCertificateNotBefore ruft den Zeitpunkt ab, zu dem das Zertifikat gültig wird.
- CertStore_GetCertificateNotAfter ruft den Zeitpunkt ab, zu dem das Zertifikat abläuft.
- CertStore_GetCertificateIssuerName ruft den Namen des Zertifikatausstellers ab.
- CertStore_GetCertificateSubjectName ruft den Namen des Antragstellers des Zertifikats ab. Das heißt, was das Zertifikat schützt
Die Not-Before- und Not-After-Zeiten sind nützlich für die Verwaltung der Zertifikatlebensdauer und -updates. Weitere Informationen finden Sie unter Zertifikatlebenszyklus und Verlängerung .
Umbenennen oder Löschen eines Zertifikats
Um ein Zertifikat umzubenennen oder zu löschen, ruft eine App CertStore_MoveCertificate oder CertStore_DeleteCertificate auf.
CertStore_MoveCertificate benennt ein Zertifikat um, indem seine Zertifikat-ID geändert wird. Da Zertifikat-IDs auf einem Gerät eindeutig sein müssen, wird das Zertifikat durch Das Umbenennen eines Zertifikats durch Zuweisen derselben ID wie ein anderes Zertifikat gelöscht. Wenn der Zertifikatspeicher z. B. und YourCertenthältMyCert, führt der Wechsel MyCert zu YourCert zu einem einzelnen Zertifikat mit der ID YourCert, das die Daten aus dem vorherigen MyCertenthält. Es wird kein Fehler zurückgegeben.
CertStore_DeleteCertificate löscht ein einzelnes Zertifikat. Das Löschen eines Zertifikats führt dazu, dass die verbleibenden Zertifikate neu indiziert werden, beginnend bei 0. Wenn Sie daher alle Zertifikate im Zertifikatspeicher löschen möchten, müssen Sie eine Schleife basierend auf der Anzahl der Zertifikate ausführen, aber das Zertifikat bei Index 0 in jeder Iteration löschen. Wenn Sie versuchen, ein Zertifikat an einem Index zu löschen, der nicht mehr verwendet wird, gibt CertStore_GetCertificateIdentifierAt ERANGE zurück.
Die folgende Methode funktioniert ordnungsgemäß:
for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
struct CertStore_Identifier id;
result = CertStore_GetCertificateIdentifierAt(0, &id);
CertStore_DeleteCertificate(id.identifier);
}
Verwenden eines Zertifikats für die Netzwerkauthentifizierung
Die WifiConfig-API stellt Funktionen bereit, die die Zertifikate festlegen und zurückgeben, die für eine bestimmte Wi-Fi-Konfiguration aktiviert sind. Ausführliche Informationen dazu, wie eine allgemeine Anwendung ein EAP-TLS-Netzwerk einrichten kann, das Zertifikate für die Authentifizierung verwendet, finden Sie unter Einrichten eines EAP-TLS-Netzwerks in einer App .
Zertifikatbeispiel
Die Beispielanwendung Zertifikate zeigt, wie eine Anwendung die CertStore-Funktionen verwenden kann.