Funkcje Keymaster

Ta strona zawiera szczegółowe informacje pomocne dla twórców aplikacji Keymaster Sprzętowe warstwy abstrakcyjne (HAL). Obejmuje każdą funkcję w API oraz wersję Keymastera, w której funkcja ta jest dostępna; opisuje implementację domyślną. W przypadku tagów zapoznaj się z sekcją Tagi Keymaster.

Ogólne wskazówki dotyczące implementacji

Poniższe wytyczne dotyczą wszystkich funkcji w interfejsie API.

Parametry wskaźnika wejściowego

Wersja: 1, 2

Parametry wskaźnika wejściowego, które nie są używane w danym wywołaniu, mogą być NULL Element wywołujący nie musi podawać zmiennych. Na przykład niektóre typy i tryby kluczy nie mogą korzystać z żadnych wartości z atrybutu inParams argumentu begin, więc wywołujący może ustaw inParams na NULL lub podaj pusty parametr ustawiony. Wywołujący mogą też podawać nieużywane parametry, a metody Keymaster powinny „brak problemu”.

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

W wersji Keymaster 3 nie ma parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartości lub odwołania stałe.

Parametry wskaźnika wyjściowego

Wersja: 1, 2

Nieużywane parametry wskaźnika wyjściowego są podobne do parametrów wskaźnika wejściowego może wynosić NULL. Jeśli metoda musi zwrócić dane w danych wyjściowych wykryto parametr NULL, powinien on zwracać ErrorCode::OUTPUT_PARAMETER_NULL

W wersji Keymaster 3 nie ma parametrów wskaźnika. Wszystkie parametry są przekazywane przez wartości lub odwołania stałe.

Nadużywanie interfejsu API

Wersja: 1, 2, 3

Dzwoniący mogą zgłaszać prośby, które nie mają sensu lub są głupie, ale nie są błędne technicznie. Implementacje Keymaster nie są niezgodność w takich przypadkach lub przeprowadzić diagnostykę. używania zbyt małych klawiszy, nieistotne parametry wejściowe, ponowne użycie IV lub jednorazowych komponentów, generowania kluczy bez żadnego celu (a tym samym bezużytecznego) i podobnym tego typu diagnozowanych na podstawie implementacji. Pominięcie wymaganych parametrów, specyfikacja nieprawidłowe wymagane parametry i trzeba zdiagnozować podobne błędy.

Za aplikacje, platformę i magazyn kluczy Androida odpowiadają aby wywołania modułów Keymaster były rozsądne i przydatne.

Funkcje

getHardwareFeatures

Wersja: 3

Nowa metoda getHardwareFeatures ujawnia klientom ważnych cech bazowego bezpiecznego sprzętu. Metoda nie przyjmuje żadnych argumentów i zwraca 4 wartości: wszystkie wartości logiczne:

  • isSecure to true, jeśli klucze są przechowywane w bezpiecznego sprzętu (TEE itp.) i nigdy go nie opuszczaj.
  • supportsEllipticCurve to true, jeśli sprzęt obsługuje kryptografię krzywych eliptycznych z krzywymi NIST (P-224, P-256, P-384 i P-521).
  • supportsSymmetricCryptography – true czy sprzęt obsługuje symetryczną kryptografię, w tym AES i HMAC.
  • supportsAttestation to true, jeśli sprzęt obsługuje generowanie certyfikatów atestu klucza publicznego Keymaster, są podpisane kluczem wstrzykiwanym w bezpiecznym środowisku.

Jedyne kody błędów, które ta metoda może zwrócić, to ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED lub jeden z kodów błędów co oznacza 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 programie Keymaster. 3, ponieważ te informacje są dostępne w plikach właściwości systemu, a nazwa producenta implementacje odczytują te pliki podczas uruchamiania.

Konfiguruje funkcję Keymaster. Ta metoda jest wywoływana raz po otwarciu urządzenia przed użyciem. Jest używany do podania KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL do . Dopóki ta metoda nie zostanie wywołana, pozostałe metody zwracają KM_ERROR_KEYMASTER_NOT_CONFIGURED Wartości podane przez ten argument są akceptowane przez keymaster tylko raz na uruchomienie. Kolejna połączenia zwracają KM_ERROR_OK, ale nie wykonują żadnych działań.

Jeśli implementacja keymastera korzysta z bezpiecznego sprzętu, z wersją systemu operacyjnego podane wartości na poziomie poprawek nie pasują do wartości podanych w bezpiecznym przez program rozruchowy (lub jeśli program rozruchowy nie podał wartości), to ta metoda zwraca KM_ERROR_INVALID_ARGUMENT i wszystkie pozostałe nadal zwraca wartość 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 nazwa została zmieniona w Keymaster 3.

Dodaje entropię dostarczoną przez metodę wywołującą do puli używanej przez implementację Keymaster 1. do generowania liczb losowych, dla kluczy, przejściówek IV itd.

Implementacje Keymaster muszą bezpiecznie łączyć podane entropii w puli, która również musi zawierać entropia generowana wewnętrznie ze sprzętowego generatora liczb losowych. Miksowanie powinno się odbywać w taki sposób, aby osoba przeprowadzająca atak miała pełną kontrolę z bitów udostępnionych przez addRngEntropy lub elementów wygenerowanych sprzętowo ale nie jedno i drugie, nie ma niepoważnej przewagi w przewidywaniu bitów generowanych z puli entropii.

