Zarządzanie certyfikatami w aplikacjach wysokiego poziomu
Ważne
Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).
Interfejs API CertStore umożliwia aplikacji wysokiego poziomu zarządzanie certyfikatami do użycia w uwierzytelnianiu sieciowym. Certyfikat azsphere device umożliwia zarządzanie certyfikatami z poziomu wiersza polecenia.
Certyfikaty są przechowywane w magazynie nienależące do woluminu na urządzeniu usługi Azure Sphere. Magazyn certyfikatów lub magazyn certyfikatów może przechowywać maksymalnie 24 kiB certyfikatów. Maksymalny rozmiar certyfikatu to 8 KiB. Certyfikaty głównego urzędu certyfikacji są zwykle większe niż certyfikaty klienta. Oprócz korzystania z magazynu certyfikatów można również uzyskać dostęp do certyfikatu klienta zarządzanego przez firmę Microsoft. Certyfikat klienta zarządzanego przez firmę Microsoft będzie dostępny tylko do użycia, gdy urządzenie jest połączone z Internetem co najmniej raz na 24 godziny.
Korzystanie z certyfikatu klienta zarządzanego przez firmę Microsoft
Użyj tych dwóch funkcji, aby uzyskać certyfikat klienta i określić, czy jest gotowy do użycia.
DeviceAuth_GetCertificatePath zwraca ścieżkę pliku do certyfikatu klienta zarządzanego przez system operacyjny. Ta ścieżka pliku jest wymagana przez niektóre biblioteki do załadowania certyfikatu do komunikacji TLS.
Application_IsDeviceAuthReady sprawdzić, czy uwierzytelnianie urządzenia dla bieżącej aplikacji jest gotowe.
Wymagania dotyczące magazynu certyfikatów
Aplikacje korzystające z interfejsu API CertStore muszą zawierać odpowiednie pliki nagłówka i dodać funkcję CertStore do manifestu aplikacji.
Pliki nagłówkowe
Uwzględnij nagłówek CertStore w projekcie:
#include <applibs\certstore.h>
Ustawienia manifestu aplikacji
Aby korzystać z interfejsów API magazynu certyfikatów, należy dodać CertStore możliwość aplikacji do manifestu aplikacji i ustawić wartość na true. Temat manifestu aplikacji usługi Azure Sphere zawiera więcej szczegółów na temat manifestu aplikacji.
{
"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
}
}
Identyfikatory certyfikatów
Każdy certyfikat jest skojarzony z identyfikatorem certyfikatu (ID). Identyfikator certyfikatu to ciąg 1–16 znaków, który jednoznacznie identyfikuje certyfikat na urządzeniu. Prawidłowe znaki to 'a'-'z', 'A'-'Z', '0'-'9', łącznik (-). i podkreślenie (_). Każdy identyfikator certyfikatu musi być unikatowy na urządzeniu, niezależnie od typu zidentyfikowanego certyfikatu.
Identyfikator każdego certyfikatu jest zapisywany w magazynie certyfikatów i jest używany w całym urządzeniu: przez interfejs API CertStore , interfejs API WifiConfig i interfejs wiersza polecenia azsphere. W związku z tym, jeśli załadujesz certyfikat z wiersza polecenia, wszystkie aplikacje, które wysyłają zapytania, przenoszą lub usuwają ten certyfikat, muszą używać tego samego identyfikatora. Podobnie, jeśli aplikacja ładuje certyfikat, wszystkie polecenia azsphere, które manipulują certyfikatem, muszą używać tego samego identyfikatora. Jeśli zainstalujesz nowy certyfikat o tym samym identyfikatorze co istniejący certyfikat dowolnego typu, nowy certyfikat zastąpi istniejący.
Uwaga
Ponieważ identyfikatory certyfikatów są w całym systemie zarówno dla certyfikatów klienta, jak i głównego urzędu certyfikacji, polecenie azsphere lub wywołanie funkcji, które dodaje nowy certyfikat, może zastąpić certyfikat, który został dodany przez wcześniejsze wywołanie polecenia lub funkcji, potencjalnie powodując błędy połączenia sieciowego. Zdecydowanie zalecamy opracowanie przejrzystych procedur aktualizacji certyfikatów i dokładne wybranie identyfikatorów certyfikatów.
Dodawanie certyfikatu do magazynu certyfikatów
Aby dodać certyfikat do magazynu certyfikatów, aplikacja wywołuje jedną z następujących funkcji:
- CertStore_InstallClientCertificate instaluje certyfikat klienta, który składa się z certyfikatu publicznego i klucza prywatnego
- CertStore_InstallRootCACertificate instaluje certyfikat głównego urzędu certyfikacji, który składa się z certyfikatu publicznego
Certyfikat musi znajdować się na urządzeniu, zanim aplikacja będzie mogła ją zainstalować. Certyfikaty muszą znajdować się w składni PKCS1 lub PKCS8, a format pem do załadowania na urządzenie usługi Azure Sphere. Uzyskiwanie i wdrażanie certyfikatów dla sieci EAP-TLS opisuje sposób uzyskiwania certyfikatów i ładowania ich na urządzeniu. Firma Microsoft nie dostarcza certyfikatów.
Zainstalowanie certyfikatu powoduje dodanie go do magazynu certyfikatów i udostępnienie go do użycia w uwierzytelnianiu. W magazynie certyfikatów certyfikaty są zarządzane przez indeks i mogą być pobierane przez indeks. Zakres wartości indeksu jest uruchamiany z zakresu od 0 do (CertStore_GetCertificateCount – 1).
Aplikacja może uzyskać identyfikator certyfikatu w określonym indeksie, wywołując funkcję CertStore_GetCertificateIdentifierAt. Następnie może użyć identyfikatora certyfikatu w wywołaniach, aby uzyskać informacje o certyfikacie, przenieść lub usunąć certyfikat oraz użyć certyfikatu do uwierzytelniania.
Uzyskiwanie informacji o certyfikacie
Interfejs API magazynu certyfikatów zawiera kilka funkcji, które zwracają informacje o przechowywanym certyfikacie:
- CertStore_GetCertificateNotBefore pobiera czas, w którym certyfikat staje się ważny
- CertStore_GetCertificateNotAfter pobiera czas wygaśnięcia certyfikatu
- CertStore_GetCertificateIssuerName pobiera nazwę wystawcy certyfikatu
- CertStore_GetCertificateSubjectName pobiera nazwę podmiotu certyfikatu, czyli to, co chroni certyfikat
Czasy not-before i not-after są przydatne w zarządzaniu okresem istnienia i aktualizacjami certyfikatu. Aby uzyskać szczegółowe informacje, zobacz Cykl życia certyfikatu i odnawianie .
Zmienianie nazwy lub usuwanie certyfikatu
Aby zmienić nazwę lub usunąć certyfikat, aplikacja wywołuje CertStore_MoveCertificate lub CertStore_DeleteCertificate.
CertStore_MoveCertificate zmienia nazwę certyfikatu, zmieniając jego identyfikator certyfikatu. Ponieważ identyfikatory certyfikatów muszą być unikatowe na urządzeniu, zmiana nazwy certyfikatu przez nadanie mu tego samego identyfikatora co inny certyfikat powoduje usunięcie tego certyfikatu. Jeśli na przykład magazyn certyfikatów zawiera MyCert element i YourCert, przejście MyCert do YourCert powoduje wyświetlenie pojedynczego certyfikatu o identyfikatorze YourCert, który zawiera dane z poprzedniego MyCert. Nie jest zwracany żaden błąd.
CertStore_DeleteCertificate usuwa pojedynczy certyfikat. Usunięcie certyfikatu powoduje ponowne indeksowanie pozostałych certyfikatów, począwszy od 0. W związku z tym, aby usunąć wszystkie certyfikaty w magazynie certyfikatów, należy wykonać pętlę na podstawie liczby certyfikatów, ale usunąć certyfikat z indeksem 0 w każdej iteracji. Jeśli spróbujesz usunąć certyfikat w indeksie, który nie jest już używany, CertStore_GetCertificateIdentifierAt zwraca element ERANGE.
Następująca metoda działa poprawnie:
for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
struct CertStore_Identifier id;
result = CertStore_GetCertificateIdentifierAt(0, &id);
CertStore_DeleteCertificate(id.identifier);
}
Używanie certyfikatu do uwierzytelniania sieciowego
Interfejs API WifiConfig udostępnia funkcje, które ustawiają i zwracają certyfikaty, które są włączone dla określonej konfiguracji sieci Wi-Fi. Aby uzyskać szczegółowe informacje na temat sposobu konfigurowania sieci EAP-TLS w aplikacji , zobacz Konfigurowanie sieci EAP-TLS korzystającej z certyfikatów na potrzeby uwierzytelniania.
Przykład certyfikatu
Przykładowa aplikacja Certificates pokazuje, jak aplikacja może używać funkcji CertStore.