Na tej stronie znajdują się szczegółowe informacje pomocne osobom wdrażającym warstwy HAL Keymaster. Obejmuje każdy tag w HAL, wersję Keymastera, w której dany tag jest dostępny i czy tag jest powtarzalny. Z wyjątkiem przypadków wskazanych w opisach znaczników, wszystkie poniższe znaczniki są używane podczas generowania klucza w celu określenia kluczowych cech.
W przypadku Keymaster 4 znaczniki są zdefiniowane w platform/hardware/interfaces/keymaster/ keymaster-version /types.hal
, np. 3.0/types.hal dla Keymaster 3 i 4.0/types.hal dla Keymaster 4. W przypadku Keymaster 2 i starszych wersji: tagi są zdefiniowane w platform/hardware/libhardware/include/hardware/keymaster_defs.h
.
Informacje na temat funkcji można znaleźć na stronie Funkcje Keymaster .
Etykieta::ACTIVE_DATETIME
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa datę i godzinę, o której klucz staje się aktywny. Przed tym czasem każda próba użycia klucza kończy się niepowodzeniem i wyświetla komunikat ErrorCode::KEY_NOT_YET_VALID
.
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Etykieta::ALGORYTM
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa algorytm kryptograficzny, z którym używany jest klucz.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class Algorithm : uint32_t { RSA = 1, EC = 3, AES = 32, HMAC = 128, };Keymaster 2 i starsze wersje
typedef enum { KM_ALGORITHM_RSA = 1, KM_ALGORITHM_EC = 3, KM_ALGORITHM_AES = 32, KM_ALGORITHM_HMAC = 128, } keymaster_algorithm_t;
Etykieta::ALL_APPLICATIONS
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Zarezerwowane do wykorzystania w przyszłości.
Etykieta::ALLOW_WHILE_ON_BODY
Wersja : 2, 3, 4
Powtarzalne ? NIE
Ten tag dotyczy tylko urządzeń z systemem Android Wear i czujnikami umieszczonymi na ciele. Na tym etapie nie oczekuje się, że jakikolwiek TEE będzie w stanie zapewnić bezpieczny dostęp do czujnika na ciele ani że czujniki na ciele będą bardzo bezpieczne, dlatego oczekuje się, że będzie to funkcja wymuszana wyłącznie programowo.
Etykieta::ALL_USERS
Wersja : 3, 4
Powtarzalne ? NIE
Zarezerwowane do wykorzystania w przyszłości.
Etykieta::APPLICATION_DATA
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Znacznik ten, dostarczony do generateKey lub importKey , określa dane, które są niezbędne podczas każdego użycia klucza. W szczególności wywołania funkcjiexportKey i getKeyCharacteristics muszą podawać tę samą wartość parametrowi clientId
, a wywołania rozpoczynające muszą udostępniać ten znacznik i te same powiązane dane jako część zestawu inParams
. Jeżeli nie zostaną podane prawidłowe dane, funkcja zwraca ErrorCode::INVALID_KEY_BLOB
.
Zawartość tego tagu jest powiązana z kluczem kryptograficznie , co oznacza, że przeciwnik, który ma dostęp do wszystkich tajemnic bezpiecznego świata, ale nie ma dostępu do treści tagu, nie może mieć możliwości odszyfrowania klucza bez użycia metody brute-force. zawartość, której aplikacje mogą zapobiec, określając zawartość o wystarczająco wysokiej entropii.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::APPLICATION_ID
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Znacznik ten, dostarczony do generateKey lub importKey , określa dane, które są niezbędne podczas każdego użycia klucza. W szczególności wywołania funkcjiexportKey i getKeyCharacteristics muszą podawać tę samą wartość w parametrze clientId
, a wywołania rozpoczynające muszą udostępniać ten znacznik i te same powiązane dane jako część zestawu inParams
. Jeżeli nie zostaną podane prawidłowe dane, funkcja zwraca ErrorCode::INVALID_KEY_BLOB
.
Zawartość tego tagu jest powiązana z kluczem kryptograficznie , co oznacza, że przeciwnik, który ma dostęp do wszystkich tajemnic bezpiecznego świata – ale nie ma dostępu do treści tagu – nie może odszyfrować klucza (bez brutalnego wymuszania zawartości tagu ).
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ASSOCIATED_DATA
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Zapewnia „powiązane dane” do szyfrowania lub deszyfrowania AES-GCM. Ten znacznik służy do aktualizacji i określa dane, które nie są szyfrowane/odszyfrowywane, ale są używane do obliczania znacznika GCM.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_APPLICATION_ID
Wersja : 3, 4
Powtarzalne ? NIE
Służy do identyfikacji zestawu możliwych zastosowań, dla których zainicjowano kluczową atestację.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_CHALLENGE
Wersja : 3, 4
Powtarzalne ? NIE
Używane do kwestionowania zaświadczenia.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_BRAND
Wersja : 3, 4
Powtarzalne ? NIE
Podaje nazwę marki urządzenia zwróconą przez Build.BRAND
w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_DEVICE
Wersja : 3, 4
Powtarzalne ? NIE
Podaje nazwę urządzenia zwróconą przez Build.DEVICE
w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_IMEI
Wersja : 3, 4
Powtarzalne ? Tak
Zapewnia numery IMEI dla wszystkich radiotelefonów w urządzeniu. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_MANUFACTURER
Wersja : 3, 4
Powtarzalne ? NIE
Podaje nazwę producenta urządzenia zwróconą przez Build.MANUFACTURER
w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_MEID
Wersja : 3, 4
Powtarzalne ? Tak
Zapewnia identyfikatory MEID dla wszystkich radiotelefonów w urządzeniu. To pole zostanie ustawione tylko w przypadku żądania potwierdzenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_MODEL
Wersja : 3, 4
Powtarzalne ? NIE
Podaje nazwę modelu urządzenia zwróconą przez Build.MODEL
w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_PRODUCT
Wersja : 3, 4
Powtarzalne ? NIE
Podaje nazwę produktu urządzenia zwróconą przez Build.PRODUCT
w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::ATTESTATION_ID_SERIAL
Wersja : 3, 4
Powtarzalne ? NIE
Podaje numer seryjny urządzenia. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds()
i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS
.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::AUTH_TIMEOUT
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa czas w sekundach, przez który klucz jest autoryzowany do użycia po uwierzytelnieniu. Jeśli Tag::USER_SECURE_ID jest obecny, a ten tag nie, wówczas klucz wymaga uwierzytelnienia przy każdym użyciu (szczegóły dotyczące przepływu uwierzytelniania na operację można znaleźć na początku ).
Wartość jest 32-bitową liczbą całkowitą określającą czas w sekundach po pomyślnym uwierzytelnieniu użytkownika określonego przez Tag::USER_SECURE_ID metodą uwierzytelnienia określoną przez Tag::USER_AUTH_TYPE , w którym można użyć klucza.
Etykieta::AUTH_TOKEN
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Zapewnia token uwierzytelniający do rozpoczęcia , aktualizacji lub zakończenia , aby udowodnić uwierzytelnienie użytkownika dla kluczowej operacji, która tego wymaga (klucz ma Tag::USER_SECURE_ID ).
Wartością jest obiekt typu blob zawierający strukturę hw_auth_token_t
.
Etykieta::BLOB_USAGE_REQUIREMENTS
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa niezbędne warunki środowiska systemowego, aby wygenerowany klucz mógł zostać użyty.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };Keymaster 2 i starsze wersje
typedef enum { KM_BLOB_STANDALONE = 0, KM_BLOB_REQUIRES_FILE_SYSTEM = 1, } keymaster_key_blob_usage_requirements_t;
Ten znacznik można określić podczas generowania klucza, aby wymagać, aby klucz nadawał się do użycia w określonym stanie. Musi zostać zwrócony z kluczowymi cechami z generateKey i getKeyCharacteristics . Jeśli obiekt wywołujący określi Tag::BLOB_USAGE_REQUIREMENTS
z wartością KeyBlobUsageRequirements::STANDALONE
zaufanie zwróci kluczowy obiekt BLOB, którego można używać bez obsługi systemu plików. Ma to kluczowe znaczenie w przypadku urządzeń z zaszyfrowanymi dyskami, gdzie system plików może nie być dostępny do czasu użycia klucza Keymaster do odszyfrowania dysku.
Etykieta::BLOCK_MODE
Wersja : 1, 2, 3, 4
Powtarzalne ? Tak
Określa tryb(y) szyfrowania blokowego, w którym można używać klucza. Ten tag dotyczy tylko kluczy AES.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };Keymaster 2 i starsze wersje
typedef enum { KM_MODE_ECB = 1, KM_MODE_CBC = 2, KM_MODE_CTR = 3, KM_MODE_GCM = 32, } keymaster_block_mode_t;
Ten znacznik jest powtarzalny, a w przypadku operacji na kluczu AES określ tryb w additionalParams
argumencie Params Begin . Jeśli określony tryb nie znajduje się w trybach skojarzonych z kluczem, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
Etykieta::BOOT_PATCHLEVEL
Wersja : 4
Tag::BOOT_PATCHLEVEL określa poziom poprawki zabezpieczeń obrazu rozruchowego (jądra), z którym można używać klucza. Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo. Każda próba użycia klucza z wartością Tag::BOOT_PATCHLEVEL
inną niż aktualnie uruchomiony poziom poprawki systemowej powoduje, że funkcja begin()
, getKeyCharacteristics()
lub exportKey()
zwraca ErrorCode::KEY_REQUIRES_UPGRADE
. Aby uzyskać szczegółowe informacje, zobacz upgradeKey()
.
Wartość znacznika jest liczbą całkowitą w postaci YYYYMMDD, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, MM to dwucyfrowy miesiąc, a DD to dwucyfrowy dzień ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego 5 czerwca 2018 r., wartość będzie wynosić 20180605. Jeśli dzień nie jest znany, można zastąpić 00.
Podczas każdego rozruchu program ładujący musi zapewnić poziom poprawki obrazu rozruchowego w bezpiecznym środowisku (mechanizm jest zdefiniowany w implementacji).
Musi być wymuszane sprzętowo.
Etykieta::BOOTLOADER_ONLY
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa, że tylko program ładujący może używać klucza.
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Każda próba użycia klucza z Tag::BOOTLOADER_ONLY
z systemu Android kończy się niepowodzeniem i wyświetleniem ErrorCode::INVALID_KEY_BLOB
.
Etykieta::CALLER_NONCE
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa, że obiekt wywołujący może zapewnić wartość jednorazową dla operacji niewymagających.
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Ten znacznik jest używany tylko dla kluczy AES i ma zastosowanie tylko w trybach blokowych CBC, CTR i GCM. Jeśli tag nie jest obecny, implementacje powinny odrzucić każdą operację, która zapewnia Tag::NONCE na początku ErrorCode::CALLER_NONCE_PROHIBITED
.
Etykieta::CREATION_DATETIME
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa datę i godzinę utworzenia klucza, w milisekundach od 1 stycznia 1970. Ten znacznik jest opcjonalny i ma wyłącznie charakter informacyjny.
Etykieta::TRAWIENIE
Wersja : 1, 2, 3, 4
Powtarzalne ? Tak
Określa algorytmy podsumowania, których można używać z kluczem do wykonywania operacji podpisywania i weryfikacji. Znacznik ten dotyczy kluczy RSA, ECDSA i HMAC.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class Digest : uint32_t { NONE = 0, MD5 = 1, SHA1 = 2, SHA_2_224 = 3, SHA_2_256 = 4, SHA_2_384 = 5, SHA_2_512 = 6, };Keymaster 2 i starsze wersje
typedef enum { KM_DIGEST_NONE = 0, KM_DIGEST_MD5 = 1, KM_DIGEST_SHA1 = 2, KM_DIGEST_SHA_2_224 = 3, KM_DIGEST_SHA_2_256 = 4, KM_DIGEST_SHA_2_384 = 5, KM_DIGEST_SHA_2_512 = 6, } keymaster_digest_t;
Ten znacznik jest powtarzalny. W przypadku operacji podpisywania i weryfikacji określ skrót w additionalParams
argumencie Begin . Jeśli określonego skrótu nie ma w podsumowaniach powiązanych z kluczem, operacja kończy się niepowodzeniem z powodu ErrorCode::INCOMPATIBLE_DIGEST
.
Etykieta::EC_CURVE
Wersja : 2, 3, 4
Powtarzalne ? NIE
W Keymaster 1 krzywa używana dla kluczy EC została odgadnięta na podstawie określonego rozmiaru klucza. Aby poprawić elastyczność w przyszłości, Keymaster 2 wprowadził wyraźny sposób określania krzywych. Żądania wygenerowania klucza EC mogą mieć Tag::EC_CURVE
, Tag::KEY_SIZE
lub oba.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };Keymaster 2 i starsze wersje
enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };
Jeśli żądanie generacji zawiera tylko Tag::KEY_SIZE
, wróć do logiki Keymaster 1, wybierając odpowiednią krzywą NIST.
Jeśli żądanie zawiera tylko Tag::EC_CURVE
, użyj określonej krzywej. W przypadku Keymaster 3 i nowszych wersji krzywe są definiowane w EcCurve
. W przypadku Keymaster 2 i wcześniejszych krzywe są zdefiniowane w keymaster_ec_curve_t
.
Jeśli żądanie zawiera oba, użyj krzywej określonej przez Tag::EC_CURVE
i sprawdź, czy określony rozmiar klucza jest odpowiedni dla tej krzywej. Jeśli nie, zwróć ErrorCode::INVALID_ARGUMENT
.
Etykieta::INCLUDE_UNIQUE_ID
Wersja : 2, 3, 4
Powtarzalne ? NIE
Ten znacznik jest określany podczas generowania klucza, aby wskazać, że certyfikat zaświadczający dla wygenerowanego klucza powinien zawierać unikalny identyfikator urządzenia o zakresie aplikacji i ograniczony czasowo, zgodnie z określeniem Tag::UNIQUE_ID .
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Etykieta::KEY_SIZE
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa rozmiar klucza w bitach, mierzony w normalny sposób dla algorytmu klucza. Na przykład dla kluczy RSA Tag::KEY_SIZE
określa rozmiar modułu publicznego. W przypadku kluczy AES określa długość materiału tajnego klucza.
Etykieta::MAC_LENGTH
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Podaje żądaną długość znacznika uwierzytelniającego MAC lub GCM w bitach.
Wartość to długość MAC w bitach. Jest to wielokrotność liczby 8 i co najmniej tak duża, jak wartość Tag::MIN_MAC_LENGTH powiązana z kluczem.
Etykieta::MAX_USES_PER_BOOT
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa maksymalną liczbę użyć klucza pomiędzy ponownymi uruchomieniami systemu. Jest to kolejny mechanizm ograniczający użycie klucza.
Wartość jest 32-bitową liczbą całkowitą reprezentującą użycia na rozruch.
Gdy w operacji używany jest klucz z tym znacznikiem, podczas wywołania rozpoczęcia należy zwiększyć licznik powiązany z kluczem. Po przekroczeniu tej wartości przez licznik kluczy, wszystkie kolejne próby użycia klucza kończą się niepowodzeniem z ErrorCode::MAX_OPS_EXCEEDED
do czasu ponownego uruchomienia urządzenia. Oznacza to, że trustlet przechowuje tabelę użycia liczników kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, tabela ta może mieć stały maksymalny rozmiar, a operacje Keymastera mogą zakończyć się niepowodzeniem, próbując użyć kluczy z tym znacznikiem, gdy tabela jest pełna. Stół musi pomieścić co najmniej 16 kluczy. Jeśli operacja nie powiedzie się, ponieważ tabela jest pełna, Keymaster zwraca ErrorCode::TOO_MANY_OPERATIONS
.
Etykieta::MIN_MAC_LENGTH
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Ten znacznik określa minimalną długość adresu MAC, o którą można poprosić lub zweryfikować za pomocą tego klucza dla kluczy HMAC i kluczy AES obsługujących tryb GCM.
Ta wartość to minimalna długość MAC w bitach. Jest to wielokrotność liczby 8. W przypadku kluczy HMAC wartość wynosi co najmniej 64. W przypadku kluczy GCM wartość wynosi co najmniej 96 i nie więcej niż 128.
Etykieta::MIN_SECONDS_BETWEEN_OPS
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa minimalny czas, jaki upływa pomiędzy dozwolonymi operacjami przy użyciu klucza. Można tego użyć do ograniczenia szybkości użycia kluczy w kontekstach, w których nieograniczone użycie może umożliwić ataki brute-force.
Wartość jest 32-bitową liczbą całkowitą reprezentującą sekundy pomiędzy dozwolonymi operacjami.
Jeśli w operacji używany jest klawisz z tym znacznikiem, należy uruchomić licznik czasu podczas kończenia lub przerywania połączenia. Każde wywołanie rozpoczęcia odebrane przed licznikiem czasu wskazuje, że upłynął interwał określony przez Tag::MIN_SECONDS_BETWEEN_OPS
co kończy się niepowodzeniem z ErrorCode::KEY_RATE_LIMIT_EXCEEDED
. Oznacza to, że trustlet przechowuje tabelę użycia liczników kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, tabela ta może mieć stały maksymalny rozmiar, a operacje Keymastera mogą zakończyć się niepowodzeniem, próbując użyć kluczy z tym znacznikiem, gdy tabela jest pełna. Stół musi pomieścić co najmniej 32 używane klucze i agresywnie ponownie wykorzystywać miejsca w stole po wygaśnięciu okresów minimalnego użycia kluczy. Jeśli operacja nie powiedzie się, ponieważ tabela jest pełna, Keymaster zwraca ErrorCode::TOO_MANY_OPERATIONS
.
Etykieta::NO_AUTH_REQUIRED
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa, że do użycia tego klucza nie jest wymagane żadne uwierzytelnianie. Ten tag wyklucza się wzajemnie z Tag::USER_SECURE_ID .
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Etykieta::NONCE
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Dostarcza lub zwraca wartość jednorazową lub wektor inicjujący (IV) dla szyfrowania lub deszyfrowania AES GCM, CBC lub CTR. Znacznik ten rozpoczyna się podczas operacji szyfrowania i deszyfrowania. Rozpoczęcie możliwe jest tylko wtedy, gdy klucz ma Tag::CALLER_NONCE . Jeśli nie zostanie podany, odpowiednia wartość jednorazowa lub IV zostanie losowo wygenerowana przez Keymaster i zwrócona od początku.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości. Dozwolone długości zależą od trybu: wartości jednorazowe GCM mają długość 12 bajtów; Długość CBC i CTR IV wynosi 16 bajtów.
Etykieta::POCHODZENIE
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa, gdzie utworzono klucz, jeśli jest znany. Znacznik ten nie może być określony podczas generowania lub importowania klucza i musi zostać dodany do charakterystyki klucza przez zaufany element.
Klucznik 3 Możliwe wartości są zdefiniowane w android::hardware::keymaster::v3_0::KeyOrigin
:
enum class KeyOrigin : uint32_t { GENERATED = 0, DERIVED = 1, IMPORTED = 2, UNKNOWN = 3, };Keymaster 2 i starsze wersje
Możliwe wartości są zdefiniowane w keymaster_origin_t
:
typedef enum { KM_ORIGIN_GENERATED = 0, KM_ORIGIN_IMPORTED = 2, KM_ORIGIN_UNKNOWN = 3, } keymaster_key_origin_t
Pełne znaczenie wartości zależy nie tylko od niej, ale także od tego, czy znajduje się ona na liście cech wymuszanych sprzętowo, czy programowo.
GENERATED
wskazuje, że Keymaster wygenerował klucz. Jeśli znajduje się na liście wymuszanej sprzętowo, klucz został wygenerowany na bezpiecznym sprzęcie i jest trwale powiązany ze sprzętem. Jeśli znajduje się na liście wymuszanej programowo, klucz został wygenerowany w SoftKeymaster i nie jest powiązany sprzętowo.
DERIVED
wskazuje, że klucz został uzyskany w programie Keymaster. Prawdopodobnie istnieje poza urządzeniem.
IMPORTED
wskazuje, że klucz został wygenerowany poza Keymaster i zaimportowany do Keymaster. Jeśli znajduje się na liście wymuszanej sprzętowo, jest trwale powiązany ze sprzętem, chociaż mogą istnieć kopie poza bezpiecznym sprzętem. Jeśli na liście wymuszanej przez oprogramowanie, klucz został zaimportowany do SoftKeymaster i nie jest powiązany sprzętowo.
UNKNOWN
powinna pojawiać się tylko na liście wymuszanej sprzętowo. Wskazuje, że klucz jest powiązany sprzętowo, ale nie wiadomo, czy klucz został pierwotnie wygenerowany na bezpiecznym sprzęcie, czy został zaimportowany. Dzieje się tak tylko wtedy, gdy sprzęt Keymaster0 jest używany do emulacji usług Keymaster1.
Etykieta::ORIGINATION_EXPIRE_DATETIME
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa datę i godzinę wygaśnięcia klucza do celów podpisywania i szyfrowania. Po tym czasie jakakolwiek próba użycia klucza z podanym na początku KeyPurpose::SIGN lub KeyPurpose::ENCRYPT kończy się niepowodzeniem i wyświetleniem błędu ErrorCode::KEY_EXPIRED
.
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Etykieta::OS_PATCHLEVEL
Wersja : 2, 3, 4
Powtarzalne ? NIE
Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo.
Wartość znacznika jest liczbą całkowitą w postaci YYYYMM, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, a MM to dwucyfrowy miesiąc ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego w grudniu 2015 r., wartość będzie wynosić 201512.
Klucze, które mają poziom poprawki inny niż bieżący poziom poprawki, nie nadają się do użycia. Próba użycia takiego klucza powoduje, że metody Begin , getKeyCharacteristics lub eksportKey zwracają ErrorCode::KEY_REQUIRES_UPGRADE
. Aby uzyskać więcej informacji, zobacz Powiązanie wersji .
Etykieta::OS_VERSION
Wersja : 2, 3, 4
Powtarzalne ? NIE
Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo.
Wartość znacznika jest liczbą całkowitą w postaci MMmmss, gdzie MM jest numerem wersji głównej, mm jest numerem wersji pomocniczej, a ss jest numerem wersji podrzędnej. Na przykład dla klucza wygenerowanego w systemie Android w wersji 4.0.3 wartość będzie wynosić 040003.
Etykieta::WKŁADKA
Wersja : 1, 2, 3, 4
Powtarzalne ? Tak
Określa tryby dopełniania, których można używać z klawiszem. Ten tag dotyczy kluczy RSA i AES.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class PaddingMode : uint32_t { NONE = 1, RSA_OAEP = 2, RSA_PSS = 3, RSA_PKCS1_1_5_ENCRYPT = 4, RSA_PKCS1_1_5_SIGN = 5, PKCS7 = 64, };Keymaster 2 i starsze wersje
typedef enum { KM_PAD_NONE = 1, KM_PAD_RSA_OAEP = 2, KM_PAD_RSA_PSS = 3, KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, KM_PAD_RSA_PKCS1_1_5_SIGN = 5, KM_PAD_PKCS7 = 64, } keymaster_padding_t;
PaddingMode::RSA_OAEP
i PaddingMode::RSA_PKCS1_1_5_ENCRYPT
są używane tylko w przypadku kluczy szyfrowania/deszyfrowania RSA i określają odpowiednio dopełnienie RSA PKCS#1v2 OAEP i losowe dopełnienie RSA PKCS#1 v1.5. PaddingMode::RSA_PSS
i PaddingMode::RSA_PKCS1_1_5_SIGN
są używane tylko dla kluczy podpisywania/weryfikacji RSA i określają odpowiednio dopełnienie PSS RSA PKCS#1v2 i dopełnienie deterministyczne RSA PKCS#1 v1.5.
PaddingMode::NONE
może być używany z kluczami RSA lub AES. W przypadku kluczy AES, jeśli PaddingMode::NONE
jest używany z trybem blokowym ECB lub CBC, a dane do zaszyfrowania lub odszyfrowania nie są wielokrotnością długości bloku AES, wywołanie zakończenia kończy się niepowodzeniem z ErrorCode::INVALID_INPUT_LENGTH
.
PaddingMode::PKCS7
może być używany tylko z kluczami AES i tylko w trybach EBC i CBC.
Ten tag jest powtarzalny. Aby rozpocząć , w wywołaniu należy określić tryb dopełniania. Jeśli określony tryb nie jest autoryzowany dla klucza, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
Etykieta::CEL
Wersja : 1, 2, 3, 4
Powtarzalne ? Tak
Określa zestaw celów, do jakich można używać klucza.
Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:
Keymaster 3enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };Keymaster 2 i starsze wersje
typedef enum { KM_PURPOSE_ENCRYPT = 0, KM_PURPOSE_DECRYPT = 1, KM_PURPOSE_SIGN = 2, KM_PURPOSE_VERIFY = 3, } keymaster_purpose_t;
Ten znacznik jest powtarzalny; klucze mogą być generowane z wieloma wartościami, chociaż operacja ma jeden cel. Kiedy funkcja Begin jest wywoływana w celu rozpoczęcia operacji, określany jest cel operacji. Jeśli cel określony w operacji nie jest autoryzowany przez klucz, operacja kończy się niepowodzeniem z błędem ErrorCode::INCOMPATIBLE_PURPOSE
.
Etykieta::RESET_SINCE_ID_ROTATION
Wersja : 3, 4
Powtarzalne ? NIE
Określa, czy urządzenie zostało zresetowane do ustawień fabrycznych od ostatniej zmiany unikalnego identyfikatora. Używany do poświadczenia klucza.
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Etykieta::ROLLBACK_RESISTANT
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Wskazuje, że klucz jest odporny na wycofywanie zmian, co oznacza, że po usunięciu przez DeleteKey lub DeleteAllKeys klucz ma gwarancję trwałego usunięcia i bezużyteczności. Możliwe, że klucze bez tego znacznika zostaną usunięte, a następnie przywrócone z kopii zapasowej.
Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Etykieta::ROOT_OF_TRUST
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa katalog główny zaufania , czyli klucz używany podczas zweryfikowanego rozruchu w celu sprawdzenia poprawności uruchomionego systemu operacyjnego (jeśli istnieje). Ten znacznik nigdy nie jest dostarczany ani zwracany przez Keymaster w ramach kluczowych cech.
Etykieta::RSA_PUBLIC_EXPONENT
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa wartość wykładnika publicznego dla pary kluczy RSA. Znacznik ten dotyczy tylko kluczy RSA i jest niezbędny w przypadku wszystkich kluczy RSA.
Wartość jest 64-bitową liczbą całkowitą bez znaku, która spełnia wymagania wykładnika publicznego RSA. Wartość ta musi być liczbą pierwszą. Trustlety obsługują wartość 2^16+1 i mogą obsługiwać inne rozsądne wartości, w szczególności wartość 3. Jeśli nie określono żadnego wykładnika lub jeśli określony wykładnik nie jest obsługiwany, generowanie klucza nie powiedzie się z błędem ErrorCode::INVALID_ARGUMENT
.
Etykieta::UNIQUE_ID
Wersja : 3, 4
Powtarzalne ? NIE
Służy do podawania unikalnego identyfikatora w zaświadczeniu.
Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.
Etykieta::USAGE_EXPIRE_DATETIME
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa datę i godzinę wygaśnięcia klucza na potrzeby weryfikacji i odszyfrowania. Po tym czasie jakakolwiek próba użycia klucza z KeyPurpose::VERIFY lub KeyPurpose::DECRYPT podanymi na początek kończy się niepowodzeniem i wyświetleniem błędu ErrorCode::KEY_EXPIRED
.
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Etykieta::USER_AUTH_TYPE
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa typy elementów uwierzytelniających użytkownika, które mogą być używane do autoryzacji tego klucza. Kiedy Keymaster zostaje poproszony o wykonanie operacji na kluczu z tym tagiem, otrzymuje token uwierzytelniający, a pole authenticator_type
tokena musi odpowiadać wartości w tagu. Na przykład (ntoh(token.authenticator_type) & auth_type_tag_value) != 0
, gdzie ntoh
to funkcja konwertująca liczby całkowite uporządkowane przez sieć na liczby całkowite uporządkowane przez hosta, a wartość auth_type_tag_value
to wartość tego znacznika.
Wartość jest 32-bitową maską bitową zawierającą wartości z wyliczenia:
Keymaster 3enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };Keymaster 2 i starsze wersje
typedef enum { HW_AUTH_NONE = 0, HW_AUTH_PASSWORD = 1 << 0, HW_AUTH_FINGERPRINT = 1 << 1, // Additional entries should be powers of 2. HW_AUTH_ANY = UINT32_MAX, } hw_authenticator_type_t;
Etykieta::USER_SECURE_ID
Wersja : 1, 2, 3, 4
Powtarzalne ? NIE
Określa, że klucz może być używany tylko w określonym stanie bezpiecznego uwierzytelniania użytkownika. Ten tag wyklucza się wzajemnie z Tag::NO_AUTH_REQUIRED .
Wartość jest 64-bitową liczbą całkowitą określającą wartość stanu polityki uwierzytelniania, która musi znajdować się w tokenie uwierzytelniania (podanym na początku od Tag::AUTH_TOKEN ), aby autoryzować użycie klucza. Każde wywołanie rozpoczynające się od klucza z tym tagiem, które nie udostępnia tokenu uwierzytelniania lub udostępnia token uwierzytelniania bez pasującej wartości stanu zasad, kończy się niepowodzeniem.
Ten tag jest powtarzalny. Jeśli którakolwiek z podanych wartości odpowiada dowolnej wartości stanu zasad w tokenie uwierzytelniania, klucz jest autoryzowany do użycia. W przeciwnym razie operacja zakończy się niepowodzeniem z ErrorCode::KEY_USER_NOT_AUTHENTICATED
.
Etykieta::VENDOR_PATCHLEVEL
Wersja : 4
Ten znacznik określa poziom poprawki zabezpieczeń obrazu dostawcy, z którym można używać klucza. Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo. Każda próba użycia klucza z wartością Tag::VENDOR_PATCHLEVEL
inną niż aktualnie uruchomiony poziom poprawki systemowej musi spowodować, że begin()
, getKeyCharacteristics()
lub exportKey()
zwróci ErrorCode::KEY_REQUIRES_UPGRADE
. Aby uzyskać szczegółowe informacje, zobacz upgradeKey()
.
Wartość znacznika jest liczbą całkowitą w postaci YYYYMMDD, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, MM to dwucyfrowy miesiąc, a DD to dwucyfrowy dzień ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego 5 czerwca 2018 r., wartość będzie wynosić 20180605.
IKeymasterDevice HAL musi odczytać aktualny poziom poprawki dostawcy z właściwości systemowej ro.vendor.build.security_patch
i dostarczyć go do bezpiecznego środowiska przy pierwszym załadowaniu warstwy HAL (mechanizm jest zdefiniowany w implementacji). Bezpieczne środowisko nie może zaakceptować kolejnego poziomu poprawek przed następnym uruchomieniem.
Musi być wymuszane sprzętowo.