Implementacje Keymaster, które próbują oszacować entropię pula wewnętrzna zakłada, że dane dostarczane przez addRngEntropy nie zawiera entropii. Implementacje Keymaster mogą zwraca ErrorCode::INVALID_INPUT_LENGTH, jeśli ma więcej niż 2 KiB danych w jednym wywołaniu.

klucz generowania

Wersja: 1, 2, 3

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

generuje nowy klucz kryptograficzny, który określa powiązane autoryzacje; które są trwale powiązane z kluczem. Dzięki implementacji Keymaster nie jest możliwe użycie klucza w sposób niezgodny z autoryzacjami określonych w momencie generowania. W odniesieniu do autoryzacji, że zabezpieczenie sprzętu nie można egzekwować, zobowiązania dotyczące bezpiecznego sprzętu są ograniczone do zapewnienie, że niewykonalne autoryzacje powiązane z kluczem nie będą mogły w taki sposób, aby każde wywołanie getKeyCharacterists zwraca pierwotną wartość. Ponadto cechy zwracane przez funkcję Funkcja generateKey prawidłowo przydziela autoryzacje między listy wymuszone oraz przez oprogramowanie. Zobacz getKeyCharacterists.

Parametry udostępniane funkcji generateKey zależą od typu klucza które są generowane. W tej sekcji znajdziesz podsumowanie tagów wymaganych i opcjonalnych każdego typu klucza. Tag::ALGORITHM jest zawsze konieczne do określenia typu.

Klucze RSA

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

  • Tag::KEY_SIZE określa rozmiar modułu publicznego w bitach. Jeśli zostanie pominięty, metoda zwraca 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ą liczby 8.
  • Tag::RSA_PUBLIC_EXPONENT określa wartość wykładnika publicznego RSA. Jeśli zostanie pominięty, zwraca ErrorCode::INVALID_ARGUMENT. Obsługiwane wartości to 3 i 65 537. Zalecane wartości to wszystkich wartości pierwszych do 2^64.

Poniższe parametry nie są niezbędne do wygenerowania klucza RSA, ale jeśli utworzysz klucz RSA bez nich, powstanie klucz, którego nie będzie można użyć. Jednak Funkcja generateKey nie zwraca błędu, jeśli te parametry są pomijane.

  • Parametr Tag::PURPOSE określa dozwolonych celach. Klucze RSA muszą być obsługiwane w każdym celu dowolną kombinację.
  • Parametr Tag::DIGEST określa do algorytmów skrótu, których można używać z nowym kluczem. Implementacje które nie obsługują wszystkich algorytmów podsumowania, muszą akceptować generowanie kluczy zawierających nieobsługiwane podsumowania. Nieobsługiwane skróty powinny być: umieszczone w „wykorzystywaniu oprogramowania sprzęgającego” wśród zwróconych cech klucza. Wynika to z tego, że klucz można wykorzystać z innymi skrótami, a trawienie jest wykonywane w oprogramowaniu. Następnie jest wywoływany sprzęt, aby wykonać operację. dzięki Digest::NONE.
  • Tag::PADDING określa parametr tryby dopełnienia, których można używać z nowym kluczem. Implementacje które nie obsługują wszystkich algorytmów podsumowania, muszą umieścić PaddingMode::RSA_PSS i PaddingMode::RSA_OAEP in wymuszonej przez oprogramowanie listy kluczowych cech, jeśli jakiekolwiek algorytmy skrótu.

Klucze ECDSA

Tylko Tag::KEY_SIZE to niezbędne do wygenerowania klucza ECDSA. Służy do wyboru grupy EC. Obsługiwane wartości to 224, 256, 384 i 521, które oznaczają krzywe p-224, p-256, p-384 i p521 odpowiednio NIST.

Tag::DIGEST jest też niezbędny do użytego klucza ECDSA, ale nie jest wymagany do wygenerowania.

Klucze AES

Tylko tag::KEY_SIZE jest konieczne do wygenerowania klucza AES. Jeśli nazwa zostanie pominięta, metoda zwróci ErrorCode::UNSUPPORTED_KEY_SIZE Obsługiwane wartości to: 128 i 256 z opcjonalną obsługą 192-bitowych kluczy AES.

Poniższe parametry są szczególnie istotne w przypadku kluczy AES, ale nie niezbędne do ich wygenerowania:

  • Tag::BLOCK_MODE określa tryby blokowania, z którymi będzie można użyć nowego klucza.
  • Tag::PADDING określa tryby dopełnienia, które mogą być . Dotyczy to tylko trybów ECB i CBC.

Jeśli tryb blokowania GCM jest określony, podaj parametr Tag::MIN_MAC_LENGTH. Jeśli nazwa zostanie pominięta, metoda zwróci wartość ErrorCode::MISSING_MIN_MAC_LENGTH. Wartość tagu jest wielokrotnością liczby 8 i od 96 do 128.

Klucze HMAC

