Verwalten von Zertifikaten in allgemeinen AnwendungenManage certificates in high-level applications

Die CertStore-API ermöglicht einer allgemeinen Anwendung das Verwalten von Zertifikaten für die Verwendung bei der Netzwerkauthentifizierung.The CertStore API lets a high-level application manage certificates for use in network authentication. Mit dem azsphere-Gerätezertifikat können Sie Zertifikate über die Befehlszeile verwalten.The azsphere device certificate lets you manage certificates from the command line.

Zertifikate werden im nicht flüchtigen Speicher auf dem Azure Sphere-Gerät gespeichert.Certificates are stored in nonvolatile storage on the Azure Sphere device. Der Zertifikatspeicher kann bis zu 24 KiB an Zertifikaten enthalten.The certificate store, or cert store, can hold up to 24 KiB of certificates. Die maximale Größe eines Zertifikat beträgt 8 KiB.The maximum size for a certificate is 8 KiB. Zertifikate der Stammzertifizierungsstelle sind in der Regel größer als Clientzertifikate.Root CA certificates are typically larger than client certificates.

CertStore-AnforderungenCertStore requirements

Anwendungen, die die CertStore-API verwenden, müssen die entsprechenden Headerdateien umfassen und die CertStore-Funktion zum Anwendungsmanifest hinzufügen.Applications that use the CertStore API must include the appropriate header files and add the CertStore capability to the application manifest.

HeaderdateienHeader files

Fügen Sie den CertStore-Header zu Ihrem Projekt hinzu:Include the CertStore header in your project:

 #include <applibs\certstore.h>

Einstellungen für das AnwendungsmanifestApplication manifest settings

Für die Verwendung der Zertifikatspeicher-APIs müssen Sie dem Anwendungsmanifest die Anwendungsfunktion CertStore hinzufügen und den Wert auf true festlegen.To use the certificate store APIs, you must add the CertStore application capability to the application manifest and set the value to true. Das Thema Azure Sphere-Anwendungsmanifest enthält weitere Details zum Anwendungsmanifest.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
  }
}

Zertifikat-IDsCertificate IDs

Jedes Zertifikat wird einer Zertifikat-ID zugeordnet.Every certificate is associated with a certificate identifier (ID). Die Zertifikat-ID ist eine Zeichenfolge mit 1 bis 16 Zeichen, die das Zertifikat auf dem Gerät eindeutig identifiziert.The certificate ID is a string of 1-16 characters that uniquely identifies the certificate on the device. Gültige Zeichen sind die Kleinbuchstaben „a“ bis „z“, die Großbuchstaben „A“ bis „Z“, die Zahlen „0“ bis „9“ sowie Bindestriche („-“).Valid characters are 'a'-'z', 'A'-'Z', '0'-'9', hyphen (-). Unterstriche können ebenfalls verwendet werden („“).and underscore (). Jede Zertifikat-ID muss unabhängig vom Typ des identifizierten Zertifikats auf dem gesamten Gerät eindeutig sein.Every certificate ID must be unique across the device, regardless of the type of certificate that it identifies.

Die Bezeichner der einzelnen Zertifikate werden im Zertifikatspeicher gespeichert und geräteweit von der CertStore-API, der WifiConfig-API und der azsphere-CLI verwendet.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. Wenn Sie also ein Zertifikat über die Befehlszeile laden, müssen alle Anwendungen, die dieses Zertifikat abfragen, verschieben oder löschen, dieselbe ID verwenden.Consequently, if you load a certificate from the command line, any applications that query, move, or delete that certificate must use the same ID. Wenn eine App das Zertifikat lädt, müssen alle azsphere-Befehle, die das Zertifikat bearbeiten, dieselbe ID verwenden.Similarly, if an app loads the certificate, any azsphere commands that manipulate the certificate must use the same ID. Wenn Sie ein neues Zertifikat mit derselben ID wie ein vorhandenes Zertifikat eines beliebigen Typs installieren, überschreibt das neue das vorhandene Zertifikat.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.

Achtung

Da Zertifikat-IDs systemweit für Clientzertifikate und Zertifikate der Stammzertifizierungsstelle gelten, kann ein azsphere-Befehl oder ein Funktionsaufruf, der ein neues Zertifikat hinzufügt, ein Zertifikat überschreiben, das mit einem früheren Befehl oder Funktionsaufruf hinzugefügt wurde. Dies kann Netzwerkverbindungsfehler verursachen.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. Es wird dringend empfohlen, klare Verfahren zum Aktualisieren von Zertifikaten zu entwickeln und Zertifikat-IDs sorgfältig auszuwählen.We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

Hinzufügen eines Zertifikats zum ZertifikatspeicherAdd a certificate to the certificate store

Eine App ruft eine der folgenden Funktionen auf, um ein Zertifikat zum Zertifikatspeicher hinzuzufügen:To add a certificate to the certificate store, an app calls one of the following functions:

  • Mit CertStore_InstallClientCertificate wird ein Clientzertifikat installiert, das aus einem öffentlichen Zertifikat und einem privaten Schlüssel besteht.CertStore_InstallClientCertificate installs a client certificate, which consists of a public certificate and a private key
  • Mit CertStore_InstallRootCACertificate wird ein Zertifikat der Stammzertifizierungsstelle installiert, das aus einem öffentlichen Zertifikat besteht.CertStore_InstallRootCACertificate installs a Root CA certificate, which consists of a public certificate

