Funkcje Keymastera, Funkcje Keymastera

Na tej stronie znajdują się szczegółowe informacje pomocne osobom wdrażającym warstwy abstrakcji sprzętu Keymaster (HAL). Omówiono każdą funkcję w API oraz wersję Keymastera, w której dana funkcja jest dostępna, a także opisano domyślną implementację. Informacje na temat tagów można znaleźć na stronie Tagi Keymaster .

Ogólne wytyczne wdrożeniowe

Poniższe wytyczne dotyczą wszystkich funkcji interfejsu API.

Parametry wskaźnika wejściowego

Wersja : 1, 2

Parametry wskaźnika wejściowego, które nie są używane dla danego wywołania, mogą mieć NULL . Osoba wywołująca nie musi podawać symboli zastępczych. Na przykład niektóre typy kluczy i tryby mogą nie używać żadnych wartości z argumentu inParams do rozpoczęcia , więc obiekt wywołujący może ustawić inParams na NULL lub udostępnić pusty zestaw parametrów. Obiekty wywołujące mogą również udostępniać nieużywane parametry, a metody Keymaster nie powinny powodować błędów.

Jeśli wymagany parametr wejściowy ma wartość NULL, metody Keymaster powinny zwrócić ErrorCode::UNEXPECTED_NULL_POINTER .

Począwszy od Keymaster 3, nie ma parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartości lub odniesienia do stałych.

Parametry wskaźnika wyjściowego

Wersja : 1, 2

Podobnie jak parametry wskaźnika wejściowego, nieużywane parametry wskaźnika wyjściowego mogą mieć NULL . Jeśli metoda musi zwrócić dane w parametrze wyjściowym, który ma wartość NULL , powinna zwrócić ErrorCode::OUTPUT_PARAMETER_NULL .

Począwszy od Keymaster 3, nie ma parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartości lub odniesienia do stałych.

Niewłaściwe użycie API

Wersja : 1, 2, 3

Istnieje wiele sposobów, w jakie osoby dzwoniące mogą składać prośby, które nie mają sensu lub są głupie, ale nie są błędne pod względem technicznym. Implementacje Keymaster nie muszą w takich przypadkach zawieść ani wydać komunikatu diagnostycznego. Stosowanie zbyt małych kluczy, specyfikacja nieistotnych parametrów wejściowych, ponowne użycie IV lub nonce, generowanie kluczy bez celów (a zatem bezużytecznych) i tym podobne nie powinny być diagnozowane przez implementacje. Należy zdiagnozować pominięcie wymaganych parametrów, podanie nieprawidłowych wymaganych parametrów i podobne błędy.

Obowiązkiem aplikacji, frameworka i magazynu kluczy systemu Android jest zapewnienie, że wywołania modułów Keymaster są rozsądne i użyteczne.

Funkcje

pobierz funkcje sprzętowe

Wersja : 3

Nowa metoda getHardwareFeatures udostępnia klientom niektóre ważne cechy bezpiecznego sprzętu. Metoda nie przyjmuje żadnych argumentów i zwraca cztery wartości, wszystkie wartości logiczne:

  • isSecure ma true , jeśli klucze są przechowywane na bezpiecznym sprzęcie (TEE itp.) i nigdy go nie opuszczają.
  • supportsEllipticCurve ma true , jeśli sprzęt obsługuje kryptografię krzywych eliptycznych z krzywymi NIST (P-224, P-256, P-384 i P-521).
  • supportsSymmetricCryptography ma true , jeśli sprzęt obsługuje kryptografię symetryczną, w tym AES i HMAC.
  • supportsAttestation ma true , jeśli sprzęt obsługuje generowanie certyfikatów zaświadczających klucz publiczny Keymaster, podpisanych kluczem wprowadzonym w bezpiecznym środowisku.

Jedyne kody błędów, które może zwrócić ta metoda, to ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED lub jeden z kodów błędów wskazujących brak komunikacji z bezpiecznym sprzętem.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

skonfiguruj

Wersja 2

Ta funkcja została wprowadzona w Keymaster 2 i przestarzała w Keymaster 3, ponieważ informacje te są dostępne w plikach właściwości systemu, a implementacje producentów odczytują te pliki podczas uruchamiania.

Konfiguruje keymastera. Metoda ta wywoływana jest jednorazowo po otwarciu urządzenia i przed jego użyciem. Służy do udostępniania kluczy KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL . Dopóki ta metoda nie zostanie wywołana, wszystkie inne metody zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED . Wartości dostarczone tą metodą są akceptowane przez keymastera tylko raz na rozruch. Kolejne wywołania zwracają KM_ERROR_OK , ale nic nie robią.

Jeśli implementacja klucza głównego odbywa się na bezpiecznym sprzęcie, a podane wartości wersji systemu operacyjnego i poziomu poprawek nie odpowiadają wartościom dostarczonym do bezpiecznego sprzętu przez program ładujący (lub jeśli program ładujący nie dostarczył wartości), wówczas ta metoda zwraca KM_ERROR_INVALID_ARGUMENT i wszystkie inne metody nadal zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED .

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

dodajRngEntropia

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako add_rng_entropy i zmieniona nazwa w Keymaster 3.

Dodaje entropię dostarczoną przez wywołującego do puli używanej przez implementację Keymaster 1 do generowania liczb losowych, kluczy, IV itp.

Implementacje Keymaster muszą bezpiecznie mieszać dostarczoną entropię z pulą, która musi również zawierać entropię wygenerowaną wewnętrznie ze sprzętowego generatora liczb losowych. Mieszanie powinno być obsługiwane w taki sposób, aby atakujący, który ma pełną kontrolę nad bitami dostarczonymi przez addRngEntropy lub bitami wygenerowanymi sprzętowo, ale nie nad obydwoma, nie miał niezauważalnej przewagi w przewidywaniu bitów generowanych z puli entropii.