Do wygenerowania 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ściami liczby 8, nie są obsługiwane. Wszystkie obsługiwane są wielokrotności liczby 8, od 64 do 512. Większe wartości mogą być obsługiwane.
  • Tag::MIN_MAC_LENGTH określa minimalną długość Adresy MAC, które można wygenerować lub zweryfikować za pomocą tego klucza. Wartość to wielokrotności liczby 8 i co najmniej 64.
  • Tag::DIGEST określa algorytm skrótu dla klucza. Dokładnie określono jeden skrót, w przeciwnym razie zwróć ErrorCode::UNSUPPORTED_DIGEST Jeśli skrót nie jest obsługiwany przez zaufanie, zwrot ErrorCode::UNSUPPORTED_DIGEST

Najważniejsze cechy

Jeśli argument cech nie jest wartością NULL, generateKey zwraca cechy nowo wygenerowanego klucza podzielone na listy wymuszone oraz przez oprogramowanie. Zobacz getKeyCharacterists dla opisu. które charakterystyczne dla danej listy Zwracane cechy uwzględnia wszystkie parametry określone na potrzeby generowania kluczy, oprócz Tag::APPLICATION_ID i Tag: APPLICATION_DATA. Jeśli te tagi zostaną uwzględnione w parametrach kluczowych, zostaną usunięte z: zwróconych cech, tak że nie można znaleźć ich wartości analizując zwrócony blob klucza. Są one jednak powiązane kryptograficznie do bloba klucza. Dzięki temu, jeśli podczas stosowania klucza nie zostaną podane poprawne wartości , użycie kończy się niepowodzeniem. Podobnie Parametr Tag::ROOT_OF_TRUST to kryptograficznie powiązanych z kluczem, ale nie można ich określić podczas lub zaimportowanie klucza i nigdy nie jest zwracany.

Oprócz dostarczonych tagów, trustlet również dodaje tag Tag::origin, o wartości KeyOrigin::GENERATED, a jeśli klucz jest odporny na wycofanie,

Tag::ROLLBACK_RESISTANT.

Ochrona przed przywróceniem starszych kluczy

Opór wycofania oznacza, że po usunięciu klucza za pomocą deleteKey lub deleteAllKeys, zagwarantuje bezpieczny sprzęt. już nigdy nie będzie nadawała się do użycia. Implementacje bez odporności na wycofanie zmian zwykle zwraca wygenerowany lub zaimportowany materiał klucza do wywołującego jako klucz blob, zaszyfrowanej i uwierzytelnionej formularza. Kiedy magazyn kluczy usuwa obiekt blob, kluczem jest ale osoba przeprowadzająca atak, która wcześniej zdołała odzyskać materiał które mogą zostać przywrócone na urządzeniu.

Klucz jest odporny na wycofanie, jeśli bezpieczny sprzęt gwarantuje jego usunięcie kluczy nie można później przywrócić. Zwykle odbywa się to przez przechowywanie dodatkowego klucza metadanych w zaufanej lokalizacji, w której osoba przeprowadzająca atak nie może manipulować. Wł. urządzeń mobilnych, mechanizmem używanym do tego jest zwykle Replay Protected Memory Blokuje (RPMB). Ponieważ liczba kluczy, które można utworzyć, jest zasadniczo nieograniczone, a zaufana pamięć masowa używana na potrzeby odporności na wycofanie może być ograniczona rozmiar, ta metoda musi się sprawdzić, nawet jeśli rezystancja nie można podać w przypadku nowego klucza. W takim przypadku Tag::ROLLBACK_RESISTANT który nie powinien być zaliczany do głównych cech.

getKeyCharakterystyka

Wersja: 1, 2, 3

Funkcja ta została wprowadzona w Keymaster 1 jako get_key_characteristics i nazwa została zmieniona w Keymaster 3.

Zwraca parametry i autoryzacje powiązane z podanym kluczem, podzielone na 2 grupy: wymuszane przez sprzęt i przez oprogramowanie. Tekst reklamy ma zastosowanie do list kluczowych cech zwracanych przez metody generateKey i importKey.

Jeśli podczas generowania klucza podano Tag::APPLICATION_ID lub importu, taka sama wartość zostanie podana w funkcji tę metodę w argumencie clientId. W przeciwnym razie zwraca wartość ErrorCode::INVALID_KEY_BLOB. Podobnie jeśli podczas generowania kodu podano Tag::APPLICATION_DATA lub importu, taka sama wartość zostanie podana w funkcji tę metodę w argumencie appData.

Cechy zwrócone przez tę metodę w pełni opisują typ i za pomocą określonego klucza.

