Funkcje Keymastera

Ta strona zawiera szczegółowe informacje przydatne dla implementatorów sprzętowych warstw abstrakcji (HAL) Keymaster. Zawiera ona opis każdej funkcji w interfejsie 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

Wejściowe parametry wskaźnika, które nie są używane w danym wywołaniu, mogą mieć postać NULL. Element wywołujący nie musi przekazywać 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. Wywołujący może też podać 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.

Począwszy od Keymaster 3 nie ma 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ścia nieużywane parametry wskaźnika wyjścia mogą mieć wartość NULL. Jeśli metoda musi zwrócić dane w parametry wyjściowym 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ść lub odwołania stałe.

Niewłaściwe użycie interfejsu API

Wersja: 1, 2, 3

Wywołujący mogą przesyłać żądania, które nie mają sensu lub są niemądre, ale nie są technicznie błędne. Implementacje Keymaster nie muszą w takich przypadkach kończyć się niepowodzeniem ani przeprowadzać 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.

Aplikacje, platforma i magazyn kluczy Androida są odpowiedzialne za to, aby wywołania modułów Keymaster były rozsądne i przydatne.

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 jest true, jeśli klucze są przechowywane na bezpiecznym sprzęcie (TEE itp.) i nigdy go nie opuszczają.
• supportsEllipticCurve to 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 jest true, jeśli sprzęt obsługuje szyfrowanie symetryczne, w tym AES i HMAC.
• supportsAttestation to true, jeśli sprzęt obsługuje generowanie certyfikatów atestu klucza publicznego Keymaster podpisanego kluczem wstrzykiwanym 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 programie Keymaster 2 i wycofana w Keymasterze 3, ponieważ informacje te są dostępne w plikach właściwości systemowych. Implementacje producenta odczytują te pliki podczas uruchamiania.

