Hantera certifikat i program på hög nivå

Artikel
09/27/2024

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

Med CertStore-API:et kan ett program på hög nivå hantera certifikat för användning i nätverksautentisering. Med azsphere-enhetscertifikatet kan du hantera certifikat från kommandoraden.

Certifikat lagras i icke-volatil lagring 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 var 24:e timme.

Använda det Microsoft-hanterade klientcertifikatet

Använd dessa två funktioner 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 enhetsautentiseringen för det aktuella programmet är klar.

CertStore-krav

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

Rubrikfiler

Inkludera CertStore-huvudet i projektet:

 #include <applibs\certstore.h>

Inställningar för programmanifest

Om du vill använda API:erna för certifikatarkivet måste du lägga till CertStore programfunktionen i programmanifestet och ange värdet till true. Avsnittet om 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:t

Varje certifikat är associerat med ett certifikatidentifierare (ID). Certifikat-ID:t ä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å enheten, oavsett vilken typ av certifikat det identifierar.

Varje certifikats identifierare sparas i certifikatarkivet och används i hela enheten: av CertStore-API:et, WifiConfig-API :et och azsphere 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 azsphere-kommandon som manipulerar 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.

Varning

Eftersom certifikat-ID:n är systemomfattande för både klient- och rotcertifikatutfärdarcertifikat kan ett azsphere-kommando eller ett funktionsanrop som lägger till ett nytt certifikat skriva över ett certifikat som lades till av ett tidigare kommando- eller funktionsanrop, vilket kan orsaka nätverksanslutningsfel. Vi rekommenderar starkt att du utvecklar tydliga procedurer för certifikatuppdatering och väljer certifikat-ID:t 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ärdarcertifikat, 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 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 i autentisering. I certifikatarkivet hanteras certifikaten efter index och kan hämtas med index. Intervallet för indexvärden körs från 0 till (CertStore_GetCertificateCount - 1).

En app kan hämta certifikatets ID vid ett visst index genom att anropa funktionen CertStore_GetCertificateIdentifierAt. Den kan sedan använda certifikat-ID:t i anrop för att hämta information om certifikatet, för att flytta eller ta bort certifikatet och för att 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 hämtar namnet på certifikatets utfärdare
CertStore_GetCertificateSubjectName hämtar namnet på certifikatets ämne, dvs. vad certifikatet skyddar

Tiderna inte före och inte efter är användbara för att hantera certifikatets livslängd 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 dess certifikat-ID. Eftersom certifikat-ID:n måste vara unika 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, resulterar övergången MyCert till YourCert ett enda certifikat med ID YourCert, som innehåller data från det tidigare MyCert. Inget fel returneras.

CertStore_DeleteCertificate tar bort ett enda certifikat. Om du tar bort ett certifikat indexeras de återstående certifikaten om från och med 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 vid 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:et innehåller funktioner som anger och returnerar de certifikat som är aktiverade för en viss Wi-Fi-konfiguration. Mer information om hur ett högnivåprogram kan konfigurera ett EAP-TLS-nätverk som använder certifikat för autentisering finns i Konfigurera EAP-TLS-nätverk i en app .

Certifikatexempel

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

Dela via