Implementacje Keymaster, które próbują oszacować entropię w swojej wewnętrznej puli, zakładają, że dane dostarczone przez addRngEntropy nie zawierają entropii. Implementacje Keymastera mogą zwrócić ErrorCode::INVALID_INPUT_LENGTH , jeśli w jednym wywołaniu otrzymają więcej niż 2 KiB danych.

wygeneruj klucz

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako generate_key i zmieniona nazwa w Keymaster 3.

Generuje nowy klucz kryptograficzny, określając powiązane uprawnienia, które są trwale powiązane z kluczem. Implementacje Keymastera uniemożliwiają użycie klucza w jakikolwiek sposób niezgodny z uprawnieniami określonymi w momencie generowania. W przypadku autoryzacji, których bezpieczny sprzęt nie jest w stanie wymusić, obowiązki bezpiecznego sprzętu ograniczają się do zapewnienia, że ​​niewykonalne autoryzacje powiązane z kluczem nie mogą zostać zmodyfikowane, tak aby każde wywołanie getKeyCharacteristics zwracało pierwotną wartość. Ponadto cechy zwracane przez generateKey prawidłowo przydzielają autoryzacje pomiędzy listami wymuszanymi sprzętowo i listami wymuszanymi programowo. Więcej szczegółów znajdziesz w getKeyCharacteristics .

Parametry dostarczone do generateKey zależą od typu generowanego klucza. W tej sekcji podsumowano niezbędne i opcjonalne znaczniki dla każdego typu klucza. Tag::ALGORITHM jest zawsze niezbędny do określenia typu.

Klucze RSA

Do wygenerowania klucza RSA niezbędne są następujące parametry.

  • Tag::KEY_SIZE określa rozmiar modułu publicznego w bitach. W przypadku pominięcia metoda zwraca ErrorCode::UNSUPPORTED_KEY_SIZE . Obsługiwane wartości to 1024, 2048, 3072 i 4096. Zalecane wartości to wszystkie rozmiary kluczy będące wielokrotnością liczby 8.
  • Tag::RSA_PUBLIC_EXPONENT określa wartość wykładnika publicznego RSA. W przypadku pominięcia metoda zwraca ErrorCode::INVALID_ARGUMENT . Obsługiwane wartości to 3 i 65537. Wszystkie zalecane wartości to wartości pierwsze do 2^64.

Poniższe parametry nie są konieczne do wygenerowania klucza RSA, ale utworzenie klucza RSA bez nich daje klucz, którego nie można użyć. Jednak funkcja generateKey nie zwraca błędu, jeśli te parametry zostaną pominięte.

  • Tag::PURPOSE określa dozwolone cele. Wszystkie cele muszą być obsługiwane przez klucze RSA, w dowolnej kombinacji.
  • Tag::DIGEST określa algorytmy podsumowania, które mogą być użyte z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów skrótów, muszą akceptować żądania wygenerowania klucza, które zawierają nieobsługiwane skróty. Nieobsługiwane skróty należy umieścić na liście „wymuszone oprogramowaniem” w zwróconej kluczowej charakterystyce. Dzieje się tak dlatego, że klucza można używać z innymi skrótami, ale trawienie odbywa się w oprogramowaniu. Następnie wywoływany jest sprzęt w celu wykonania operacji z Digest::NONE .
  • Tag::PADDING określa tryby dopełniania, których można używać z nowym klawiszem. Implementacje, które nie obsługują wszystkich algorytmów podsumowania, muszą umieścić PaddingMode::RSA_PSS i PaddingMode::RSA_OAEP na wymuszanej programowo liście kluczowych cech, jeśli określono jakiekolwiek nieobsługiwane algorytmy podsumowania.

Klucze ECDSA

Do wygenerowania klucza ECDSA potrzebny jest tylko Tag::KEY_SIZE . Służy do wyboru grupy EC. Obsługiwane wartości to 224, 256, 384 i 521, które wskazują odpowiednio krzywe p-224, p-256, p-384 i p521 NIST.

Tag::DIGEST jest również niezbędny dla przydatnego klucza ECDSA, ale nie jest wymagany do jego wygenerowania.

Klucze AES

Do wygenerowania klucza AES potrzebny jest tylko Tag::KEY_SIZE . W przypadku pominięcia metoda zwraca ErrorCode::UNSUPPORTED_KEY_SIZE . Obsługiwane wartości to 128 i 256, z opcjonalną obsługą 192-bitowych kluczy AES.

Następujące parametry są szczególnie istotne w przypadku kluczy AES, ale nie są konieczne do ich wygenerowania:

  • Tag::BLOCK_MODE określa tryby blokowe, w których można używać nowego klucza.
  • Tag::PADDING określa tryby dopełniania, które mogą być używane. Dotyczy to tylko trybów EBC i CBC.

Jeśli określono tryb bloku GCM, podaj Tag::MIN_MAC_LENGTH . W przypadku pominięcia metoda zwraca ErrorCode::MISSING_MIN_MAC_LENGTH . Wartość tagu jest wielokrotnością 8 i mieści się w przedziale od 96 do 128.

Klucze HMAC

Do wygenerowania klucza HMAC wymagane są następujące parametry:

  • Tag::KEY_SIZE określa rozmiar klucza w bitach. Wartości mniejsze niż 64 i wartości, które nie są wielokrotnościami 8, nie są obsługiwane. Obsługiwane są wszystkie wielokrotności liczby 8, od 64 do 512. Większe wartości mogą być obsługiwane.
  • Tag::MIN_MAC_LENGTH określa minimalną długość adresów MAC, które można wygenerować lub zweryfikować za pomocą tego klucza. Wartość jest wielokrotnością 8 i co najmniej 64.
  • Tag::DIGEST określa algorytm skrótu dla klucza. Określono dokładnie jeden skrót, w przeciwnym razie zwróć ErrorCode::UNSUPPORTED_DIGEST . Jeśli podsumowanie nie jest obsługiwane przez trustlet, zwróć ErrorCode::UNSUPPORTED_DIGEST .