Konfiguruje funkcję Keymaster. Ta metoda jest wywoływana raz po otwarciu urządzenia i przed jego użyciem. Służy on do przekazywania parametrów KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL do klucza głównego. Do czasu wywołania tej metody wszystkie inne zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED. Wartości podane za pomocą 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 łatki systemu operacyjnego nie są zgodne z wartościami przekazanymi przez bootloader do bezpiecznego sprzętu (lub jeśli bootloader nie podał 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 entropię dostarczoną przez wywołującego do puli używanej przez implementację Keymaster 1 do generowania liczb losowych, dla kluczy, identyfikatorów IV itp.

Implementacje Keymaster muszą bezpiecznie mieszać dostarczoną entropię z ich pulą, 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 puli entropii.

Implementacje Keymaster, które próbują oszacować entropię w swojej puli wewnętrznej, zakładają, że dane dostarczane przez funkcję 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.

klucz generowania

Wersja: 1, 2, 3

Funkcja ta została wprowadzona w Keymaster 1 pod nazwą generate_key, a jej nazwa została zmieniona 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ą korzystanie z klucza w sposób niezgodny z autoryzacjami określonymi w momencie jego utworzenia. W odniesieniu do autoryzacji, których bezpieczny sprzęt nie może egzekwować, zabezpieczenia sprzętowe są ograniczone do tego, aby nie można było modyfikować niewykonalnych autoryzacji powiązanych z kluczem, tak aby każde wywołanie metody getKeyCharacterists zwróciło pierwotną wartość. Dodatkowo funkcje zwracane przez funkcję generateKey poprawnie przypisują autoryzacje do list kontrolowanych przez sprzęt i oprogramowanie. Aby dowiedzieć się więcej, zapoznaj się z sekcją getKeyCharacteristics.

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

Klucze RSA

Podane niżej parametry są niezbędne do wygenerowania klucza RSA.

• 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 ten argument zostanie pominięty, metoda zwróci ErrorCode::INVALID_ARGUMENT. Obsługiwane wartości to 3 i 65 537. Zalecane wartości to wszystkie wartości podstawowe do 2^64.

Poniższe parametry nie są wymagane do wygenerowania klucza RSA, ale wygenerowanie klucza RSA bez nich spowoduje, że klucz będzie bezużyteczny. Funkcja generateKey nie zwraca jednak błędu, jeśli te parametry zostaną pominięte.

• Tag::PURPOSE określa dozwolone cele. Klucze RSA muszą być obsługiwane we wszystkich celach, w dowolnej kombinacji.
• Tag::DIGEST określa algorytmy szyfrowania, które można używać z nowym kluczem. Implementacje, które nie obsługują wszystkich algorytmów digest, muszą akceptować żądania generowania kluczy, które obejmują 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ływane jest urządzenie, aby wykonać operację Digest::NONE.
• Tag::PADDING określa tryby wypełniania, które można stosować z nowym kluczem. Jeśli określono nieobsługiwane algorytmy podsumowania, implementacje, które nie obsługują wszystkich algorytmów skrótu, muszą umieścić elementy PaddingMode::RSA_PSS i PaddingMode::RSA_OAEP na wymuszonej przez oprogramowanie liście najważniejszych cech.

Klucze ECDSA

Do wygenerowania klucza ECDSA potrzebna jest tylko wartość Tag::KEY_SIZE. Służy do wybierania 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 Tag::DIGEST jest też niezbędny do zastosowania przydatnego klucza ECDSA, ale nie jest wymagany do wygenerowania.

Klucze AES

Do wygenerowania klucza AES potrzebna jest tylko wartość Tag::KEY_SIZE. Jeśli ten argument zostanie pominięty, metoda zwróci wartość 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ą wymagane do ich wygenerowania:

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

Jeśli jest określony tryb blokowania w GCM, podaj Tag::MIN_MAC_LENGTH. Jeśli ten argument zostanie pominięty, 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 liczby 8 z zakresu od 64 do 512. Mogą być obsługiwane większe wartości.
• Tag::MIN_MAC_LENGTH określa minimalną długość MAC-ów, które można wygenerować lub zweryfikować za pomocą tego klucza. Wartość jest wielokrotnością liczby 8 i co najmniej 64.
• Tag::DIGEST określa algorytm skrótu dla klucza. Musisz podać dokładnie jedno zestawienie. W przeciwnym razie zwracaj wartość ErrorCode::UNSUPPORTED_DIGEST. Jeśli digert nie jest obsługiwany przez element zaufania, zwracaj ErrorCode::UNSUPPORTED_DIGEST.

Najważniejsze cechy

Jeśli argument cech nie jest wartością NULL, generateKey zwraca cechy nowo wygenerowanego klucza podzielone odpowiednio na listy wymuszone przez sprzęt i przez oprogramowanie. Aby dowiedzieć się, które cechy znajdują się na której liście, zobacz opis funkcji getKeyCharacteristics. Zwracane cechy obejmują wszystkie parametry określone na potrzeby generowania klucza oprócz Tag::APPLICATION_ID i Tag::APPLICATION_DATA. Jeśli te tagi zostaną uwzględnione w kluczowych parametrach, są one usuwane ze zwracanych cech, więc nie można znaleźć ich wartości przez sprawdzenie zwróconego obiektu blob klucza. 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 tag Tag::ROOT_OF_TRUST jest powiązany kryptograficznie z kluczem, 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 cofanie,

Tag::ROLLBACK_RESISTANT.

Ochrona przed przywróceniem starszych kluczy

Odporność na cofanie oznacza, że po usunięciu klucza za pomocą funkcji deleteKey lub deleteAllKeys jest on zabezpieczony przez sprzęt zabezpieczający przed ponownym użyciem. Implementacje bez odporności na cofnięcie zazwyczaj zwracają wygenerowany lub zaimportowany materiał klucza do wywołującego jako blob klucza, czyli szyfrowany i uwierzytelniony formularz. Gdy klucz zostanie usunięty z keystore, klucz zniknie, ale atakujący, który wcześniej pobrał 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ą atakujący nie może zmanipulować. W przypadku urządzeń mobilnych mechanizmem jest zwykle Replay Protected Memory Blocks (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 rozmiarem. Dlatego ta metoda musi się powieść, nawet jeśli nie można zapewnić ochrony przed cofnięciem dla nowego klucza. W takim przypadku element Tag::ROLLBACK_RESISTANT nie powinien być dodawany do kluczowych cech.

getKeyCharakterystyka

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: wymuszane sprzętowo i wymuszane programowo. 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 Tag::APPLICATION_DATA, ta sama wartość zostanie podana dla tej metody w argumencie appData.

Cechy zwracane przez tę metodę całkowicie opisują typ i zastosowanie 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 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 właściwe 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 zbiorcze wiadomości e-mail trafiają na listę obsługiwaną przez oprogramowanie.
• Wartości Tag::PADDING zwykle znajdują się na liście obsługiwanych sprzętowo, chyba że istnieje możliwość, że określony tryb dopełnienia będzie musiał być wykonywany przez oprogramowanie. W takim przypadku użytkownicy są dodawani do listy wymuszonej przez oprogramowanie. Taka możliwość występuje w przypadku kluczy RSA, które zezwalają na wypełnianie PSS lub OAEP za pomocą algorytmów digest, które nie są obsługiwane przez bezpieczny sprzęt.
• Tag::USER_SECURE_ID i Tag::USER_AUTH_TYPE są wymuszane przez sprzęt tylko wtedy, gdy uwierzytelnianie użytkownika jest wymuszane przez sprzęt. Aby to osiągnąć, zaufana jednostka Keymaster i odpowiednia zaufana jednostka uwierzytelniania muszą być bezpieczne i udostępniać tajny klucz HMAC używany 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ć. Najbardziej bezpieczny sprzęt ma dostęp tylko do informacji o czasie dostarczonych przez niezabezpieczony system operacyjny, co oznacza, że tagi są egzekwowane przez oprogramowanie.
• Tag::ORIGIN jest zawsze na liście sprzętu w przypadku kluczy powiązanych ze sprzętem. Obecność klucza na tej liście pozwala wyższym poziomom określić, że klucz jest obsługiwany przez sprzęt.

importKey

Wersja: 1, 2, 3

Funkcja ta została wprowadzona w Keymaster 1 pod nazwą import_key, a jej nazwa została zmieniona w Keymaster 3.

Importuje materiał klucza do sprzętu 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 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 RSA lub EC Keymaster.

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 ErrorCode::INVALID_KEY_BLOB. Podobnie, jeśli podczas generowania lub importowania podano parametr Tag::APPLICATION_DATA, ta sama wartość zostanie przekazana do tej metody w argumencie appData.

deleteKey

Wersja: 1, 2, 3

Funkcja ta została wprowadzona w Keymaster 1 pod nazwą delete_key, a jej nazwa została zmieniona 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 (usuńWszystkie klucze)

Wersja: 1, 2, 3

Funkcja ta została wprowadzona w Keymaster 1 pod nazwą delete_all_keys, a jej nazwa została zmieniona 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 zdecydowanie 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 jest trwale wyłączona, nie należy w ogóle stosować weryfikacji tożsamości. W takim przypadku ta metoda nie robi nic i zwraca wartość ErrorCode::UNIMPLEMENTED. Jeśli weryfikacja tożsamości jest obsługiwana, musisz zaimplementować tę metodę i trwało wyłączyć wszystkie przyszłe próby weryfikacji tożsamości. Metoda może być wywoływana 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.

begin

Wersja: 1, 2, 3

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

Implementacja Keymaster obsługuje co najmniej 16 jednoczesnych operacji. Magazyn kluczy używa ich maksymalnie 15. Jeden magazyn jest przeznaczony do szyfrowania haseł. Gdy magazyn kluczy ma 15 operacji w toku (zostało wywołanych begin, ale nie zostało wywołanych finish lub abort) i otrzymuje żądanie rozpoczęcia 16., wywołuje abort w najrzadziej użytej operacji, by zmniejszyć liczbę aktywnych operacji do 14, zanim wywołuje begin w celu rozpoczęcia nowo żądanej operacji.

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

Egzekwowanie autoryzacji

W ramach tej metody zaufalność klucza jest wymuszana przez zaufanego agenta, jeśli implementacja umieściła je w charakterystyce „wymuszonej przez sprzęt”, a operacja nie jest operacją klucza publicznego. Operacje z użyciem kluczy publicznych, 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 odpowiadać jednemu z celów w autoryzacji klucza, chyba że żądana operacja jest operacją klucza publicznego. Jeśli podany cel nie pasuje i operacja nie jest operacją z kluczem publicznym, begin zwraca ErrorCode::UNSUPPORTED_PURPOSE. Operacje klucza publicznego to operacje szyfrowania asymetrycznego lub weryfikacji.
• Tag Tag::ACTIVE_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ą wcześniejsze niż wartość tagu, metoda zwraca ErrorCode::KEY_NOT_YET_VALID.
• Tag::ORIGINATION_EXPIRE_DATETIME można zastosować tylko wtedy, gdy jest dostępny zaufany dostawca czasu UTC. Jeśli bieżąca data i godzina przypadają później niż wartość tagu, a cel to KeyPurpose::ENCRYPT lub KeyPurpose::SIGN, metoda zwraca ErrorCode::KEY_EXPIRED.
• Tag Tag:USAGE_Wymaż_DATETIME można wymusić tylko wtedy, gdy dostępne jest zaufane źródło czasu UTC. Jeśli bieżąca data i godzina przypadają później niż wartość tagu, a cel to KeyPurpose::DECRYPT lub KeyPurpose::VERIFY, metoda zwraca ErrorCode::KEY_EXPIRED.
• Wartość Tag::MIN_SECONDS_BETWEEN_OPS jest porównywana z zaufanym względnym zegarem wskazującym ostatnio używany klucz. Jeśli czas ostatniego użycia plus wartość tagu jest krótszy niż bieżący czas, metoda zwraca ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Ważne informacje o wdrażaniu 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.
• Metoda Tag::USER_SECURE_ID jest egzekwowana przez tę metodę tylko wtedy, gdy klucz ma też parametr Tag::AUTH_TIMEOUT. Jeśli klucz ma obie te wartości, metoda musi otrzymać prawidłową wartość Tag::AUTH_TOKEN w inParams. Aby token uwierzytelniający był prawidłowy, muszą być spełnione wszystkie te warunki:
  • Pole HMAC jest poprawnie zweryfikowane.
  • co najmniej 1 wartośćTag::USER_SECURE_IDz klucza pasuje do co najmniej 1 wartości bezpiecznego identyfikatora w tokenie;
  • Klucz ma wartość Tag::USER_AUTH_TYPE, która jest zgodna z typem uwierzytelniania w tokenie.

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

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

Klucze RSA

Wszystkie operacje na kluczu RSA określają dokładnie 1 tryb wypełniania w parametrye inParams. Jeśli nie jest określony lub jest określony więcej niż raz, zwracana jest wartość ErrorCode::UNSUPPORTED_PADDING_MODE.

Operacje podpisywania i weryfikacji RSA wymagają skrótu, podobnie jak operacje szyfrowania i odszyfrowania RSA w trybie wypełniania OAEP. W takich przypadkach wywołujący określa dokładnie 1 wyciąg w elementach inParams. Jeśli wartość jest nieokreślona lub podana więcej niż raz, metoda zwraca ErrorCode::UNSUPPORTED_DIGEST.

Operacje z użyciem klucza prywatnego (KeyPurpose::DECYPT i KeyPurpose::SIGN) wymagają autoryzacji skrótu i wypełnienia, co oznacza, że autoryzacje klucza muszą zawierać określone wartości. Jeśli nie, zwraca odpowiednio ErrorCode::INCOMPATIBLE_DIGEST lub 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 podany tryb nie obsługuje podanego 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ślone dla skrótu. W przypadku niezabezpieczonego szyfrowania lub odszyfrowywania nie jest potrzebny digest.
• PaddingMode::RSA_PKCS1_1_5_SIGN wypełnienie wymaga skrótu. Digest może być Digest::NONE, co oznacza, że 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 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 wypełnienie nie wymaga skrótu.
• Wypełnianie pola PaddingMode::RSA_PSS wymaga 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. Wielkość soli to D.
• Wypełnianie pola PaddingMode::RSA_OAEP wymaga 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 inParams. Jeśli nie jest określony lub jest określony więcej niż raz, zwraca ErrorCode::UNSUPPORTED_PADDING_MODE.

Operacje z kluczem prywatnym (KeyPurpose::SIGN) wymagają autoryzacji danych z digest i wypełniania, 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 1 tryb bloku i 1 tryb dopełnienia w inParams. Jeśli któraś z wartości nie jest określona lub jest określona więcej niż raz, zwracana jest wartość ErrorCode::UNSUPPORTED_BLOCK_MODE lub ErrorCode::UNSUPPORTED_PADDING_MODE. Wspólne 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, inParams określa Tag::MAC_LENGTH, a podana wartość jest wielokrotnością liczby 8, która nie jest większa niż 128 ani mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacji klucza. W przypadku długości adresu MAC większej niż 128 lub niebędącej wielokrotnością 8 zwraca ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości mniejszych niż minimalna długość klucza zwracany jest element 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 losowy ciąg znaków. W większości przypadków wywołujący nie powinien podawać IV ani nonce. W takim przypadku implementacja Keymaster generuje losowy IV lub kod jednorazowy i zwraca go za pomocą parametru Tag::NONCE w outParams. CBC i CTR IV mają 16 bajtów. Liczby jednorazowe w GCM mają 12 bajtów. Jeśli autoryzacje klucza zawierają tag Tag::CALLER_NONCE, dzwoniący może podać IV lub nonce za pomocą tagu Tag::NONCE w inParams. Jeśli wartość jednorazowa jest podana, gdy brak autoryzacji Tag::CALLER_NONCE, zwróć ErrorCode::CALLER_NONCE_PROHIBITED. Jeśli nie podano liczby jednorazowej, gdy użytkownik ma uprawnienia Tag::CALLER_NONCE, wygeneruj losowy IV/raz.

Klucze HMAC

Operacje na kluczu HMAC określają Tag::MAC_LENGTH w inParams. Podana wartość musi być wielokrotnością 8, która nie jest większa niż długość digestu 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 wielokrotności liczby 8 zwróć ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości mniejszych niż minimalna długość klucza zwraca wartość ErrorCode::INVALID_MAC_LENGTH.

aktualizować

Wersja: 1, 2, 3

Dostarcza danych 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 mogą zużywać mniej 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 przekazanych 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ślać ilość danych do zwrócenia w wyniku aktualizacji. Dotyczy to tylko operacji szyfrowania i odszyfrowania, ponieważ podpisywanie i weryfikacja nie zwracają żadnych danych, dopóki nie skończą. Zwracaj dane jak najwcześniej, 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 uchwyt operacji zostanie unieważniony. 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, gdy klucz ma:

• co najmniej Tag::USER_SECURE_ID,
• Brak parametru Tag::AUTH_TIMEOUT

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, zwróć ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Użytkownik przekazuje 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 ona zajmować tylko części bloku. Jeśli jednak wywołujący zdecyduje się przesłać dane w kilku aktualizacjach, ta metoda je zaakceptuje. Jeśli element wywołujący dostarcza więcej danych do podpisania, niż można wykorzystać (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 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ę przesłać 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 sposobu obsługi nadmiarowych danych w podobnych operacjach RSA). Powodem jest zgodność ze starszymi klientami.

Klucze AES

Tryb GCM AES obsługuje „powiązane dane uwierzytelniania” podawane za pomocą tagu Tag::ASSOCIATED_DATA w argumencie inParams. Powiązane dane można podawać w powtórnych wywołaniach (to ważne, jeśli dane są zbyt duże, aby wysłać je w jednym bloku), ale zawsze przed danymi do zaszyfrowania lub odszyfrowania. Wywołanie aktualizacji może otrzymywać 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 zawierającym dane do zaszyfrowania lub odszyfrowania, zwraca ErrorCode::INVALID_TAG.

W przypadku szyfrowania GCM tag jest dołączany do tekstu zaszyfrowanego przez finish. Podczas odszyfrowywania tagiem ostatnim Tag::MAC_LENGTH bajtów danych przekazanych do ostatniego wywołania aktualizacji. 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

Kończy trwającą operację, która rozpoczęła się od rozpoczęcia, przez co przetwarza wszystkie jeszcze nieprzetworzone dane dostarczone przez aktualizacje.

Ta metoda jest wywoływana jako ostatnia 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 update lub 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

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

• co najmniej 1 tag Tag::USER_SECURE_ID oraz
• Nie ma tagu Tag::AUTH_TIMEOUT

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, zwróć ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Użytkownik przekazuje token uwierzytelniający w każdym wywołaniu metody update i finish. Implementacja musi potwierdzić token tylko raz.

Klucze RSA

Dodatkowe wymagania zależnie od trybu dopełnienia:

• 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ą wypełniane zerami z zera po lewej stronie. Jeśli dane mają taką samą długość jak klucz, ale są większe liczbowo, zwracają ErrorCode::INVALID_ARGUMENT. W przypadku operacji weryfikacji i odszyfrowywania dane muszą mieć dokładnie taką samą długość jak klucz. W przeciwnym razie zwróć ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. W przypadku operacji podpisywania z wypełnieniem PSS sól PSS ma rozmiar równy rozmiarowi skrótu wiadomości i jest generowana losowo. Treść digest określona za pomocą atrybutu Tag::DIGEST w elemencie inputParams w sekcji begin jest używana jako algorytm digest PSS oraz algorytm digest MGF1.
• 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 skróć.

Klucze AES

Niektóre 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łniającego, 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 przetwarzaj ostatnie bajty Tag::MAC_LENGTH jako tag. Jeśli weryfikacja tagu się nie powiedzie, zwracaj ErrorCode::VERIFICATION_FAILED.

przerwij

Wersja: 1, 2, 3

Przerywa wykonywaną 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 implementację sprzętową 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.

tryby get_supported_block_modes

Wersja: 1

Zwraca listę trybów blokowania AES obsługiwanych przez implementację sprzętową Keymaster 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ą Keymaster dla określonego algorytmu i celu.

HMAC i EC nie mają pojęcia dopełnienia, więc metoda zwraca pustą listę dla wszystkich prawidłowych celów. Nieprawidłowe cele powinny powodować zwrócenie 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 niedopełnionego szyfrowania i podpisywania, jeśli wiadomość jest krótsza niż moduł publiczny, implementacje muszą dopełniać go z lewej strony zerami. W przypadku niedopełnionego odszyfrowywania i weryfikacji długość wejściowa musi być zgodna z rozmiarem modułu publicznego.
• Tryby dopełnienia podpisywania PKCS#1 w wersji 1.5 i podpisywania
• PSS z minimalną długością soli 20
• protokół OAEP

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

get_supported_podsumowania

Wersja: 1

Zwraca listę trybów skrótu obsługiwanych przez implementację sprzętową Keymaster dla określonego algorytmu i przeznaczenia.

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

Implementacje Keymaster 1 mogą stosować podzbiór zdefiniowanych digestów. Implementacje zapewniają SHA-256 i mogą zapewniać MD5, SHA-1, 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ą implementacja Keymaster 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 kluczy AES i HMAC.

get_supported_export_formats

Wersja: 1

Zwraca listę formatów eksportu obsługiwanych przez sprzętową implementacja Keymaster 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

Poniższe funkcje należą do pierwotnej definicji Keymaster 0. Były one obecne w strukturze Keymaster 1 keymaster1_device_t. W Keymaster 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

Podane niżej 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

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

• configure