Funkcje Keymastera

Ta strona zawiera szczegółowe informacje, które ułatwią implementację warstw abstrakcji sprzętowej (HAL) Keymaster. Zawiera opis każdej funkcji interfejsu API oraz wersji Keymaster, w której jest ona dostępna, a także implementację domyślną. Informacje o tagach znajdziesz na stronie Tagi Keymaster.

Ogólne wskazówki dotyczące implementacji

Te wytyczne obowiązują w przypadku wszystkich funkcji interfejsu API.

Parametry wskaźnika danych wejściowych

Wersja: 1, 2

Parametry wskaźnika wejściowego, które nie są używane w przypadku danego wywołania, mogą być oznaczone jako NULL. Wywołujący nie musi podawać obiektów zastępczych. Na przykład niektóre typy i tryby klucza mogą nie używać żadnych wartości z argumentu inParams w begin, więc wywołujący może ustawić inParams na NULL lub podać pusty zestaw parametrów. Użytkownicy mogą też podawać nieużywane parametry, a metody Keymaster nie powinny generować błędów.

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

Od wersji Keymaster 3 nie ma już parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartość lub odwołania const.

Parametry wskaźnika wyjściowego

Wersja: 1, 2

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

Od wersji Keymaster 3 nie ma już parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartość lub odwołania const.

Niewłaściwe użycie interfejsu API

Wersja: 1, 2, 3

Wywołujący mogą wysyłać żądania, które nie mają sensu lub są niemądre, ale nie są błędne pod względem technicznym. W takich przypadkach nie jest wymagane, aby implementacje Keymaster zakończyły działanie ani nie były w stanie przeprowadzić diagnostyki. Implementacje nie powinny diagnozować korzystania z za małych kluczy, określania nieistotnych parametrów wejściowych, ponownego używania IV lub nonce, generowania kluczy bez celu (czyli bezużytecznych) itp. Należy zdiagnozować pominięcie wymaganych parametrów, podanie nieprawidłowych wymaganych parametrów i podobnych błędów.

Odpowiedzialność za to, aby wywołania do modułów Keymaster były sensowne i przydatne, spoczywa na aplikacjach, frameworku i magazynie kluczy Androida.

Funkcje

getHardwareFeatures

Wersja: 3

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

  • isSecure to true, jeśli klucze są przechowywane na bezpiecznym sprzęcie (TEE itp.) i nigdy go nie opuszczają.
  • supportsEllipticCurve jest true, jeśli sprzęt obsługuje szyfrowanie za pomocą krzywych eliptycznych z krzywami NIST (P-224, P-256, P-384 i P-521).
  • supportsSymmetricCryptography to true, jeśli sprzęt obsługuje szyfrowanie symetryczne, w tym AES i HMAC.
  • supportsAttestation jest true, jeśli sprzęt obsługuje generowanie certyfikatów atestackich klucza publicznego Keymaster, podpisanych kluczem wstrzykniętym w bezpiecznym środowisku.

Ta metoda może zwrócić tylko kody błędów ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED lub jeden z kodów błędów wskazujących na 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 wycofana w Keymaster 3, ponieważ te informacje są dostępne w plikach właściwości systemowych, a implementacje producentów odczytują te pliki podczas uruchamiania.

Konfiguruje Keymaster. Ta metoda jest wywoływana raz po otwarciu urządzenia i przed jego użyciem. Służy do przekazywania kluczowi masterowi wartości KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL. Do czasu wywołania tej metody wszystkie inne zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED. Wartości podane w ramach tej metody są akceptowane przez keymastera tylko raz podczas uruchamiania. Kolejne wywołania zwracają KM_ERROR_OK, ale nic nie robią.

Jeśli implementacja klucza głównego znajduje się na bezpiecznym sprzęcie, a podane wartości poziomu wersji i aktualizacji systemu operacyjnego nie pasują do wartości przekazanych bezpiecznemu sprzętowi przez program ładujący (lub jeśli program ładujący nie podał żadnych wartości), ta metoda zwraca KM_ERROR_INVALID_ARGUMENT, a 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);

addRngEntropy

Wersja: 1, 2, 3

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

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

Implementacje Keymaster muszą bezpiecznie mieszać dostarczoną entropię w swojej puli, która musi też zawierać entropię wygenerowaną wewnętrznie przez sprzętowy generator liczb losowych. Mieszanie powinno być obsługiwane w taki sposób, aby atakujący, który ma pełną kontrolę nad bitami dostarczanymi przez addRngEntropy lub generowanymi przez sprzęt, ale nie nad obiema tymi opcjami, nie miał znaczącej przewagi w przewidywaniu bitów wygenerowanych z pulu entropii.

Implementacje Keymaster, które próbują oszacować entropię w swoim wewnętrznym zbiorze, zakładają, że dane udostępnione przez addRngEntropy nie zawierają entropii. Implementacje Keymaster mogą zwracać ErrorCode::INVALID_INPUT_LENGTH, jeśli w pojedynczym wywołaniu otrzymają więcej niż 2 KiB danych.

generateKey

Wersja: 1, 2, 3

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