Cechy charakterystyczne

Jeśli argument charakterystyki nie ma wartości NULL, generateKey zwraca charakterystykę nowo wygenerowanego klucza podzieloną odpowiednio na listy wymuszane sprzętowo i wymuszane programowo. Zobacz getKeyCharacteristics , aby uzyskać opis, które cechy znajdują się na której liście. Zwrócone cechy obejmują wszystkie parametry określone do generowania klucza, z wyjątkiem Tag::APPLICATION_ID i Tag::APPLICATION_DATA . Jeśli te znaczniki zostały uwzględnione w kluczowych parametrach, są one usuwane ze zwróconych cech, tak że nie będzie możliwe znalezienie ich wartości poprzez sprawdzenie zwróconego obiektu typu blob klucza. Są one jednak kryptograficznie powiązane z obiektem blob klucza, więc jeśli podczas używania klucza nie zostaną podane prawidłowe wartości, użycie nie powiedzie się. Podobnie Tag::ROOT_OF_TRUST jest kryptograficznie powiązany z kluczem, ale może nie zostać określony podczas tworzenia lub importu klucza i nigdy nie jest zwracany.

Oprócz dostarczonych tagów trustlet dodaje również Tag::ORIGIN z wartością KeyOrigin::GENERATED i jeśli klucz jest odporny na wycofanie,

Tag::ROLLBACK_RESISTANT .

Opór cofania

Odporność na wycofywanie oznacza, że ​​po usunięciu klucza za pomocą polecenia DeleteKey lub DeleteAllKeys bezpieczny sprzęt gwarantuje, że nigdy więcej nie będzie można go użyć. Implementacje bez odporności na wycofywanie zazwyczaj zwracają wygenerowany lub zaimportowany materiał klucza do obiektu wywołującego jako kluczowy obiekt blob, czyli zaszyfrowaną i uwierzytelnioną formę. Gdy magazyn kluczy usuwa obiekt BLOB klucza, klucz znika, ale osoba atakująca, której udało się wcześniej odzyskać materiał klucza, może potencjalnie przywrócić go na urządzeniu.

Klucz jest odporny na wycofanie, jeśli bezpieczny sprzęt gwarantuje, że usuniętych kluczy nie będzie można później przywrócić. Zwykle odbywa się to poprzez przechowywanie dodatkowych kluczowych metadanych w zaufanej lokalizacji, która nie może zostać zmanipulowana przez osobę atakującą. Na urządzeniach mobilnych wykorzystywanym do tego mechanizmem są zwykle bloki pamięci chronione przed odtwarzaniem (RPMB). Ponieważ liczba kluczy, które można utworzyć, jest w zasadzie nieograniczona, a zaufana pamięć używana do zabezpieczenia przed wycofywaniem może mieć ograniczony rozmiar, metoda ta musi się powieść, nawet jeśli dla nowego klucza nie można zapewnić odporności na wycofywanie. W takim przypadku do kluczowych cech nie należy dodawać Tag::ROLLBACK_RESISTANT .

pobierzKeyCharakterystyka

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako get_key_characteristics i zmieniona nazwa w Keymaster 3.

Zwraca parametry i autoryzacje powiązane z podanym kluczem, podzielone na dwa zestawy: wymuszane sprzętowo i wymuszane programowo. Poniższy opis odnosi się w równym stopniu do list kluczowych cech zwracanych przez generateKey i importKey .

Jeśli podczas generowania lub importu klucza podano Tag::APPLICATION_ID , ta sama wartość jest dostarczana do tej metody w argumencie clientId . W przeciwnym razie metoda zwraca ErrorCode::INVALID_KEY_BLOB . Podobnie, jeśli podczas generowania lub importu podano Tag::APPLICATION_DATA , ta sama wartość zostanie przekazana tej metodzie w argumencie appData .

Charakterystyka zwrócona przez tę metodę całkowicie opisuje typ i użycie określonego klucza.

Ogólna zasada podejmowania decyzji, czy dany znacznik należy do listy wymuszanej sprzętowo, czy programowo, jest taka, że ​​jeśli znaczenie znacznika jest w pełni zabezpieczone przez bezpieczny sprzęt, jest ono wymuszane sprzętowo. W przeciwnym razie jest to wymuszane programowo. Poniżej znajduje się lista konkretnych tagów, których prawidłowe przypisanie może być niejasne:

  • Tag::ALGORITHM , Tag::KEY_SIZE i Tag::RSA_PUBLIC_EXPONENT są nieodłącznymi właściwościami klucza. W przypadku każdego klucza zabezpieczonego sprzętowo znaczniki te będą znajdować się na liście wymuszanej sprzętowo.
  • Wartości Tag::DIGEST obsługiwane przez bezpieczny sprzęt są umieszczane na liście obsługiwanych sprzętów. Nieobsługiwane skróty znajdują się na liście obsługiwanych programów.
  • Wartości Tag::PADDING zazwyczaj znajdują się na liście obsługiwanych sprzętowo, chyba że istnieje możliwość, że konieczne będzie wykonanie określonego trybu dopełniania przez oprogramowanie. W takim przypadku trafiają na listę wymuszaną programowo. Taka możliwość pojawia się w przypadku kluczy RSA, które pozwalają na uzupełnienie PSS lub OAEP algorytmami skrótu, które nie są obsługiwane przez bezpieczny sprzęt.
  • Etykiety Tag::USER_SECURE_ID i Tag::USER_AUTH_TYPE są wymuszane sprzętowo tylko wtedy, gdy uwierzytelnianie użytkownika jest wymuszane sprzętowo. Aby to osiągnąć, zaufany klucz Keymaster i odpowiedni zaufany uwierzytelniający muszą być bezpieczne i mieć wspólny tajny klucz HMAC używany do podpisywania i sprawdzania tokenów uwierzytelniania. Aby uzyskać szczegółowe informacje, zobacz stronę Uwierzytelnianie .
  • Tagi Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME i Tag ::USAGE_EXPIRE_DATETIME wymagają dostępu do weryfikowalnie prawidłowego zegara ściennego. Większość bezpiecznego sprzętu ma dostęp wyłącznie do informacji o czasie dostarczonych przez niezabezpieczony system operacyjny, co oznacza, że ​​znaczniki są wymuszane programowo.
  • Tag::ORIGIN zawsze znajduje się na liście sprzętu dla kluczy powiązanych ze sprzętem. Jego obecność na tej liście pozwala wyższym warstwom określić, czy klucz jest wspierany sprzętowo.

