Funkcje Keymastera, Funkcje Keymastera

Ta strona zawiera szczegółowe informacje ułatwiające implementację warstw abstrakcji sprzętu (HAL) Keymaster. Obejmuje każdą funkcję w interfejsie API oraz wersję Keymaster, w której ta funkcja jest dostępna, a także opisuje domyślną implementację. Więcej informacji na temat tagów znajdziesz na stronie Keymaster Tags .

Ogólne wytyczne wdrożeniowe

Poniższe wskazówki dotyczą wszystkich funkcji w interfejsie API.

Parametry wskaźnika wejściowego

Wersja : 1, 2

Parametry wskaźnika wejściowego, które nie są używane w danym wywołaniu, mogą mieć NULL . Rozmówca nie musi podawać symboli zastępczych. Na przykład niektóre typy i tryby kluczy mogą nie używać żadnych wartości z argumentu inParams , aby begin , więc osoba wywołująca może ustawić inParams na NULL lub podać pusty zestaw parametrów. Wywołujący mogą również podać nieużywane parametry, a metody Keymaster nie powinny powodować błędów.

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

Począwszy od Keymaster 3, nie ma parametrów wskaźnika. Wszystkie parametry są przekazywane przez odniesienia do wartości lub 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 NULL , powinna zwrócić ErrorCode::OUTPUT_PARAMETER_NULL .

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

Niewłaściwe użycie API

Wersja : 1, 2, 3

Istnieje wiele sposobów, dzięki którym dzwoniący mogą zgłaszać żądania, które nie mają sensu lub są głupie, ale nie są technicznie błędne. Implementacje Keymaster nie muszą w takich przypadkach kończyć się niepowodzeniem ani generować diagnostyki. Użycie zbyt małych kluczy, specyfikacja nieistotnych parametrów wejściowych, ponowne użycie IV lub nonces, generowanie kluczy bez celu (a więc bezużyteczne) 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.

Odpowiedzialność za to, aby wywołania do modułów Keymaster były rozsądne i użyteczne, spoczywają na aplikacjach, frameworku i magazynie kluczy Androida.

Funkcje

PobierzFunkcje sprzętu

Wersja : 3

Nowa metoda getHardwareFeatures udostępnia klientom kilka ważnych cech podstawowego bezpiecznego sprzętu. Metoda nie przyjmuje argumentów i zwraca cztery wartości, wszystkie logiczne:

  • isSecure jest true , jeśli klucze są przechowywane na bezpiecznym sprzęcie (TEE itp.) i nigdy go nie opuszczają.
  • supportsEllipticCurve ma wartość true , jeśli sprzęt obsługuje kryptografię krzywych eliptycznych z krzywymi NIST (P-224, P-256, P-384 i P-521).
  • supportsSymmetricCryptography ma wartość true , jeśli sprzęt obsługuje kryptografię symetryczną, w tym AES i HMAC.
  • supportsAttestation jest true , jeśli sprzęt obsługuje generowanie certyfikatów poświadczania klucza publicznego Keymaster, podpisanych kluczem wstrzykniętym w bezpieczne środowisko.

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

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

skonfigurować

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 producenta odczytują te pliki podczas uruchamiania.

Konfiguruje administratora. Ta metoda jest wywoływana raz po otwarciu urządzenia i przed jego użyciem. Służy do udostępniania administratorowi kluczy KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL . Do czasu wywołania tej metody wszystkie inne metody zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED . Wartości dostarczone przez tę metodę są akceptowane przez keymastera tylko raz na rozruch. Kolejne wywołania zwracają KM_ERROR_OK , ale nic nie robią.

Jeśli implementacja keymastera jest na bezpiecznym sprzęcie, a podane wartości wersji systemu operacyjnego i poziomu poprawek nie są zgodne z wartościami dostarczonymi bezpiecznemu sprzętowi przez bootloader (lub jeśli bootloader nie dostarczył wartości), 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);

addRngEntropia

Wersja : 1, 2, 3

