Ta strona zawiera szczegółowe informacje pomocne osobom wdrażającym warstwy Keymaster HAL. Obejmuje każdy tag w HAL, w której wersji Keymaster ten tag jest dostępny i czy tag jest powtarzalny. Z wyjątkiem przypadków opisanych w opisach tagów, wszystkie poniższe tagi są używane podczas generowania klucza do określenia kluczowych cech.
W przypadku Keymaster 4 tagi są zdefiniowane w platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , na przykład 3.0/types.hal dla Keymaster 3 i 4.0/types.hal dla Keymaster 4. Dla Keymaster 2 i starszych, znaczniki są zdefiniowane w platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Aby zapoznać się z funkcjami, zobacz stronę Funkcje klawiatury .
Tag::ACTIVE_DATETIME
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa datę i godzinę, w której klucz staje się aktywny. Przed tym czasem każda próba użycia klucza kończy się niepowodzeniem z ErrorCode::KEY_NOT_YET_VALID .
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Tag::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 przez następujące wyliczenie:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
Keymaster 2 i wcześniejsze
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Tag::ALL_APPLICATIONS
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Zarezerwowane do wykorzystania w przyszłości.
Tag::ALLOW_WHILE_ON_BODY
Wersja : 2, 3, 4
powtarzalne ? NIE
Ten tag ma zastosowanie tylko do urządzeń Android Wear z czujnikami na ciele. W tym momencie nie oczekuje się, że jakikolwiek TEE będzie w stanie zapewnić bezpieczny dostęp do czujnika na ciele lub że czujniki na ciele są bardzo bezpieczne, więc oczekuje się, że będzie to funkcja wymuszona wyłącznie przez oprogramowanie.
Tag::ALL_USERS
Wersja : 3, 4
powtarzalne ? NIE
Zarezerwowane do wykorzystania w przyszłości.
Tag::APPLICATION_DATA
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
W przypadku podania do generateKey lub importKey ten tag określa dane, które są niezbędne podczas wszystkich zastosowań klucza. W szczególności wywołania exportKey i getKeyCharacteristics muszą zapewnić taką samą wartość parametrowi clientId , a wywołania begin muszą podać ten znacznik i te same powiązane dane jako część zestawu inParams . Jeśli nie podano poprawnych danych, funkcja zwraca ErrorCode::INVALID_KEY_BLOB .
Zawartość tego znacznika jest kryptograficznie powiązana z kluczem, co oznacza, że przeciwnik, który ma dostęp do wszystkich chronionych tajemnic światowych, ale nie ma dostępu do zawartości znacznika, nie może mieć możliwości odszyfrowania klucza bez brutalnego użycia znacznika zawartość, której aplikacje mogą zapobiec, określając zawartość o wystarczająco wysokiej entropii.
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::APPLICATION_ID
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
W przypadku podania do generateKey lub importKey ten tag określa dane, które są niezbędne podczas wszystkich zastosowań klucza. W szczególności wywołania exportKey i getKeyCharacteristics muszą zawierać tę samą wartość w parametrze clientId , a wywołania begin muszą podać ten znacznik i te same powiązane dane jako część zestawu inParams . Jeśli nie podano poprawnych danych, funkcja zwraca ErrorCode::INVALID_KEY_BLOB .
Zawartość tego znacznika jest powiązana z kluczem kryptograficznie , co oznacza, że przeciwnik, który ma dostęp do wszystkich chronionych tajemnic światowych — ale nie ma dostępu do treści znacznika — nie może odszyfrować klucza (bez brutalnego wymuszenia zawartości znacznika ).
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::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 aktualizowania i określania danych, które nie są szyfrowane/odszyfrowywane, ale są używane do obliczania znacznika GCM.
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_APPLICATION_ID
Wersja : 3, 4
powtarzalne ? NIE
Służy do identyfikacji zestawu możliwych aplikacji, z których jedna zainicjowała kluczową atestację.
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_CHALLENGE
Wersja : 3, 4
powtarzalne ? NIE
Używane do rzucania wyzwania w zaświadczeniu.
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_BRAND
Wersja : 3, 4
powtarzalne ? NIE
Zawiera markę urządzenia zwróconą przez Build.BRAND w systemie Android. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_DEVICE
Wersja : 3, 4
powtarzalne ? NIE
Zawiera nazwę urządzenia zwróconą przez Build.DEVICE w systemie Android. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_IMEI
Wersja : 3, 4
powtarzalne ? Tak
Zapewnia numery IMEI dla wszystkich radiotelefonów w urządzeniu. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_MANUFACTURER
Wersja : 3, 4
powtarzalne ? NIE
Zawiera nazwę producenta urządzenia zwróconą przez Build.MANUFACTURER w systemie Android. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::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 poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_MODEL
Wersja : 3, 4
powtarzalne ? NIE
Zawiera nazwę modelu urządzenia zwróconą przez Build.MODEL w systemie Android. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_PRODUCT
Wersja : 3, 4
powtarzalne ? NIE
Zawiera nazwę produktu urządzenia zwróconą przez Build.PRODUCT w systemie Android. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::ATTESTATION_ID_SERIAL
Wersja : 3, 4
powtarzalne ? NIE
Podaje numer seryjny urządzenia. To pole jest ustawiane tylko w przypadku żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza, które zawiera ten znacznik, zakończy się niepowodzeniem z błędem ErrorCode::CANNOT_ATTEST_IDS .
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::AUTH_TIMEOUT
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa czas w sekundach, przez jaki klucz jest autoryzowany do użycia, po uwierzytelnieniu. Jeśli Tag::USER_SECURE_ID jest obecny, a tego tagu nie ma, klucz wymaga uwierzytelnienia przy każdym użyciu (szczegółowe informacje na temat 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 za pomocą metody uwierzytelnienia określonej przez Tag::USER_AUTH_TYPE , kiedy klucz może być użyty.
Tag::AUTH_TOKEN
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Zapewnia token uwierzytelniania , aby rozpocząć , zaktualizować lub zakończyć , aby udowodnić uwierzytelnienie użytkownika dla operacji klucza, która tego wymaga (klucz ma Tag::USER_SECURE_ID ).
Wartość jest obiektem blob, który zawiera strukturę hw_auth_token_t .
Tag::BLOB_USAGE_REQUIREMENTS
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa warunki środowiska systemowego niezbędne do użycia wygenerowanego klucza.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 i wcześniejsze
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żytku w określonych warunkach. Musi zostać zwrócony z kluczowymi cechami z generateKey i getKeyCharacteristics . Jeśli wywołujący określi Tag::BLOB_USAGE_REQUIREMENTS z wartością KeyBlobUsageRequirements::STANDALONE trustlet zwróci kluczowy obiekt blob, którego można używać bez obsługi systemu plików. Ma to krytyczne znaczenie w przypadku urządzeń z zaszyfrowanymi dyskami, w przypadku których system plików może być niedostępny dopiero po użyciu klucza Keymaster do odszyfrowania dysku.
Tag::BLOCK_MODE
Wersja : 1, 2, 3, 4
powtarzalne ? Tak
Określa tryby szyfrowania blokowego, z którymi może być używany klucz. Ten tag dotyczy tylko kluczy AES.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
Keymaster 2 i wcześniejsze
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 dla operacji na klawiszach AES określ tryb w argumencie additionalParams metody begin . Jeśli określony tryb nie znajduje się w trybach skojarzonych z kluczem, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::BOOT_PATCHLEVEL
Wersja : 4
Tag::BOOT_PATCHLEVEL określa poziom poprawki bezpieczeństwa obrazu rozruchowego (jądra), z którym można użyć klucza. Ten znacznik nigdy nie jest wysyłany do głównego TA, ale jest dodawany do listy autoryzacji wymuszonych sprzętowo przez TA. Każda próba użycia klucza z wartością Tag::BOOT_PATCHLEVEL inną niż bieżący poziom poprawki systemowej powoduje, że metody begin() , getKeyCharacteristics() lub exportKey() zwracają ErrorCode::KEY_REQUIRES_UPGRADE . Zobacz upgradeKey() po szczegóły.
Wartością znacznika jest liczba całkowita w postaci RRRRMMDD, gdzie RRRR 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 systemem Android, którego ostatnia aktualizacja miała miejsce 5 czerwca 2018 r., wartością będzie 20180605. Jeśli dzień nie jest znany, można wstawić 00.
Podczas każdego rozruchu program ładujący musi zapewnić poziom poprawki obrazu rozruchowego w bezpiecznym środowisku (mechanizm jest zdefiniowany przez implementację).
Musi być wymuszany sprzętowo.
Tag::BOOTLOADER_ONLY
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa, że tylko program ładujący może używać klucza.
Ten znacznik jest logiczny, 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 z ErrorCode::INVALID_KEY_BLOB .
Tag::CALLER_NONCE
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa, że obiekt wywołujący może podać wartość jednorazową dla operacji niewymagających.
Ten znacznik jest logiczny, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Ten tag jest używany tylko dla kluczy AES i ma znaczenie tylko dla trybów bloków CBC, CTR i GCM. Jeśli tag nie jest obecny, implementacje powinny odrzucać wszelkie operacje, które dostarczają Tag::NONCE rozpoczynające się od ErrorCode::CALLER_NONCE_PROHIBITED .
Tag::CREATION_DATETIME
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa datę i godzinę utworzenia klucza, w milisekundach od 1 stycznia 1970 r. Ten znacznik jest opcjonalny i służy wyłącznie do celów informacyjnych.
Tag::SPIS
Wersja : 1, 2, 3, 4
powtarzalne ? Tak
Określa algorytmy skrótu, które mogą być używane z kluczem do wykonywania operacji podpisywania i weryfikacji. Ten znacznik dotyczy kluczy RSA, ECDSA i HMAC.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum 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 wcześniejsze
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 tag jest powtarzalny. W przypadku operacji podpisywania i weryfikacji podaj skrót w argumencie additionalParams metody begin . Jeśli określonego skrótu nie ma w skrótach skojarzonych z kluczem, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_DIGEST .
Tag::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 Keymaster 2 wprowadzono wyraźny sposób określania krzywych. Żądania generowania klucza EC mogą mieć Tag::EC_CURVE , Tag::KEY_SIZE lub oba.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Keymaster 2 i wcześniejsze
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Jeśli żądanie generowania zawiera tylko Tag::KEY_SIZE , powróć do logiki Keymaster 1, wybierając odpowiednią krzywą NIST.
Jeśli żądanie zawiera tylko Tag::EC_CURVE , użyj określonej krzywej. W Keymaster 3 i późniejszych krzywe są definiowane w EcCurve . Dla Keymaster 2 i wcześniejszych krzywe są zdefiniowane w keymaster_ec_curve_t .
Jeśli żądanie zawiera oba elementy, 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 .
Tag::INCLUDE_UNIQUE_ID
Wersja : 2, 3, 4
powtarzalne ? NIE
Ten tag jest określany podczas generowania klucza, aby wskazać, że certyfikat zaświadczający dla wygenerowanego klucza powinien zawierać identyfikator unikatowy dla urządzenia w zakresie aplikacji i ograniczony czasowo, zgodnie z parametrem Tag::UNIQUE_ID .
Ten znacznik jest logiczny, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Tag::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.
Tag::MAC_LENGTH
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Podaje żądaną długość znacznika uwierzytelniania MAC lub GCM w bitach.
Wartość to długość MAC w bitach. Jest to wielokrotność 8 i co najmniej tak duża, jak wartość Tag::MIN_MAC_LENGTH powiązana z kluczem.
Tag::MAX_USES_PER_BOOT
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa maksymalną liczbę przypadków użycia klucza między ponownymi uruchomieniami systemu. Jest to kolejny mechanizm ograniczania szybkości użycia klucza.
Wartość jest 32-bitową liczbą całkowitą reprezentującą użycie na rozruch.
Gdy klucz z tym znacznikiem jest używany w operacji, licznik związany z kluczem powinien zostać zwiększony podczas wywołania begin . Gdy licznik klucza przekroczy tę wartość, wszystkie kolejne próby użycia klucza kończą się niepowodzeniem z ErrorCode::MAX_OPS_EXCEEDED do momentu ponownego uruchomienia urządzenia. Oznacza to, że trustlet przechowuje tabelę liczników użycia dla kluczy z tym znacznikiem. Ponieważ pamięć Keymaster jest często ograniczona, ta tabela może mieć ustalony maksymalny rozmiar, a Keymaster może zakończyć się niepowodzeniem operacji, które próbują 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 .
Tag::MIN_MAC_LENGTH
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Ten znacznik określa minimalną długość adresu MAC, którego można zażądać lub zweryfikować za pomocą tego klucza dla kluczy HMAC i kluczy AES obsługujących tryb GCM.
Ta wartość to minimalna długość adresu MAC w bitach. Jest to wielokrotność 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.
Tag::MIN_SECONDS_BETWEEN_OPS
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa minimalny czas, jaki upływa między dozwolonymi operacjami przy użyciu klucza. Można to wykorzystać do ograniczenia szybkości użycia kluczy w kontekstach, w których nieograniczone użycie może umożliwić ataki siłowe.
Wartość jest 32-bitową liczbą całkowitą reprezentującą sekundy między dozwolonymi operacjami.
Gdy klawisz z tym znacznikiem jest używany w operacji, uruchom stoper podczas zakończenia lub przerwania połączenia. Każde wywołanie rozpoczęcia , które zostanie odebrane przed licznikiem czasu, wskazuje, że interwał określony przez Tag::MIN_SECONDS_BETWEEN_OPS upłynął, kończy się niepowodzeniem z ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Oznacza to, że trustlet przechowuje tabelę liczników użycia dla kluczy z tym znacznikiem. Ponieważ pamięć Keymaster jest często ograniczona, ta tabela może mieć ustalony maksymalny rozmiar, a Keymaster może zakończyć się niepowodzeniem operacji, które próbują 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 na stole, gdy wygasną minimalne interwały użycia klucza. Jeśli operacja nie powiedzie się, ponieważ tabela jest pełna, Keymaster zwraca ErrorCode::TOO_MANY_OPERATIONS .
Tag::NO_AUTH_REQUIRED
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa, że do użycia tego klucza nie jest wymagane uwierzytelnianie. Ten tag wyklucza się wzajemnie z Tag::USER_SECURE_ID .
Ten znacznik jest logiczny, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Tag::NIE
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Dostarcza lub zwraca wartość nonce lub wektor inicjujący (IV) dla szyfrowania lub odszyfrowywania AES GCM, CBC lub CTR. Ten tag jest dostarczany, aby rozpocząć się podczas operacji szyfrowania i deszyfrowania. Jest dostarczany tylko na początek , jeśli klucz ma Tag::CALLER_NONCE . Jeśli nie zostanie podany, odpowiedni identyfikator jednorazowy lub IV zostanie losowo wygenerowany przez Keymaster i zwrócony od początku.
Wartość to blob, tablica bajtów o dowolnej długości. Dozwolone długości zależą od trybu: Jednostki GCM mają długość 12 bajtów; CBC i CTR IV mają długość 16 bajtów.
Tag::POCHODZENIE
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa miejsce utworzenia klucza, jeśli jest znane. Ten znacznik nie może być określony podczas generowania lub importowania klucza i musi zostać dodany do charakterystyki klucza przez trustlet.
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 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 wartości, ale także od tego, czy znajduje się 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 w bezpiecznym sprzęcie i jest trwale powiązany sprzętowo. Jeśli na liście wymuszanej programowo, klucz został wygenerowany w SoftKeymaster i nie jest powiązany sprzętowo.
DERIVED wskazuje, że klucz został wyprowadzony wewnątrz 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 związany ze sprzętem, chociaż mogą istnieć kopie poza bezpiecznym sprzętem. Jeśli na liście wymusza oprogramowanie, klucz został zaimportowany do SoftKeymaster i nie jest związany ze sprzętem.
UNKNOWN powinien pojawić się tylko na liście wymuszonej sprzętowo. Wskazuje, że klucz jest powiązany sprzętowo, ale nie wiadomo, czy klucz został pierwotnie wygenerowany w bezpiecznym sprzęcie, czy też został zaimportowany. Dzieje się tak tylko wtedy, gdy sprzęt keymaster0 jest używany do emulacji usług keymaster1.
Tag::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 każda próba użycia klucza z KeyPurpose::SIGN lub KeyPurpose::ENCRYPT podana do rozpoczęcia kończy się niepowodzeniem z ErrorCode::KEY_EXPIRED .
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Tag::OS_PATCHLEVEL
Wersja : 2, 3, 4
powtarzalne ? NIE
Ten znacznik nigdy nie jest wysyłany do głównego TA, ale jest dodawany do listy autoryzacji wymuszonych sprzętowo przez TA.
Wartością znacznika jest liczba całkowita w postaci RRRRMM, gdzie RRRR 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 zaktualizowanym w grudniu 2015 r. wartość wyniosłaby 201512.
Klawisze, które mają inny poziom patcha niż aktualny poziom patcha, nie są użyteczne. Próba użycia takiego klucza powoduje, że metody begin , getKeyCharacteristics lub exportKey zwracają błąd ErrorCode::KEY_REQUIRES_UPGRADE . Zobacz Powiązanie wersji , aby uzyskać więcej informacji.
Tag::OS_VERSION
Wersja : 2, 3, 4
powtarzalne ? NIE
Ten znacznik nigdy nie jest wysyłany do głównego TA, ale jest dodawany do listy autoryzacji wymuszonych sprzętowo przez TA.
Wartością znacznika jest liczba całkowita w postaci MMmmss, gdzie MM to numer wersji głównej, mm to numer wersji pomocniczej, a ss to numer wersji podrzędnej. Na przykład dla klucza wygenerowanego w systemie Android w wersji 4.0.3 wartość to 040003.
Tag::PADDING
Wersja : 1, 2, 3, 4
powtarzalne ? Tak
Określa tryby dopełnienia, które mogą być używane z klawiszem. Ten znacznik dotyczy kluczy RSA i AES.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum 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 wcześniejsze
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 dla kluczy szyfrowania/odszyfrowywania 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 do kluczy podpisywania/weryfikacji RSA i określają odpowiednio dopełnienie RSA PKCS#1v2 PSS 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ą rozmiaru 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 z trybami EBC i CBC.
Ten tag jest powtarzalny. Aby rozpocząć , w wywołaniu należy określić tryb uzupełniania. Jeśli określony tryb nie jest autoryzowany dla klucza, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::CEL
Wersja : 1, 2, 3, 4
powtarzalne ? Tak
Określa zestaw celów, do których może być używany klucz.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3
enum 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 wcześniejsze
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Ten tag jest powtarzalny; klucze mogą być generowane z wieloma wartościami, chociaż operacja ma jeden cel. Gdy funkcja begin jest wywoływana w celu rozpoczęcia operacji, określany jest cel operacji. Jeśli cel określony dla operacji nie jest autoryzowany przez klucz, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_PURPOSE .
Znacznik::RESET_SINCE_ID_ROTATION
Wersja : 3, 4
powtarzalne ? NIE
Określa, czy urządzenie zostało zresetowane do ustawień fabrycznych od czasu ostatniej rotacji unikalnego identyfikatora. Używany do atestacji klucza.
Ten znacznik jest logiczny, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Tag::ROLLBACK_RESISTANT
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Wskazuje, że klucz jest odporny na wycofywanie, co oznacza, że po usunięciu przez deleteKey lub deleteAllKeys klucz jest gwarantowany jako trwale usunięty i bezużyteczny. Możliwe, że klucze bez tego znacznika mogą zostać usunięte, a następnie przywrócone z kopii zapasowej.
Ten znacznik jest logiczny, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).
Tag::ROOT_OF_TRUST
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa root of trust , klucz używany przez zweryfikowany rozruch do sprawdzania poprawności uruchomionego systemu operacyjnego (jeśli istnieje). Ten znacznik nigdy nie jest dostarczany ani zwracany przez firmę Keymaster w kluczowych cechach.
Tag::RSA_PUBLIC_EXPONENT
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa wartość publicznego wykładnika dla pary kluczy RSA. Ten znacznik dotyczy tylko kluczy RSA i jest niezbędny dla wszystkich kluczy RSA.
Wartość jest 64-bitową liczbą całkowitą bez znaku, która spełnia wymagania publicznego wykładnika RSA. Ta wartość musi być liczbą pierwszą. Trustlets obsługują wartość 2^16+1 i mogą obsługiwać inne rozsądne wartości, w szczególności wartość 3. Jeśli żaden wykładnik nie zostanie określony lub jeśli określony wykładnik nie jest obsługiwany, generowanie klucza kończy się niepowodzeniem z ErrorCode::INVALID_ARGUMENT .
Tag::UNIQUE_ID
Wersja : 3, 4
powtarzalne ? NIE
Służy do podania unikalnego identyfikatora w poświadczeniu.
Wartość to blob, tablica bajtów o dowolnej długości.
Tag::USAGE_EXPIRE_DATETIME
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa datę i godzinę wygaśnięcia klucza w celu weryfikacji i odszyfrowania. Po tym czasie każda próba użycia klucza z KeyPurpose::VERIFY lub KeyPurpose::DECRYPT podana do rozpoczęcia kończy się niepowodzeniem z ErrorCode::KEY_EXPIRED .
Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.
Tag::USER_AUTH_TYPE
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa typy uwierzytelniaczy użytkowników, których można użyć do autoryzacji tego klucza. Kiedy Keymaster jest proszony o wykonanie operacji na kluczu z tym znacznikiem, otrzymuje token uwierzytelniania, a pole authenticator_type tokena musi być zgodne z wartością w znaczniku. Na przykład (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , gdzie ntoh jest funkcją, która konwertuje liczby całkowite uporządkowane w sieci na liczby całkowite uporządkowane przez hosta, a auth_type_tag_value jest wartością tego znacznika.
Wartość to 32-bitowa maska bitowa liczb całkowitych wartości z wyliczenia:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 i wcześniejsze
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;
Tag::USER_SECURE_ID
Wersja : 1, 2, 3, 4
powtarzalne ? NIE
Określa, że klucz może być używany tylko w określonym bezpiecznym stanie uwierzytelniania użytkownika. Ten tag wyklucza się wzajemnie z Tag::NO_AUTH_REQUIRED .
Wartość to 64-bitowa liczba całkowita określająca wartość stanu zasad uwierzytelniania, która musi być obecna w tokenie uwierzytelniania (podany na początku Tag::AUTH_TOKEN ), aby autoryzować użycie klucza. Każde wywołanie rozpoczynające się od klucza z tym tagiem, które nie dostarcza tokenu uwierzytelniania lub dostarcza token uwierzytelniania bez pasującej wartości stanu zasad, kończy się niepowodzeniem.
Ten tag jest powtarzalny. Jeśli dowolna z podanych wartości pasuje do 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 .
Tag::VENDOR_PATCHLEVEL
Wersja : 4
Ten znacznik określa poziom poprawki zabezpieczeń obrazu dostawcy, z którym może być używany klucz. Ten znacznik nigdy nie jest wysyłany do głównego TA, ale jest dodawany do listy autoryzacji wymuszonych sprzętowo przez TA. Każda próba użycia klucza z wartością Tag::VENDOR_PATCHLEVEL inną niż aktualnie działający poziom poprawki systemowej musi spowodować, że metody begin() , getKeyCharacteristics() lub exportKey() zwrócą ErrorCode::KEY_REQUIRES_UPGRADE . Zobacz upgradeKey() po szczegóły.
Wartością znacznika jest liczba całkowita w postaci RRRRMMDD, gdzie RRRR 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 systemem Android, którego ostatnia aktualizacja miała miejsce 5 czerwca 2018 r., wartością będzie 20180605.
IKeymasterDevice HAL musi odczytać aktualny poziom poprawek dostawcy z właściwości systemowej ro.vendor.build.security_patch i dostarczyć go do bezpiecznego środowiska podczas pierwszego ładowania warstwy HAL (mechanizm jest zdefiniowany w implementacji). Bezpieczne środowisko nie może akceptować kolejnego poziomu poprawek aż do następnego rozruchu.
Musi być wymuszany sprzętowo.