Správa certifikátů v aplikacích vysoké úrovně

Článek
10/23/2024

Důležité

Toto je dokumentace k Azure Sphere (starší verze). Azure Sphere (starší verze) se vyřazuje 27. září 2027 a uživatelé musí do této doby migrovat do Azure Sphere (integrované). K zobrazení dokumentace k Azure Sphere (integrované) použijte selektor verzí umístěný nad obsahem.

Rozhraní CertStore API umožňuje vysoké úrovni spravovat certifikáty pro použití při ověřování sítě. Certifikát zařízení azsphere umožňuje spravovat certifikáty z příkazového řádku.

Certifikáty se ukládají v nevolatilovém úložišti na zařízení Azure Sphere. Úložiště certifikátů nebo úložiště certifikátů může obsahovat až 24 KiB certifikátů. Maximální velikost certifikátu je 8 KiB. Certifikáty kořenové certifikační autority jsou obvykle větší než klientské certifikáty. Kromě použití úložiště certifikátů můžete také přistupovat k klientskému certifikátu spravovanému Microsoftem. Klientský certifikát spravovaný Microsoftem bude k dispozici pouze v případě, že je zařízení připojené k internetu alespoň jednou za 24 hodin.

Použití klientského certifikátu spravovaného Microsoftem

Pomocí těchto dvou funkcí získejte klientský certifikát a určete, jestli je připravený k použití.

DeviceAuth_GetCertificatePath vrátí cestu k souboru klientskému certifikátu spravovanému operačním systémem. Tato cesta k souboru je vyžadována některými knihovnami k načtení certifikátu pro komunikaci tls.
Application_IsDeviceAuthReady ověřit, jestli je ověřování zařízení pro aktuální aplikaci připravené.

Požadavky CertStore

Aplikace, které používají rozhraní CertStore API, musí obsahovat příslušné soubory hlaviček a přidat do manifestu aplikace funkci CertStore.

Soubory hlaviček

Do projektu zahrňte hlavičku CertStore:

 #include <applibs\certstore.h>

Nastavení manifestu aplikace

Pokud chcete používat rozhraní API úložiště certifikátů, musíte do manifestu aplikace přidat CertStore funkci aplikace a nastavit hodnotu na true. Téma manifestu aplikace Azure Sphere obsahuje další podrobnosti o manifestu aplikace.

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

ID certifikátů

Každý certifikát je přidružený k identifikátoru certifikátu (ID). ID certifikátu je řetězec 1–16 znaků, který jednoznačně identifikuje certifikát v zařízení. Platné znaky jsou 'a'-'z', 'A'-'Z', '0'-'9', pomlčka (-). a podtržítko (_). Každé ID certifikátu musí být v celém zařízení jedinečné bez ohledu na typ certifikátu, který identifikuje.

Identifikátor každého certifikátu se uloží do úložiště certifikátů a používá se pro celé zařízení: rozhraní API CertStore , rozhraní API WifiConfig a azsphere CLI. Pokud tedy načtete certifikát z příkazového řádku, musí všechny aplikace, které tento certifikát dotazují, přesunout nebo odstranit, používat stejné ID. Podobně pokud aplikace načte certifikát, musí všechny příkazy azsphere, které s certifikátem manipulují, používat stejné ID. Pokud nainstalujete nový certifikát se stejným ID jako existující certifikát libovolného typu, nový certifikát přepíše stávající certifikát.

Upozornění

Vzhledem k tomu, že ID certifikátů jsou systémová pro certifikáty klienta i kořenové certifikační autority, může příkaz azsphere nebo volání funkce, které přidá nový certifikát, přepsat certifikát, který byl přidán dřívějším voláním příkazu nebo funkce, což může způsobit selhání síťového připojení. Důrazně doporučujeme vyvinout jasné postupy aktualizace certifikátů a pečlivě zvolit ID certifikátů.

Přidání certifikátu do úložiště certifikátů