Ta funkcja została wprowadzona w Keymaster 1 jako add_rng_entropy i przemianowana 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ę ze swoją pulą, która również musi zawierać wewnętrznie generowaną entropię ze sprzętowego generatora liczb losowych. Mieszanie powinno być obsługiwane tak, aby osoba atakująca, która ma pełną kontrolę nad bitami dostarczonymi przez addRngEntropy lub bitami generowanymi przez sprzęt, ale nie obydwoma, nie miała znaczącej 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 Keymaster mogą zwrócić ErrorCode::INVALID_INPUT_LENGTH , jeśli otrzymają więcej niż 2 KiB danych w jednym wywołaniu.

wygeneruj klucz

Wersja : 1, 2, 3

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

Generuje nowy klucz kryptograficzny, określając powiązane autoryzacje, które są na stałe powiązane z kluczem. Implementacje Keymaster uniemożliwiają użycie klucza w jakikolwiek sposób niezgodny z uprawnieniami określonymi w czasie generowania. W odniesieniu do autoryzacji, których bezpieczny sprzęt nie może wyegzekwować, obowiązek bezpiecznego sprzętu ogranicza się do zapewnienia, że ​​niewykonalne autoryzacje powiązane z kluczem nie mogą być modyfikowane, tak aby każde wywołanie getKeyCharacteristics zwracało pierwotną wartość. Ponadto charakterystyka zwracana przez generateKey prawidłowo przydziela autoryzacje między listami wymuszonymi sprzętowo i programowo. Zobacz getKeyCharacteristics , aby uzyskać więcej informacji.

Parametry dostarczone do generateKey zależą od typu generowanego klucza. Ta sekcja zawiera podsumowanie niezbędnych i opcjonalnych tagów 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. Zalecanymi wartościami są wszystkie rozmiary kluczy będące wielokrotnością 8.
  • Tag::RSA_PUBLIC_EXPONENT określa wartość publicznego wykładnika RSA. W przypadku pominięcia metoda zwraca ErrorCode::INVALID_ARGUMENT . Obsługiwane wartości to 3 i 65537. Zalecane wartości to wszystkie wartości pierwsze do 2^64.

Poniższe parametry nie są konieczne do wygenerowania klucza RSA, ale utworzenie klucza RSA bez nich powoduje wygenerowanie klucza, który jest bezużyteczny. 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 dla kluczy RSA w dowolnej kombinacji.
  • Tag::DIGEST określa algorytmy skrótu, które mogą być używane z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów skrótów, muszą akceptować żądania generowania kluczy, które zawierają nieobsługiwane skróty. Nieobsługiwane skróty powinny zostać umieszczone na liście „wymuszone programowo” w zwróconych parametrach klucza. Dzieje się tak, ponieważ klucz można używać z innymi skrótami, ale trawienie odbywa się w oprogramowaniu. Następnie wywoływany jest sprzęt do wykonania operacji z Digest::NONE .
  • Tag::PADDING określa tryby dopełniania, które mogą być używane z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów skrótu, muszą umieścić PaddingMode::RSA_PSS i PaddingMode::RSA_OAEP na wymuszonej przez oprogramowanie liście cech kluczowych, jeśli określono jakiekolwiek nieobsługiwane algorytmy skrótu.

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 NIST p-224, p-256, p-384 i p521.

Tag::DIGEST jest również niezbędny dla użytecznego klucza ECDSA, ale nie jest wymagany do generowania.

Klawisze 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 dla kluczy AES, ale nie są konieczne do ich wygenerowania:

  • Tag::BLOCK_MODE określa tryby bloku, z którymi może być używany nowy klucz.
  • Tag::PADDING określa tryby dopełniania, które mogą być użyte. Dotyczy to tylko trybów ECB i CBC.

Jeśli określono tryb blokowy 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 zakresie od 96 do 128.

Klawisze HMAC

Do generowania kluczy 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ścią 8, nie są obsługiwane. Obsługiwane są wszystkie wielokrotności 8, od 64 do 512. Mogą być obsługiwane większe wartości.
  • 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 skrót nie jest obsługiwany przez trustlet, zwróć ErrorCode::UNSUPPORTED_DIGEST .

Cechy charakterystyczne

