Delen via

Certificaten beheren in toepassingen op hoog niveau

  • Artikel

Belangrijk

Dit is de Documentatie voor Azure Sphere (verouderd). Azure Sphere (verouderd) wordt op 27 september 2027 buiten gebruik gesteld en gebruikers moeten tegen deze tijd migreren naar Azure Sphere (geïntegreerd). Gebruik de versiekiezer boven de inhoudsweergave om de Documentatie van Azure Sphere (geïntegreerd) weer te geven.

Met de CertStore-API kunnen certificaten op hoog niveau worden beheerd voor gebruik in netwerkverificatie. Met het azsphere-apparaatcertificaat kunt u certificaten vanaf de opdrachtregel beheren.

Certificaten worden opgeslagen in niet-compatibele opslag op het Azure Sphere-apparaat. Het certificaatarchief, of het certificaatarchief, kan maximaal 24 KiB-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 is verbonden met internet.

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 over het 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 waarmee het certificaat op het apparaat uniek wordt geïdentificeerd. 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 azsphere CLI. Als u een certificaat laadt vanaf de opdrachtregel, moeten alle toepassingen die dat certificaat opvragen, verplaatsen of verwijderen, dezelfde id gebruiken. Als een app het certificaat laadt, moeten alle azsphere-opdrachten die het certificaat manipuleren, dezelfde id gebruiken. Als u een nieuw certificaat met dezelfde id als een bestaand certificaat van een willekeurig type installeert, overschrijft het nieuwe certificaat het bestaande certificaat.

Let op

Omdat certificaat-id's systeembreed zijn voor zowel client- als basis-CA-certificaten, kan een azsphere-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 certificaatupdates te ontwikkelen en zorgvuldig certificaat-id's 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 een PKCS1- of PKCS8-syntaxis hebben en de PEM-indeling die moet worden geladen op het Azure Sphere-apparaat. Certificaten verkrijgen en implementeren voor EAP-TLS-netwerken beschrijft hoe u certificaten op een apparaat kunt verkrijgen en laden. Microsoft levert geen certificaten.

Als u een certificaat installeert, wordt het 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 door index. Het bereik van indexwaarden wordt uitgevoerd 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 een certificaat voor verificatie te gebruiken.

Certificaatgegevens ophalen

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

  • CertStore_GetCertificateNotBefore het tijdstip ophaalt 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 certificaatonderwerp ophaalt. Dat wil gezegd, wat het certificaat beveiligt

De niet-voor- en niet-natijden zijn handig bij het beheren van de levensduur en updates van certificaten. Zie levenscyclus van certificaten en verlenging 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, wijzigt u de naam van een certificaat door deze dezelfde id te geven als een ander certificaat dat certificaat verwijdert. Als het certificaatarchief bijvoorbeeld één certificaat met id bevat MyCert en YourCert, verplaatst MyCert naar YourCert een enkel certificaat met id YourCert, dat de gegevens uit de voormalige MyCertbevat. Er wordt geen fout geretourneerd.

CertStore_DeleteCertificate één certificaat verwijdert. Als u een certificaat verwijdert, worden de resterende certificaten opnieuw geïndexeerd, beginnend bij 0. Als u daarom alle certificaten in het certificaatarchief wilt verwijderen, moet u herhalen op basis van het aantal certificaten, maar het certificaat verwijderen op index 0 in elke iteratie. Als u een certificaat probeert 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 die de certificaten instellen en retourneren die zijn ingeschakeld voor een bepaalde Wi-Fi-configuratie. 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.