Ogólna reguła określająca, czy dany tag należy do – jeśli znaczenie tagu jest w pełni egzekwowany przez bezpieczny sprzęt. W przeciwnym razie jest to wymuszanie użycia oprogramowania. Poniżej znajdziesz listę konkretnych tagów, których prawidłowe przydziały mogą być niejasne:

  • Tag::ALGORITHM, Tag:KEY_SIZE, i Tag::RSA_PUBLIC_EXPONENT są nieodłącznymi właściwościami klucza. W przypadku każdego klucza zabezpieczonego sprzętowo czyli na liście wymuszonych tagów.
  • Wartości Tag::DIGEST obsługiwanych przez bezpieczny sprzęt są umieszczane w na liście obsługiwanych urządzeń. Nieobsługiwane skróty znajdziesz na liście obsługiwanych przez oprogramowanie.
  • Wartości Tag::PADDING można znaleźć na liście obsługiwanych sprzętów, o ile nie jest możliwość, że określony tryb dopełnienia będzie musiał być uruchamiany przez oprogramowanie. W takim przypadku trafiają na listę osób wymuszonych przez oprogramowanie. Taka możliwość pojawia się w przypadku kluczy RSA, które zezwalają na dopełnienie 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 jest wymuszane przez sprzęt tylko wtedy, gdy jest wymuszone sprzętowe uwierzytelnianie użytkownika. Do aby to osiągnąć, zaufanie Keymaster oraz odpowiednie uwierzytelnianie muszą być bezpieczne i udostępniać tajny klucz HMAC używany do podpisywania weryfikować tokeny uwierzytelniania. Zobacz na stronie Uwierzytelnianie.
  • Tag::ACTIVE_DATETIME, Tag: originATION_EXPIRE_DATETIME, i tagi Tag::USAGE_disable_DATETIME wymagają dostępu do możliwego do zweryfikowania zegara ściennego. Najbezpieczniejszy sprzęt ma dostęp wyłącznie do informacji o czasie dostarczanych przez niezabezpieczony system operacyjny, który oznacza, że tagi są wymuszane programowo.
  • Aktualna wartość Tag::origin: są zawsze na liście sprzętu w przypadku kluczy powiązanych sprzętowo. Jego obecność w tym kontekście pozwala wyższemu warstwom ustalić, że klucz jest wspierany sprzętowo.

klucz importu

Wersja: 1, 2, 3

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

Importuje materiał klucza na sprzęt Keymaster. Parametry definicji klucza oraz charakterystyka wyjściowa jest obsługiwana 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 zostanie podana, powiernik wydobywa wartości z podanego materiału klucza i dodaje odpowiednich tagów i wartości kluczowych cech. Jeśli parametry to dostępny jest certyfikat weryfikacji w odniesieniu do materiału klucza. W niezgodność, metoda zwraca ErrorCode::IMPORT_PARAMETER_MISMATCH.
  • Zwrócony tag Tag::ORIGIN zawiera element ta sama wartość co KeyOrigin::IMPORTED.

klucz_eksportu

Wersja: 1, 2, 3

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

Eksportuje klucz publiczny z pary kluczy RSA lub EC Keymaster.

Jeśli podczas generowania klucza podano Tag::APPLICATION_ID lub importowaniu, dla tej metody podawana jest ta sama wartość w clientId. W przeciwnym razie zwraca ErrorCode::INVALID_KEY_BLOB Podobnie, jeśli Tag::APPLICATION_DATA została podana podczas generowania lub importowania, ta sama wartość zostanie podana do tę metodę w argumencie appData.

deleteKey

Wersja: 1, 2, 3

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

Usuwa podany klucz. Ta metoda jest opcjonalna i pozwala implementowane przez moduły Keymaster, które zapewniają odporność na wycofywanie zmian.

deleteAllKeys (usuńWszystkie klucze)

Wersja: 1, 2, 3

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

Usuwa wszystkie klawisze. Ta metoda jest opcjonalna i dostępna tylko przez moduły Keymaster, które zapewniają odporność na wycofywanie zmian.

identyfikatoryAtestacji zniszczenia

Wersja: 3

Metoda destroyAttestationIds() jest używana do trwałego wyłącz nowy (opcjonalny, ale zdecydowanie zalecany) Atestacja identyfikatora funkcji. Jeśli TEE nie ma sposobu na zapewnienie trwałego poświadczenia tożsamości wyłączone po wywołaniu tej metody, to poświadczanie identyfikatora nie może być w ogóle nie została zaimplementowana. W takim przypadku ta metoda nie działa i zwraca ErrorCode::UNIMPLEMENTED. Jeśli atest identyfikatora to jest obsługiwana, ta metoda musi zostać zaimplementowana i musi zostać trwale wyłączona wszystkich przyszłych prób poświadczenia tożsamości. Metoda może być wywoływana dowolną liczbą razy. Jeśli atest identyfikatora jest już trwale wyłączony, metoda nic i zwraca ErrorCode::OK.

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

rozpocznij

Wersja: 1, 2, 3

Rozpoczyna operację kryptograficzną przy użyciu określonego klucza dla określonego argumentu przeznaczenia z określonymi parametrami (stosownie do przypadku) i zwraca uchwyt operacji, który jest używany z przyciskami update i finish do ukończenia tej operacji. Uchwyt operacji to jest również używany jako „wyzwanie” w uwierzytelnionych operacjach. W przypadku takich operacji operacje są uwzględnione w polu challenge funkcji token uwierzytelniania.

Implementacja Keymaster obsługuje co najmniej 16 jednoczesnych zadań operacji. Magazyn kluczy używa do 15 znaków. Jeden magazyn jest przeznaczony do użycia jako hasło szyfrowaniem. Gdy w magazynie kluczy jest 15 operacji (begin ma zostały wysłane, ale nie ma jeszcze połączeń finish lub abort ) i otrzymuje żądanie rozpoczęcia szesnastego, zwraca abort w przypadku najrzadziej używanej operacji, aby zmniejszyć liczbę aktywne operacje na 14 przed wywołaniem funkcji begin w celu uruchomienia funkcji w nowo żądanej operacji.

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