Jeśli argument właściwości nie ma wartości NULL, generateKey zwraca właściwości nowo wygenerowanego klucza podzielone odpowiednio na listy wymuszane sprzętowo i programowo. Zobacz getKeyCharacteristics , aby dowiedzieć się, które cechy znajdują się na której liście. Zwracane cechy zawierają 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 parametrach kluczowych, są usuwane z zwracanych cech, aby nie było możliwe odnalezienie ich wartości przez zbadanie zwróconego obiektu 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 być określony podczas tworzenia lub importowania klucza i nigdy nie jest zwracany.

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

Etykieta::ROLLBACK_RESISTANT .

Odporność na wycofywanie

Odporność na wycofywanie oznacza, że ​​gdy klucz zostanie usunięty za pomocą deleteKey lub deleteAllKeys , bezpieczny sprzęt gwarantuje, że nigdy nie będzie można go ponownie użyć. Implementacje bez odporności na wycofywanie zwykle zwracają wygenerowany lub zaimportowany materiał klucza do wywołującego jako obiekt BLOB klucza, zaszyfrowany i uwierzytelniony formularz. Gdy magazyn kluczy usuwa obiekt BLOB klucza, klucz znika, ale osoba atakująca, która wcześniej zdołała pobrać materiał klucza, może potencjalnie przywrócić go na urządzeniu.

Klucz jest odporny na wycofywanie, jeśli bezpieczny sprzęt gwarantuje, że usuniętych kluczy nie można później przywrócić. Zwykle odbywa się to poprzez przechowywanie dodatkowych kluczowych metadanych w zaufanej lokalizacji, której atakujący nie może zmanipulować. Na urządzeniach mobilnych mechanizmem używanym do tego jest zwykle Replay Protected Memory Blocks (RPMB). Ponieważ liczba kluczy, które można utworzyć, jest zasadniczo nieograniczona, a zaufany magazyn używany do odporności na wycofywanie może mieć ograniczony rozmiar, ta metoda musi się powieść, nawet jeśli nie można zapewnić odporności na wycofywanie dla nowego klucza. W takim przypadku Tag::ROLLBACK_RESISTANT nie powinien być dodawany do kluczowej charakterystyki.

getKeyCharacteristics

Wersja : 1, 2, 3

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

Zwraca parametry i uprawnienia związane z dostarczonym kluczem, podzielone na dwa zestawy: wymuszone sprzętowo i wymuszone programowo. Opis w tym miejscu dotyczy w równym stopniu list cech kluczowych zwracanych przez generateKey i importKey .

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

Charakterystyki zwracane przez tę metodę całkowicie opisują typ i użycie określonego klucza.

Ogólna zasada przy podejmowaniu decyzji o tym, czy dany znacznik należy do listy wymuszonej sprzętowo, czy programowo, jest taka, że ​​jeśli znaczenie znacznika jest w pełni zapewnione przez bezpieczny sprzęt, jest on wymuszony sprzętowo. W przeciwnym razie jest to wymuszone przez oprogramowanie. Poniżej znajduje się lista konkretnych tagów, których poprawna alokacja może być niejasna:

  • Tag::ALGORITHM , Tag::KEY_SIZE i Tag::RSA_PUBLIC_EXPONENT to wewnętrzne właściwości klucza. W przypadku każdego klucza zabezpieczonego sprzętowo tagi te będą znajdować się na liście wymuszonych sprzętowo.
  • Wartości Tag::DIGEST obsługiwane przez bezpieczny sprzęt są umieszczane na liście obsługiwanych urządzeń. Nieobsługiwane skróty trafiają na listę obsługiwanych przez oprogramowanie.
  • Wartości Tag::PADDING zazwyczaj znajdują się na liście obsługiwanych sprzętowo, chyba że istnieje możliwość, że określony tryb dopełnienia może być wykonywany przez oprogramowanie. W takim przypadku trafiają na listę wymuszoną przez oprogramowanie. Taka możliwość pojawia się w przypadku kluczy RSA, które umożliwiają wypełnianie PSS lub OAEP algorytmami skrótu, które nie są obsługiwane przez bezpieczny sprzęt.
  • 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 certyfikat Keymaster i odpowiedni certyfikat uwierzytelniający muszą być bezpieczne i współdzielić tajny klucz HMAC używany do podpisywania i weryfikowania tokenów uwierzytelniania. Zobacz stronę Uwierzytelnianie , aby uzyskać szczegółowe informacje.
  • Tagi::ACTIVE_DATETIME , Tag ::ORIGINATION_EXPIRE_DATETIME i Tag::USAGE_EXPIRE_DATETIME wymagają dostępu do zegara ściennego, który można zweryfikować. Najbardziej bezpieczny sprzęt ma dostęp tylko do informacji o czasie dostarczanych przez niezabezpieczony system operacyjny, co oznacza, że ​​tagi są wymuszane programowo.
  • Tag::ORIGIN jest zawsze na liście sprzętu dla kluczy związanych ze sprzętem. Jego obecność na tej liście jest sposobem, w jaki wyższe warstwy określają, że klucz jest wspierany sprzętowo.

