Tagi autoryzacji keymastera

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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 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 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 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 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 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 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 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 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 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 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 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 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 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 .

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 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 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.