Egzekwowanie autoryzacji

W ramach tej metody następujące autoryzacje kluczy są wymuszane przez zaufania, jeśli implementacja umieściła je w tagu „sprzętowe”, a operacja nie jest operacją na kluczu publicznym. Klucz publiczny operacje, czyli KeyPurpose::ENCRYPT i KeyPurpose::VERIFY, za pomocą kluczy RSA lub EC, mogą zadziałać nawet po autoryzacji nie są spełnione.

  • Tag::CEL – cel. określone w wywołaniu begin() muszą pasować do jednego z celów w autoryzacji kluczy, chyba że żądana operacja jest kluczem publicznym . Jeśli podany cel nie pasuje, a operacja nie jest zgodna operacji na kluczu publicznym, begin zwróci ErrorCode::UNSUPPORTED_PURPOSE Operacje na kluczu publicznym są asymetrycznych operacji szyfrowania i weryfikacji.
  • Tag::ACTIVE_DATETIME może być egzekwowane tylko wtedy, gdy dostępne jest zaufane źródło czasu UTC. Jeśli bieżąca data i godzina są przed wartością tagu, metoda zwróci ErrorCode::KEY_NOT_YET_VALID
  • Tag: ORIGINATION_Wygasła_DATETIME może być egzekwowane 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 celem jest KeyPurpose::ENCRYPT lub KeyPurpose::SIGN, metoda zwraca ErrorCode::KEY_EXPIRED.
  • Tag::USAGE_EXPIRE_DATETIME może być egzekwowane 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 celem jest KeyPurpose::DECRYPT lub KeyPurpose::VERIFY, metoda zwraca ErrorCode::KEY_EXPIRED.
  • Tag::MIN_SECONDS_BETWEEN_OPS jest porównywany z zaufanym licznikiem czasu, który wskazuje ostatnie użycie klucz. Jeśli czas ostatniego użycia plus wartość tagu jest krótszy niż bieżący czas, metoda zwraca ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Zobacz opis tagu , gdzie znajdziesz ważne informacje o implementacji.
  • Tag: MAX_USES_PER_BOOT jest porównywana z bezpiecznym licznikiem, który śledzi użycie klucza od uruchomienia. Jeśli liczba wcześniejszych użycia przekroczy wartość określoną przez tag, zwraca wartość ErrorCode::KEY_MAX_OPS_EXCEEDED.
  • Tag::USER_SECURE_ID jest egzekwowane przez tę metodę tylko wtedy, gdy klucz ma również Tag::AUTH_TIMEOUT. Jeśli klucz zawiera oba, ta metoda musi otrzymać prawidłową wartość Tag::AUTH_TOKEN w inParams Aby token uwierzytelniania był prawidłowy, wszystkie te elementy musi być prawdziwy:
    • Weryfikacja pola HMAC przebiega poprawnie.
    • Co najmniej jedna z Tag::USER_SECURE_ID wartości z klucza pasują do co najmniej jednej z wartości token.
    • Klucz ma Tag::USER_AUTH_TYPE zgodnego 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 inicjującego (IV) lub liczby jednorazowej. Jeśli klucz nie ma tego tagu, ale element wywołujący podał Tag::NONCE do tej metody, Zwracana jest wartość ErrorCode::CALLER_NONCE_PROHIBITED.
  • Tag::BOOTLOADER_ONLY określa, że tego klucza może używać tylko program rozruchowy. Jeśli ta metoda jest jest wywoływane za pomocą klucza służącego tylko do programu rozruchowego po zakończeniu działania programu rozruchowego, zwraca ErrorCode::INVALID_KEY_BLOB.

Klucze RSA

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

Operacje podpisywania i weryfikacji RSA wymagają skrótu, podobnie jak szyfrowanie RSA i odszyfrowywania w trybie dopełnienia OAEP. W takich przypadkach rozmówca określa dokładnie jeden skrót w funkcji inParams. Jeśli nie określono lub nie określono więcej niż raz, metoda zwraca ErrorCode::UNSUPPORTED_DIGEST.

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

Z wyjątkiem PaddingMode::NONE wszystkie tryby dopełnienia elastycznych reklam w wyszukiwarce są mające zastosowanie tylko w niektórych celach. Konkretnie: PaddingMode::RSA_PKCS1_1_5_SIGN i PaddingMode::RSA_PSS obsługują tylko podpisywanie i weryfikację, a PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT a PaddingMode::RSA_OAEP obsługują tylko szyfrowanie i odszyfrowywanie. Metoda zwraca ErrorCode::UNSUPPORTED_PADDING_MODE, jeśli określony tryb nie obsługuje określonego przeznaczenia.