klucz importu

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako import_key i zmieniona nazwa w Keymaster 3.

Importuje kluczowy materiał do sprzętu Keymaster. Parametry definicji klucza i charakterystyki wyjściowe są obsługiwane tak samo jak w przypadku generateKey , z następującymi wyjątkami:

  • Tag::KEY_SIZE i Tag::RSA_PUBLIC_EXPONENT (tylko dla kluczy RSA) nie są konieczne w parametrach wejściowych. Jeśli nie zostanie podany, trustlet wyprowadza wartości z dostarczonego materiału klucza i dodaje odpowiednie znaczniki i wartości do kluczowych cech. Jeśli parametry zostaną podane, trustlet sprawdza je w oparciu o kluczowy materiał. W przypadku niezgodności metoda zwraca ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Zwrócony Tag::ORIGIN ma taką samą wartość jak KeyOrigin::IMPORTED .

klucz eksportu

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako export_key i zmieniona nazwa w Keymaster 3.

Eksportuje klucz publiczny z pary kluczy Keymaster RSA lub EC.

Jeśli podczas generowania lub importu klucza podano Tag::APPLICATION_ID , ta sama wartość jest dostarczana do tej metody w argumencie clientId . W przeciwnym razie metoda zwraca ErrorCode::INVALID_KEY_BLOB . Podobnie, jeśli podczas generowania lub importu podano Tag::APPLICATION_DATA , ta sama wartość jest przekazywana tej metodzie w argumencie appData .

usuńKlucz

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako delete_key i zmieniona nazwa w Keymaster 3.

Usuwa podany klucz. Ta metoda jest opcjonalna i jest realizowana tylko przez moduły Keymaster, które zapewniają odporność na wycofanie.

usuńWszystkie klucze

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako delete_all_keys i zmieniona nazwa w Keymaster 3.

Usuwa wszystkie klucze. Ta metoda jest opcjonalna i jest realizowana tylko przez moduły Keymaster, które zapewniają odporność na wycofanie.

zniszczyćIdentyfikatoryAtestacji

Wersja : 3

destroyAttestationIds() służy do trwałego wyłączenia nowej (opcjonalnej, ale zdecydowanie zalecanej) funkcji poświadczania tożsamości . Jeśli TEE nie ma sposobu, aby zapewnić trwałe wyłączenie zaświadczania identyfikatora po wywołaniu tej metody, wówczas zaświadczanie identyfikatora nie może być w ogóle implementowane. W takim przypadku metoda ta nie robi nic i zwraca ErrorCode::UNIMPLEMENTED . Jeśli obsługiwane jest poświadczanie tożsamości, należy wdrożyć tę metodę i trwale wyłączać wszystkie przyszłe próby poświadczania tożsamości. Metodę można wywołać dowolną ilość razy. Jeśli zaświadczenie identyfikatora jest już trwale wyłączone, metoda nie robi nic i zwraca ErrorCode::OK .

Jedyne kody błędów, które może zwrócić ta metoda, to ErrorCode::UNIMPLEMENTED (jeśli zaświadczenie ID nie jest obsługiwane), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED lub jeden z kodów błędów wskazujących brak komunikacji z bezpiecznym sprzętem.

zaczynać

Wersja : 1, 2, 3

Rozpoczyna operację kryptograficzną przy użyciu określonego klucza, w określonym celu, z określonymi parametrami (w zależności od potrzeb) i zwraca uchwyt operacji używany podczas aktualizacji i zakończenia w celu zakończenia operacji. Uchwyt operacji jest również używany jako token „wyzwania” w operacjach uwierzytelnionych i dla takich operacji jest zawarty w polu challenge tokenu uwierzytelniania.

Implementacja Keymaster obsługuje co najmniej 16 jednoczesnych operacji. Magazyn kluczy wykorzystuje do 15, pozostawiając jeden do wykorzystania przez vold do szyfrowania haseł. Kiedy Keystore ma 15 operacji w toku (wywołano begin , ale nie wywołano jeszcze finish ani abort ) i otrzyma żądanie rozpoczęcia 16-tej, wywołuje abort dla ostatnio używanej operacji, aby zmniejszyć liczbę aktywnych operacji do 14 przed begin wywołania, aby rozpocząć nowo żądaną operację.

Jeśli podczas generowania lub importowania klucza określono Tag::APPLICATION_ID lub Tag::APPLICATION_DATA , wywołania funkcji begin uwzględniają te znaczniki z pierwotnie określonymi wartościami w argumencie inParams tej metody.

Egzekucja autoryzacji

