Certificaten beheren in toepassingen op hoog niveau

Artikel
08/09/2023

Met de CertStore-API kan een toepassing op hoog niveau certificaten beheren voor gebruik in netwerkverificatie. Met az sphere device certificate kunt u certificaten beheren vanaf de opdrachtregel.

Certificaten worden opgeslagen in niet-onvolatile opslag op het Azure Sphere-apparaat. Het certificaatarchief of certificaatarchief kan maximaal 24 KiB aan certificaten bevatten. De maximale grootte voor een certificaat is 8 KiB. Basis-CA-certificaten zijn doorgaans groter dan clientcertificaten. Naast het gebruik van het certificaatarchief hebt u ook toegang tot het door Microsoft beheerde clientcertificaat. Het door Microsoft beheerde clientcertificaat is alleen beschikbaar voor gebruik wanneer het apparaat ten minste eenmaal per 24 uur met internet is verbonden.

Het door Microsoft beheerde clientcertificaat gebruiken

Gebruik deze twee functies om een clientcertificaat te verkrijgen en te bepalen of het gereed is voor gebruik.

DeviceAuth_GetCertificatePath retourneert een bestandspad naar een clientcertificaat dat wordt beheerd door het besturingssysteem. Dit bestandspad is vereist voor sommige bibliotheken om een certificaat voor TLS-communicatie te laden.
Application_IsDeviceAuthReady om te controleren of apparaatverificatie voor de huidige toepassing gereed is.

Vereisten voor CertStore

Toepassingen die gebruikmaken van de CertStore-API moeten de juiste headerbestanden bevatten en de CertStore-mogelijkheid toevoegen aan het toepassingsmanifest.

Koptekstbestanden

Neem de CertStore-header op in uw project:

 #include <applibs\certstore.h>

Toepassingsmanifestinstellingen

Als u de API's voor het certificaatarchief wilt gebruiken, moet u de CertStore toepassingsmogelijkheid toevoegen aan het toepassingsmanifest en de waarde instellen op true. Het onderwerp Azure Sphere-toepassingsmanifest bevat meer informatie over het toepassingsmanifest.

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

Certificaat-id's

Elk certificaat is gekoppeld aan een certificaat-id (ID). De certificaat-id is een tekenreeks van 1-16 tekens die het certificaat op het apparaat uniek identificeert. Geldige tekens zijn 'a'-'z', 'A'-'Z', '0'-'9', afbreekstreepje (-). en onderstrepingsteken (_). Elke certificaat-id moet uniek zijn op het apparaat, ongeacht het type certificaat dat wordt geïdentificeerd.

De id van elk certificaat wordt opgeslagen in het certificaatarchief en wordt apparaatbreed gebruikt: door de CertStore-API , de WifiConfig-API en de Azure CLI-extensie. Als u een certificaat vanaf de opdrachtregel laadt, moeten alle toepassingen die dat certificaat opvragen, verplaatsen of verwijderen, dezelfde id gebruiken. Als een app het certificaat laadt, moeten alle az sphere opdrachten waarmee het certificaat wordt gemanipuleerd, dezelfde id gebruiken. Als u een nieuw certificaat installeert met dezelfde id als een bestaand certificaat van welk type dan ook, wordt het bestaande certificaat overschreven door het nieuwe certificaat.

Voorzichtigheid

Omdat certificaat-id's systeembreed zijn voor zowel client- als basis-CA-certificaten, kan een az sphere-opdracht of een functieaanroep waarmee een nieuw certificaat wordt toegevoegd, een certificaat overschrijven dat is toegevoegd door een eerdere opdracht of functieaanroep, waardoor netwerkverbindingsfouten kunnen optreden. We raden u ten zeerste aan duidelijke procedures voor het bijwerken van certificaten te ontwikkelen en certificaat-id's zorgvuldig te kiezen.

Een certificaat toevoegen aan het certificaatarchief

Als u een certificaat wilt toevoegen aan het certificaatarchief, roept een app een van de volgende functies aan:

CertStore_InstallClientCertificate installeert een clientcertificaat, dat bestaat uit een openbaar certificaat en een persoonlijke sleutel
CertStore_InstallRootCACertificate installeert een basis-CA-certificaat, dat bestaat uit een openbaar certificaat

Het certificaat moet aanwezig zijn op het apparaat voordat de app het kan installeren. Certificaten moeten de syntaxis PKCS1 of PKCS8 en de PEM-indeling hebben om op het Azure Sphere-apparaat te kunnen worden geladen. Certificaten verkrijgen en implementeren voor EAP-TLS-netwerken beschrijft hoe u certificaten kunt verkrijgen en deze op een apparaat kunt laden. Microsoft levert geen certificaten.

Als u een certificaat installeert, wordt dit toegevoegd aan het certificaatarchief en wordt het beschikbaar gemaakt voor gebruik in verificatie. In het certificaatarchief worden certificaten beheerd door index en kunnen ze worden opgehaald per index. Het bereik van indexwaarden loopt van 0 tot (CertStore_GetCertificateCount - 1).

Een app kan de id van het certificaat op een bepaalde index ophalen door de functie CertStore_GetCertificateIdentifierAt aan te roepen. Vervolgens kan de certificaat-id in aanroepen worden gebruikt om informatie over het certificaat op te halen, het certificaat te verplaatsen of te verwijderen en om een certificaat te gebruiken voor verificatie.

Certificaatgegevens ophalen

De CertStore-API bevat verschillende functies die informatie over een opgeslagen certificaat retourneren:

CertStore_GetCertificateNotBefore krijgt het tijdstip waarop het certificaat geldig wordt
CertStore_GetCertificateNotAfter krijgt het tijdstip waarop het certificaat verloopt
CertStore_GetCertificateIssuerName de naam van de verlener van het certificaat ophaalt
CertStore_GetCertificateSubjectName de naam van het onderwerp van het certificaat ophaalt; dat wil gezegd, wat het certificaat beschermt

De not-before- en not-after-tijden zijn handig bij het beheren van de levensduur en updates van certificaten. Zie Levenscyclus en verlenging van certificaat voor meer informatie.

De naam van een certificaat wijzigen of verwijderen

Als u de naam van een certificaat wilt wijzigen of verwijderen, roept een app CertStore_MoveCertificate of CertStore_DeleteCertificate aan.

CertStore_MoveCertificate wijzigt de naam van een certificaat door de certificaat-id te wijzigen. Omdat certificaat-id's uniek moeten zijn op een apparaat, wordt dat certificaat verwijderd door de naam van een certificaat te wijzigen door het dezelfde id te geven als een ander certificaat. Als het certificaatarchief bijvoorbeeld en YourCertbevatMyCert, resulteert het verplaatsen MyCert naar YourCert één certificaat met id YourCert, dat de gegevens uit de vorige MyCertbevat. Er wordt geen fout geretourneerd.

CertStore_DeleteCertificate verwijdert één certificaat. Als u een certificaat verwijdert, worden de resterende certificaten opnieuw geïndexeerd, te beginnen bij 0. Als u alle certificaten in het certificaatarchief wilt verwijderen, moet u daarom een lus maken op basis van het aantal certificaten, maar het certificaat bij index 0 in elke iteratie verwijderen. Als u probeert een certificaat te verwijderen in een index die niet meer wordt gebruikt, retourneert CertStore_GetCertificateIdentifierAt ERANGE.

De volgende methode werkt correct:

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

Een certificaat gebruiken voor netwerkverificatie

De WifiConfig-API biedt functies waarmee de certificaten die zijn ingeschakeld voor een bepaalde Wi-Fi configuratie, worden ingesteld en geretourneerd. Zie EAP-TLS-netwerk instellen in een app voor meer informatie over hoe een toepassing op hoog niveau een EAP-TLS-netwerk kan instellen dat gebruikmaakt van certificaten voor verificatie.

Certificaatvoorbeeld

De voorbeeldtoepassing Certificaten laat zien hoe een toepassing de CertStore-functies kan gebruiken.

Delen via