importKey

Wersja : 1, 2, 3

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

Importuje materiał klucza 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ą wymagane w parametrach wejściowych. Jeśli nie zostanie podany, trustlet wydedukuje wartości z dostarczonego materiału klucza i dodaje odpowiednie znaczniki i wartości do kluczowych cech. Jeśli podano parametry, trustlet weryfikuje je pod kątem materiału klucza. W przypadku niezgodności metoda zwraca ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Zwrócony Tag::ORIGIN ma taką samą wartość jak KeyOrigin::IMPORTED .

exportKey

Wersja : 1, 2, 3

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

Eksportuje klucz publiczny z pary kluczy Keymaster RSA lub EC.

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

UsuńKlucz

Wersja : 1, 2, 3

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

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

usuń wszystkie klawisze

Wersja : 1, 2, 3

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

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

zniszczyćAtestationIds

Wersja : 3

Metoda destroyAttestationIds() służy do trwałego wyłączenia nowej (opcjonalnej, ale wysoce zalecanej) funkcji poświadczania identyfikatorów . Jeśli TEE nie ma możliwości zapewnienia, że ​​zaświadczanie identyfikatora jest trwale wyłączone po wywołaniu tej metody, wówczas zaświadczanie identyfikatora nie może być w ogóle zaimplementowane, w takim przypadku ta metoda nic nie robi i zwraca ErrorCode::UNIMPLEMENTED . Jeśli zaświadczanie identyfikatora jest obsługiwane, ta metoda musi zostać zaimplementowana i musi trwale wyłączyć wszystkie przyszłe próby zaświadczania identyfikatora. Metodę można wywoływać dowolną liczbę razy. Jeśli zaświadczanie identyfikatora jest już trwale wyłączone, metoda nic nie robi i zwraca ErrorCode::OK .

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

zaczynać

Wersja : 1, 2, 3

Rozpoczyna operację kryptograficzną przy użyciu określonego klucza w określonym celu z określonymi parametrami (odpowiednio) i zwraca uchwyt operacji, który jest używany z update i finish w celu ukończenia operacji. Uchwyt operacji jest również używany jako token „wyzwania” w uwierzytelnianych operacjach i dla takich operacji jest zawarty w polu challenge tokenu uwierzytelnienia.

Implementacja Keymaster obsługuje co najmniej 16 jednoczesnych operacji. Keystore używa do 15, pozostawiając jeden dla vold do szyfrowania hasła. Gdy Keystore ma 15 operacji w toku ( begin , ale finish lub abort nie zostały jeszcze wywołane) i otrzymuje żądanie rozpoczęcia 16., wywołuje abort na ostatnio używanej operacji, aby zmniejszyć liczbę aktywnych operacji do 14 przed wywołaniem begin nowo żądaną operację.

Jeśli Tag::APPLICATION_ID lub Tag::APPLICATION_DATA zostały określone podczas generowania lub importowania klucza, wywołania begin zawierają te znaczniki z pierwotnie określonymi wartościami w argumencie inParams tej metody.

Egzekwowanie uprawnień