Podczas tej metody zaufane autoryzacje wymuszają następujące autoryzacje kluczy, jeśli implementacja umieściła je w charakterystyce „wymuszanej sprzętowo” i jeśli operacja nie jest operacją na kluczu publicznym. Operacje na kluczach publicznych, czyli KeyPurpose::ENCRYPT i KeyPurpose::VERIFY , z kluczami RSA lub EC, mogą zakończyć się sukcesem nawet jeśli wymagania autoryzacyjne nie są spełnione.

  • Tag::PURPOSE : Cel określony w wywołaniu begin() musi odpowiadać jednemu z celów określonych w autoryzacji klucza, chyba że żądana operacja jest operacją na kluczu publicznym. Jeśli określony cel nie jest zgodny i operacja nie jest operacją na kluczu publicznym, begin zwróci ErrorCode::UNSUPPORTED_PURPOSE . Operacje na kluczu publicznym to asymetryczne operacje szyfrowania lub weryfikacji.
  • Tag::ACTIVE_DATETIME można wymusić tylko wtedy, gdy dostępne jest zaufane źródło czasu UTC. Jeśli bieżąca data i godzina przypada przed wartością tagu, metoda zwraca ErrorCode::KEY_NOT_YET_VALID .
  • Tag::ORIGINATION_EXPIRE_DATETIME można wymusić tylko wtedy, gdy dostępne jest zaufane źródło czasu UTC. Jeśli bieżąca data i godzina jest późniejsza niż wartość tagu, a celem jest KeyPurpose::ENCRYPT lub KeyPurpose::SIGN , metoda zwraca ErrorCode::KEY_EXPIRED .
  • Tag::USAGE_EXPIRE_DATETIME można wymusić tylko wtedy, gdy dostępne jest zaufane źródło czasu UTC. Jeśli bieżąca data i godzina jest późniejsza niż wartość tagu, a celem jest KeyPurpose::DECRYPT lub KeyPurpose::VERIFY , metoda zwraca ErrorCode::KEY_EXPIRED .
  • Tag::MIN_SECONDS_BETWEEN_OPS jest porównywany z zaufanym względnym licznikiem czasu wskazującym ostatnie użycie klucza. Jeśli czas ostatniego użycia plus wartość znacznika jest krótszy niż bieżący czas, metoda zwraca ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Zobacz opis tagu , aby poznać ważne szczegóły implementacji.
  • Tag::MAX_USES_PER_BOOT jest porównywany z bezpiecznym licznikiem, który śledzi użycie klucza od czasu rozruchu. Jeśli liczba poprzednich zastosowań przekracza wartość tagu, metoda zwraca ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Tag::USER_SECURE_ID jest wymuszany tą metodą tylko wtedy, gdy klucz ma również Tag::AUTH_TIMEOUT . Jeśli klucz ma oba, wówczas ta metoda musi otrzymać prawidłowy Tag::AUTH_TOKEN w inParams . Aby token autoryzacji był ważny, muszą być spełnione wszystkie poniższe warunki:
    • Pole HMAC sprawdza poprawność.
    • Co najmniej jedna z wartości Tag::USER_SECURE_ID z klucza odpowiada co najmniej jednej z wartości bezpiecznego identyfikatora w tokenie.
    • Klucz ma Tag::USER_AUTH_TYPE , który odpowiada typowi uwierzytelniania w tokenie.

    Jeśli którykolwiek z tych warunków nie jest spełniony, metoda zwraca ErrorCode::KEY_USER_NOT_AUTHENTICATED .

  • Tag::CALLER_NONCE pozwala wywołującemu określić wartość jednorazową lub wektor inicjujący (IV). Jeśli klucz nie ma tego znacznika, ale wywołujący podał do tej metody Tag::NONCE , zwracany jest ErrorCode::CALLER_NONCE_PROHIBITED .
  • Tag::BOOTLOADER_ONLY określa, że ​​tylko program ładujący może używać klucza. Jeśli ta metoda zostanie wywołana z kluczem przeznaczonym tylko dla programu ładującego po zakończeniu wykonywania programu ładującego, zwróci ErrorCode::INVALID_KEY_BLOB .

Klucze RSA

Wszystkie operacje na klawiszach RSA określają dokładnie jeden tryb dopełniania w inParams . Jeśli nie określono lub określono więcej niż raz, metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE .

Operacje podpisywania i weryfikacji RSA wymagają skrótu, podobnie jak operacje szyfrowania i deszyfrowania RSA w trybie uzupełniania OAEP. W takich przypadkach osoba wywołująca określa dokładnie jedno podsumowanie w inParams . Jeśli nie określono lub określono więcej niż raz, metoda zwraca ErrorCode::UNSUPPORTED_DIGEST .

Operacje na kluczu prywatnym ( KeyPurpose::DECYPT i KeyPurpose::SIGN ) wymagają autoryzacji skrótu i ​​dopełnienia, co oznacza, że ​​autoryzacje klucza muszą zawierać określone wartości. Jeśli nie, metoda zwraca odpowiednio ErrorCode::INCOMPATIBLE_DIGEST lub ErrorCode::INCOMPATIBLE_PADDING . Operacje na kluczu publicznym ( KeyPurpose::ENCRYPT i KeyPurpose::VERIFY ) są dozwolone z nieautoryzowanym skrótem lub dopełnieniem.

Z wyjątkiem PaddingMode::NONE , wszystkie tryby dopełniania RSA mają zastosowanie tylko do określonych celów. W szczególności PaddingMode::RSA_PKCS1_1_5_SIGN i PaddingMode::RSA_PSS obsługują tylko podpisywanie i weryfikację, podczas gdy PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT i PaddingMode::RSA_OAEP obsługują tylko szyfrowanie i deszyfrowanie. Metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE , jeśli określony tryb nie obsługuje określonego celu.

Istnieje kilka ważnych interakcji pomiędzy trybami uzupełniania i skrótami:

  • PaddingMode::NONE wskazuje, że wykonywana jest „surowa” operacja RSA. W przypadku podpisywania lub weryfikacji, dla podsumowania jest określony Digest::NONE . Do szyfrowania lub deszyfrowania bez wypełnienia nie jest konieczne żadne podsumowanie.
  • Dopełnienie PaddingMode::RSA_PKCS1_1_5_SIGN wymaga podsumowania. Skrótem może być Digest::NONE , w którym to przypadku implementacja Keymaster nie może zbudować prawidłowej struktury podpisu PKCS#1 v1.5, ponieważ nie może dodać struktury DigestInfo. Zamiast tego implementacja konstruuje 0x00 || 0x01 || PS || 0x00 || M , gdzie M to dostarczony komunikat, a PS to ciąg dopełniający. Rozmiar klucza RSA musi być co najmniej 11 bajtów większy od wiadomości, w przeciwnym razie metoda zwróci ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT dopełnienie nie wymaga skrótu.
  • Dopełnienie PaddingMode::RSA_PSS wymaga skrótu, który może nie być Digest::NONE . Jeśli określono Digest::NONE , metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST . Ponadto rozmiar klucza RSA musi być co najmniej o 2 + D bajtów większy niż wyjściowy rozmiar skrótu, gdzie D jest rozmiarem skrótu w bajtach. W przeciwnym razie metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST . Rozmiar soli to D.
  • Dopełnienie PaddingMode::RSA_OAEP wymaga skrótu, który może nie być Digest::NONE . Jeśli określono Digest::NONE , metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST .

Klucze EC

Operacje na klawiszach EC określają dokładnie jeden tryb dopełniania w inParams . Jeśli nie określono lub określono więcej niż raz, metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE .

Operacje na kluczu prywatnym ( KeyPurpose::SIGN ) wymagają autoryzacji skrótu i ​​dopełnienia, co oznacza, że ​​autoryzacje klucza muszą zawierać określone wartości. Jeśli nie, zwróć ErrorCode::INCOMPATIBLE_DIGEST . Operacje na kluczu publicznym ( KeyPurpose::VERIFY ) są dozwolone z nieautoryzowanym skrótem lub dopełnieniem.

Klucze AES

Operacje na klawiszach AES określają dokładnie jeden tryb blokowy i jeden tryb dopełniania w inParams . Jeśli którakolwiek wartość jest nieokreślona lub określona więcej niż raz, zwróć ErrorCode::UNSUPPORTED_BLOCK_MODE lub ErrorCode::UNSUPPORTED_PADDING_MODE . Określone tryby muszą być autoryzowane kluczem, w przeciwnym razie metoda zwróci ErrorCode::INCOMPATIBLE_BLOCK_MODE lub ErrorCode::INCOMPATIBLE_PADDING_MODE .

Jeśli tryb blokowy to BlockMode::GCM , inParams określa Tag::MAC_LENGTH , a określona wartość jest wielokrotnością 8, która nie jest większa niż 128 lub mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacjach klucza. W przypadku długości MAC większych niż 128 lub niebędących wielokrotnościami 8 zwróć ErrorCode::UNSUPPORTED_MAC_LENGTH . W przypadku wartości mniejszych niż minimalna długość klucza zwróć ErrorCode::INVALID_MAC_LENGTH .

Jeśli tryb blokowania to BlockMode::GCM lub BlockMode::CTR , określony tryb dopełniania musi mieć wartość PaddingMode::NONE . W przypadku BlockMode::ECB lub BlockMode::CBC trybem może być PaddingMode::NONE lub PaddingMode::PKCS7 . Jeśli tryb dopełniania nie spełnia tych warunków, zwróć ErrorCode::INCOMPATIBLE_PADDING_MODE .

Jeśli tryb blokowy to BlockMode::CBC , BlockMode::CTR lub BlockMode::GCM , potrzebny jest wektor inicjujący lub wartość jednorazowa. W większości przypadków osoby dzwoniące nie powinny podawać kroplówki ani jednorazowej kwoty. W takim przypadku implementacja Keymaster generuje losową wartość IV lub nonce i zwraca ją poprzez Tag::NONCE w outParams . Wartości CBC i CTR IV mają 16 bajtów. Nonce GCM mają 12 bajtów. Jeśli autoryzacje klucza zawierają Tag::CALLER_NONCE , wówczas osoba wywołująca może podać IV/nonce z Tag::NONCE w inParams . Jeśli podano wartość jednorazową, gdy Tag::CALLER_NONCE nie jest autoryzowany, zwróć ErrorCode::CALLER_NONCE_PROHIBITED . Jeśli wartość jednorazowa nie zostanie podana podczas autoryzacji Tag::CALLER_NONCE , wygeneruj losową wartość IV/nonce.

Klucze HMAC

Operacje na kluczach HMAC określają Tag::MAC_LENGTH w inParams . Podana wartość musi być wielokrotnością liczby 8, która nie jest większa niż długość skrótu ani mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacjach klucza. W przypadku długości MAC większych niż długość skrótu lub wartości innych niż wielokrotność 8 zwróć ErrorCode::UNSUPPORTED_MAC_LENGTH . W przypadku wartości mniejszych niż minimalna długość klucza zwróć ErrorCode::INVALID_MAC_LENGTH .

aktualizacja

Wersja : 1, 2, 3

Dostarcza dane do przetworzenia w trwającej operacji rozpoczętej od Begin . Operację określa się parametrem operationHandle .

Aby zapewnić większą elastyczność obsługi buforów, implementacje tej metody umożliwiają zużywanie mniejszej ilości danych niż podano. Osoba wywołująca jest odpowiedzialna za pętlę dostarczającą resztę danych w kolejnych wywołaniach. Ilość zużytych danych wejściowych jest zwracana w parametrze inputConsumed . Implementacje zawsze zajmują co najmniej jeden bajt, chyba że operacja nie może przyjąć więcej; jeśli podano więcej niż zero bajtów i zużyto zero bajtów, obiekty wywołujące uznają to za błąd i przerywają operację.

Implementacje mogą również decydować, ile danych ma zostać zwróconych w wyniku aktualizacji. Ma to znaczenie tylko w przypadku operacji szyfrowania i deszyfrowania, ponieważ podpisywanie i weryfikacja nie zwracają żadnych danych do czasu zakończenia . Zwróć dane tak wcześnie, jak to możliwe, zamiast je buforować.

Obsługa błędów

Jeśli ta metoda zwróci kod błędu inny niż ErrorCode::OK , operacja zostanie przerwana, a dojście operacji zostanie unieważnione. Każde przyszłe użycie uchwytu za pomocą tej metody Finish lub Abort zwraca ErrorCode::INVALID_OPERATION_HANDLE .

Egzekucja autoryzacji