Pokud chcete přidat certifikát do úložiště certifikátů, aplikace volá jednu z následujících funkcí:

CertStore_InstallClientCertificate nainstaluje klientský certifikát, který se skládá z veřejného certifikátu a privátního klíče.
CertStore_InstallRootCACertificate nainstaluje kořenový certifikát certifikační autority, který se skládá z veřejného certifikátu.

Certifikát musí být na zařízení k dispozici, aby ji aplikace mohl nainstalovat. Certifikáty musí být v syntaxi PKCS1 nebo PKCS8 a ve formátu .pem, který se má načíst do zařízení Azure Sphere. Získání a nasazení certifikátů pro sítě EAP-TLS popisuje, jak získat certifikáty a načíst je do zařízení. Společnost Microsoft neposkytuje certifikáty.

Instalace certifikátu ho přidá do úložiště certifikátů a zpřístupní ho k použití při ověřování. V úložišti certifikátů se certifikáty spravují pomocí indexu a dají se načíst pomocí indexu. Rozsah hodnot indexu se spouští od 0 do (CertStore_GetCertificateCount – 1).

Aplikace může získat ID certifikátu v určitém indexu voláním funkce CertStore_GetCertificateIdentifierAt. Pak může pomocí ID certifikátu ve volání získat informace o certifikátu, přesunout nebo odstranit certifikát a použít certifikát k ověření.

Získání informací o certifikátu

Rozhraní CertStore API obsahuje několik funkcí, které vracejí informace o uloženém certifikátu:

CertStore_GetCertificateNotBefore získá čas, kdy se certifikát stane platným
CertStore_GetCertificateNotAfter získá čas vypršení platnosti certifikátu.
CertStore_GetCertificateIssuerName získá název vystavitele certifikátu.
CertStore_GetCertificateSubjectName získá název subjektu certifikátu; to znamená, co certifikát chrání.

Not-before a not-after times jsou užitečné při správě životnosti a aktualizací certifikátů. Podrobnosti najdete v části Životní cyklus certifikátu a prodloužení platnosti .

Přejmenování nebo odstranění certifikátu

Pokud chcete certifikát přejmenovat nebo odstranit, aplikace volá CertStore_MoveCertificate nebo CertStore_DeleteCertificate.

CertStore_MoveCertificate certifikát přejmenuje změnou ID certifikátu. Vzhledem k tomu, že ID certifikátů musí být v rámci zařízení jedinečná, přejmenování certifikátu tím, že mu udělíte stejné ID jako jiný certifikát, tento certifikát odstraní. Pokud například úložiště certifikátů obsahuje MyCert a přesune MyCert se na YourCert výsledek jednoho certifikátu s IDYourCert, který obsahuje data z předchozího MyCertYourCert. Nevrátí se žádná chyba.

CertStore_DeleteCertificate odstraní jeden certifikát. Odstranění certifikátu způsobí, že se zbývající certifikáty přeindexují od 0. Proto pokud chcete odstranit všechny certifikáty v úložišti certifikátů, musíte smyčku založenou na počtu certifikátů odstranit, ale v každé iteraci odstranit certifikát na indexu 0. Pokud se pokusíte odstranit certifikát v indexu, který se už nepoužívá, CertStore_GetCertificateIdentifierAt vrátí ERANGE.

Následující metoda funguje správně:

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

Použití certifikátu pro ověřování sítě

Rozhraní Api WifiConfig poskytuje funkce, které nastaví a vrátí certifikáty, které jsou povolené pro konkrétní konfiguraci Wi-Fi. Podrobnosti o tom, jak může aplikace nastavit síť EAP-TLS, která používá certifikáty k ověřování, najdete v tématu Nastavení sítě EAP-TLS v aplikaci .

Ukázka certifikátu

Ukázková aplikace Certifikáty ukazuje, jak může aplikace používat funkce CertStore.

Sdílet prostřednictvím