Generuje nowy klucz kryptograficzny, określając powiązane autoryzacje, które są trwale powiązane z kluczem. Implementacje Keymaster uniemożliwiają użycie klucza w sposób niezgodny z autoryzacjami określonymi w momencie jego utworzenia. W przypadku autoryzacji, których nie można zastosować w sprzęcie zabezpieczonym, odpowiedzialność tego sprzętu ogranicza się do zapewnienia, że niewykonalne autoryzacje powiązane z kluczem nie mogą zostać zmienione, tak aby każde wywołanie funkcji getKeyCharacteristics zwracało pierwotną wartość. Dodatkowo funkcje zwracane przez generateKey poprawnie przypisują uprawnienia do list kontrolowanych przez sprzęt i oprogramowanie. Aby dowiedzieć się więcej, zapoznaj się z funkcją getKeyCharacteristics.

Parametry przekazywane do funkcji generateKey zależą od typu generowanego klucza. W tej sekcji znajdziesz podsumowanie tagów wymaganych i opcjonalnych dla każdego typu klucza. Tag::ALGORITHM jest zawsze wymagany, aby określić typ.

Klucze RSA

Do wygenerowania klucza RSA są potrzebne te parametry.

  • Tag::KEY_SIZE określa rozmiar publicznego modułu w bitach. Jeśli pominiesz ten parametr, metoda zwróci wartość ErrorCode::UNSUPPORTED_KEY_SIZE. Obsługiwane wartości to 1024, 2048, 3072 i 4096. Zalecane wartości to wszystkie rozmiary kluczy, które są wielokrotnością 8.
  • Tag::RSA_PUBLIC_EXPONENT określa wartość wykładniczej klucza publicznego RSA. Jeśli pominiesz tę właściwość, metoda zwróci wartość ErrorCode::INVALID_ARGUMENT. Obsługiwane wartości to 3 i 65 537. Zalecane wartości to wszystkie wartości pierwsze do 2^64.

Poniższe parametry nie są wymagane do wygenerowania klucza RSA, ale wygenerowanie klucza RSA bez nich spowoduje, że nie będzie on można użyć. Funkcja generateKey nie zwraca jednak błędu, jeśli pominiesz te parametry.

  • Tag::PURPOSE określa dozwolone cele. Klucze RSA muszą obsługiwać wszystkie cele w dowolnej kombinacji.
  • Tag::DIGEST określa algorytmy szyfrowania, które można stosować z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów digest, muszą akceptować żądania generowania kluczy, które zawierają nieobsługiwane digesty. Nieobsługiwane zbiorcze zestawienia informacji powinny być umieszczane na liście „Wymuszane przez oprogramowanie” w charakterystyce klucza zwracanego. Dzieje się tak, ponieważ klucz można używać z tymi innymi skrótami, ale ich generowanie odbywa się w oprogramowaniu. Następnie wywoływany jest sprzęt, aby wykonać operację Digest::NONE.
  • Tag::PADDING określa tryby wypełnienia, których można używać z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów digest, muszą umieścić wartościPaddingMode::RSA_PSS i PaddingMode::RSA_OAEP na liście kluczowych cech wymuszonych przez oprogramowanie, jeśli są określone nieobsługiwane algorytmy digest.

Klucze ECDSA

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

Tag::DIGEST jest też potrzebny do utworzenia klucza ECDSA, ale nie jest wymagany do jego wygenerowania.

Klucze AES

Do wygenerowania klucza AES potrzebna jest tylko wartość Tag::KEY_SIZE. Jeśli pominiesz tę wartość, metoda zwróci ErrorCode::UNSUPPORTED_KEY_SIZE. Obsługiwane wartości to 128 i 256, z opcjonalnym wsparciem dla kluczy AES 192-bitowych.

Te parametry są szczególnie istotne w przypadku kluczy AES, ale nie są konieczne do ich wygenerowania:

  • Tag::BLOCK_MODE określa tryby blokowania, w których można używać nowego klucza.
  • Tag::PADDING określa tryby wypełniania, których można używać. Dotyczy to tylko trybów ECB i CBC.

Jeśli podano tryb blokowania GCM, podaj wartość Tag::MIN_MAC_LENGTH. Jeśli pominiesz tę wartość, metoda zwróci wartość ErrorCode::MISSING_MIN_MAC_LENGTH. Wartość tagu jest wielokrotnością 8 i mieści się w przedziale od 96 do 128.

Klucze HMAC

Do generowania klucza HMAC wymagane są te 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ść ciągów MAC, które można wygenerować lub zweryfikować za pomocą tego klucza. Wartość jest wielokrotnością 8 i nie mniejsza niż 64.
  • Tag::DIGEST określa algorytm skrótu dla klucza. Musi być podany dokładnie jeden digest, w przeciwnym razie zwracany jest ErrorCode::UNSUPPORTED_DIGEST. Jeśli digest nie jest obsługiwany przez element zaufania, zwraca: ErrorCode::UNSUPPORTED_DIGEST.

Najważniejsze cechy