Wymuszanie autoryzacji klucza odbywa się głównie w pliku Begin . Jedynym wyjątkiem jest przypadek, gdy klucz posiada:

W tym przypadku klucz wymaga autoryzacji dla każdej operacji, a metoda aktualizacji otrzymuje Tag::AUTH_TOKEN w argumencie inParams . HMAC sprawdza, czy token jest ważny i zawiera pasujący bezpieczny identyfikator użytkownika, pasuje do klucza Tag::USER_AUTH_TYPE i zawiera uchwyt operacji bieżącej operacji w polu wyzwania. Jeśli te warunki nie są spełnione, zwróć ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Obiekt wywołujący udostępnia token uwierzytelniający przy każdym wywołaniu w celu aktualizacji i zakończenia . Implementacja musi tylko raz zweryfikować token, jeśli tak woli.

Klucze RSA

W przypadku operacji podpisywania i weryfikacji za pomocą Digest::NONE ta metoda akceptuje podpisanie lub weryfikację całego bloku w ramach jednej aktualizacji. Nie może zużywać tylko części bloku. Jeśli jednak wywołujący zdecyduje się udostępnić dane w wielu aktualizacjach, ta metoda to zaakceptuje. Jeśli wywołujący podaje więcej danych do podpisu, niż można użyć (długość danych przekracza rozmiar klucza RSA), zwróć ErrorCode::INVALID_INPUT_LENGTH .

Klucze ECDSA

W przypadku operacji podpisywania i weryfikacji za pomocą Digest::NONE ta metoda akceptuje podpisanie lub weryfikację całego bloku w ramach jednej aktualizacji. Ta metoda nie może zużywać tylko części bloku.

Jeśli jednak wywołujący zdecyduje się udostępnić dane w wielu aktualizacjach, ta metoda to zaakceptuje. Jeśli obiekt wywołujący udostępni do podpisania więcej danych, niż można ich użyć, dane zostaną dyskretnie obcięte. (Różni się to od obsługi nadmiaru danych dostarczonych w podobnych operacjach RSA. Powodem tego jest kompatybilność ze starszymi klientami.)

Klucze AES

Tryb AES GCM obsługuje „powiązane dane uwierzytelniające” dostarczane za pośrednictwem tagu Tag::ASSOCIATED_DATA w argumencie inParams . Powiązane dane mogą być dostarczane w powtarzanych wywołaniach (ważne, jeśli dane są zbyt duże, aby wysłać je w jednym bloku), ale zawsze poprzedzają dane do zaszyfrowania lub odszyfrowania. Wywołanie aktualizacji może obejmować zarówno powiązane dane, jak i dane do zaszyfrowania/odszyfrowania, ale kolejne aktualizacje mogą nie zawierać powiązanych danych. Jeśli wywołujący udostępnia powiązane dane z wywołaniem aktualizacji po wywołaniu zawierającym dane do zaszyfrowania/odszyfrowania, zwróć ErrorCode::INVALID_TAG .

W przypadku szyfrowania GCM znacznik jest dołączany do tekstu zaszyfrowanego po zakończeniu . Podczas deszyfrowania znacznikiem są ostatnie bajty Tag::MAC_LENGTH danych dostarczonych do ostatniego wywołania aktualizacji. Ponieważ dane wywołanie aktualizacji nie może wiedzieć, czy jest to ostatnie wywołanie, przetwarza ono wszystko oprócz długości znacznika i buforuje możliwe dane znacznika podczas zakończenia .

skończyć

Wersja : 1, 2, 3

Kończy trwającą operację rozpoczętą od Begin , przetwarzając wszystkie jeszcze nieprzetworzone dane dostarczone przez aktualizacje .

Ta metoda jest ostatnią wywoływaną w operacji, więc wszystkie przetworzone dane są zwracane.

Niezależnie od tego, czy zakończy się pomyślnie, czy zwraca błąd, ta metoda finalizuje operację, a zatem unieważnia podany uchwyt operacyjny. Wszelkie przyszłe użycie uchwytu, z tą metodą, aktualizacją lub przerywaniem , zwraca ErrorCode::INVALID_OPERATION_HANDLE .

Operacje podpisywania Zwraca podpis jako wyjście. Operacje weryfikacyjne akceptują podpis w parametrze signature i nie zwracają wyjścia.

Egzekwowanie prawa autoryzacji

Kluczowe egzekwowanie autoryzacji jest wykonywane przede wszystkim na początek . Jednym wyjątkiem jest przypadek, w którym ma klucz:

W takim przypadku klucz wymaga autoryzacji na operację, a metoda aktualizacji odbiera tag :: Auth_Token w argumencie inParams . HMAC weryfikuje, że token jest prawidłowy i zawiera pasujący bezpieczny identyfikator użytkownika, pasuje do znacznika klucza :: user_auth_type i zawiera uchwyt operacyjny bieżącej operacji w polu prowokacji. Jeśli te warunki nie są spełnione, zwróć ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Dzwoniący zapewnia token uwierzytelniający każdemu wezwaniu do aktualizacji i zakończenia . Implementacja wymaga weryfikacji tokena tylko raz, jeśli woli.

Klucze RSA

Niektóre dodatkowe wymagania, w zależności od trybu wyściółki:

  • PaddingMode::NONE . W przypadku niezapadanych operacji podpisywania i szyfrowania, jeśli dostarczone dane są krótsze niż klucz, dane są zerowe po lewej stronie przed podpisaniem/szyfrowaniem. Jeśli dane mają taką samą długość co klucz, ale numerycznie większy, zwróć ErrorCode::INVALID_ARGUMENT . W przypadku operacji weryfikacji i deszyfrowania dane muszą być dokładnie tak długo, jak klucz. W przeciwnym razie zwróć ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . W przypadku operacji podpisanych przez PSS sól PSS jest rozmiarem komunikatu trawienia i losowo wygenerowana. Trawienie określone za pomocą TAG :: Digest w inputParams On Begin jest używany jako algorytm PSS Digest i jako algorytm MGF1 Digest.
  • PaddingMode::RSA_OAEP . Trawienie określone za pomocą TAG :: Digest w inputParams na początku jest używany jako algorytm OAEP Digest, a SHA1 jest używany jako algorytm trawienia MGF1.