Między trybami dopełnienia a podsumowaniem istnieje kilka ważnych interakcji:

  • PaddingMode::NONE oznacza, że wartość „nieprzetworzona” Operacja RSA to przeprowadzonych przez nas działań. Jeśli logujesz się lub weryfikujesz, Digest::NONE to określony dla skrótu. W przypadku szyfrowania bez dopełnienia nie jest wymagane żadne skrót i odszyfrowywaniu.
  • Dopełnienie PaddingMode::RSA_PKCS1_1_5_SIGN wymaga skrótu. skrót może mieć postać Digest::NONE, w którym to przypadku Keymaster implementacja 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 jest podany komunikat, a PS to ciąg dopełnienia. Rozmiar klucza RSA musi wynosić być o co najmniej 11 bajtów większy niż wiadomość. W przeciwnym razie metoda zwróci ErrorCode::INVALID_INPUT_LENGTH
  • Dopełnienie PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT nie wymaga skrótu.
  • Dopełnienie PaddingMode::RSA_PSS wymaga skrótu, które może nie być Digest::NONE Jeśli określono Digest::NONE, parametr zwraca wartość ErrorCode::INCOMPATIBLE_DIGEST. Dodatkowo klucz RSA musi być co najmniej 2 + D B większy niż dane wyjściowe rozmiar skrótu, gdzie D to rozmiar skrótu w bajtach. W przeciwnym razie metoda zwraca ErrorCode::INCOMPATIBLE_DIGEST. Wielkość soli to D.
  • Dopełnienie PaddingMode::RSA_OAEP wymaga skrótu, które może nie być Digest::NONE Jeśli określono Digest::NONE, parametr zwraca wartość ErrorCode::INCOMPATIBLE_DIGEST.

Klucze EC

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

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

Klucze AES

Operacje klucza AES określają dokładnie 1 tryb bloku i 1 tryb dopełnienia w usłudze inParams. Jeśli wartość jest nieokreślona lub określona bardziej niż raz, zwróć ErrorCode::UNSUPPORTED_BLOCK_MODE lub ErrorCode::UNSUPPORTED_PADDING_MODE Podane środki muszą być autoryzowany przez klucz, w przeciwnym razie zwraca ErrorCode::INCOMPATIBLE_BLOCK_MODE lub ErrorCode::INCOMPATIBLE_PADDING_MODE

Jeśli tryb blokowania to BlockMode::GCM, inParams określa Tag::MAC_LENGTH, a parametr określona wartość jest wielokrotnością liczby 8, która nie jest większa niż 128 lub mniejsza od wartości Tag::MIN_MAC_LENGTH w autoryzacje kluczy. W przypadku adresów MAC większych niż 128 lub wielokrotności argumentu 8, powrót ErrorCode::UNSUPPORTED_MAC_LENGTH. Dla wartości niższej niż minimalna długość klucza, zwróć ErrorCode::INVALID_MAC_LENGTH.

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

Jeśli tryb blokowania to BlockMode::CBC, BlockMode::CTR, lub BlockMode::GCM, potrzebny jest wektor inicjujący lub liczba jednorazowa. W większości przypadków rozmówcy nie powinni podawać wartości IV ani liczby jednorazowej. W takim przypadku Implementacja Keymaster generuje losową wartość IV lub liczbę jednorazową i zwraca ją przez Tag::NONCE w języku outParams. Urządzenia CBC i CTR IV mają 16 bajtów. Liczby jednorazowe w GCM mają 12 bajtów. Jeśli klucz (autoryzacje zawierają) Tag::CALLER_NONCE, dzwoniący może podać IV/nonce Tag::NONCE w języku: inParams. Jeśli liczba jednorazowa została podana, gdy argument Tag::CALLER_NONCE nie jest autoryzowany, zwróć ErrorCode::CALLER_NONCE_PROHIBITED. Jeśli liczba jednorazowa nie zostanie podana, Tag::CALLER_NONCE jest autoryzowany, generuje losowy ruch IV/liczbowy.

Klucze HMAC

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

aktualizować

Wersja: 1, 2, 3

Udostępnia dane do przetworzenia w trwającej operacji rozpoczętej begin (rozpoczęcie). Operacja jest określana przez parametr operationHandle.

Implementacje tej metody pozwalają zapewnić większą elastyczność obsługi bufora zużywać mniej danych niż zostały udostępnione. Rozmówca to odpowiedzialny za zapętlenie pozostałych danych w kolejnych wywołaniach. ilość wykorzystanych danych wejściowych jest zwracana w parametrze inputConsumed. Implementacje zawsze wykorzystują co najmniej 1 bajt, chyba że operacja nie może przyjąć więcej danych; jeśli podano więcej niż 0 bajtów i 0 bajtów bajty, osoby wywołujące uznają to za błąd i przerywają operację.

Implementacje mogą też określać ilość danych do zwrócenia, ponieważ . Ma to zastosowanie tylko w przypadku operacji szyfrowania i odszyfrowywania, ponieważ podpisywanie i weryfikacja nie zwracają danych do zakończenia. Zwracaj dane jak najwcześniej, zamiast je buforować.

Obsługa błędów

Jeśli ta metoda zwraca kod błędu inny niż ErrorCode::OK, operacja została przerwana, a uchwyt operacji jest unieważniony. Dowolne użycia nicka w przyszłości, zakończyć lub przerwać, zwraca ErrorCode::INVALID_OPERATION_HANDLE.

Egzekwowanie autoryzacji

Egzekwowanie autoryzacji klucza jest przeprowadzane głównie na początku. Wyjątkiem jest sytuacja, w której klucz ma:

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

Element wywołujący podaje token uwierzytelniania przy każdym wywołaniu, aby update i finans (Zakończ). W razie potrzeby implementacja musi zatwierdzić token tylko raz.

