Zarządzanie certyfikatami w aplikacjach wysokiego poziomu
Interfejs API CertStore umożliwia aplikacji wysokiego poziomu zarządzanie certyfikatami do użycia w uwierzytelnianiu sieciowym. Certyfikat urządzenia azsphere umożliwia zarządzanie certyfikatami z wiersza polecenia.
Certyfikaty są przechowywane w niewolatile magazynu na urządzeniu Azure Sphere. Magazyn certyfikatów lub magazyn certyfikatów może zawierać maksymalnie 24 certyfikaty KiB. Maksymalny rozmiar certyfikatu to 8 kib. Certyfikaty głównego urzędu certyfikacji są zazwyczaj większe niż certyfikaty klienta. Oprócz korzystania ze 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 do użytku tylko wtedy, gdy urządzenie jest połączone z Internetem co najmniej raz na 24 godziny.
Używanie certyfikatu klienta zarządzanego przez firmę Microsoft
Te dwie funkcje umożliwiają uzyskanie certyfikatu klienta i określenie, czy jest on 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 usługi CertStore
Aplikacje korzystające z interfejsu API CertStore muszą zawierać odpowiednie pliki nagłówka i dodać funkcję CertStore do manifestu aplikacji.
Pliki nagłówków
Uwzględnij nagłówek CertStore w projekcie:
#include <applibs\certstore.h>
Ustawienia manifestu aplikacji
Aby użyć interfejsów API magazynu certyfikatów, należy dodać funkcję CertStore aplikacji do manifestu aplikacji i ustawić truewartość . Temat manifestu aplikacji 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. Identyfikator certyfikatu to ciąg znaków od 1 do 16, 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 całym urządzeniu, niezależnie od typu certyfikatu, który identyfikuje.
Identyfikator każdego certyfikatu jest zapisywany w magazynie certyfikatów i używany na całym urządzeniu: przez interfejs API CertStore , interfejs API WifiConfig i rozszerzenie Azure CLI. W związku z tym, jeśli załadujesz certyfikat z wiersza polecenia, wszystkie aplikacje, które prześliją lub usuną ten certyfikat, muszą użyć tego samego identyfikatora. Podobnie, jeśli aplikacja ładuje certyfikat, wszelkie az sphere polecenia, które manipulują certyfikatem, muszą używać tego samego identyfikatora. Jeśli zainstalujesz nowy certyfikat z tym samym identyfikatorem co istniejący certyfikat dowolnego typu, nowy certyfikat zastąpi istniejący.
Ostrożność
Ponieważ identyfikatory certyfikatów są dostępne w całym systemie zarówno dla certyfikatów klienta, jak i certyfikatów głównego urzędu certyfikacji, polecenie azsphere lub wywołanie funkcji, które dodaje nowy certyfikat, może zastąpić certyfikat dodany przez wcześniejsze wywołanie polecenia lub funkcji, co może powodować błędy połączenia sieciowego. Zdecydowanie zalecamy opracowanie przejrzystych procedur aktualizacji certyfikatów i staranne wybieranie 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 być obecny na urządzeniu, aby aplikacja mogła go zainstalować. Certyfikaty muszą mieć składnię PKCS1 lub PKCS8 i format pem, aby można było je załadować na urządzenie Azure Sphere. Uzyskiwanie i wdrażanie certyfikatów dla sieci EAP-TLS opisuje sposób uzyskiwania certyfikatów i ładowania ich na urządzenie. Firma Microsoft nie dostarcza certyfikatów.
Zainstalowanie certyfikatu powoduje dodanie go do magazynu certyfikatów i udostępnienie go do użycia podczas uwierzytelniania. W magazynie certyfikatów certyfikaty są zarządzane przez indeks i mogą być pobierane przez indeks. Zakres wartości indeksu wynosi 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 połączeniach, aby uzyskać informacje o certyfikacie, przenieść lub usunąć certyfikat oraz użyć certyfikatu do uwierzytelniania.
Uzyskiwanie informacji o certyfikacie
Interfejs API CertStore zawiera kilka funkcji, które zwracają informacje o przechowywanym certyfikacie:
- CertStore_GetCertificateNotBefore uzyskuje czas, w którym certyfikat staje się prawidłowy
- CertStore_GetCertificateNotAfter otrzymuje czas wygaśnięcia certyfikatu
- CertStore_GetCertificateIssuerName otrzymuje nazwę wystawcy certyfikatu
- CertStore_GetCertificateSubjectName otrzymuje nazwę tematu certyfikatu; oznacza to, co certyfikat chroni
Godziny spoza i nie po są przydatne w zarządzaniu okresem istnienia certyfikatu i aktualizacjami. Aby uzyskać szczegółowe informacje, zobacz Cykl życia certyfikatu i odnawianie .
Zmienianie nazwy certyfikatu lub usuwanie go
Aby zmienić nazwę certyfikatu lub go usunąć, 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 różnych urządzeniach, 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 i YourCertpowoduje przejście MyCert do YourCert jednego certyfikatu z identyfikatorem YourCert, który zawiera dane z poprzedniego MyCert. Nie jest zwracany żaden błąd.
CertStore_DeleteCertificate usuwa pojedynczy certyfikat. Usunięcie certyfikatu powoduje ponowneexowanie pozostałych certyfikatów, rozpoczynając od wartości 0. Dlatego, aby usunąć wszystkie certyfikaty w magazynie certyfikatów, należy w pętli na podstawie liczby certyfikatów, ale usunąć certyfikat w indeksie 0 w każdej iteracji. Jeśli spróbujesz usunąć certyfikat w indeksie, który nie jest już używany, CertStore_GetCertificateIdentifierAt zwraca wartość ERANGE.
Następująca metoda działa poprawnie:
#define ALWAYS_GET_FIRST (0)
int result = 0; // no error
for (size_t i = 0; i < CertStore_GetCertificateCount(); i++) {
struct CertStore_Identifier id;
result = CertStore_GetCertificateIdentifierAt(ALWAYS_GET_FIRST , &id);
if (result == 0) {
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 Wi-Fi. Zobacz Konfigurowanie sieci EAP-TLS w aplikacji , aby uzyskać szczegółowe informacje o tym, jak aplikacja wysokiego poziomu może skonfigurować sieć EAP-TLS korzystającą z certyfikatów do uwierzytelniania.
Przykład certyfikatu
Przykładowa aplikacja Certyfikaty pokazuje, jak aplikacja może używać funkcji CertStore.