Klucze ECDSA

Jeśli przewidziane dane dotyczące niezapadanego podpisywania lub weryfikacji są zbyt długie, obcięj je.

Klucze AES

Niektóre dodatkowe warunki, w zależności od trybu blokowego:

  • BlockMode::ECB lub BlockMode::CBC . Jeśli wyściółka jest PaddingMode::NONE , a długość danych nie jest wielokrotnością rozmiaru bloku AES, zwróć ErrorCode::INVALID_INPUT_LENGTH . Jeśli wyściółka jest PaddingMode::PKCS7 , wyłóż dane zgodnie ze specyfikacją PKCS#7. Należy pamiętać, że PKCS#7 zaleca dodanie dodatkowego bloku wyściółki, jeśli dane są wielokrotnością długości bloku.
  • BlockMode::GCM . Podczas szyfrowania, po przetworzeniu wszystkich tekstów, oblicz tag ( tag :: bajty Mac_Length ) i dołącz go do zwróconego tekstu szyfrowania. Podczas deszyfrowania przetwarzaj ostatni tag :: bajty Mac_Length jako znacznik. Jeśli weryfikacja znacznika nie powiedzie się, zwróć ErrorCode::VERIFICATION_FAILED .

anulować

Wersja : 1, 2, 3

Przerywa operację w toku. Po wezwaniu do przerwania, zwróć ErrorCode::INVALID_OPERATION_HANDLE do dowolnego użycia dostarczonego uchwytu operacyjnego z aktualizacją , wykończeniem lub przerywaniem .

get_supported_algorytms

Wersja 1

Zwraca listę algorytmów obsługiwanych przez implementację sprzętu Keymaster. Implementacja oprogramowania zwraca pustą listę; Hybrydowa implementacja zwraca listę zawierającą tylko algorytmy obsługiwane przez sprzęt.

Wdrożenia Keymaster 1 obsługują RSA, EC, AES i HMAC.

get_supported_block_modes

Wersja 1

Zwraca listę trybów bloków AES obsługiwanych przez implementację sprzętu Keymaster dla określonego algorytmu i celu.

W przypadku RSA, EC i HMAC, które nie są szyframi blokowymi, metoda zwraca pustą listę do wszystkich ważnych celów. Nieprawidłowe cele powinny spowodować, że metoda zwróci ErrorCode::INVALID_PURPOSE .

Wdrożenia Keymaster 1 obsługują EBC, CBC, CTR i GCM w zakresie szyfrowania i deszyfrowania AES.

get_supported_padding_modes

Wersja 1

Zwraca listę trybów wyściółki obsługiwanych przez implementację sprzętu Keymaster dla określonego algorytmu i celu.

HMAC i EC nie mają pojęcia wyściółki, więc metoda zwraca pustą listę do wszystkich ważnych celów. Nieprawidłowe cele powinny spowodować, że metoda zwróci ErrorCode::INVALID_PURPOSE .

W przypadku RSA implementacje Keymaster 1 obsługują:

  • Niepatrzone szyfrowanie, deszyfrowanie, podpisanie i weryfikacja. W przypadku niezapadanego szyfrowania i podpisywania, jeśli wiadomość jest krótsza niż moduł publiczny, implementacje muszą go lewy z zerami. W przypadku niezapadanego deszyfrowania i weryfikacji długość wejściowa musi pasować do wielkości modułu publicznego.
  • PKCS#1 V1.5 Szyfrowanie i podpisywanie trybów wyściółki
  • PSS o minimalnej długości soli wynoszącej 20
  • OAEP

W przypadku AE w trybach EBC i CBC implementacje Keymaster 1 nie obsługują wyściółki i PKC#7-padding. Tryby CTR i GCM obsługują tylko brak wyściółki.

get_supported_digests

Wersja 1

Zwraca listę trybów trawienia obsługiwanych przez implementację sprzętu Keymaster dla określonego algorytmu i celu.

Brak trybów AES nie obsługuje ani nie wymaga trawienia, więc metoda zwraca pustą listę do ważnych celów.

Implementacje Keymaster 1 mogą zaimplementować podzbiór zdefiniowanych podsumowań. Wdrożenia zapewniają SHA-256 i mogą zapewnić MD5, SHA1, SHA-224, SHA-256, SHA384 i SHA512 (pełny zestaw zdefiniowanych trawień).

get_supported_import_formats

Wersja 1

Zwraca listę formatów importu obsługiwanego przez implementację sprzętu Keymaster określonego algorytmu.

Implementacje Keymaster 1 obsługują format PKCS#8 (bez ochrony hasła) do importowania par kluczowych i EC oraz obsługi surowego importu AES i kluczowych materiałów HMAC.

get_supported_export_formats

Wersja 1

Zwraca listę formatów eksportowych obsługiwanych przez implementację sprzętu Keymaster określonego algorytmu.

Wdrożenia Keymaster1 obsługują format X.509 do eksportowania kluczy RSA i EC Public. Eksport prywatnych kluczy lub klawiszy asymetrycznych nie jest obsługiwany.

Funkcje historyczne

Keymaster 0

Poniższe funkcje należą do oryginalnej definicji Keymaster 0. Były one obecne w Keymaster 1 struct keymaster1_device_t. Jednak w Keymaster 1.0 nie zostały wdrożone, a ich wskaźniki funkcji zostały ustawione na NULL.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

Poniższe funkcje należą do definicji Keymaster 1, ale zostały usunięte w Keymaster 2, wraz z wymienionymi powyżej funkcjami Keymaster 0.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

Poniższe funkcje należą do definicji Keymaster 2, ale zostały usunięte w Keymaster 3, wraz z wymienionymi powyżej funkcjami Keymaster 1.

  • configure