Jeśli argument characteristics jest inny niż NULL, funkcja generateKey zwraca właściwości nowo wygenerowanego klucza podzielone na listy z wymuszeniami sprzętowymi i oprogramowania. Informacje o tym, które cechy znajdują się na której liście, znajdziesz w metodzie getKeyCharacteristics. Zwracane właściwości obejmują wszystkie parametry określone do generowania klucza, z wyjątkiem parametrów Tag::APPLICATION_ID i Tag::APPLICATION_DATA. Jeśli te tagi były uwzględnione w parametrach klucza, są usuwane z zwróconych cech, aby nie można było znaleźć ich wartości, analizując zwrócony klucz blob. Są one jednak powiązane kryptograficznie z blobem klucza, więc jeśli podczas używania klucza nie zostaną podane prawidłowe wartości, nie uda się go użyć. Podobnie parametr Tag::ROOT_OF_TRUST jest powiązany z kluczem za pomocą kryptografii, ale nie można go określić podczas tworzenia lub importowania klucza i nigdy nie jest zwracany.

Oprócz podanych tagów element zaufania dodaje też tag Tag::ORIGIN z wartością KeyOrigin::GENERATED, a jeśli klucz jest odporny na cofnięcie, tag Tag::ROLLBACK_RESISTANT.

Ochrona przed przywróceniem starszych kluczy

Odporność na cofanie oznacza, że gdy klucz zostanie usunięty za pomocą funkcji deleteKey lub deleteAllKeys, zabezpieczenia sprzętowe zagwarantują, że nie będzie można go już nigdy użyć. W implementacjach bez odporności na cofanie zmian generowany lub zaimportowany materiał klucza jest zwykle zwracany do wywołującego w postaci bloba klucza, czyli zaszyfrowanej i uwierzytelnionej formy. Gdy schowisko kluczy usunie klucz blob, klucz zniknie, ale atakujący, który wcześniej odzyskał materiał klucza, może go przywrócić na urządzenie.

Klucz jest odporny na cofanie, jeśli sprzęt zabezpieczający gwarantuje, że usunięte klucze nie mogą zostać przywrócone później. Zwykle polega to na przechowywaniu dodatkowych metadanych klucza w zaufanej lokalizacji, którą osoba atakująca nie może zmienić. Na urządzeniach mobilnych mechanizmem używanym do tego celu są zazwyczaj bloki pamięci chronione przed wielokrotnym odtwarzaniem (RPMB). Liczba kluczy, które można utworzyć, jest w zasadzie nieograniczona, a zaufane miejsce na dane używane do ochrony przed cofnięciem może być ograniczone pod względem rozmiaru. Dlatego ta metoda musi się powieść, nawet jeśli nie można zapewnić odporności na cofnięcie dla nowego klucza. W takim przypadku element Tag::ROLLBACK_RESISTANT nie powinien być dodawany do kluczowych cech.

getKeyCharacteristics

Wersja: 1, 2, 3

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

Zwraca parametry i upoważnienia powiązane z podanym kluczem, podzielone na 2 zbiory: sprzętowe i oparte na oprogramowaniu. Opis tutaj dotyczy również list kluczowych cech zwracanych przez funkcje generateKey i importKey.

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

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

Ogólna zasada określania, czy dany tag należy do listy tagów obsługiwanych przez sprzęt czy oprogramowanie, jest taka, że jeśli znaczenie tagu jest w pełni zapewnione przez bezpieczny sprzęt, jest on obsługiwany przez sprzęt. W przeciwnym razie jest to wymuszane przez oprogramowanie. Poniżej znajdziesz listę konkretnych tagów, których przypisanie może być niejasne:

  • Tag::ALGORITHM, Tag::KEY_SIZE i Tag::RSA_PUBLIC_EXPONENT to właściwości klucza. W przypadku każdego klucza chronionego przez sprzęt te tagi znajdują się na liście tagów wymagających sprzętu.
  • Wartości Tag::DIGEST obsługiwane przez bezpieczny sprzęt są umieszczane na liście obsługiwanej przez sprzęt. Nieobsługiwane podsumowania są umieszczane na liście obsługiwanej przez oprogramowanie.
  • Wartości Tag::PADDING są zazwyczaj umieszczane na liście obsługiwanej przez sprzęt, chyba że istnieje możliwość, że określony tryb wypełnienia musi być wykonany przez oprogramowanie. W takim przypadku są one umieszczane na liście kontrolowanej przez oprogramowanie. Taka możliwość występuje w przypadku kluczy RSA, które zezwalają na wypełnianie PSS lub OAEP za pomocą algorytmów skrótu, które nie są obsługiwane przez bezpieczny sprzęt.
  • Tag::USER_SECURE_ID i Tag::USER_AUTH_TYPE są obsługiwane przez sprzęt tylko wtedy, gdy uwierzytelnianie użytkownika jest obsługiwane przez sprzęt. Aby to osiągnąć, zaufana aplikacja Keymaster i odpowiednia zaufana aplikacja uwierzytelniania muszą być bezpieczne i mieć wspólny klucz HMAC, który służy do podpisywania i weryfikowania tokenów uwierzytelniania. Więcej informacji znajdziesz na stronie Uwierzytelnianie.
  • Tagi Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME i Tag::USAGE_EXPIRE_DATETIME wymagają dostępu do poprawnego zegara systemowego, którego działanie można zweryfikować. Większość urządzeń zabezpieczających ma dostęp tylko do informacji o czasie dostarczanych przez niezabezpieczony system operacyjny, co oznacza, że tagi są egzekwowane przez oprogramowanie.
  • W przypadku kluczy powiązanych z urządzeniem parametr Tag::ORIGIN jest zawsze widoczny na liście sprzętu. Jego obecność na tej liście jest sposobem, w jaki wyższe warstwy określają, że klucz jest obsługiwany przez sprzęt.