Klucze RSA

Na potrzeby operacji podpisywania i weryfikacji za pomocą Digest::NONE: ta metoda akceptuje cały blok, aby podpisać lub zweryfikować go w jednym . Nie może wykorzystać tylko części bloku. Jeśli jednak rozmówca jeśli postanowisz dostarczyć dane w wielu aktualizacjach, ta metoda je akceptuje. Jeśli wywołujący poda więcej danych do podpisania niż można wykorzystać (długość danych przekracza rozmiar klucza RSA), zwraca wartość ErrorCode::INVALID_INPUT_LENGTH.

Klucze ECDSA

Na potrzeby operacji podpisywania i weryfikacji za pomocą Digest::NONE: ta metoda akceptuje cały blok, aby podpisać lub zweryfikować go w jednym . Ta metoda nie może wykorzystywać tylko części bloku.

Jeśli jednak rozmówca postanowi podać dane w wielu aktualizacjach, akceptowana jest metoda. Jeśli rozmówca poda więcej danych do podpisania niż może zostać użyte, dane są dyskretnie obcinane. (Różni się to od obsługi nadmiarowych danych przekazanych w ramach podobnych operacji RSA. Przyczyna jest zgodność ze starszymi klientami).

Klucze AES

Tryb AES GCM obsługuje „powiązane dane uwierzytelniania”, dostarczona przez Tag::ASSOCIATED_DATA w argumencie inParams. Powiązane dane można podawać w wielu rozmowach (ważne, jeśli dane są zbyt duże, aby wysłać je w pojedynczym bloku), ale zawsze poprzedzają dane do zaszyfrowania lub odszyfrowania. Połączenie w aktualizacji może otrzymać oba powiązane dane i danych do szyfrowania/odszyfrowywania, ale kolejne aktualizacje mogą nie uwzględniać powiązanych i skalowalnych danych. Jeśli rozmówca przekaże powiązane dane do aktualizacji wywołania po zakończeniu połączenia zawierający dane do zaszyfrowania/odszyfrowania, zwraca wartość ErrorCode::INVALID_TAG.

W przypadku szyfrowania GCM tag jest dołączany do tekstu szyfrowania przez finish (Zakończ). Podczas odszyfrowywania ostatni Tag::MAC_LENGTH bajtów danych przekazanych ostatniemu jest tagiem. Od danego wywołania funkcji update nie może określić, czy jest to ostatnie wywołanie, przetwarza wszystko poza długością tagu i buforuje możliwe dane tagu podczas zakończenia.

zakończ

Wersja: 1, 2, 3

kończy trwającą operację rozpoczętą od begin, przetwarzania wszystkich jeszcze nieprzetworzonych danych dostarczanych przez aktualizacja

Jest to ostatnia metoda wywołana w operacji, więc wszystkie przetworzone dane.

Ta metoda finalizuje działanie – bez względu na to, czy zakończy się powodzeniem, czy zwróci błąd. i unieważnia podany uchwyt operacji. Dowolne użycia w przyszłości nicka z tą metodą lub przy użyciu funkcji update lub abort, zwraca ErrorCode::INVALID_OPERATION_HANDLE.

Operacje podpisywania zwracają podpis jako dane wyjściowe. Operacje weryfikacji zaakceptuj podpis w parametrze signature i nie zwróci żadnych danych wyjściowych.

Egzekwowanie autoryzacji

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

W tym przypadku klucz wymaga autoryzacji na operację, a aktualizacja otrzymuje wartość Tag::AUTH_TOKEN w argumencie inParams. HMAC weryfikuje, czy token jest prawidłowy i zawiera pasujący bezpieczny identyfikator użytkownika, zgodny z Tag::USER_AUTH_TYPE oraz zawiera uchwyt operacji bieżącej operacji w sekcji pole wyzwania. Jeśli te warunki nie są spełnione, zwróć ErrorCode::KEY_USER_NOT_AUTHENTICATED

Element wywołujący podaje token uwierzytelniania przy każdym wywołaniu do zaktualizuj i zakończ. W razie potrzeby implementacja musi zatwierdzić token tylko raz.

Klucze RSA

Dodatkowe wymagania zależnie od trybu dopełnienia:

  • PaddingMode::NONE W przypadku niedopełnionych operacji podpisywania i szyfrowania: Jeśli podane dane są krótsze niż klucz, dane zostaną uzupełnione zero po lewej przed podpisaniem/zaszyfrowaniem. Jeśli dane są tej samej długości co klucz, ale większą liczbowo, zwraca ErrorCode::INVALID_ARGUMENT. Dla: operacji weryfikacji i odszyfrowywania, dane muszą być tak długie, jako klucz. W przeciwnym razie zwróć ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS W przypadku operacji podpisu z dopełnieniem PSS ciąg zaburzający PSS to rozmiar skrótu wiadomości wygenerowanego losowo. skrót określony za pomocą polecenia Tag::DIGEST w inputParams na begin jest używany jako skrót PSS oraz algorytmem skrótu MGF1.
  • PaddingMode::RSA_OAEP Skrót określony za pomocą funkcji Parametr Tag::DIGEST w Ścieżka inputParams na początek jest używana jako OAEP z algorytmem skrótu, a SHA1 jako algorytmu skrótu MGF1.

