Hantera certifikat i program på hög nivå

Artikel
08/09/2023

Med CertStore API kan ett program på hög nivå hantera certifikat för användning i nätverksautentisering. Med azsfärenhetscertifikatet kan du hantera certifikat från kommandoraden.

Certifikat lagras i icke-volatillagring på Azure Sphere-enheten. Certifikatarkivet, eller certifikatarkivet, kan innehålla upp till 24 KiB-certifikat. Den maximala storleken för ett certifikat är 8 KiB. Rotcertifikatutfärdarcertifikat är vanligtvis större än klientcertifikat. Förutom att använda certifikatarkivet kan du också komma åt det Microsoft-hanterade klientcertifikatet. Det Microsoft-hanterade klientcertifikatet är endast tillgängligt för användning när enheten är ansluten till Internet minst en gång per dygn.

Använda det Microsoft-hanterade klientcertifikatet

Använd de här två funktionerna för att hämta ett klientcertifikat och avgöra om det är klart för användning.

DeviceAuth_GetCertificatePath returnerar en filsökväg till ett klientcertifikat som hanteras av operativsystemet. Den här filsökvägen krävs av vissa bibliotek för att läsa in ett certifikat för TLS-kommunikation.
Application_IsDeviceAuthReady för att kontrollera om enhetsautentisering för det aktuella programmet är klar.

Krav för CertStore

Program som använder CertStore API måste innehålla lämpliga huvudfiler och lägga till CertStore-funktionen i programmanifestet.

Sidhuvudfiler

Ta med CertStore-sidhuvudet i projektet:

 #include <applibs\certstore.h>

Inställningar för programmanifest

Om du vill använda API:er för certifikatarkivet måste du lägga till CertStore programfunktionen i programmanifestet och ange värdet .true Azure Sphere-programmanifestet innehåller mer information om programmanifestet.

{
  "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
  }
}

Certifikat-ID:ar

Varje certifikat är kopplat till ett certifikatidentifierare (ID). Certifikat-ID är en sträng med 1–16 tecken som unikt identifierar certifikatet på enheten. Giltiga tecken är 'a'-'z', 'A'-'Z', '0'-'9', bindestreck (-). och understreck (_). Varje certifikat-ID måste vara unikt på hela enheten, oavsett vilken typ av certifikat som identifieras.

Varje certifikats identifierare sparas i certifikatarkivet och används på hela enheten: av CertStore API, WifiConfig API och azsfären CLI. Om du läser in ett certifikat från kommandoraden måste därför alla program som frågar, flyttar eller tar bort certifikatet använda samma ID. På samma sätt måste alla azsfärkommandon som hanterar certifikatet använda samma ID om en app läser in certifikatet. Om du installerar ett nytt certifikat med samma ID som ett befintligt certifikat av någon typ skriver det nya certifikatet över det befintliga.

Försiktighet

Eftersom certifikat-ID:er är systemomfattande för både klient- och rotcertifikatutfärdarcertifikat kan ett azsfärkommando eller ett funktionsanrop som lägger till ett nytt certifikat skriva över ett certifikat som har lagts till av ett tidigare kommando- eller funktionsanrop, vilket kan orsaka fel i nätverksanslutningen. Vi rekommenderar starkt att du utvecklar tydliga procedurer för certifikatuppdatering och väljer certifikat-ID:er noggrant.

Lägga till ett certifikat i certifikatarkivet

Om du vill lägga till ett certifikat i certifikatarkivet anropar en app någon av följande funktioner:

CertStore_InstallClientCertificate installerar ett klientcertifikat, som består av ett offentligt certifikat och en privat nyckel
CertStore_InstallRootCACertificate installerar ett rotcertifikatutfärdare, som består av ett offentligt certifikat

Certifikatet måste finnas på enheten innan appen kan installera det. Certifikat måste ha PKCS1- eller PKCS8-syntax och PEM-format för att kunna läsas in på Azure Sphere-enheten. Hämta och distribuera certifikat för EAP-TLS-nätverk beskriver hur du hämtar certifikat och läser in dem på en enhet. Microsoft tillhandahåller inte certifikat.

När du installerar ett certifikat läggs det till i certifikatarkivet och blir tillgängligt för användning vid autentisering. I certifikatarkivet hanteras certifikat av index och kan hämtas med index. Intervallet med indexvärden går från 0 till (CertStore_GetCertificateCount - 1).

En app kan hämta certifikatets ID för ett visst index genom att anropa funktionen CertStore_GetCertificateIdentifierAt. Den kan sedan använda certifikat-ID:t i samtal för att få information om certifikatet, flytta eller ta bort certifikatet och använda ett certifikat för autentisering.

Hämta certifikatinformation

CertStore-API:et innehåller flera funktioner som returnerar information om ett lagrat certifikat:

CertStore_GetCertificateNotBefore får den tid då certifikatet blir giltigt
CertStore_GetCertificateNotAfter får den tid då certifikatet upphör att gälla
CertStore_GetCertificateIssuerName får namnet på certifikatets utfärdare
CertStore_GetCertificateSubjectName får namnet på certifikatets ämne. det vill sa vad certifikatet skyddar

Tiderna inte före och inte efter är användbara för att hantera certifikatets livstid och uppdateringar. Mer information finns i Certifikatets livscykel och förnyelse .

Byta namn på eller ta bort ett certifikat

Om du vill byta namn på eller ta bort ett certifikat anropar en app CertStore_MoveCertificate eller CertStore_DeleteCertificate.

CertStore_MoveCertificate byter namn på ett certifikat genom att ändra certifikat-ID:et. Eftersom certifikat-ID måste vara unikt för en enhet tas certifikatet bort om du byter namn på ett certifikat genom att ge det samma ID som ett annat certifikat. Om certifikatarkivet till exempel innehåller MyCert och YourCert, om du flyttar MyCert till YourCert resulterar det i ett enda certifikat med ID YourCert, som innehåller data från det förra MyCert. Inget fel returneras.

CertStore_DeleteCertificate tar bort ett enda certifikat. Om du tar bort ett certifikat indexeras de återstående certifikaten om, med början vid 0. För att ta bort alla certifikat i certifikatarkivet måste du därför loopa baserat på antalet certifikat men ta bort certifikatet med index 0 i varje iteration. Om du försöker ta bort ett certifikat i ett index som inte längre används returnerar CertStore_GetCertificateIdentifierAt ERANGE.

Följande metod fungerar korrekt:

for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
    struct CertStore_Identifier id;
    result = CertStore_GetCertificateIdentifierAt(0, &id);
    CertStore_DeleteCertificate(id.identifier);
}

Använda ett certifikat för nätverksautentisering

WifiConfig-API:t innehåller funktioner som anger och returnerar certifikat som är aktiverade för en viss Wi-Fi konfiguration. Mer information om hur ett program på hög nivå kan konfigurera ett EAP-TLS-nätverk som använder certifikat för autentisering finns i Konfigurera EAP-TLS-nätverk i en app .

Exempel på certifikat

Exempelprogrammet Certifikat visar hur ett program kan använda CertStore-funktionerna.

Dela via