importKey

Wersja: 1, 2, 3

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

Importuje materiał klucza do urządzenia Keymaster. Parametry definicji klucza i cechy wyjściowe są obsługiwane tak samo jak w przypadku funkcji generateKey, z tymi wyjątkami:

  • Parametry Tag::KEY_SIZE i Tag::RSA_PUBLIC_EXPONENT (tylko w przypadku kluczy RSA) nie są wymagane w parametrach wejściowych. Jeśli nie zostaną podane, trustlet wywnioskuje wartości z podanych kluczowych materiałów i doda odpowiednie tagi i wartości do kluczowych cech. Jeśli parametry są podane, zaufalność weryfikuje je na podstawie kluczowych materiałów. W przypadku niezgodności metoda zwraca wartość ErrorCode::IMPORT_PARAMETER_MISMATCH.
  • Zwracany parametr Tag::ORIGIN ma tę samą wartość co parametr KeyOrigin::IMPORTED.

exportKey

Wersja: 1, 2, 3

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

Eksportuje klucz publiczny z pary kluczy Keymaster RSA lub EC.

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

deleteKey

Wersja: 1, 2, 3

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

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

deleteAllKeys

Wersja: 1, 2, 3

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

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

destroyAttestationIds

Wersja: 3

Metoda destroyAttestationIds() służy do trwałego wyłączenia nowej (opcjonalnej, ale bardzo zalecanej) funkcji potwierdzania tożsamości. Jeśli TEE nie ma możliwości zapewnienia, że po wywołaniu tej metody weryfikacja tożsamości nie zostanie trwale wyłączona, oznacza to, że weryfikacja tożsamości nie została wdrożona. W takim przypadku ta metoda nie robi nic i zwraca wartość ErrorCode::UNIMPLEMENTED. Jeśli weryfikacja tożsamości jest obsługiwana, należy zaimplementować tę metodę i trwało wyłączyć wszystkie przyszłe próby weryfikacji tożsamości. Metodę można wywołać dowolną liczbę razy. Jeśli weryfikacja tożsamości jest już trwale wyłączona, metoda nie robi nic i zwraca wartość ErrorCode::OK.

Ta metoda może zwrócić tylko te kody błędów: ErrorCode::UNIMPLEMENTED (jeśli uwierzytelnianie tożsamości nie jest obsługiwane), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED lub jeden z kodów błędów wskazujących na niemożność nawiązania komunikacji z bezpiecznym sprzętem.

zacznij

Wersja: 1, 2, 3

Rozpoczyna operację kryptograficzną, używając określonego klucza, w określonym celu, z określonymi parametrami (w odpowiednich przypadkach) i zwraca identyfikator operacji, który jest używany z update i finish w celu zakończenia operacji. Uchwyt operacji jest też używany jako token „wyzwania” w operacjach uwierzytelnionych. W przypadku takich operacji jest on uwzględniony w polu challenge tokena uwierzytelniania.

Implementacja Keymaster obsługuje co najmniej 16 jednoczesnych operacji. Keystore używa maksymalnie 15 kluczy, pozostawiając jeden dla vold do szyfrowania haseł. Gdy Keystore ma 15 działających operacji (wywołano begin, ale finish lub abort nie zostały wywołane) i otrzyma prośbę o rozpoczęcie 16 operacji, wywołuje abort w ramach operacji, która była używana najwcześniej, aby zmniejszyć liczbę aktywnych operacji do 14 i następnie wywołać begin w ramach nowo żądanej operacji.

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

Egzekwowanie autoryzacji