Klucze ECDSA

Jeśli dane podane do podpisywania lub weryfikacji bez dopełnienia są za długie, skróć .

Klucze AES

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

  • BlockMode::ECB lub BlockMode::CBC. Jeśli dopełnienie ma wartość PaddingMode::NONE, a parametr długość danych nie jest wielokrotnością rozmiaru bloku AES, zwróć ErrorCode::INVALID_INPUT_LENGTH Jeśli dopełnienie to PaddingMode::PKCS7, dopasuj dane zgodnie ze specyfikacją PKCS#7. Pamiętaj, że PKCS#7 zaleca dodanie dodatkowego bloku dopełnienia jeśli dane są wielokrotnością długości bloku.
  • BlockMode::GCM W trakcie szyfrowania, po przetworzeniu cały zwykły tekst, oblicz tag (Tag::MAC_LENGTH B) i dołączam go do zwróconego tekstu zaszyfrowanego. Podczas odszyfrowywania ostatni tag Tag::MAC_LENGTH bajtów jako tagu. Jeśli weryfikacja tagu się nie powiedzie, zwróć ErrorCode::VERIFICATION_FAILED

przerwij

Wersja: 1, 2, 3

Przerywa wykonywaną operację. Po wywołaniu przerwania wróć do ErrorCode::INVALID_OPERATION_HANDLE – użycie podanego nicka operacji z poleceniem update, zakończyć lub przerwać.

get_supported_algorytmy

Wersja: 1

Zwraca listę algorytmów obsługiwanych przez sprzęt Keymaster implementacji. Implementacja oprogramowania zwraca pustą listę. hybrydowy zwraca listę zawierającą tylko algorytmy, które są przez sprzęt.

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

tryby get_supported_block_modes

Wersja: 1

Zwraca listę trybów blokowania AES obsługiwanych przez sprzęt Keymaster dla określonego algorytmu i przeznaczenia.

W przypadku RSA, EC i HMAC, które nie są szyframi blokowymi, metoda zwraca błąd pustą listę we wszystkich uzasadnionych celach. Nieprawidłowe cele powinny powodować, że metoda zwróć ErrorCode::INVALID_PURPOSE.

Implementacje Keymaster 1 obsługują ECB, CBC, CTR i GCM w przypadku AES szyfrowaniem i odszyfrowywaniu.

tryb get_supported_fill_modes

Wersja: 1

Zwraca listę trybów dopełnienia obsługiwanych przez sprzęt Keymaster. dla określonego algorytmu i przeznaczenia.

HMAC i EC nie mają pojęcia dopełnienia, więc metoda zwraca pustą listę. we wszystkich uzasadnionych celach. Nieprawidłowe cele powinny powodować zwrócenie metody ErrorCode::INVALID_PURPOSE

W przypadku sprzedawców RSA implementacje Keymaster 1 obsługują:

  • Szyfrowanie, odszyfrowywanie, podpisywanie i weryfikacja bez wypełnienia. Do wyściełania szyfrowanie i podpisywanie, jeśli wiadomość jest krótsza niż wartość modułu publicznego, muszą być wypełnione zerami. Do odszyfrowywania bez dopełnienia 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 o długości 20
  • protokół OAEP

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

get_supported_podsumowania

Wersja: 1

Zwraca listę trybów podsumowania obsługiwanych przez sprzęt Keymaster dla określonego algorytmu i przeznaczenia.

Żadne tryby AES nie obsługują ani nie wymagają podsumowania, więc metoda zwraca pusty w prawidłowych celach.

Implementacje Keymaster 1 mogą implementować podzbiór zdefiniowanych podsumowań. Implementacje zapewniają SHA-256 i mogą dostarczać MD5, SHA1, SHA-224, SHA-256, SHA384 i SHA512 (pełny zestaw zdefiniowanych skrótów).

get_supported_import_formats;

Wersja: 1

Zwraca listę formatów importu obsługiwanych przez sprzęt Keymaster implementacji określonego algorytmu.

Implementacje Keymaster 1 obsługują format PKCS#8 (bez hasła) ochrony) do importowania par kluczy RSA i EC oraz obsługuje import RAW Materiał klucza AES i HMAC.

get_supported_export_formats

Wersja: 1

Zwraca listę formatów eksportu obsługiwanych przez sprzęt Keymaster. implementacji określonego algorytmu.

Implementacje Keymaster1 obsługują format X.509 na potrzeby eksportowania RSA i Klucze publiczne EC. Eksport kluczy prywatnych i kluczy asymetrycznych nie jest obsługiwany.

Funkcje historyczne

Keymaster 0

Poniższe funkcje należą do pierwotnej definicji Keymaster 0. Ta były obecne w Keymaster 1 struct keymaster1_device_t. Jednak w programie Keymaster 1.0 – nie zostały zaimplementowane, a ich wskaźniki funkcji miały wartość NULL.

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

Keymaster 1

Poniższe funkcje należą do definicji narzędzia Keymaster 1, ale zostały usunięte w programie Keymaster 2 oraz funkcje Keymaster 0 wymienione 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 narzędzia Keymaster 2, ale zostały usunięte w programie Keymaster 3 wraz z wymienionymi powyżej funkcjami Keymaster 1.

  • configure