Podczas tej metody następujące autoryzacje kluczy są wymuszane przez trustlet, jeśli implementacja umieściła je w charakterystyce „wymuszonej sprzętowo” i jeśli operacja nie jest operacją z użyciem klucza publicznego. Operacje na kluczu publicznym, czyli KeyPurpose::ENCRYPT i KeyPurpose::VERIFY , z kluczami RSA lub EC, mogą się powieść, nawet jeśli wymagania dotyczące autoryzacji nie są spełnione.

  • Tag::CEL : Cel określony w wywołaniu begin() musi odpowiadać jednemu z celów w autoryzacji klucza, chyba że żądana operacja jest operacją klucza publicznego. Jeśli określony cel nie pasuje, a operacja nie jest operacją z kluczem 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 są wcześniejsze od 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 są późniejsze niż wartość znacznika, 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 są późniejsze 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 zegarem wskazującym ostatnie użycie klucza. Jeśli czas ostatniego użycia plus wartość tagu jest krótszy niż czas bieżący, 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 użyć przekracza wartość tagu, metoda zwraca ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Tag::USER_SECURE_ID jest wymuszany przez tę metodę tylko wtedy, gdy klucz ma również Tag::AUTH_TIMEOUT . Jeśli klucz ma oba, to ta metoda musi otrzymać prawidłowy Tag::AUTH_TOKEN w inParams . Aby token uwierzytelniania był ważny, muszą być spełnione wszystkie poniższe warunki:
    • Pole HMAC sprawdza się poprawnie.
    • Co najmniej jedna z wartości Tag::USER_SECURE_ID z klucza jest zgodna z co najmniej jedną 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 dzwoniącemu określić jednorazowy lub wektor inicjujący (IV). Jeśli klucz nie ma tego tagu, ale obiekt wywołujący dostarczył tag::NONCE do tej metody, zwracany jest ErrorCode::CALLER_NONCE_PROHIBITED .
  • Tag::BOOTLOADER_ONLY określa, że ​​tylko bootloader może używać klucza. Jeśli ta metoda jest wywoływana z kluczem tylko dla bootloadera po zakończeniu wykonywania bootloadera, zwraca 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 odszyfrowywania RSA w trybie dopełniania OAEP. W takich przypadkach obiekt wywołujący określa dokładnie jeden skrót 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ę, natomiast PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT i PaddingMode::RSA_OAEP obsługują tylko szyfrowanie i odszyfrowywanie. Metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE , jeśli określony tryb nie obsługuje określonego celu.

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

  • PaddingMode::NONE wskazuje, że wykonywana jest „surowa” operacja RSA. W przypadku podpisywania lub weryfikacji, Digest::NONE jest określany dla skrótu. Skrót nie jest potrzebny do niepełnego szyfrowania lub deszyfrowania.
  • PaddingMode::RSA_PKCS1_1_5_SIGN dopełnienie wymaga skrótu. Skrótem może być Digest::NONE , w którym to przypadku implementacja Keymaster nie może zbudować prawidłowej struktury sygnatury PKCS#1 v1.5, ponieważ nie może dodać struktury DigestInfo. Zamiast tego implementacja konstruuje 0x00 || 0x01 || PS || 0x00 || M , gdzie M jest dostarczoną wiadomością, a PS jest ciągiem wypełniającym. Rozmiar klucza RSA musi być co najmniej 11 bajtów większy niż wiadomość, w przeciwnym razie metoda zwraca ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT dopełnienie nie wymaga skrótu.
  • 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ć o co najmniej 2 + D bajtów większy niż rozmiar wyjściowy skrótu, gdzie D jest rozmiarem skrótu w bajtach. W przeciwnym razie metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST . Rozmiar soli to D.
  • PaddingMode::RSA_OAEP dopełnienie wymaga skrótu, który może nie być Digest::NONE . Jeśli określono Digest::NONE , metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST .

klawisze WE

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 ​​autoryzacja klucza musi 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.

Klawisze 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 przez klucz, w przeciwnym razie metoda zwraca 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 adresów MAC o długości większej niż 128 lub niewielokrotności 8 zwróć ErrorCode::UNSUPPORTED_MAC_LENGTH . W przypadku wartości mniejszych niż minimalna długość klucza zwróć ErrorCode::INVALID_MAC_LENGTH .

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