W ramach tej metody zaufalność jest egzekwowana przez moduł zaufania, jeśli implementacja umieściła je w charakterystyce „wymuszonej przez sprzęt”, a operacja nie jest operacją klucza publicznego. Operacje z wykorzystaniem klucza publicznego, czyli KeyPurpose::ENCRYPT i KeyPurpose::VERIFY, z kluczami RSA lub EC, mogą się udać nawet wtedy, gdy nie są spełnione wymagania dotyczące autoryzacji.

  • Tag::PURPOSE: cel określony w wywołaniu begin() musi być zgodny z jednym z celów autoryzacji klucza, chyba że żądana operacja jest operacją klucza publicznego. Jeśli podany cel nie pasuje i operacja nie jest operacją dotyczącą klucza publicznego, begin zwraca ErrorCode::UNSUPPORTED_PURPOSE. Operacje z użyciem klucza publicznego to operacje szyfrowania asymetrycznego lub weryfikacji.
  • Tag Tag::ACTIVE_DATETIME może być stosowany tylko wtedy, gdy jest dostępny zaufany źródło czasu UTC. Jeśli bieżąca data i godzina są wcześniejsze niż wartość tagu, metoda zwraca ErrorCode::KEY_NOT_YET_VALID.
  • Tag::ORIGINATION_EXPIRE_DATETIME może być stosowany tylko wtedy, gdy jest dostępny zaufany źródło czasu UTC. Jeśli bieżąca data i godzina są późniejsze niż wartość tagu, a cel to KeyPurpose::ENCRYPT lub KeyPurpose::SIGN, metoda zwraca ErrorCode::KEY_EXPIRED.
  • Tag::USAGE_EXPIRE_DATETIME może być stosowany tylko wtedy, gdy jest dostępne zaufane źródło czasu UTC. Jeśli bieżąca data i godzina są późniejsze niż wartość tagu, a cel to 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 ostatnio używany klucz. Jeśli czas ostatniego użycia plus wartość tagu jest mniejsza niż bieżący czas, metoda zwraca wartość ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Ważne informacje o wdrożeniu znajdziesz w opisie tagu.
  • Tag::MAX_USES_PER_BOOT jest porównywany z bezpiecznym licznikiem, który śledzi użycie klucza od momentu uruchomienia. 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 zawiera też tag Tag::AUTH_TIMEOUT. Jeśli klucz zawiera obie te wartości, metoda musi otrzymać prawidłową wartość Tag::AUTH_TOKEN w inParams. Aby token uwierzytelniania był prawidłowy, muszą być spełnione wszystkie te warunki:
    • Pole HMAC jest poprawnie zweryfikowane.
    • co najmniej 1 wartośćTag::USER_SECURE_IDz klucza jest zgodna z co najmniej 1 wartością identyfikatora bezpiecznego w tokenie.
    • Klucz ma parametr Tag::USER_AUTH_TYPE, który jest zgodny z typem uwierzytelniania w tokenie.

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

  • Tag::CALLER_NONCE umożliwia rozmówcy podanie wartości nonce lub wektora inicjującego (IV). Jeśli klucz nie ma tego tagu, ale wywołujący podał Tag::NONCE w ramach tej metody, zwracana jest wartość ErrorCode::CALLER_NONCE_PROHIBITED.
  • Tag::BOOTLOADER_ONLY określa, że klucz może używać tylko bootloader. Jeśli ta metoda zostanie wywołana za pomocą klucza tylko dla programu rozruchowego po zakończeniu jego działania, zwróci wartość ErrorCode::INVALID_KEY_BLOB.

Klucze RSA

Wszystkie operacje na kluczu RSA określają dokładnie 1 tryb wypełniania w polu inParams. Jeśli nie podano tego argumentu lub podano go 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 wypełniania OAEP. W takich przypadkach wywołujący określa dokładnie 1 wartość digest w elementach inParams. Jeśli nie zostanie podany żaden argument lub zostanie podany więcej niż raz, metoda zwróci wartość ErrorCode::UNSUPPORTED_DIGEST.

Operacje klucza prywatnego (KeyPurpose::DECYPT i KeyPurpose::SIGN) wymagają autoryzacji skrótu i wypełniania, co oznacza, że autoryzacje klucza muszą zawierać określone wartości. W przeciwnym razie zwraca odpowiednio wartość ErrorCode::INCOMPATIBLE_DIGESTlub ErrorCode::INCOMPATIBLE_PADDING. Operacje z użyciem klucza publicznego (KeyPurpose::ENCRYPT i KeyPurpose::VERIFY) są dozwolone z nieautoryzowanym skrótem lub wypełnieniem.

Z wyjątkiem PaddingMode::NONE wszystkie tryby wypełniania danych RSA są stosowane 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ę, a PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT i PaddingMode::RSA_OAEP – tylko szyfrowanie i odszyfrowywanie. Jeśli określony tryb nie obsługuje określonego celu, metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE.

Istnieją pewne ważne zależności między trybami wypełnienia i wyciągiem:

  • PaddingMode::NONE oznacza, że wykonywana jest „surowa” operacja RSA. Jeśli podpisujesz lub weryfikujesz, Digest::NONE jest określony dla skrótu. W przypadku szyfrowania bez wypełnienia lub odszyfrowania nie jest potrzebny ciąg.
  • Dopełnienie PaddingMode::RSA_PKCS1_1_5_SIGN wymaga skrótu. Digest może być Digest::NONE, w którym przypadku implementacja Keymaster nie może utworzyć prawidłowej struktury podpisu PKCS#1 w wersji 1.5, ponieważ nie może dodać struktury DigestInfo. Zamiast tego implementacja tworzy 0x00 || 0x01 || PS || 0x00 || M, gdzie M to podana wiadomość, a PS to ciąg znaków wypełniającego. Rozmiar klucza RSA musi być co najmniej o 11 bajtów większy niż wiadomość, w przeciwnym razie metoda zwraca wartość ErrorCode::INVALID_INPUT_LENGTH.
  • Dopełnienie PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT nie wymaga skrótu.
  • Wypełnianie pola PaddingMode::RSA_PSS wymaga podania skrótu, który nie może być typu Digest::NONE. Jeśli określono parametr Digest::NONE, metoda zwraca wartość ErrorCode::INCOMPATIBLE_DIGEST. Dodatkowo rozmiar klucza RSA musi być co najmniej o 2 bajty większy od rozmiaru danych wyjściowych digestu, gdzie D to rozmiar digestu w bajtach. W przeciwnym razie zwraca wartość ErrorCode::INCOMPATIBLE_DIGEST. Rozmiar soli to D.
  • Wypełnianie pola PaddingMode::RSA_OAEP wymaga podania skrótu, który nie może być typu Digest::NONE. Jeśli określono parametr Digest::NONE, metoda zwraca wartość ErrorCode::INCOMPATIBLE_DIGEST.

