Funkcje Keymastera

Ta strona zawiera szczegółowe informacje, które ułatwią implementację warstw abstrakcji sprzętowej (HAL) Keymaster. Zawiera ona każdą funkcję w interfejsie API, listę wersji Keymaster, w których jest dostępna, oraz opis implementacji domyślnej. Informacje o tagach znajdziesz na stronie Tagi autoryzacji 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. 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 to 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 const.

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. 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 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 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 (np. TEE) 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 jest true, jeśli sprzęt obsługuje generowanie certyfikatów atestackich kluczy publicznych 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 systemu, 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. Jest używany do przekazywania klucza głównegoKM_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 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 aktualizacji systemu operacyjnego nie są zgodne z wartościami przekazanymi do bezpiecznego sprzętu przez bootloader (lub jeśli bootloader 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_entropy, a następnie została 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 i innych elementów.

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 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ą korzystanie z 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 funkcję generateKey poprawnie przypisują uprawnienia do list kontrolowanych przez sprzęt i oprogramowanie. Więcej informacji znajdziesz w sekcji getKeyCharacteristics.

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

Klucze RSA

Do wygenerowania klucza RSA potrzebne są te parametry.

  • Tag::KEY_SIZEokreś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_EXPONENTokreśla wartość wykładnika publicznego klucza 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 pierwsze 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ą 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 obejmują nieobsługiwane digesty. Nieobsługiwane zbiorcze wiadomości tekstowe należy umieścić na liście z wymuszonym stosowaniem oprogramowania w zwróconych właściwościach klucza. Dzieje się tak, ponieważ klucz można używać z innymi skrótami, ale skróty są generowane w oprogramowaniu. Następnie wywoływane jest urządzenie, 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ą umieszczać wartościPaddingMode::RSA_PSS i PaddingMode::RSA_OAEP na liście kluczowych cech wymuszanych przez oprogramowanie, jeśli są określone nieobsługiwane algorytmy digest.

Klucze ECDSA

Do wygenerowania klucza ECDSA potrzebny jest tylko Tag::KEY_SIZE. Użyj tego tagu, aby wybrać grupę 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ż potrzebny do utworzenia klucza ECDSA, ale nie jest wymagany do wygenerowania.

Klucze AES

Do wygenerowania klucza AES potrzebny jest tylko parametr Tag::KEY_SIZE. Jeśli ten argument zostanie pominięty, 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ą wymagane do ich wygenerowania:

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

Jeśli wybrano tryb blokowania GCM, podaj wartość 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_SIZEokreś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_LENGTHokreśla minimalną długość kodów MAC, które można wygenerować lub zweryfikować za pomocą tego klucza. Wartość jest wielokrotnością 8 i nie mniejsza niż 64.
  • Tag::DIGESTokreśla algorytm skrótu dla klucza. Musisz podać dokładnie jedno zestawienie. W przeciwnym razie zwracaj wartość ErrorCode::UNSUPPORTED_DIGEST. Jeśli digest nie jest obsługiwany przez element zaufania, zwracaj ErrorCode::UNSUPPORTED_DIGEST.

Najważniejsze cechy

Jeśli argument characteristics nie jest NULL, funkcja generateKey zwraca właściwości nowo wygenerowanego klucza podzielone na listy z ograniczeniami sprzętowymi i oprogramowania. Informacje o tym, które cechy znajdują się na której liście, znajdziesz w sekcji getKeyCharacteristics. Zwracane cechy obejmują wszystkie parametry określone do generowania kluczy, z wyjątkiem parametrów Tag::APPLICATION_ID i Tag::APPLICATION_DATA. Jeśli te tagi były uwzględnione w parametrach klucza, zostaną usunięte z zwróconych cech, aby nie można było znaleźć ich wartości przez zbadanie zwróconego klucza 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 Tag::ROOT_OF_TRUST jest powiązany z kluczem za pomocą szyfrowania, 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::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 gdy klucz zostanie usunięty za pomocądeleteKey lub deleteAllKeys, nie będzie można go już nigdy użyć. Implementacje bez odporności na cofanie zazwyczaj zwracają wygenerowany lub zaimportowany materiał klucza do wywołującego jako blob klucza, czyli szyfrowany i uwierzytelniony formularz. Gdy magazyn kluczy usunie klucz blob, klucz zniknie, ale atakujący, który wcześniej pobrał materiał klucza, może go przywrócić na urządzenie.

Klucz jest chroniony przed cofnięciem, 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 zaufanym miejscu, które nie może zostać zmanipulowane przez osobę przeprowadzającą atak. W przypadku urządzeń mobilnych mechanizmem używanym do tego celu są zwykle 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 zapewnienia odporności na cofanie może być ograniczone pod względem rozmiaru. Dlatego ta metoda musi się powieść, nawet jeśli nie można zapewnić odporności na cofanie dla nowego klucza. W takim przypadkuTag::ROLLBACK_RESISTANTnie należy dodawać do kluczowych cech.

getKeyCharacteristics

Wersja: 1, 2, 3

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

Zwraca parametry i upoważnienia powiązane z podanym kluczem, podzielone na 2 zbiory: z wymogiem sprzętowym i z wymogiem programowym. Opis tutaj dotyczy również list kluczowych cech zwracanych przez 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 tej metodzie 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 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 są zwykle umieszczane na liście obsługiwanej przez sprzęt, chyba że istnieje możliwość, że określony tryb wypełniania może być wykonywany przez oprogramowanie. W takim przypadku trafiają na listę kontrolowaną 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 zegara ściennego, którego poprawność 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

Ta funkcja została wprowadzona w Keymaster 1 jako import_key, a następnie została 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 tymi wyjątkami:

  • 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_key, a następnie została 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

Ta funkcja została wprowadzona w Keymaster 1 jako delete_key, a następnie została 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_keys, a następnie została 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 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, należy 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.

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 uchwyt operacji, który jest używany z update i finish do wykonania 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 celu rozpoczęcia operacji, której dotyczy nowe żądanie.

Jeśli podczas generowania lub importowania klucza zostały określone parametry 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 wymuszana przez zaufanego agenta, jeśli implementacja umieściła je w charakterystyce obsługiwanej przez sprzęt, a operacja nie jest operacją klucza publicznego. Operacje z kluczem publicznym, czyli KeyPurpose::ENCRYPT i KeyPurpose::VERIFY, z kluczami RSA lub EC, mogą się powieść 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 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::ACTIVE_DATETIME może być stosowany tylko wtedy, gdy dostępne jest 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że być stosowany 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 cel to KeyPurpose::ENCRYPT lub KeyPurpose::SIGN, metoda zwraca ErrorCode::KEY_EXPIRED.
  • Tag::USAGE_EXPIRE_DATETIME może być stosowany 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 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 czas ostatniego użycia klucza. Jeśli czas ostatniego użycia plus wartość znacznika jest mniejsza 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.
  • Tag::USER_SECURE_ID jest stosowana przez tę metodę tylko wtedy, gdy klucz ma też atrybuty Tag::AUTH_TIMEOUT. Jeśli klucz zawiera oba te elementy, ta 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 jedna z wartościTag::USER_SECURE_IDz klucza musi być zgodna z co najmniej jedną z wartości bezpiecznego identyfikatora w tokenie.
    • Klucz maTag::USER_AUTH_TYPE, który jest zgodny z typem uwierzytelniania w tokenie.

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

  • Tag::CALLER_NONCE pozwala rozmówcy określić wektor losowy lub wektor inicjujący (IV). Jeśli klucz nie ma tego tagu, ale wywołujący podał Tag::NONCE do tej metody, zwracana jest wartość ErrorCode::CALLER_NONCE_PROHIBITED.
  • Tag::BOOTLOADER_ONLYokreśla, że tylko bootloader może używać klucza. 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 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 nie podano tego argumentu lub podano go 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. W przeciwnym razie zwraca ona 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 podany tryb nie obsługuje podanego celu, metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE.

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

  • PaddingMode::NONE oznacza, że wykonywana jest operacja na surowych danych RSA. Jeśli podpisujesz lub weryfikujesz, Digest::NONE jest określony 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 o 11 bajtów większy niż wiadomość, w przeciwnym razie metoda zwraca 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. Rozmiar 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 użyciem klucza prywatnego (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 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, 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, 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 zwraca ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości mniejszych niż minimalna długość klucza zwracaj 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 nonce i zwraca go z 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::CALLER_NONCE, to wywołujący może podać IV lub nonce za pomocą Tag::NONCEw inParams. Jeśli w przypadku nieautoryzowanego wywołania funkcji Tag::CALLER_NONCE zostanie podany losowy numer, zwracaj ErrorCode::CALLER_NONCE_PROHIBITED. Jeśli podczas autoryzacji Tag::CALLER_NONCE nie zostanie podany nonce, 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 lub mniejsza niż wartość Tag::MIN_MAC_LENGTH w autoryzacjach klucza. W przypadku długości MAC większej niż długość digest lub niebędącej wielokrotnością 8 zwracaj ErrorCode::UNSUPPORTED_MAC_LENGTH. W przypadku wartości krótszych niż minimalna długość klucza zwracany jest ciąg ErrorCode::INVALID_MAC_LENGTH.

aktualizować

Wersja: 1, 2, 3

Dostarcza danych do przetworzenia w ramach trwającej operacji rozpoczętej za pomocą 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 podano więcej niż 0 bajtów, a zużycie wynosi 0, wywołujący uzna to za błąd i przerwie operację.

Implementacje mogą też określić, ile danych zaktualizować. Ma to zastosowanie tylko do operacji szyfrowania i odszyfrowywania, ponieważ podpisywanie i weryfikacja nie zwracają żadnych danych do momentu finish. zwracaj dane jak najszybciej, 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 stanie się nieważny. Każde przyszłe użycie klamry za pomocą tej metody, finish lub abort, zwraca ErrorCode::INVALID_OPERATION_HANDLE.

Egzekwowanie autoryzacji

Wymuszanie autoryzacji klucza jest wykonywane głównie w begin. Wyjątkiem jest sytuacja, gdy klucz:

W tym przypadku klucz wymaga autoryzacji na potrzeby każdej operacji, a metoda update otrzymuje parametr inParams o 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, oraz 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 przypadku każdego połączenia z numerem update i finish. Implementacja musi zweryfikować token tylko raz.

Klucze RSA

W przypadku operacji podpisywania i weryfikacji za pomocą Digest::NONE ta metoda akceptuje cały blok, który ma być podpisany lub zweryfikowany w ramach jednej aktualizacji. Nie może ona zajmować tylko części bloku. Jeśli jednak wywołujący zdecyduje się przekazać 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 być 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 sposobu obsługi nadmiarowych danych w podobnych operacjach RSA). Powodem jest zgodność ze starszymi wersjami.

Klucze AES

Tryb AES GCM obsługuje powiązane dane uwierzytelniania, które są 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 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 za pomocą funkcji finish. Podczas odszyfrowywania ostatnie Tag::MAC_LENGTH bajty 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 zapisują możliwe dane tagu w buforze podczas finish.

zakończ

Wersja: 1, 2, 3

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

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 klamry za pomocą tej metody lub za pomocą 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

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

W tym przypadku klucz wymaga autoryzacji na potrzeby każdej operacji, a metoda update otrzymuje parametr inParams o wartości Tag::AUTH_TOKEN. HMAC sprawdza, czy token jest prawidłowy i zawiera dopasowany bezpieczny identyfikator użytkownika, czy jest zgodny z kluczem Tag::USER_AUTH_TYPE oraz 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 przypadku każdego wywołania do update i finish. Implementacja musi zweryfikować 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 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 zwraca 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ą parametru Tag::DIGEST w inputParams w begin jest używana jako algorytm digest PSS oraz algorytm digest MGF1.
  • PaddingMode::RSA_OAEP. Digest określony za pomocą Tag::DIGEST w inputParams na begin 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 tag (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 identyfikatora 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 implementację sprzętową Keymaster dla określonego algorytmu i celu.

W przypadku algorytmów 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 o wypełnianiu, 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 odszyfrowywania i weryfikacji bez wypełnienia długość danych wejściowych musi być zgodna z rozmiarem publicznego modułu.
  • Tryby wypełniania danych w ramach 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ę 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ętowe przetwarzanie algorytmu Keymaster.

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ętowe wdrożenie Keymastera 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

Te 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

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

  • configure