Das Zertifikat muss auf dem Gerät vorhanden sein, bevor es von der App installiert werden kann.The certificate must be present on the device before the app can install it. Die Zertifikate müssen die PKCS1- oder PKCS8-Syntax und das PEM-Format aufweisen, um auf das Azure Sphere-Gerät geladen werden zu können.Certificates must be in PKCS1 or PKCS8 syntax and the .pem format to load onto the Azure Sphere device. Im Artikel Abrufen und Bereitstellen von Zertifikaten für EAP-TLS-Netzwerke wird beschrieben, wie Sie Zertifikate abrufen und auf ein Gerät laden.Acquire and deploy certificates for EAP-TLS networks describes how to acquire certificates and load them onto a device. Microsoft stellt keine Zertifikate bereit.Microsoft does not supply certificates.

Durch die Installation eines Zertifikats wird dieses zum Zertifikatspeicher hinzugefügt und zur Verwendung bei der Authentifizierung zur Verfügung gestellt.Installing a certificate adds it to the certificate store and makes it available for use in authentication. Im Zertifikatspeicher werden Zertifikate über einen Index verwaltet und können über diesen abgerufen werden.Within the certificate store, certificates are managed by index and can be retrieved by index. Der Bereich der Indexwerte reicht von „0“ bis (CertStore_GetCertificateCount – 1).The range of index values runs from 0 to (CertStore_GetCertificateCount - 1).

Eine App kann durch das Aufrufen der CertStore_GetCertificateIdentifierAt-Funktion die ID des Zertifikats bei einem bestimmten Index abrufen.An app can get the ID of the certificate at a particular index by calling the CertStore_GetCertificateIdentifierAt function. Anschließend kann die Zertifikat-ID in Aufrufen verwendet werden, um Informationen über das Zertifikat zu erhalten, dieses zu verschieben oder zu löschen und ein Zertifikat für die Authentifizierung zu verwenden.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.

Abrufen von ZertifikatinformationenGet certificate information

Die CertStore-API umfasst mehrere Funktionen, die Informationen zu einem gespeicherten Zertifikat zurückgeben:The CertStore API includes several functions that return information about a stored certificate:

Die Zeitpunkte „NotBefore“ und „NotAfter“ sind bei der Verwaltung der Zertifikatlebensdauer und Updates nützlich.The not-before and not-after times are useful in managing certificate lifetime and updates. Informationen finden Sie unter Zertifikatlebenszyklus und -verlängerung.See Certificate life cycle and renewal for details.

Umbenennen oder Löschen eines ZertifikatsRename or delete a certificate

Eine App ruft CertStore_MoveCertificate oder CertStore_DeleteCertificate auf, um ein Zertifikat umzubenennen oder zu löschen.To rename or delete a certificate, an app calls CertStore_MoveCertificate or CertStore_DeleteCertificate.

Mit CertStore_MoveCertificate wird ein Zertifikat durch das Ändern der Zertifikat-ID umbenannt.CertStore_MoveCertificate renames a certificate by changing its certificate ID. Da Zertifikat-IDs auf einem Gerät eindeutig sein müssen, wird dieses Zertifikat gelöscht, wenn ein Zertifikat durch das Angeben derselben ID wie bei einem anderen Zertifikat umbenannt wird.Because certificate IDs must be unique across a device, renaming a certificate by giving it the same ID as another certificate deletes that certificate. Wenn der Zertifikatspeicher beispielsweise MyCert und YourCert enthält, führt das Verschieben von MyCert und YourCert zu einem einzelnen Zertifikat mit der ID YourCert, die die Daten aus dem früheren MyCert-Zertifikat enthält.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. Es wird kein Fehler zurückgegeben.No error is returned.

Mit CertStore_DeleteCertificate wird ein einzelnes Zertifikat gelöscht.CertStore_DeleteCertificate deletes a single certificate. Das Löschen eines Zertifikats bewirkt eine Neuindizierung der verbleibenden Zertifikate, beginnend bei „0“ (Null).Deleting a certificate causes the remaining certificates to be reindexed, starting at 0. Wenn Sie daher alle Zertifikate im Zertifikatspeicher löschen möchten, müssen Sie diesen Vorgang abhängig von der Anzahl der Zertifikate wiederholen, das Zertifikat jedoch in jeder Iterationen beim Index „0“ löschen.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. Wenn Sie versuchen, ein Zertifikat bei einem Index zu löschen, der nicht mehr verwendet wird, gibt CertStore_GetCertificateIdentifierAt „ERANGE“ zurück.If you try to delete a certificate at an index that is no longer in use, CertStore_GetCertificateIdentifierAt returns ERANGE.

Die folgende Methode funktioniert ordnungsgemäß: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);
}

Verwenden eines Zertifikats für die NetzwerkauthentifizierungUse a certificate for network authentication

Die WifiConfig-API stellt Funktionen bereit, die die Zertifikate festlegen und zurückgeben, die für eine bestimmte WLAN-Konfiguration aktivierten sind.The WifiConfig API provides functions that set and return the certificates that are enabled for a particular Wi-Fi configuration. 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.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.

ZertifikatsbeispielCertificate sample

In der Zertifikatbeispielanwendung sehen Sie, wie eine Anwendung die CertStore-Funktionen nutzen kann.The Certificates sample application shows how an application can use the CertStore functions.