Klucze EC

Operacje klucza EC określają dokładnie jeden tryb wypełniania w elementach inParams. Jeśli nie jest określony lub jest określony więcej niż raz, zwraca ErrorCode::UNSUPPORTED_PADDING_MODE.

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

Klucze AES

Operacje klucza AES określają dokładnie jeden tryb blokowania i jeden tryb wypełniania w inParams. Jeśli któraś z wartości nie jest określona lub jest określona więcej niż raz, zwracaj 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 blokowania to BlockMode::GCM, inParamsokreśla Tag::MAC_LENGTH, a podana wartość jest wielokrotnością 8, która nie jest większa niż 128 ani mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacjach klucza. W przypadku długości adresu MAC większej niż 128 lub niebędącej wielokrotnością 8 zwracaj ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości krótszych niż minimalna długość klucza zwraca ErrorCode::INVALID_MAC_LENGTH.

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

Jeśli tryb blokowania to BlockMode::CBC, BlockMode::CTR lub BlockMode::GCM, wymagany jest wektor inicjalizacji lub nonce. W większości przypadków wywołujący nie powinien podawać IV ani nonce. W takim przypadku implementacja Keymaster generuje losowy IV lub nonce i zwraca go za pomocą Tag::NONCE w outParams. CBC i CTR IV mają 16 bajtów. Losowe ciągi znaków GCM mają długość 12 bajtów. Jeśli autoryzacje klucza zawierają tag Tag::CALLER_NONCE, wywołujący może podać IV lub nonce za pomocą tagu Tag::NONCE w inParams. Jeśli w przypadku parametru Tag::CALLER_NONCE nie jest autoryzowany nonce, zwraca wartość ErrorCode::CALLER_NONCE_PROHIBITED. Jeśli Tag::CALLER_NONCE nie jest autoryzowany, wygeneruj losowy IV/nonce.

Klucze HMAC

Operacje klucza HMAC określają Tag::MAC_LENGTH w inParams. Podana wartość musi być wielokrotnością 8, która nie jest większa niż długość digest ani mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacjach klucza. W przypadku długości MAC większej niż długość skrótu lub niebędącej wielokrotnością 8 zwracaj ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości krótszych niż minimalna długość klucza zwracana jest wartość ErrorCode::INVALID_MAC_LENGTH.

aktualizować

Wersja: 1, 2, 3

Przekazuje dane do przetworzenia w ramach trwającej operacji rozpoczętej za pomocą instrukcji begin. Operacja jest określana przez parametr operationHandle.

Aby zapewnić większą elastyczność obsługi bufora, implementacje tej metody mają opcję zużycia mniejszej ilości danych niż podano. Rozmówca jest odpowiedzialny za przekazywanie pozostałych danych w kolejnych wywołaniach. Ilość wykorzystanych danych wejściowych jest zwracana w parametrze inputConsumed. Implementacje zawsze zużywają co najmniej 1 bajt, chyba że operacja nie może przyjąć więcej danych. Jeśli zostanie podanych więcej niż 0 bajtów, a zużycie będzie równe 0, wywołujący uzna to za błąd i przerwie operację.

Implementacje mogą też określić, ile danych mają zwrócić w ramach aktualizacji. Ma to zastosowanie tylko do operacji szyfrowania i odszyfrowywania, ponieważ podpisywanie i weryfikowanie nie zwracają żadnych danych, dopóki nie zakończą. Zwracaj dane jak najszybciej, a nie przechowuj ich w buforze.

Obsługa błędów

Jeśli ta metoda zwróci kod błędu inny niż ErrorCode::OK, operacja zostanie przerwana, a uchwyt operacji stanie się nieważny. Każde przyszłe użycie uchwytu za pomocą tej metody kończy lub przerywa i zwraca ErrorCode::INVALID_OPERATION_HANDLE.

Egzekwowanie autoryzacji

Egzekwowanie autoryzacji klucza jest wykonywane głównie w begin. Wyjątkiem jest sytuacja, w której klucz ma:

W tym przypadku klucz wymaga autoryzacji na potrzeby każdej operacji, a metoda update otrzymuje parametr inParams z wartością Tag::AUTH_TOKEN. HMAC weryfikuje, czy token jest prawidłowy i zawiera dopasowany bezpieczny identyfikator użytkownika, czy pasuje do klucza Tag::USER_AUTH_TYPE, a także czy zawiera identyfikator operacji bieżącej operacji w polu challenge. Jeśli te warunki nie są spełnione, ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Użytkownik dzwoniący podaje token uwierzytelniający w każdym wywołaniu, aby zaktualizować i zakończyć. Implementacja musi potwierdzić token tylko raz.

Klucze RSA

W przypadku operacji podpisywania i weryfikacji za pomocą Digest::NONE ta metoda akceptuje cały blok, który ma zostać podpisany lub zweryfikowany w ramach jednej aktualizacji. Nie może zużyć tylko części bloku. Jeśli jednak wywołujący zdecyduje się przesłać dane w kilku aktualizacjach, ta metoda je zaakceptuje. Jeśli wywołujący podaje więcej danych do podpisania, niż można wykorzystać (długość danych przekracza rozmiar klucza RSA), zwraca wartość ErrorCode::INVALID_INPUT_LENGTH.

Klucze ECDSA

W przypadku operacji podpisywania i weryfikacji za pomocą Digest::NONE ta metoda akceptuje cały blok, który ma zostać podpisany lub zweryfikowany w ramach jednej aktualizacji. Ta metoda nie może wykorzystywać tylko części bloku.

Jeśli jednak wywołujący zdecyduje się przekazać dane w kilku aktualizacjach, ta metoda je zaakceptuje. Jeśli dzwoniący poda więcej danych do podpisania, niż można wykorzystać, dane zostaną skrócone. (różni się to od obsługi nadmiarowych danych w przypadku podobnych operacji RSA). Powodem jest zgodność ze starszymi klientami.

Klucze AES

Tryb AES GCM obsługuje „powiązane dane uwierzytelniania” przekazywane za pomocą tagu Tag::ASSOCIATED_DATA w argumencie inParams. Powiązane dane mogą być podawane w powtarzających się wywołaniach (co jest ważne, jeśli dane są zbyt duże, aby wysłać je w pojedynczym bloku), ale zawsze poprzedzają dane, które mają zostać zaszyfrowane lub odszyfrowane. Wywołanie aktualizacji może zawierać zarówno powiązane dane, jak i dane do zaszyfrowania lub odszyfrowania, ale kolejne aktualizacje nie mogą zawierać powiązanych danych. Jeśli dzwoniący podaje powiązane dane w połączeniu aktualizującym po połączeniu, które zawiera dane do zaszyfrowania lub odszyfrowania, zwraca ErrorCode::INVALID_TAG.

W przypadku szyfrowania GCM tag jest dołączany do szyfrogramu przez funkcję finish. Podczas odszyfrowywania ostatnie Tag::MAC_LENGTH bajtów danych przekazanych do ostatniego wywołania metody update to tag. Ponieważ wywołanie funkcji update nie może wiedzieć, czy jest to ostatnie wywołanie, przetwarza wszystkie dane z wyjątkiem długości tagu i zapisuje do bufora możliwe dane tagu podczas finish.

zakończ

Wersja: 1, 2, 3

Zakończenie trwającej operacji rozpoczętej za pomocą funkcji begin, która przetwarza wszystkie nieprzetworzone jeszcze dane dostarczone przez update.

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

Niezależnie od tego, czy operacja zakończy się pomyślnie, czy zwróci błąd, ta metoda kończy operację, co powoduje unieważnienie przekazanego identyfikatora operacji. Każde przyszłe użycie uchwytu za pomocą tej metody lub metody update albo abort zwraca ErrorCode::INVALID_OPERATION_HANDLE.

Operacje podpisywania zwracają podpis jako dane wyjściowe. Operacje weryfikacyjne akceptują podpis w parametrze signature i nie zwracają żadnego wyniku.

Egzekwowanie autoryzacji

Wymuszanie autoryzacji klucza odbywa się głównie w begin. Wyjątkiem jest sytuacja, w której klucz ma:

W tym przypadku klucz wymaga autoryzacji na potrzeby każdej operacji, a metoda update otrzymuje parametr inParams z wartością Tag::AUTH_TOKEN. HMAC sprawdza, czy token jest prawidłowy i zawiera dopasowujący się bezpieczny identyfikator użytkownika, czy pasuje do klucza Tag::USER_AUTH_TYPE, a także czy zawiera identyfikator operacji bieżącej operacji w polu challenge. Jeśli te warunki nie są spełnione, ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Użytkownik wywołujący udostępnia token uwierzytelniania w każdym wywołaniu metody update i finish. Implementacja musi potwierdzić token tylko raz.

Klucze RSA

Dodatkowe wymagania w zależności od trybu wypełniania:

  • PaddingMode::NONE. W przypadku operacji podpisywania i szyfrowania bez wypełnienia, jeśli podane dane są krótsze niż klucz, przed podpisaniem/szyfrowaniem dane są uzupełniane zerami z zera po lewej stronie. Jeśli dane mają taką samą długość jak klucz, ale są większe pod względem liczbowym, zwracają ErrorCode::INVALID_ARGUMENT. W przypadku operacji weryfikacji i odszyfrowywania dane muszą mieć dokładnie taką samą długość jak klucz. W przeciwnym razie zwraca ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS. W przypadku operacji podpisywania z wypełnieniem PSS sól PSS ma rozmiar równy rozmiarowi digestu wiadomości i jest generowana losowo. Skrót określony za pomocą parametru Tag::DIGEST w elementach inputParams w sekcji begin jest używany jako algorytm PSS digest i jako algorytm MGF1 digest.
  • PaddingMode::RSA_OAEP. Digest określony za pomocą parametru Tag::DIGEST w inputParams na początku jest używany jako algorytm digest OAEP, a algorytm SHA1 jest używany jako algorytm digest MGF1.

Klucze ECDSA

Jeśli dane przekazane do podpisywania lub weryfikacji bez wypełnienia są za długie, je obcinaj.

Klucze AES

Dodatkowe warunki w zależności od trybu blokowania:

  • BlockMode::ECB lub BlockMode::CBC. Jeśli wypełnienie to PaddingMode::NONE, a długość danych nie jest wielokrotnością rozmiaru bloku AES, zwracaj ErrorCode::INVALID_INPUT_LENGTH. Jeśli wypełnianie jest ustawione naPaddingMode::PKCS7, wypełnij dane zgodnie ze specyfikacją PKCS#7. Pamiętaj, że PKCS#7 zaleca dodanie dodatkowego bloku wypełniania, jeśli dane są wielokrotnością długości bloku.
  • BlockMode::GCM. Podczas szyfrowania, po przetworzeniu całego tekstu zwykłego, oblicz znacznik (Tag::MAC_LENGTH bajtów) i dołącz go do zwróconego tekstu zaszyfrowanego. Podczas odszyfrowywania przetwórz ostatnie Tag::MAC_LENGTHbajty jako tag. Jeśli weryfikacja tagu się nie powiedzie, zwracaj ErrorCode::VERIFICATION_FAILED.

przerwij

Wersja: 1, 2, 3

Przerywa trwającą operację. Po wywołaniu funkcji przerwania zwracaj ErrorCode::INVALID_OPERATION_HANDLE w przypadku każdego kolejnego użycia przekazanego uchwytu operacji z update, finish lub abort.

get_supported_algorithms

Wersja: 1

Zwraca listę algorytmów obsługiwanych przez sprzętową implementację Keymaster. Implementacja oprogramowania zwraca pustą listę, a implementacja hybrydowa zwraca listę zawierającą tylko te algorytmy, które są obsługiwane przez sprzęt.

Implementacje Keymaster 1 obsługują protokoły RSA, EC, AES i HMAC.

get_supported_block_modes

Wersja: 1

Zwraca listę trybów blokowania AES obsługiwanych przez sprzętową implementację Keymastera w przypadku określonego algorytmu i celu.

W przypadku RSA, EC i HMAC, które nie są szyframi blokowymi, metoda zwraca pustą listę dla wszystkich prawidłowych celów. Nieprawidłowe cele powinny powodować zwracanie przez metodę wartości ErrorCode::INVALID_PURPOSE.

Implementacje Keymaster 1 obsługują szyfrowanie i odszyfrowywanie AES z użyciem algorytmów ECB, CBC, CTR i GCM.

get_supported_padding_modes

Wersja: 1

Zwraca listę trybów wypełniania obsługiwanych przez implementację sprzętową Keymastera dla określonego algorytmu i celu.

HMAC i EC nie mają pojęcia o wypełnianiu, więc metoda zwraca pustą listę dla wszystkich prawidłowych celów. Nieprawidłowe cele powinny powodować zwracanie przez metodę wartości ErrorCode::INVALID_PURPOSE.

W przypadku RSA implementacje Keymaster 1 obsługują:

  • Szyfrowanie bez wypełnienia, odszyfrowywanie, podpisywanie i weryfikacja. W przypadku niezabezpieczonego szyfrowania i podpisywania, jeśli wiadomość jest krótsza niż publiczny moduł, implementacje muszą ją uzupełnić zerami z zera po lewej stronie. W przypadku odszyfrowywania i weryfikacji bez wypełnienia długość danych wejściowych musi być zgodna z rozmiarem modułu publicznego.
  • Tryby wypełniania danych w procesie szyfrowania i podpisywania PKCS#1 w wersji 1.5
  • PSS z minimalną długością soli 20
  • OAEP

W przypadku AES w trybach ECB i CBC implementacje Keymaster 1 obsługują brak wypełnienia i wypełnienie PKCS#7. Tryby CTR i GCM obsługują tylko brak wypełnienia.

get_supported_digests

Wersja: 1

Zwraca listę trybów digest obsługiwanych przez implementację sprzętową Keymastera dla określonego algorytmu i celu.

Żaden z trybów AES nie obsługuje ani nie wymaga szyfrowania hasz, więc metoda zwraca pustą listę.

Implementacje Keymaster 1 mogą stosować podzbiór zdefiniowanych digestów. Implementacje zapewniają SHA-256 i mogą zapewniać MD5, SHA1, SHA-224, SHA-256, SHA384 i SHA512 (pełny zestaw zdefiniowanych digestów).

get_supported_import_formats

Wersja: 1

Zwraca listę formatów importu obsługiwanych przez sprzętową implementację Keymaster dla określonego algorytmu.

Implementacje Keymaster 1 obsługują format PKCS#8 (bez ochrony hasłem) do importowania par kluczy RSA i EC oraz obsługują import w formacie RAW materiału klucza AES i HMAC.

get_supported_export_formats

Wersja: 1

Zwraca listę formatów eksportu obsługiwanych przez sprzętową implementację Keymaster dla określonego algorytmu.

Implementacje Keymaster1 obsługują format X.509 do eksportowania kluczy publicznych RSA i EC. Eksportowanie kluczy prywatnych lub asymetrycznych nie jest obsługiwane.

Funkcje historyczne

Keymaster 0

Podane niżej funkcje należą do pierwotnej definicji Keymaster 0. Były one obecne w strukturze Keymaster 1 keymaster1_device_t. W Keymasterze 1.0 nie zostały one jednak zaimplementowane, 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 z Keymaster 2 wraz z funkcjami Keymaster 0 wymienionymi powyżej.

  • 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 z Keymaster 3 wraz z funkcjami Keymaster 1 wymienionymi powyżej.

  • configure