Jeśli tryb blokowy to BlockMode::CBC , BlockMode::CTR lub BlockMode::GCM , wymagany jest wektor inicjujący lub jednorazowy. W większości przypadków dzwoniący nie powinni podawać IV ani jednorazówki. W takim przypadku implementacja Keymaster generuje losową wartość IV lub jednorazową i zwraca ją przez Tag::NONCE w outParams . CBC i CTR IV mają 16 bajtów. Nonces GCM mają 12 bajtów. Jeśli autoryzacja klucza zawiera Tag::CALLER_NONCE , osoba wywołująca może podać IV/nonce z Tag::NONCE w inParams . Jeśli podano jednorazową wartość, gdy Tag::CALLER_NONCE nie jest autoryzowany, zwróć ErrorCode::CALLER_NONCE_PROHIBITED . Jeśli numer jednorazowy nie jest podany, gdy Tag::CALLER_NONCE jest autoryzowany, wygeneruj losowe IV/noce.

Klawisze 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 kluczy. W przypadku adresów MAC o długości większej niż długość skrótu lub niewielokrotności 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 . Operacja jest określona przez parametr operationHandle .

Aby zapewnić większą elastyczność obsługi buforów, implementacje tej metody mają opcję zużywania mniejszej ilości danych niż zostało dostarczone. Dzwoniący jest odpowiedzialny za pętlę w celu dostarczenia reszty danych w kolejnych połączeniach. Ilość zużytych danych wejściowych jest zwracana w parametrze inputConsumed . Implementacje zawsze zużywają co najmniej jeden bajt, chyba że operacja nie może zaakceptować więcej; jeśli podano więcej niż zero bajtów i zero bajtów zostało zużytych, wywołujący uważają to za błąd i przerywają operację.

Implementacje mogą również wybrać, ile danych ma zostać zwróconych w wyniku aktualizacji. Dotyczy to tylko operacji szyfrowania i odszyfrowywania, ponieważ podpisywanie i weryfikacja nie zwracają żadnych danych do końca . Zwróć dane tak szybko, 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 .

Egzekwowanie uprawnień

Egzekwowanie autoryzacji klucza odbywa się głównie w begin . Jedynym wyjątkiem jest przypadek, w którym klucz ma:

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

Obiekt wywołujący dostarcza token uwierzytelniania do każdego wywołania aktualizacji i zakończenia . Implementacja musi tylko raz zweryfikować token, jeśli 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 obiekt wywołujący zdecyduje się udostępnić dane w wielu aktualizacjach, ta metoda je zaakceptuje. Jeśli obiekt wywołujący dostarcza więcej danych do podpisania, 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 obiekt wywołujący zdecyduje się udostępnić dane w wielu aktualizacjach, ta metoda je zaakceptuje. Jeśli osoba wywołująca dostarczy więcej danych do podpisania, niż można wykorzystać, dane są dyskretnie obcinane. (Różni się to od obsługi nadmiaru danych dostarczanych w podobnych operacjach RSA. Powodem tego jest zgodność ze starszymi klientami).

Klawisze AES

Tryb AES GCM obsługuje „skojarzone dane uwierzytelniające” dostarczane przez tag Tag::ASSOCIATED_DATA w argumencie inParams . Powiązane dane mogą być dostarczane w powtarzających się wywołaniach (ważne, jeśli dane są zbyt duże do wysłania w jednym bloku), ale zawsze poprzedzają dane do zaszyfrowania lub odszyfrowania. Wywołanie aktualizacji może odbierać zarówno dane skojarzone, jak i dane do zaszyfrowania/odszyfrowania, ale kolejne aktualizacje mogą nie zawierać skojarzonych danych. Jeśli obiekt wywołujący dostarcza skojarzone dane z wywołaniem aktualizacji po wywołaniu, które zawiera dane do zaszyfrowania/odszyfrowania, zwróć ErrorCode::INVALID_TAG .

W przypadku szyfrowania GCM tag jest dołączany do zaszyfrowanego tekstu przez finish . Podczas odszyfrowywania Tag::MAC_LENGTH jest ostatnim bajtem danych dostarczonych do ostatniego wywołania aktualizacji. Ponieważ dane wywołanie update nie może wiedzieć, czy jest to ostatnie wywołanie, przetwarza wszystko poza długością tagu i buforuje możliwe dane tagu podczas finish .

koniec

Wersja : 1, 2, 3

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure