Tagi autoryzacyjne Keymastera

Na tej stronie znajdują się szczegółowe informacje pomocne osobom wdrażającym warstwy HAL Keymaster. Obejmuje każdy tag w HAL, wersję Keymastera, w której dany tag jest dostępny i czy tag jest powtarzalny. Z wyjątkiem przypadków wskazanych w opisach znaczników, wszystkie poniższe znaczniki są używane podczas generowania klucza w celu określenia kluczowych cech.

W przypadku Keymaster 4 znaczniki są zdefiniowane w platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , np. 3.0/types.hal dla Keymaster 3 i 4.0/types.hal dla Keymaster 4. W przypadku Keymaster 2 i starszych wersji: tagi są zdefiniowane w platform/hardware/libhardware/include/hardware/keymaster_defs.h .

Informacje na temat funkcji można znaleźć na stronie Funkcje Keymaster .

Etykieta::ACTIVE_DATETIME

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa datę i godzinę, o której klucz staje się aktywny. Przed tym czasem każda próba użycia klucza kończy się niepowodzeniem i wyświetla komunikat ErrorCode::KEY_NOT_YET_VALID .

Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.

Etykieta::ALGORYTM

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa algorytm kryptograficzny, z którym używany jest klucz.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 3
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 i starsze wersje
typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Etykieta::ALL_APPLICATIONS

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Zarezerwowane do wykorzystania w przyszłości.

Etykieta::ALLOW_WHILE_ON_BODY

Wersja : 2, 3, 4

Powtarzalne ? NIE

Ten tag dotyczy tylko urządzeń z systemem Android Wear i czujnikami umieszczonymi na ciele. Na tym etapie nie oczekuje się, że jakikolwiek TEE będzie w stanie zapewnić bezpieczny dostęp do czujnika na ciele ani że czujniki na ciele będą bardzo bezpieczne, dlatego oczekuje się, że będzie to funkcja wymuszana wyłącznie programowo.

Etykieta::ALL_USERS

Wersja : 3, 4

Powtarzalne ? NIE

Zarezerwowane do wykorzystania w przyszłości.

Etykieta::APPLICATION_DATA

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Znacznik ten, dostarczony do generateKey lub importKey , określa dane, które są niezbędne podczas każdego użycia klucza. W szczególności wywołania funkcjiexportKey i getKeyCharacteristics muszą podawać tę samą wartość parametrowi clientId , a wywołania rozpoczynające muszą udostępniać ten znacznik i te same powiązane dane jako część zestawu inParams . Jeżeli nie zostaną podane prawidłowe dane, funkcja zwraca ErrorCode::INVALID_KEY_BLOB .

Zawartość tego tagu jest powiązana z kluczem kryptograficznie , co oznacza, że ​​przeciwnik, który ma dostęp do wszystkich tajemnic bezpiecznego świata, ale nie ma dostępu do treści tagu, nie może mieć możliwości odszyfrowania klucza bez użycia metody brute-force. zawartość, której aplikacje mogą zapobiec, określając zawartość o wystarczająco wysokiej entropii.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::APPLICATION_ID

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Znacznik ten, dostarczony do generateKey lub importKey , określa dane, które są niezbędne podczas każdego użycia klucza. W szczególności wywołania funkcjiexportKey i getKeyCharacteristics muszą podawać tę samą wartość w parametrze clientId , a wywołania rozpoczynające muszą udostępniać ten znacznik i te same powiązane dane jako część zestawu inParams . Jeżeli nie zostaną podane prawidłowe dane, funkcja zwraca ErrorCode::INVALID_KEY_BLOB .

Zawartość tego tagu jest powiązana z kluczem kryptograficznie , co oznacza, że ​​przeciwnik, który ma dostęp do wszystkich tajemnic bezpiecznego świata – ale nie ma dostępu do treści tagu – nie może odszyfrować klucza (bez brutalnego wymuszania zawartości tagu ).

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ASSOCIATED_DATA

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Zapewnia „powiązane dane” do szyfrowania lub deszyfrowania AES-GCM. Ten znacznik służy do aktualizacji i określa dane, które nie są szyfrowane/odszyfrowywane, ale są używane do obliczania znacznika GCM.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_APPLICATION_ID

Wersja : 3, 4

Powtarzalne ? NIE

Służy do identyfikacji zestawu możliwych zastosowań, dla których zainicjowano kluczową atestację.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_CHALLENGE

Wersja : 3, 4

Powtarzalne ? NIE

Używane do kwestionowania zaświadczenia.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_BRAND

Wersja : 3, 4

Powtarzalne ? NIE

Podaje nazwę marki urządzenia zwróconą przez Build.BRAND w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_DEVICE

Wersja : 3, 4

Powtarzalne ? NIE

Podaje nazwę urządzenia zwróconą przez Build.DEVICE w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_IMEI

Wersja : 3, 4

Powtarzalne ? Tak

Zapewnia numery IMEI dla wszystkich radiotelefonów w urządzeniu. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_MANUFACTURER

Wersja : 3, 4

Powtarzalne ? NIE

Podaje nazwę producenta urządzenia zwróconą przez Build.MANUFACTURER w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_MEID

Wersja : 3, 4

Powtarzalne ? Tak

Zapewnia identyfikatory MEID dla wszystkich radiotelefonów w urządzeniu. To pole zostanie ustawione tylko w przypadku żądania potwierdzenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_MODEL

Wersja : 3, 4

Powtarzalne ? NIE

Podaje nazwę modelu urządzenia zwróconą przez Build.MODEL w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_PRODUCT

Wersja : 3, 4

Powtarzalne ? NIE

Podaje nazwę produktu urządzenia zwróconą przez Build.PRODUCT w systemie Android. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::ATTESTATION_ID_SERIAL

Wersja : 3, 4

Powtarzalne ? NIE

Podaje numer seryjny urządzenia. Pole to ustawiane jest tylko w przypadku żądania zaświadczenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje zaświadczania identyfikatora (lub wcześniej wywołano destroyAttestationIds() i urządzenie nie może już zaświadczyć swoich identyfikatorów), każde żądanie zaświadczenia klucza zawierające ten znacznik kończy się niepowodzeniem i wyświetleniem ErrorCode::CANNOT_ATTEST_IDS .

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::AUTH_TIMEOUT

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa czas w sekundach, przez który klucz jest autoryzowany do użycia po uwierzytelnieniu. Jeśli Tag::USER_SECURE_ID jest obecny, a ten tag nie, wówczas klucz wymaga uwierzytelnienia przy każdym użyciu (szczegóły dotyczące przepływu uwierzytelniania na operację można znaleźć na początku ).

Wartość jest 32-bitową liczbą całkowitą określającą czas w sekundach po pomyślnym uwierzytelnieniu użytkownika określonego przez Tag::USER_SECURE_ID metodą uwierzytelnienia określoną przez Tag::USER_AUTH_TYPE , w którym można użyć klucza.

Etykieta::AUTH_TOKEN

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Zapewnia token uwierzytelniający do rozpoczęcia , aktualizacji lub zakończenia , aby udowodnić uwierzytelnienie użytkownika dla kluczowej operacji, która tego wymaga (klucz ma Tag::USER_SECURE_ID ).

Wartością jest obiekt typu blob zawierający strukturę hw_auth_token_t .

Etykieta::BLOB_USAGE_REQUIREMENTS

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa niezbędne warunki środowiska systemowego, aby wygenerowany klucz mógł zostać użyty.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 i starsze wersje
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Ten znacznik można określić podczas generowania klucza, aby wymagać, aby klucz nadawał się do użycia w określonym stanie. Musi zostać zwrócony z kluczowymi cechami z generateKey i getKeyCharacteristics . Jeśli obiekt wywołujący określi Tag::BLOB_USAGE_REQUIREMENTS z wartością KeyBlobUsageRequirements::STANDALONE zaufanie zwróci kluczowy obiekt BLOB, którego można używać bez obsługi systemu plików. Ma to kluczowe znaczenie w przypadku urządzeń z zaszyfrowanymi dyskami, gdzie system plików może nie być dostępny do czasu użycia klucza Keymaster do odszyfrowania dysku.

Etykieta::BLOCK_MODE

Wersja : 1, 2, 3, 4

Powtarzalne ? Tak

Określa tryb(y) szyfrowania blokowego, w którym można używać klucza. Ten tag dotyczy tylko kluczy AES.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 3
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 i starsze wersje
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Ten znacznik jest powtarzalny, a w przypadku operacji na kluczu AES określ tryb w additionalParams argumencie Params Begin . Jeśli określony tryb nie znajduje się w trybach skojarzonych z kluczem, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Etykieta::BOOT_PATCHLEVEL

Wersja : 4

Tag::BOOT_PATCHLEVEL określa poziom poprawki zabezpieczeń obrazu rozruchowego (jądra), z którym można używać klucza. Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo. Każda próba użycia klucza z wartością Tag::BOOT_PATCHLEVEL inną niż aktualnie uruchomiony poziom poprawki systemowej powoduje, że funkcja begin() , getKeyCharacteristics() lub exportKey() zwraca ErrorCode::KEY_REQUIRES_UPGRADE . Aby uzyskać szczegółowe informacje, zobacz upgradeKey() .

Wartość znacznika jest liczbą całkowitą w postaci YYYYMMDD, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, MM to dwucyfrowy miesiąc, a DD to dwucyfrowy dzień ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego 5 czerwca 2018 r., wartość będzie wynosić 20180605. Jeśli dzień nie jest znany, można zastąpić 00.

Podczas każdego rozruchu program ładujący musi zapewnić poziom poprawki obrazu rozruchowego w bezpiecznym środowisku (mechanizm jest zdefiniowany w implementacji).

Musi być wymuszane sprzętowo.

Etykieta::BOOTLOADER_ONLY

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa, że ​​tylko program ładujący może używać klucza.

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Każda próba użycia klucza z Tag::BOOTLOADER_ONLY z systemu Android kończy się niepowodzeniem i wyświetleniem ErrorCode::INVALID_KEY_BLOB .

Etykieta::CALLER_NONCE

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa, że ​​obiekt wywołujący może zapewnić wartość jednorazową dla operacji niewymagających.

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Ten znacznik jest używany tylko dla kluczy AES i ma zastosowanie tylko w trybach blokowych CBC, CTR i GCM. Jeśli tag nie jest obecny, implementacje powinny odrzucić każdą operację, która zapewnia Tag::NONCE na początku ErrorCode::CALLER_NONCE_PROHIBITED .

Etykieta::CREATION_DATETIME

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa datę i godzinę utworzenia klucza, w milisekundach od 1 stycznia 1970. Ten znacznik jest opcjonalny i ma wyłącznie charakter informacyjny.

Etykieta::TRAWIENIE

Wersja : 1, 2, 3, 4

Powtarzalne ? Tak

Określa algorytmy podsumowania, których można używać z kluczem do wykonywania operacji podpisywania i weryfikacji. Znacznik ten dotyczy kluczy RSA, ECDSA i HMAC.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 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 starsze wersje
typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

Ten znacznik jest powtarzalny. W przypadku operacji podpisywania i weryfikacji określ skrót w additionalParams argumencie Begin . Jeśli określonego skrótu nie ma w podsumowaniach powiązanych z kluczem, operacja kończy się niepowodzeniem z powodu ErrorCode::INCOMPATIBLE_DIGEST .

Etykieta::EC_CURVE

Wersja : 2, 3, 4

Powtarzalne ? NIE

W Keymaster 1 krzywa używana dla kluczy EC została odgadnięta na podstawie określonego rozmiaru klucza. Aby poprawić elastyczność w przyszłości, Keymaster 2 wprowadził wyraźny sposób określania krzywych. Żądania wygenerowania klucza EC mogą mieć Tag::EC_CURVE , Tag::KEY_SIZE lub oba.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 i starsze wersje
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Jeśli żądanie generacji zawiera tylko Tag::KEY_SIZE , wróć do logiki Keymaster 1, wybierając odpowiednią krzywą NIST.

Jeśli żądanie zawiera tylko Tag::EC_CURVE , użyj określonej krzywej. W przypadku Keymaster 3 i nowszych wersji krzywe są definiowane w EcCurve . W przypadku Keymaster 2 i wcześniejszych krzywe są zdefiniowane w keymaster_ec_curve_t .

Jeśli żądanie zawiera oba, użyj krzywej określonej przez Tag::EC_CURVE i sprawdź, czy określony rozmiar klucza jest odpowiedni dla tej krzywej. Jeśli nie, zwróć ErrorCode::INVALID_ARGUMENT .

Etykieta::INCLUDE_UNIQUE_ID

Wersja : 2, 3, 4

Powtarzalne ? NIE

Ten znacznik jest określany podczas generowania klucza, aby wskazać, że certyfikat zaświadczający dla wygenerowanego klucza powinien zawierać unikalny identyfikator urządzenia o zakresie aplikacji i ograniczony czasowo, zgodnie z określeniem Tag::UNIQUE_ID .

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Etykieta::KEY_SIZE

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa rozmiar klucza w bitach, mierzony w normalny sposób dla algorytmu klucza. Na przykład dla kluczy RSA Tag::KEY_SIZE określa rozmiar modułu publicznego. W przypadku kluczy AES określa długość materiału tajnego klucza.

Etykieta::MAC_LENGTH

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Podaje żądaną długość znacznika uwierzytelniającego MAC lub GCM w bitach.

Wartość to długość MAC w bitach. Jest to wielokrotność liczby 8 i co najmniej tak duża, jak wartość Tag::MIN_MAC_LENGTH powiązana z kluczem.

Etykieta::MAX_USES_PER_BOOT

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa maksymalną liczbę użyć klucza pomiędzy ponownymi uruchomieniami systemu. Jest to kolejny mechanizm ograniczający użycie klucza.

Wartość jest 32-bitową liczbą całkowitą reprezentującą użycia na rozruch.

Gdy w operacji używany jest klucz z tym znacznikiem, podczas wywołania rozpoczęcia należy zwiększyć licznik powiązany z kluczem. Po przekroczeniu tej wartości przez licznik kluczy, wszystkie kolejne próby użycia klucza kończą się niepowodzeniem z ErrorCode::MAX_OPS_EXCEEDED do czasu ponownego uruchomienia urządzenia. Oznacza to, że trustlet przechowuje tabelę użycia liczników kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, tabela ta może mieć stały maksymalny rozmiar, a operacje Keymastera mogą zakończyć się niepowodzeniem, próbując użyć kluczy z tym znacznikiem, gdy tabela jest pełna. Stół musi pomieścić co najmniej 16 kluczy. Jeśli operacja nie powiedzie się, ponieważ tabela jest pełna, Keymaster zwraca ErrorCode::TOO_MANY_OPERATIONS .

Etykieta::MIN_MAC_LENGTH

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Ten znacznik określa minimalną długość adresu MAC, o którą można poprosić lub zweryfikować za pomocą tego klucza dla kluczy HMAC i kluczy AES obsługujących tryb GCM.

Ta wartość to minimalna długość MAC w bitach. Jest to wielokrotność liczby 8. W przypadku kluczy HMAC wartość wynosi co najmniej 64. W przypadku kluczy GCM wartość wynosi co najmniej 96 i nie więcej niż 128.

Etykieta::MIN_SECONDS_BETWEEN_OPS

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa minimalny czas, jaki upływa pomiędzy dozwolonymi operacjami przy użyciu klucza. Można tego użyć do ograniczenia szybkości użycia kluczy w kontekstach, w których nieograniczone użycie może umożliwić ataki brute-force.

Wartość jest 32-bitową liczbą całkowitą reprezentującą sekundy pomiędzy dozwolonymi operacjami.

Jeśli w operacji używany jest klawisz z tym znacznikiem, należy uruchomić licznik czasu podczas kończenia lub przerywania połączenia. Każde wywołanie rozpoczęcia odebrane przed licznikiem czasu wskazuje, że upłynął interwał określony przez Tag::MIN_SECONDS_BETWEEN_OPS co kończy się niepowodzeniem z ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Oznacza to, że trustlet przechowuje tabelę użycia liczników kluczy z tym znacznikiem. Ponieważ pamięć Keymastera jest często ograniczona, tabela ta może mieć stały maksymalny rozmiar, a operacje Keymastera mogą zakończyć się niepowodzeniem, próbując użyć kluczy z tym znacznikiem, gdy tabela jest pełna. Stół musi pomieścić co najmniej 32 używane klucze i agresywnie ponownie wykorzystywać miejsca w stole po wygaśnięciu okresów minimalnego użycia kluczy. Jeśli operacja nie powiedzie się, ponieważ tabela jest pełna, Keymaster zwraca ErrorCode::TOO_MANY_OPERATIONS .

Etykieta::NO_AUTH_REQUIRED

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa, że ​​do użycia tego klucza nie jest wymagane żadne uwierzytelnianie. Ten tag wyklucza się wzajemnie z Tag::USER_SECURE_ID .

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Etykieta::NONCE

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Dostarcza lub zwraca wartość jednorazową lub wektor inicjujący (IV) dla szyfrowania lub deszyfrowania AES GCM, CBC lub CTR. Znacznik ten rozpoczyna się podczas operacji szyfrowania i deszyfrowania. Rozpoczęcie możliwe jest tylko wtedy, gdy klucz ma Tag::CALLER_NONCE . Jeśli nie zostanie podany, odpowiednia wartość jednorazowa lub IV zostanie losowo wygenerowana przez Keymaster i zwrócona od początku.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości. Dozwolone długości zależą od trybu: wartości jednorazowe GCM mają długość 12 bajtów; Długość CBC i CTR IV wynosi 16 bajtów.

Etykieta::POCHODZENIE

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa, gdzie utworzono klucz, jeśli jest znany. Znacznik ten nie może być określony podczas generowania lub importowania klucza i musi zostać dodany do charakterystyki klucza przez zaufany element.

Klucznik 3

Możliwe wartości są zdefiniowane w android::hardware::keymaster::v3_0::KeyOrigin :

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 i starsze wersje

Możliwe wartości są zdefiniowane w keymaster_origin_t :

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

Pełne znaczenie wartości zależy nie tylko od niej, ale także od tego, czy znajduje się ona na liście cech wymuszanych sprzętowo, czy programowo.

GENERATED wskazuje, że Keymaster wygenerował klucz. Jeśli znajduje się na liście wymuszanej sprzętowo, klucz został wygenerowany na bezpiecznym sprzęcie i jest trwale powiązany ze sprzętem. Jeśli znajduje się na liście wymuszanej programowo, klucz został wygenerowany w SoftKeymaster i nie jest powiązany sprzętowo.

DERIVED wskazuje, że klucz został uzyskany w programie Keymaster. Prawdopodobnie istnieje poza urządzeniem.

IMPORTED wskazuje, że klucz został wygenerowany poza Keymaster i zaimportowany do Keymaster. Jeśli znajduje się na liście wymuszanej sprzętowo, jest trwale powiązany ze sprzętem, chociaż mogą istnieć kopie poza bezpiecznym sprzętem. Jeśli na liście wymuszanej przez oprogramowanie, klucz został zaimportowany do SoftKeymaster i nie jest powiązany sprzętowo.

UNKNOWN powinna pojawiać się tylko na liście wymuszanej sprzętowo. Wskazuje, że klucz jest powiązany sprzętowo, ale nie wiadomo, czy klucz został pierwotnie wygenerowany na bezpiecznym sprzęcie, czy został zaimportowany. Dzieje się tak tylko wtedy, gdy sprzęt Keymaster0 jest używany do emulacji usług Keymaster1.

Etykieta::ORIGINATION_EXPIRE_DATETIME

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa datę i godzinę wygaśnięcia klucza do celów podpisywania i szyfrowania. Po tym czasie jakakolwiek próba użycia klucza z podanym na początku KeyPurpose::SIGN lub KeyPurpose::ENCRYPT kończy się niepowodzeniem i wyświetleniem błędu ErrorCode::KEY_EXPIRED .

Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.

Etykieta::OS_PATCHLEVEL

Wersja : 2, 3, 4

Powtarzalne ? NIE

Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo.

Wartość znacznika jest liczbą całkowitą w postaci YYYYMM, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, a MM to dwucyfrowy miesiąc ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego w grudniu 2015 r., wartość będzie wynosić 201512.

Klucze, które mają poziom poprawki inny niż bieżący poziom poprawki, nie nadają się do użycia. Próba użycia takiego klucza powoduje, że metody Begin , getKeyCharacteristics lub eksportKey zwracają ErrorCode::KEY_REQUIRES_UPGRADE . Aby uzyskać więcej informacji, zobacz Powiązanie wersji .

Etykieta::OS_VERSION

Wersja : 2, 3, 4

Powtarzalne ? NIE

Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo.

Wartość znacznika jest liczbą całkowitą w postaci MMmmss, gdzie MM jest numerem wersji głównej, mm jest numerem wersji pomocniczej, a ss jest numerem wersji podrzędnej. Na przykład dla klucza wygenerowanego w systemie Android w wersji 4.0.3 wartość będzie wynosić 040003.

Etykieta::WKŁADKA

Wersja : 1, 2, 3, 4

Powtarzalne ? Tak

Określa tryby dopełniania, których można używać z klawiszem. Ten tag dotyczy kluczy RSA i AES.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 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 starsze wersje
typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP i PaddingMode::RSA_PKCS1_1_5_ENCRYPT są używane tylko w przypadku kluczy szyfrowania/deszyfrowania RSA i określają odpowiednio dopełnienie RSA PKCS#1v2 OAEP i losowe dopełnienie RSA PKCS#1 v1.5. PaddingMode::RSA_PSS i PaddingMode::RSA_PKCS1_1_5_SIGN są używane tylko dla kluczy podpisywania/weryfikacji RSA i określają odpowiednio dopełnienie PSS RSA PKCS#1v2 i dopełnienie deterministyczne RSA PKCS#1 v1.5.

PaddingMode::NONE może być używany z kluczami RSA lub AES. W przypadku kluczy AES, jeśli PaddingMode::NONE jest używany z trybem blokowym ECB lub CBC, a dane do zaszyfrowania lub odszyfrowania nie są wielokrotnością długości bloku AES, wywołanie zakończenia kończy się niepowodzeniem z ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 może być używany tylko z kluczami AES i tylko w trybach EBC i CBC.

Ten tag jest powtarzalny. Aby rozpocząć , w wywołaniu należy określić tryb dopełniania. Jeśli określony tryb nie jest autoryzowany dla klucza, operacja kończy się niepowodzeniem z ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Etykieta::CEL

Wersja : 1, 2, 3, 4

Powtarzalne ? Tak

Określa zestaw celów, do jakich można używać klucza.

Możliwe wartości są zdefiniowane poprzez następujące wyliczenie:

Keymaster 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 starsze wersje
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Ten znacznik jest powtarzalny; klucze mogą być generowane z wieloma wartościami, chociaż operacja ma jeden cel. Kiedy funkcja Begin jest wywoływana w celu rozpoczęcia operacji, określany jest cel operacji. Jeśli cel określony w operacji nie jest autoryzowany przez klucz, operacja kończy się niepowodzeniem z błędem ErrorCode::INCOMPATIBLE_PURPOSE .

Etykieta::RESET_SINCE_ID_ROTATION

Wersja : 3, 4

Powtarzalne ? NIE

Określa, czy urządzenie zostało zresetowane do ustawień fabrycznych od ostatniej zmiany unikalnego identyfikatora. Używany do poświadczenia klucza.

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Etykieta::ROLLBACK_RESISTANT

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Wskazuje, że klucz jest odporny na wycofywanie zmian, co oznacza, że ​​po usunięciu przez DeleteKey lub DeleteAllKeys klucz ma gwarancję trwałego usunięcia i bezużyteczności. Możliwe, że klucze bez tego znacznika zostaną usunięte, a następnie przywrócone z kopii zapasowej.

Ten znacznik jest wartością logiczną, więc możliwe wartości to prawda (jeśli znacznik jest obecny) i fałsz (jeśli znacznik nie jest obecny).

Etykieta::ROOT_OF_TRUST

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa katalog główny zaufania , czyli klucz używany podczas zweryfikowanego rozruchu w celu sprawdzenia poprawności uruchomionego systemu operacyjnego (jeśli istnieje). Ten znacznik nigdy nie jest dostarczany ani zwracany przez Keymaster w ramach kluczowych cech.

Etykieta::RSA_PUBLIC_EXPONENT

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa wartość wykładnika publicznego dla pary kluczy RSA. Znacznik ten dotyczy tylko kluczy RSA i jest niezbędny w przypadku wszystkich kluczy RSA.

Wartość jest 64-bitową liczbą całkowitą bez znaku, która spełnia wymagania wykładnika publicznego RSA. Wartość ta musi być liczbą pierwszą. Trustlety obsługują wartość 2^16+1 i mogą obsługiwać inne rozsądne wartości, w szczególności wartość 3. Jeśli nie określono żadnego wykładnika lub jeśli określony wykładnik nie jest obsługiwany, generowanie klucza nie powiedzie się z błędem ErrorCode::INVALID_ARGUMENT .

Etykieta::UNIQUE_ID

Wersja : 3, 4

Powtarzalne ? NIE

Służy do podawania unikalnego identyfikatora w zaświadczeniu.

Wartością jest obiekt typu blob, tablica bajtów o dowolnej długości.

Etykieta::USAGE_EXPIRE_DATETIME

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa datę i godzinę wygaśnięcia klucza na potrzeby weryfikacji i odszyfrowania. Po tym czasie jakakolwiek próba użycia klucza z KeyPurpose::VERIFY lub KeyPurpose::DECRYPT podanymi na początek kończy się niepowodzeniem i wyświetleniem błędu ErrorCode::KEY_EXPIRED .

Wartość jest 64-bitową liczbą całkowitą reprezentującą milisekundy od 1 stycznia 1970 r.

Etykieta::USER_AUTH_TYPE

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa typy elementów uwierzytelniających użytkownika, które mogą być używane do autoryzacji tego klucza. Kiedy Keymaster zostaje poproszony o wykonanie operacji na kluczu z tym tagiem, otrzymuje token uwierzytelniający, a pole authenticator_type tokena musi odpowiadać wartości w tagu. Na przykład (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , gdzie ntoh to funkcja konwertująca liczby całkowite uporządkowane przez sieć na liczby całkowite uporządkowane przez hosta, a wartość auth_type_tag_value to wartość tego znacznika.

Wartość jest 32-bitową maską bitową zawierającą wartości z wyliczenia:

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 i starsze wersje
typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Etykieta::USER_SECURE_ID

Wersja : 1, 2, 3, 4

Powtarzalne ? NIE

Określa, że ​​klucz może być używany tylko w określonym stanie bezpiecznego uwierzytelniania użytkownika. Ten tag wyklucza się wzajemnie z Tag::NO_AUTH_REQUIRED .

Wartość jest 64-bitową liczbą całkowitą określającą wartość stanu polityki uwierzytelniania, która musi znajdować się w tokenie uwierzytelniania (podanym na początku od Tag::AUTH_TOKEN ), aby autoryzować użycie klucza. Każde wywołanie rozpoczynające się od klucza z tym tagiem, które nie udostępnia tokenu uwierzytelniania lub udostępnia token uwierzytelniania bez pasującej wartości stanu zasad, kończy się niepowodzeniem.

Ten tag jest powtarzalny. Jeśli którakolwiek z podanych wartości odpowiada dowolnej wartości stanu zasad w tokenie uwierzytelniania, klucz jest autoryzowany do użycia. W przeciwnym razie operacja zakończy się niepowodzeniem z ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Etykieta::VENDOR_PATCHLEVEL

Wersja : 4

Ten znacznik określa poziom poprawki zabezpieczeń obrazu dostawcy, z którym można używać klucza. Ten znacznik nigdy nie jest wysyłany do głównego TA klucza, ale jest dodawany przez TA do listy autoryzacji wymuszanej sprzętowo. Każda próba użycia klucza z wartością Tag::VENDOR_PATCHLEVEL inną niż aktualnie uruchomiony poziom poprawki systemowej musi spowodować, że begin() , getKeyCharacteristics() lub exportKey() zwróci ErrorCode::KEY_REQUIRES_UPGRADE . Aby uzyskać szczegółowe informacje, zobacz upgradeKey() .

Wartość znacznika jest liczbą całkowitą w postaci YYYYMMDD, gdzie YYYY to czterocyfrowy rok ostatniej aktualizacji, MM to dwucyfrowy miesiąc, a DD to dwucyfrowy dzień ostatniej aktualizacji. Na przykład dla klucza wygenerowanego na urządzeniu z Androidem, ostatnio zaktualizowanego 5 czerwca 2018 r., wartość będzie wynosić 20180605.

IKeymasterDevice HAL musi odczytać aktualny poziom poprawki dostawcy z właściwości systemowej ro.vendor.build.security_patch i dostarczyć go do bezpiecznego środowiska przy pierwszym załadowaniu warstwy HAL (mechanizm jest zdefiniowany w implementacji). Bezpieczne środowisko nie może zaakceptować kolejnego poziomu poprawek przed następnym uruchomieniem.

Musi być wymuszane sprzętowo.