Ta strona zawiera szczegółowe informacje ułatwiające wdrażanie licencji HAL Keymaster. Obejmuje każdy tag w HAL, wersję Keymastera, w której 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 w celu 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. W przypadku Keymaster 2 i niższych, tagi są zdefiniowane w platform/hardware/libhardware/include/hardware/keymaster_defs.h
.
Aby zapoznać się z funkcjami, zobacz stronę Keymaster Functions .
Tag::ACTIVE_DATETIME
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa datę i godzinę, w której klucz staje się aktywny. Do tego czasu 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 roku.
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 3enum 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 wyposażonych w czujniki 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 czysto programowa.
Tag::ALL_USERS
Wersja : 3, 4
Powtarzalne ? Nie
Zarezerwowane do wykorzystania w przyszłości.
Tag::APPLICATION_DANE
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ą dostarczać tę samą wartość parametru clientId
, a wywołania rozpoczynające muszą dostarczać ten znacznik i te same powiązane dane jako część zestawu inParams
. Jeśli nie podano prawidłowych 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 bezpiecznych sekretów świata, ale nie ma dostępu do zawartości znacznika, nie może odszyfrować klucza bez użycia siły zawartość, której aplikacje mogą zapobiec, określając zawartość o wystarczająco wysokiej entropii.
Wartość jest obiektem blob, tablicą 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ą dostarczać tę samą wartość w parametrze clientId
, a wywołania rozpoczynające muszą dostarczać ten znacznik i te same powiązane dane jako część zestawu inParams
. Jeśli nie podano prawidłowych danych, funkcja zwraca ErrorCode::INVALID_KEY_BLOB
.
Zawartość tego znacznika jest powiązana z kluczem kryptograficznie , co oznacza, że jest to przeciwnik, który może uzyskać dostęp do wszystkich bezpiecznych sekretów świata — ale nie ma dostępu do zawartości znacznika — nie może odszyfrować klucza (bez brutalnego wymuszania zawartości znacznika ).
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::DANE ZWIĄZANE
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Zapewnia „powiązane dane” do szyfrowania lub deszyfrowania AES-GCM. Ten tag służy do aktualizowania i określania danych, które nie są zaszyfrowane/odszyfrowane, ale są używane do obliczania tagu GCM.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_APPLICATION_ID
Wersja : 3, 4
Powtarzalne ? Nie
Służy do identyfikacji zestawu możliwych zastosowań, z których jedna zainicjowała kluczową atestację.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_CHALLENGE
Wersja : 3, 4
Powtarzalne ? Nie
Służy do zapewnienia wyzwania w atestacji.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_ID_BRAND
Wersja : 3, 4
Powtarzalne ? Nie
Zawiera nazwę marki urządzenia zwróconą przez Build.BRAND
w systemie Android. To pole jest ustawiane tylko podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_ID_DEVICE
Wersja : 3, 4
Powtarzalne ? Nie
Udostępnia nazwę urządzenia urządzenia zwróconą przez Build.DEVICE
w systemie Android. To pole jest ustawiane tylko podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_ID_IMEI
Wersja : 3, 4
Powtarzalne ? TAk
Udostępnia numery IMEI dla wszystkich radiotelefonów w urządzeniu. To pole jest ustawiane tylko podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą 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 podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::ATTESTATION_ID_MEID
Wersja : 3, 4
Powtarzalne ? TAk
Udostępnia identyfikatory MEID dla wszystkich radiotelefonów w urządzeniu. To pole zostanie ustawione tylko podczas żądania poświadczenia identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą 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 podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą 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 podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą 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 podczas żądania atestacji identyfikatorów urządzenia.
Jeśli urządzenie nie obsługuje poświadczania identyfikatorów (lub destroyAttestationIds()
, a urządzenie nie może już poświadczać swoich identyfikatorów), każde żądanie poświadczenia klucza zawierające ten tag kończy się niepowodzeniem z ErrorCode::CANNOT_ATTEST_IDS
.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości.
Tag::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 jest, klucz wymaga uwierzytelnienia przy każdym użyciu (zobacz początek , aby uzyskać szczegółowe informacje na temat przepływu uwierzytelniania na operację).
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ą uwierzytelniania określoną przez Tag::USER_AUTH_TYPE , w którym można użyć klucza.
Tag::AUTH_TOKEN
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Udostępnia token uwierzytelniania do begin , update lub finish , aby potwierdzić uwierzytelnianie użytkownika dla operacji z kluczem, która tego wymaga (klucz ma Tag::USER_SECURE_ID ).
Wartość jest obiektem blob zawierającym strukturę hw_auth_token_t
.
Tag::BLOB_USAGE_REQUIREMENTS
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa niezbędne warunki środowiska systemowego dla wygenerowanego klucza, który ma zostać użyty.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3enum 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 tag można określić podczas generowania klucza, aby wymagać, aby klucz mógł być używany 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
STANDALONE, trustlet zwróci kluczowy obiekt BLOB, którego można użyć bez obsługi systemu plików. Ma to krytyczne 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.
Tag::BLOCK_MODE
Wersja : 1, 2, 3, 4
Powtarzalne ? TAk
Określa tryby szyfrowania blokowego, w których można użyć klucza. Ten tag dotyczy tylko kluczy AES.
Możliwe wartości są zdefiniowane przez następujące wyliczenie:
Keymaster 3enum 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
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że być używany klucz. Znacznik ten nigdy nie jest wysyłany do agenta administratora klucza, ale jest dodawany do listy autoryzacji wymuszanej sprzętowo przez agenta agenta. Każda próba użycia klucza z wartością Tag::BOOT_PATCHLEVEL
inną niż aktualnie działający poziom poprawek systemowych powoduje, że begin()
, getKeyCharacteristics()
lub exportKey()
zwracają ErrorCode::KEY_REQUIRES_UPGRADE
. Zobacz upgradeKey()
, aby uzyskać szczegółowe informacje.
Wartość znacznika jest liczbą całkowitą 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 w przypadku klucza wygenerowanego na urządzeniu z systemem Android 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 bootloader musi dostarczyć poziom poprawek obrazu rozruchowego do bezpiecznego środowiska (mechanizm jest zdefiniowany przez implementację).
Musi być wymuszone sprzętowo.
Tag::BOOTLOADER_ONLY
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa, że tylko bootloader może używać klucza.
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag nie jest obecny).
Każda próba użycia klucza z Tag::BOOTLOADER_ONLY
z systemu Android kończy się niepowodzeniem z błędem ErrorCode::INVALID_KEY_BLOB
.
Tag::CALLER_NONCE
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa, że obiekt wywołujący może zapewnić jednorazową wartość dla operacji jednorazowych wymagających.
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag nie jest obecny).
Ten znacznik jest używany tylko dla kluczy AES i dotyczy tylko trybów blokowych CBC, CTR i GCM. Jeśli tag nie jest obecny, implementacje powinny odrzucać każdą operację, która zapewnia Tag::NONCE , zaczynając 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. Ten znacznik jest opcjonalny i ma charakter wyłącznie informacyjny.
Tag::PRZEGLĄD
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 tag dotyczy kluczy RSA, ECDSA i HMAC.
Możliwe wartości są zdefiniowane przez 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 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 określ skrót w argumencie additionalParams
begin . Jeśli określonego skrótu nie ma w skrótach skojarzonych z kluczem, operacja kończy się niepowodzeniem z komunikatem 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ść, posuwając się naprzód, 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 przez 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 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 przypadku Keymaster 3 i nowszych 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
.
Tag::INCLUDE_UNIQUE_ID
Wersja : 2, 3, 4
Powtarzalne ? Nie
Ten tag jest określany podczas generowania klucza, aby wskazać, że certyfikat atestacji dla wygenerowanego klucza powinien zawierać unikalny identyfikator urządzenia ograniczony do aplikacji i ograniczony czasowo, zgodnie z tagiem Tag::UNIQUE_ID .
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag 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 klucza tajnego.
Tag:: MAC_DŁUGOŚĆ
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Podaje żądaną długość tagu 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 skojarzona z kluczem.
Tag::MAX_USES_PER_BOOT
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa maksymalną liczbę razy, które klucz może być używany między ponownymi uruchomieniami systemu. Jest to kolejny mechanizm ograniczania wykorzystania 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 skojarzony z kluczem powinien zostać zwiększony podczas wywołania początkowego . Gdy licznik kluczy 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 tablicę liczników użycia kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, ta tabela może mieć ustalony maksymalny rozmiar, a Keymaster może zawieść operacje, 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 tag określa minimalną długość adresu MAC, której można zażądać lub zweryfikować za pomocą tego klucza w przypadku kluczy HMAC i kluczy AES obsługujących tryb GCM.
Ta wartość to minimalna długość 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 typu brute force.
Wartość jest 32-bitową liczbą całkowitą reprezentującą sekundy między dozwolonymi operacjami.
Gdy klucz z tym znacznikiem jest używany w operacji, uruchom licznik czasu podczas zakończenia lub przerwania połączenia. Każde wywołanie rozpoczęcia , które zostanie odebrane przed licznikiem czasu wskazuje, że upłynął interwał określony przez Tag::MIN_SECONDS_BETWEEN_OPS
, który kończy się niepowodzeniem z ErrorCode::KEY_RATE_LIMIT_EXCEEDED
. Oznacza to, że trustlet przechowuje tablicę liczników użycia kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, ta tabela może mieć ustalony maksymalny rozmiar, a Keymaster może zawieść operacje, które próbują użyć kluczy z tym znacznikiem, gdy tabela jest pełna. Tabela musi pomieścić co najmniej 32 używane klucze i agresywnie ponownie wykorzystywać gniazda tabeli po wygaśnięciu minimalnych interwałów 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 korzystania z tego klucza nie jest wymagane uwierzytelnianie. Ten tag wyklucza się wzajemnie z tagiem::USER_SECURE_ID .
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag nie jest obecny).
Tag::NIE!
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Zapewnia lub zwraca wartość jednorazową lub wektor inicjujący (IV) dla szyfrowania lub deszyfrowania AES GCM, CBC lub CTR. Ten tag jest dostarczany, aby rozpocząć podczas operacji szyfrowania i odszyfrowywania. Jest dostarczany tylko wtedy, gdy klucz ma Tag::CALLER_NONCE . Jeśli nie zostanie podany, odpowiedni numer jednorazowy lub IV zostanie losowo wygenerowany przez Keymaster i zwrócony od początku.
Wartość jest obiektem blob, tablicą bajtów o dowolnej długości. Dozwolone długości zależą od trybu: nonces 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, gdzie został utworzony klucz, jeśli jest znany. Ten znacznik nie może być określony podczas generowania lub importowania klucza i musi zostać dodany do kluczowych cech przez trustlet.
Keymaster 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 wcześniejsze
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ę ona na liście cech wymuszanych sprzętowo, czy programowo.
GENERATED
wskazuje, że Keymaster wygenerował klucz. Jeśli znajduje się na liście wymuszonych sprzętowo, klucz został wygenerowany na bezpiecznym sprzęcie i jest trwale powiązany sprzętowo. Jeśli znajduje się na liście wymuszonych programowo, klucz został wygenerowany w programie SoftKeymaster i nie jest powiązany sprzętowo.
DERIVED
wskazuje, że klucz został wyprowadzony wewnątrz Keymastera. Prawdopodobnie istnieje poza urządzeniem.
IMPORTED
wskazuje, że klucz został wygenerowany poza programem Keymaster i zaimportowany do programu Keymaster. Jeśli znajduje się na liście urządzeń wymuszonych, jest trwale powiązany ze sprzętem, chociaż mogą istnieć kopie poza bezpiecznym sprzętem. Jeśli znajduje się na liście wymuszeń programowych, klucz został zaimportowany do SoftKeymaster i nie jest powiązany sprzętowo.
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 na bezpiecznym sprzęcie, czy 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 dostarczonych 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 roku.
Tag::OS_PATCHLEVEL
Wersja : 2, 3, 4
Powtarzalne ? Nie
Znacznik ten nigdy nie jest wysyłany do agenta administratora klucza, ale jest dodawany do listy autoryzacji wymuszanej sprzętowo przez agenta agenta.
Wartość znacznika jest liczbą całkowitą w postaci RRRRMM, gdzie RRRR to czterocyfrowy rok ostatniej aktualizacji, a MM to dwucyfrowy miesiąc ostatniej aktualizacji. Na przykład w przypadku klucza wygenerowanego na urządzeniu z systemem Android, który został ostatnio zaktualizowany w grudniu 2015 r., wartość będzie wynosić 201512.
Klucze, które mają inny poziom poprawek niż obecny, nie nadają się do użytku. Próba użycia takiego klucza powoduje, że begin , getKeyCharacteristics lub exportKey zwraca ErrorCode::KEY_REQUIRES_UPGRADE
. Zobacz Wiązanie wersji , aby uzyskać więcej informacji.
Tag::OS_VERSION
Wersja : 2, 3, 4
Powtarzalne ? Nie
Znacznik ten nigdy nie jest wysyłany do agenta administratora klucza, ale jest dodawany do listy autoryzacji wymuszanej sprzętowo przez agenta agenta.
Wartość znacznika jest liczbą całkowitą w postaci MMmmss, gdzie MM to główny numer wersji, mm to podrzędny numer wersji, a ss to podrzędny numer wersji. Na przykład dla klucza wygenerowanego w systemie Android w wersji 4.0.3 wartość będzie wynosić 040003.
Tag::WYPEŁNIENIE
Wersja : 1, 2, 3, 4
Powtarzalne ? TAk
Określa tryby dopełnienia, które mogą być używane z klawiszem. Ten tag dotyczy kluczy RSA i AES.
Możliwe wartości są zdefiniowane przez 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 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 RSA PKCS#1v2 OAEP i randomizowane 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 RSA PKCS#1v2 PSS i deterministyczne dopełnienie 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 ECB 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
.
Tag::CEL
Wersja : 1, 2, 3, 4
Powtarzalne ? TAk
Określa zestaw celów, do których można użyć klucza.
Możliwe wartości są zdefiniowane przez 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 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
.
Tag::RESET_SINCE_ID_ROTATION
Wersja : 3, 4
Powtarzalne ? Nie
Określa, czy urządzenie zostało zresetowane do ustawień fabrycznych od ostatniej rotacji unikatowego identyfikatora. Używany do poświadczenia klucza.
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag 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 ma gwarancję, że zostanie trwale usunięty i nie będzie można go używać. Możliwe, że klucze bez tego tagu mogą zostać usunięte, a następnie przywrócone z kopii zapasowej.
Ten tag jest wartością logiczną, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag 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 tag nigdy nie jest dostarczany ani zwracany przez Keymaster w kluczowych cechach.
Tag::RSA_PUBLIC_EXPONENT
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa wartość wykładnika publicznego dla pary kluczy RSA. Ten tag 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ą. 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 wykładnika lub jeśli określony wykładnik nie jest obsługiwany, generowanie klucza kończy się niepowodzeniem z ErrorCode::INVALID_ARGUMENT
.
Tag::UNIKALNE_ID
Wersja : 3, 4
Powtarzalne ? Nie
Służy do podania unikalnego identyfikatora w poświadczeniu.
Wartość jest obiektem blob, tablicą 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 roku.
Tag::USER_AUTH_TYPE
Wersja : 1, 2, 3, 4
Powtarzalne ? Nie
Określa typy obiektów uwierzytelniających użytkownika, które mogą być używane do autoryzacji tego klucza. Gdy Keymaster zostanie poproszony o wykonanie operacji z kluczem z tym tagiem, otrzyma token uwierzytelniający, a pole tokena authenticator_type
musi być zgodne z wartością w tagu. Na przykład (ntoh(token.authenticator_type) & auth_type_tag_value) != 0
, gdzie ntoh
to funkcja, 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ść jest 32-bitową masą bitową liczb całkowitych 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 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 stanie bezpiecznego uwierzytelniania użytkownika. Ten tag wyklucza się wzajemnie z tagiem::NO_AUTH_REQUIRED .
Wartość jest 64-bitową liczbą całkowitą określającą wartość stanu zasad uwierzytelniania, która musi być obecna w tokenie uwierzytelniania (o ile zaczyna się od Tag::AUTH_TOKEN ), aby autoryzować użycie klucza. Każde wywołanie rozpoczynające się od klucza z tym tagiem, który nie zapewnia tokenu uwierzytelniania lub udostępnia token uwierzytelniania bez pasującej wartości stanu zasad, kończy się niepowodzeniem.
Ten tag jest powtarzalny. Jeśli dowolna z podanych wartości jest zgodna z dowolną 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. Znacznik ten nigdy nie jest wysyłany do agenta administratora klucza, ale jest dodawany do listy autoryzacji wymuszanej sprzętowo przez agenta agenta. Każda próba użycia klucza z wartością Tag::VENDOR_PATCHLEVEL
inną niż aktualnie działający poziom poprawek systemowych musi spowodować, że begin()
, getKeyCharacteristics()
lub exportKey()
zwróci ErrorCode::KEY_REQUIRES_UPGRADE
. Zobacz upgradeKey()
, aby uzyskać szczegółowe informacje.
Wartość znacznika jest liczbą całkowitą 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 w przypadku klucza wygenerowanego na urządzeniu z systemem Android ostatnio zaktualizowanego 5 czerwca 2018 r. wartość będzie wynosić 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 przed następnym uruchomieniem.
Musi być wymuszone sprzętowo.