Tagi autoryzacji Keymaster

Ta strona zawiera szczegółowe informacje pomocne w wdrażaniu kluczy HAL Keymaster. Obejmuje on każdy tag w HAL, wersję Keymastera, w której jest dostępny, oraz to, czy można go powtórzyć. O ile nie zaznaczono inaczej w opisach tagów, wszystkie poniższe tagi są używane podczas generowania kluczy do określenia klucza dla niektórych cech produktu.

W przypadku Keymaster 4 tagi są zdefiniowane tutaj: platform/hardware/interfaces/keymaster/keymaster-version/types.hal, na przykład 3.0/types.hal w przypadku Keymaster 3 i . 4.0/types.hal dla Keymaster 4. W przypadku Keymaster 2 i starszych wersji tagi są definiowane w pliku platform/hardware/libhardware/include/hardware/keymaster_defs.h.

Informacje o funkcjach znajdziesz na stronie Funkcje Keymastera.

Tag::ACTIVE_DATETIME

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Określa datę i godzinę aktywacji klucza. Wcześniej każda próba użycia klucza kończyła się niepowodzeniem z wiadomością ErrorCode::KEY_NOT_YET_VALID.

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

Tag::ALGORITHM

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa algorytm kryptograficzny, za pomocą którego jest używany klucz.

Możliwe wartości są zdefiniowane w ramach tej listy:

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 i starsze 
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

Czy można powtórzyć ten błąd? Nie

Zarezerwowany do użycia w przyszłości.

Tag::ALLOW_WHILE_ON_BODY

Wersja: 2, 3, 4

Powtarzalne? Nie

Ten tag dotyczy tylko urządzeń z Androidem Wear z czujnikami noszącego. Obecnie nie jest spodziewane, aby jakikolwiek TEE mógł zapewnić bezpieczny dostęp do czujnika na ciele lub aby czujniki na ciele były bardzo bezpieczne, dlatego ta funkcja ma być obsługiwana wyłącznie przez oprogramowanie.

Tag::ALL_USERS

Wersja: 3, 4

Powtarzalne? Nie

Zarezerwowany do użycia w przyszłości.

Tag::APPLICATION_DATA

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Gdy ten tag jest używany w przypadku wywołania generateKey lub importKey, określa on dane, które są niezbędne podczas wszystkich użyć klucza. W szczególności wywołania funkcji exportKey i getKeyCharacteristics muszą przekazywać tę samą wartość parametru clientId, a wywołania funkcji begin muszą przekazywać ten tag i te same powiązane dane jako część zbioru inParams. Jeśli nie podasz prawidłowych danych, funkcja zwróci wartość ErrorCode::INVALID_KEY_BLOB.

Treść tego znacznika jest powiązana z kluczem kryptografinie, co oznacza, że przeciwnik, który ma dostęp do wszystkich bezpiecznych tajemnic świata, ale nie ma dostępu do treści znacznika, nie może odszyfrować klucza bez użycia metody zgadywania, co aplikacje mogą uniemożliwić, określając treści o wystarczająco wysokiej entropii.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::APPLICATION_ID

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Po przekazaniu do generateKey lub importKey, określa dane, które są niezbędne podczas każdego użycia klucza. W a zwłaszcza połączenia do exportKey oraz getKeyCharacterists muszą podać tę samą wartość w parametrze clientId i begin musi podać ten tag i te same powiązane dane w ramach tagu Ustawiono inParams. Jeśli nie podasz prawidłowych danych, funkcja zwróci wartość ErrorCode::INVALID_KEY_BLOB.

Zawartość tego tagu jest powiązana z kluczem kryptograficznym, czyli wrogiem, który może poznać wszystkie sekrety bezpiecznego świata. nie ma dostępu do zawartości tagu – nie może odszyfrować (bez narzucania zawartości tagu).

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

Tag::ASSOCIATED_DATA

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Dostarcza „powiązanych danych” do szyfrowania lub odszyfrowania AES-GCM. Ten tag służy do aktualizowania i określania danych, które nie są szyfrowane ani odszyfrowane, ale są używane do obliczania tagu GCM.

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

Tag::ATTESTATION_APPLICATION_ID

Wersja: 3, 4

Czy można powtórzyć ten błąd? Nie

Służy do identyfikowania zestawu możliwych aplikacji, z których jedna rozpoczęła uwierzytelnianie klucza.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::ATTESTATION_CHALLENGE

Wersja: 3 i 4

Powtarzalne? Nie

Służy do podawania wyzwania w atestie.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::ATTESTATION_ID_BRAND

Wersja: 3, 4

Powtarzalne? Nie

Zawiera nazwę marki urządzenia podaną przez usługę Build.BRAND na Androidzie. To pole jest ustawiane tylko podczas żądania atestu identyfikatorów urządzeń.

Jeśli urządzenie nie obsługuje poświadczania tożsamości (lub Wcześniej zostało nawiązane połączenie z numerem destroyAttestationIds(), a urządzenie może nie potwierdza już swoich identyfikatorów), wszelkie żądania atestu kluczy, które zawierają dla tego tagu występuje błąd ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_DEVICE

Wersja: 3 i 4

Czy można powtórzyć ten błąd? Nie

Zawiera nazwę urządzenia zwracaną przez funkcję Build.DEVICEw Androidzie. To pole jest ustawiane tylko podczas żądania atestu identyfikatorów urządzeń.

Jeśli urządzenie nie obsługuje poświadczania tożsamości (lub Wcześniej zostało nawiązane połączenie z numerem destroyAttestationIds(), a urządzenie może nie potwierdza już swoich identyfikatorów), wszelkie żądania atestu kluczy, które zawierają dla tego tagu występuje błąd ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_IMEI

Wersja: 3 i 4

Czy można powtórzyć ten błąd? Tak

Zawiera identyfikatory IMEI wszystkich modułów radiowych na urządzeniu. To pole jest ustawiane tylko podczas żądania uwierzytelnienia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_MANUFACTURER

Wersja: 3 i 4

Czy można powtórzyć ten błąd? Nie

Zawiera nazwę producenta urządzenia zwracaną przez funkcję Build.MANUFACTURER w Androidzie. To pole ustawia się tylko wtedy, gdy wysyłanie żądań poświadczania identyfikatorów urządzeń.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::ATTESTATION_ID_MEID

Wersja: 3 i 4

Powtarzalne? Tak

Podaje identyfikatory MEID wszystkich radia na urządzeniu. Tylko to pole jest ustawione gdy prosisz o potwierdzenie identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_MODEL

Wersja: 3 i 4

Powtarzalne? Nie

Zawiera nazwę modelu urządzenia podaną przez Build.MODEL na Androidzie. To pole ustawia się tylko wtedy, gdy wysyłanie żądań poświadczania identyfikatorów urządzeń.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::ATTESTATION_ID_PRODUCT

Wersja: 3, 4

Czy można powtórzyć ten błąd? Nie

Zawiera nazwę urządzenia zwracaną przez funkcję Build.PRODUCT w Androidzie. To pole jest ustawiane tylko wtedy, gdy żądasz potwierdzenia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::ATTESTATION_ID_SERIAL

Wersja: 3, 4

Czy można powtórzyć ten błąd? Nie

Zawiera numer seryjny urządzenia. To pole jest ustawiane tylko wtedy, gdy żądasz uwierzytelnienia identyfikatorów urządzenia.

Jeśli urządzenie nie obsługuje uwierzytelniania tożsamości (lub destroyAttestationIds() zostało wcześniej wywołane i urządzenie nie może już uwierzytelnić swoich identyfikatorów), żądanie uwierzytelnienia klucza, które zawiera ten tag, zakończy się niepowodzeniem z wartością ErrorCode::CANNOT_ATTEST_IDS.

Wartość jest blobem, czyli 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 może być używany po uwierzytelnieniu. Jeśli Tag::USER_SECURE_ID zamiast tego tagu, klucz wymaga uwierzytelnienia wykorzystanie danych (patrz rozpoczęcie, szczegóły procesu uwierzytelniania dla każdej operacji).

Wartość to 32-bitowa liczba całkowita określająca czas w sekundach po udanym uwierzytelnieniu użytkownika określonego przez parametr Tag::USER_SECURE_ID przy użyciu metody uwierzytelniania określonej przez parametr Tag::USER_AUTH_TYPE, w której można używać klucza.

Tag::AUTH_TOKEN

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Udostępnia token uwierzytelniający, aby rozpocząć, zaktualizować lub zakończyć proces uwierzytelniania użytkownika w przypadku operacji klucza, która go wymaga (klucz ma tag Tag::USER_SECURE_ID).

Wartość to blob zawierający strukturę hw_auth_token_t.

Tag::BLOB_USAGE_REQUIREMENTS

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa warunki środowiska systemowego, które są wymagane do użycia wygenerowanego klucza.

Możliwe wartości są określone przez następujące wyliczenie:

Keymaster 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 lub starsza wersja 
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 był dostępny w określonych warunkach. Musi być zwracany z kluczowymi właściwościami z funkcji generateKey i getKeyCharacteristics. Jeśli wywołujący określa Tag::BLOB_USAGE_REQUIREMENTS z wartość KeyBlobUsageRequirements::STANDALONE zaufanialet zwraca kluczowy obiekt blob których można używać bez obsługi systemu plików. Jest to bardzo ważne w przypadku urządzeń z zaszyfrowanymi dyskami, ponieważ system plików może być niedostępny, dopóki nie użyjesz klucza Keymaster do odszyfrowania dysku.

Tag::BLOCK_MODE

Wersja: 1, 2, 3, 4

Czy można go powtórzyć? Tak

Określa tryby szyfrowania blokowego, z którymi można używać klucza. Ten tag dotyczy tylko kluczy AES.

Możliwe wartości są określone przez następujące wyliczenie:

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

Ten tag jest powtarzalny, a w przypadku operacji klucza AES określa tryb w argumencie additionalParams funkcji begin. Jeśli wybrany tryb nie jest jednym z tych, które można przypisać do klucza, operacja zakończy się niepowodzeniem z wartością ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::BOOT_PATCHLEVEL

Wersja: 4

Tag::BOOT_PATCHLEVEL określa poziom poprawek zabezpieczeń obrazu rozruchowego (jądro) z którym można go używać. Ten tag nie jest nigdy wysyłany do zespołu pomocy ds. klucza, ale zostanie dodany do listy stron wymuszanych przez sprzęt. Każda próba użyj klucza z wartością Tag::BOOT_PATCHLEVEL inną niż uruchomiony stan poprawek systemu powoduje begin(), getKeyCharacteristics() lub exportKey() do zwrotu ErrorCode::KEY_REQUIRES_UPGRADE. Zobacz upgradeKey() .

Wartość tagu jest liczbą całkowitą w formacie RRRRMMDD, gdzie RRRR czterocyfrowy rok ostatniej aktualizacji, MM to miesiąc, a DD to miesiąc dwucyfrowy dzień ostatniej aktualizacji. Na przykład w przypadku klucza wygenerowanego na Ostatnia aktualizacja urządzenia z Androidem 5 czerwca 2018 roku to 20180605. Jeśli dzień nie jest znany, można zastąpić 00.

Podczas każdego rozruchu bootloader musi przekazać poziom poprawek obrazu rozruchowego do bezpiecznego środowiska (mechanizm jest zdefiniowany przez implementację).

Musi być realizowane na poziomie sprzętowym.

Tag::BOOTLOADER_ONLY

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Określa, że klucz może używać tylko bootloader.

Ten tag jest tagiem logicznym, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag jest nieobecny).

Każda próba użycia klucza z kluczem Tag::BOOTLOADER_ONLY z W systemie Android występuje błąd ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Określa, że wywołujący może podać losowy ciąg znaków do operacji wymagających losowego ciągu znaków.

Ten tag jest wartością logiczną, więc jego możliwe wartości to „prawda” (jeśli jest dostępny) i false (jeśli nie ma tagu).

Ten tag jest używany wyłącznie w przypadku kluczy AES i ma zastosowanie wyłącznie w przypadku CBC, CTR i GCM i blokować tryby. Jeśli tag nie jest obecny, implementacje powinny odrzucać wszystkie operacje, które podają Tag::NONCE z początkiem ErrorCode::CALLER_NONCE_PROHIBITED.

Tag::CREATION_DATETIME

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa datę i godzinę utworzenia klucza w milisekundach od 1 stycznia 1970 r. Ten tag jest opcjonalny i służy wyłącznie do celów informacyjnych.

Tag::DIGEST

Wersja: 1, 2, 3, 4

Powtarzalne? Tak

Określa algorytmy skrótu, których można używać z kluczem do wykonywania podczas podpisywania i weryfikacji. Ten tag dotyczy kluczy RSA, ECDSA i HMAC.

Możliwe wartości są zdefiniowane w ramach tej listy:

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

Ten tag jest powtarzalny. W przypadku operacji podpisywania i weryfikacji podaj ciągi kontrolne w argumencie additionalParams funkcji begin. Jeśli podany skrót nie znajduje się w skrótach powiązanych z kluczem, operacja kończy się niepowodzeniem z wartością ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

Wersja: 2, 3, 4

Powtarzalne? Nie

W Keymaster 1 krzywizna używana do kluczy EC została odgadnięta na podstawie określonego rozmiaru klucza. Aby zwiększyć elastyczność, w Keymaster 2 wprowadzono 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 w ramach tej listy:

Keymaster 3 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 lub starsza wersja 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Jeśli żądanie wygenerowania zawiera tylko ciąg Tag::KEY_SIZE, korzystając z logiki Keymaster 1, wybierając odpowiednią krzywą NIST.

Jeśli żądanie zawiera tylko Tag::EC_CURVE, użyj parametru zgodnie z określoną krzywą. W przypadku Keymaster 3 i nowszych krzywe są definiowane w pliku EcCurve. W przypadku Keymaster 2 i starszych krzywe są definiowane w pliku keymaster_ec_curve_t.

Jeśli żądanie zawiera obie te wartości, użyj krzywej określonej przez Tag::EC_CURVE i sprawdź, czy podany rozmiar klucza to dla danej 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 uwierzytelniający dla wygenerowanego klucza powinien zawierać unikalny identyfikator urządzenia w zakresie aplikacji i ograniczony czasowo, zgodnie z tagiem Tag::UNIQUE_ID.

Ten tag jest wartością logiczną, więc jego możliwe wartości to „prawda” (jeśli jest dostępny) i false (jeśli nie ma tagu).

Tag::KEY_SIZE

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Określa rozmiar klucza (w bitach) mierzony w normalny sposób za pomocą algorytmu klucza. Na przykład w przypadku kluczy RSA parametr Tag::KEY_SIZE określa rozmiar modułu publicznego. W przypadku kluczy AES określa długość materiału klucza obiektu tajnego.

Tag::MAC_LENGTH

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Podaje żądaną długość tagu uwierzytelniania MAC lub GCM (w bitach).

Wartość to długość adresu MAC w bitach. Jest wielokrotnością liczby 8 i co najmniej taka sama jak wartość Tag::MIN_MAC_LENGTH powiązane z kluczem.

Tag::MAX_USES_PER_BOOT

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa maksymalną liczbę razy, ile klucz można użyć między ponownymi uruchamianiami systemu. Jest to kolejny mechanizm ograniczania użycia klucza liczby żądań.

Wartość jest 32-bitową liczbą całkowitą, która reprezentuje liczbę użyć na uruchomienie.

Jeśli w operacji jest używany klucz z tym tagiem, powiązany z nim licznik powinna zostać zwiększona podczas begin. Po kluczu licznik przekroczył tę wartość, wszystkie kolejne próby użycia klucza kończą się niepowodzeniem za pomocą funkcji ErrorCode::MAX_OPS_EXCEEDED, dopóki urządzenie nie zostanie ponownie uruchomione. Oznacza to, że powiernik przechowuje tabelę liczników użycia dla kluczy z tym argumentem . Ponieważ pamięć Keymaster jest często ograniczona, ta tabela może mieć stały maksymalny rozmiar, a Keymaster może nie wykonać operacji, które próbują użyć kluczy z tym tagiem, gdy tabela jest pełna. Tabela musi pomieścić co najmniej 16 kluczy. Jeśli operacja się nie powiedzie, ponieważ tabela jest pełna, Keymaster zwróci ErrorCode::TOO_MANY_OPERATIONS.

Tag::MIN_MAC_LENGTH

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Ten tag określa minimalną długość MAC, której można zażądać lub zweryfikowane przy użyciu tego klucza w przypadku kluczy HMAC i AES obsługujących tryb GCM.

Jest to minimalna długość adresu MAC w bitach. Jest ona wielokrotnością 8. Dla: kluczy HMAC, wartość wynosi co najmniej 64. W przypadku kluczy GCM wartość jest co najmniej 96, a maksymalnie 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Wersja: 1, 2, 3, 4

Czy można go powtórzyć? Nie

Określa minimalny czas, który upływa od dozwolonej wersji za pomocą klucza. Może służyć do ograniczania liczby przypadków użycia kluczy w kontekstach. w którym nieograniczone wykorzystanie mogłoby umożliwić ataki brute-force.

Wartość jest 32-bitową liczbą całkowitą określającą sekundy od dozwolonych operacji.

Gdy klucz z tym tagiem jest używany w operacji, uruchom minutnik podczas wywołania finish lub abort. Każde wywołanie metody begin, które zostanie odebrane przed tym, jak licznik czasu wskaże, że upłynął interwał określony przez parametr Tag::MIN_SECONDS_BETWEEN_OPS, zakończy się niepowodzeniem z kodem ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Ten oznacza, że powiernik przechowuje tabelę liczników użycia dla kluczy z tym tagiem. Pamięć Keymaster jest często ograniczona, więc tabela może mieć stałą maksymalną wartość rozmiaru i Keymaster może zakończyć wykonywanie operacji, które próbują użyć kluczy z tym tagiem. gdy tabela będzie pełna. Tabela musi pomieścić co najmniej 32 klucze w użyciu i intensywnie wykorzystywać gniazda tabeli, gdy wygasną minimalne okresy użytkowania klucza. Jeśli operacja się nie powiedzie, ponieważ tabela jest pełna, Keymaster zwróci ErrorCode::TOO_MANY_OPERATIONS.

Tag::NO_AUTH_REQUIRED

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa, że do użycia tego klucza nie jest wymagane uwierzytelnianie. Ten tag jest wzajemnie wykluczający się z tagiem Tag::USER_SECURE_ID.

Ten tag jest tagiem logicznym, więc możliwe wartości to prawda (jeśli tag jest obecny) i fałsz (jeśli tag jest nieobecny).

Tag::NONCE

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Udostępnia lub zwraca wektor początkowy (IV) dla szyfrowania lub odszyfrowania AES GCM, CBC lub CTR. Ten tag jest udostępniany, aby rozpocząć operacje szyfrowania i odszyfrowania. Jest on dostępny tylko dla początek jeśli klucz zawiera ciąg Tag::CALLER_NONCE. Jeśli nie zostanie podany, Keymaster wygeneruje losowo odpowiedni identyfikator nonce lub IV i zwróci go z funkcji begin.

Wartością jest obiekt blob, czyli tablica bajtów o dowolnej długości. Dozwolone długości zależą od trybu: nonce GCM ma długość 12 bajtów, a IV CBC i CTR – 16 bajtów.

Tag::ORIGIN

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Wskazuje, gdzie klucz został utworzony (jeśli jest to znane). Nie można określić tego tagu podczas generowania lub importowania kluczy; należy je dodać do kluczowych cech przez fundację.

Keymaster 3

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

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

Możliwe wartości są zdefiniowane w elementach 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 samej, ale też od tego, czy znajduje się ona na liście funkcji obsługiwanych przez sprzęt lub oprogramowanie.

GENERATED wskazuje, że klucz został wygenerowany przez Keymaster. Jeśli klucz znajduje się na liście sprzętowych kluczy bezpieczeństwa, oznacza to, że został wygenerowany na sprzęcie zabezpieczonym i jest na stałe powiązany ze sprzętem. Jeśli klucz znajduje się na liście kluczy kontrolowanych przez oprogramowanie, został wygenerowany w SoftKeymaster i nie jest powiązany z sprzętem.

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

IMPORTED oznacza, że klucz został wygenerowany poza domeną. z Keymaster i zaimportowany do Mistrz kluczy. Jeśli znajduje się na liście urządzeń z ograniczeniami sprzętowymi, jest na stałe powiązany ze sprzętem, ale mogą istnieć kopie poza zabezpieczonym sprzętem. Jeśli na liście „Wymuszanie oprogramowania” klucz został zaimportowany do SoftKeymaster i nie jest powiązany z sprzętem.

Element UNKNOWN powinien pojawiać się tylko na liście wymuszonych ustawień sprzętowych. Wskazuje, że klucz jest powiązany ze sprzętem, ale nie wiadomo, czy został pierwotnie wygenerowany na bezpiecznym sprzęcie, czy został zaimportowany. Dzieje się tak tylko wtedy, gdy sprzęt keymaster0 jest używany do emulowania usług keymaster1.

Tag::ORIGINATION_EXPIRE_DATETIME

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa datę i godzinę wygaśnięcia klucza do podpisywania i szyfrowania. Po tym czasie każda próba użycia klucza z KeyApplication::SIGN lub KeyGoal::ENCRYPT został podany. niepowodzenie begin dzięki ErrorCode::KEY_EXPIRED.

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

Tag::OS_PATCHLEVEL

Wersja: 2, 3, 4

Powtarzalne? Nie

Ten tag nigdy nie jest wysyłany do kluczowego zespołu pomocy technicznej, ale jest dodawany przez ten zespół do listy autoryzacji z weryfikacją sprzętową.

Wartość tagu to liczba całkowita w formacie 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 Androidem ostatnio w grudniu 2015 r. wartością będzie 201512.

Klucze, których poziom poprawek jest inny niż obecny poziom poprawek nie są użyteczność. Próba użycia takiego klucza powoduje, że funkcje begin, getKeyCharacteristics lub exportKey zwracają ErrorCode::KEY_REQUIRES_UPGRADE. Więcej informacji znajdziesz w artykule Powiązanie wersji.

Tag::OS_VERSION

Wersja: 2, 3, 4

Powtarzalne? Nie

Ten tag nie jest nigdy wysyłany do usługi Keymaster TA, ale jest dodawany do sekcji lista uwierzytelniania wymuszane przez sprzęt.

Wartość tagu jest liczbą całkowitą w formie MMmmss, gdzie MM to numer wersji głównej, mm to numer wersji podrzędnej, a ss to numer wersji podrzędnej podrzędnej. Na przykład w przypadku klucza wygenerowanego w wersji Androida 4.0.3 jego wartość będzie wynosić 040003.

Tag::PADDING

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Tak

Określa tryby dopełnienia, których można używać z kluczem. Ten tag jest istotne dla kluczy RSA i AES.

Możliwe wartości są zdefiniowane w ramach tej listy:

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 
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 Zajęte miejsce: PaddingMode::RSA_PKCS1_1_5_ENCRYPT tylko dla kluczy szyfrowania/odszyfrowywania RSA i określ RSA PKCS#1v2 OAEP odpowiednio dopełnienie i losowe dopełnienie RSA PKCS#1 w wersji 1.5. PaddingMode::RSA_PSS i PaddingMode::RSA_PKCS1_1_5_SIGN są używane tylko w elastycznych reklamach w wyszukiwarce klucze podpisywania/weryfikacji i określenie RSA PKCS#1v2 PSS odpowiednio dopełnienie i dopełnienie deterministyczne RSA PKCS#1 w wersji 1.5.

Typu PaddingMode::NONE można używać zarówno ze sprzedawcami RSA, Klucze AES. W przypadku kluczy AES, jeśli używany jest PaddingMode::NONE z ECB lub CBC w trybie blokowania i danymi do zaszyfrowania lub odszyfrowania nie jest wielokrotnością rozmiaru bloku AES, połączenie do zakończenia niepowodzenie w wyniku ErrorCode::INVALID_INPUT_LENGTH.

PaddingMode::PKCS7 można używać tylko z kluczami AES i tylko w trybach ECB i CBC.

Ten tag jest powtarzalny. W wywołaniu funkcji dopełnienia należy określić tryb dopełnienia begin. Jeśli określony tryb nie jest autoryzowany przez klucz, operacja zakończy się niepowodzeniem z wartością ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::PURPOSE

Wersja: 1, 2, 3, 4

Powtarzalne? Tak

Określa zestaw celów, do których może być używany klucz.

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

Keymaster 3 
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 i starsze 
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 można generować z wieloma wartościami, chociaż operacja ma jeden cel. Gdy wywoływana jest funkcja begin, aby rozpocząć działanie, określany jest cel tej operacji. Jeśli cel operacji nie jest autoryzowany przez oznacza to, że operacja zakończy się niepowodzeniem, gdy zostanie ErrorCode::INCOMPATIBLE_PURPOSE.

Tag::RESET_SINCE_ID_ROTATION

Wersja: 3 i 4

Powtarzalne? Nie

Określa, czy urządzenie zostało przywrócone do ustawień fabrycznych od ostatniej rotacji identyfikatora. Służy do uwierzytelniania kluczy.

Ten tag jest wartością logiczną, więc jego możliwe wartości to „prawda” (jeśli jest dostępny) i false (jeśli nie ma tagu).

Tag::ROLLBACK_RESISTANT

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Wskazuje, że klucz jest odporny na wycofanie, co oznacza, że po usunięciu deleteKey lub deleteAllKeys, klucz zostanie trwale usunięty i nie będzie można z niego korzystać. Możliwe, że klucze bez tego znacznika zostaną usunięte, a następnie przywrócone z kopii zapasowej.

Ten tag jest wartością logiczną, więc jego możliwe wartości to „prawda” (jeśli jest dostępny) i false (jeśli nie ma tagu).

Tag::ROOT_OF_TRUST

Wersja: 1, 2, 3, 4

Czy można go powtórzyć? Nie

Określa katalog główny zaufania, czyli klucz używany podczas weryfikacji podczas uruchamiania sprawdzić poprawność rozruchu systemu operacyjnego (jeśli jest dostępny); Ten tag nigdy nie jest przekazywany do Keymaster ani zwracany z Keymaster w charakterystyce klucza.

Tag::RSA_PUBLIC_EXPONENT

Wersja: 1, 2, 3, 4

Czy można powtórzyć ten błąd? Nie

Określa wartość wykładnika publicznego dla pary kluczy RSA. Ten tag jest istotne tylko w przypadku kluczy RSA i niezbędne dla wszystkich kluczy RSA.

Wartość jest 64-bitową nieoznaczoną liczbą całkowitą, która spełnia wymagania funkcji Wykładnik publiczny RSA. Ta wartość musi być liczbą pierwszą. Trustlety obsługują wartości 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 nie jest on obsługiwany, nie można wygenerować klucza ErrorCode::INVALID_ARGUMENT.

Tag::UNIQUE_ID

Wersja: 3, 4

Powtarzalne? Nie

Służy do podawania w atestie unikalnego identyfikatora.

Wartość jest blobem, czyli tablicą bajtów o dowolnej długości.

Tag::USAGE_EXPIRE_DATETIME

Wersja: 1, 2, 3, 4

Czy można go powtórzyć? Nie

Określa datę i godzinę, kiedy klucz wygasa na potrzeby weryfikacji oraz w celach odszyfrowywania. Po tym czasie każda próba użycia klucza z KeyCel::WERYFIKACJA lub KeyApplication::DECRYPT przekazany do niepowodzenie begin dzięki ErrorCode::KEY_EXPIRED.

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

Tag::USER_AUTH_TYPE

Wersja: 1, 2, 3, 4

Powtarzalne? Nie

Określa typy uwierzytelniania użytkownika, które można wykorzystać do autoryzacji tego klucza. Gdy Keymaster otrzyma żądanie wykonania operacji na kluczu o takim identyfikatorze otrzymuje token uwierzytelniania, Wartość w polu authenticator_type musi pasować do 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 posortowane w sieci na liczby całkowite posortowane według hosta, a auth_type_tag_value to wartość tego tagu.

Wartość jest 32-bitową liczbą całkowitą maską bitową 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 
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? Tak

Określa, że klucz może być używany tylko w przypadku określonego stanu uwierzytelniania użytkownika. Ten tag wzajemnie się wyklucza za pomocą parametru Tag::NO_AUTH_REQUIRED.

Wartość to 64-bitowa liczba całkowita określająca stan zasady uwierzytelniania wartość, która musi znajdować się w tokenie uwierzytelniania (podanym do rozpoczyna się od Tag::AUTH_TOKEN), aby autoryzować użycie klucza. Dowolne wywołanie do begin klucz z tym tagiem, który nie dostarcza token uwierzytelniania lub udostępnia token uwierzytelniania bez pasującej wartości stanu zasady kończy się niepowodzeniem.

Ten tag można powtarzać. Jeśli któraś z podanych wartości pasuje do dowolnej wartości stanu zasad w tokenie uwierzytelniania, klucz jest autoryzowany do użycia. W przeciwnym razie operacja nie powiedzie się i zostanie zwrócony błąd ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Tag::VENDOR_PATCHLEVEL

Wersja: 4

Ten tag określa poziom zabezpieczeń obrazu dostawcy, z którym można używać klucza. Ten tag nie jest nigdy wysyłany do usługi Keymaster TA, ale jest dodawany do sekcji lista uwierzytelniania wymuszane przez sprzęt. Każda próba użycia klucza z wartością Tag::VENDOR_PATCHLEVEL inną niż poziom poprawek systemu, który jest obecnie używany, musi powodować zwrócenie wartości begin(), getKeyCharacteristics() lub exportKey(). Więcej informacji znajdziesz na stronie upgradeKey().

Wartość tagu jest liczbą całkowitą w formacie RRRRMMDD, gdzie RRRR 4-cyfrowy rok ostatniej aktualizacji, MM to miesiąc, a DD to miesiąc dwucyfrowy dzień ostatniej aktualizacji. Na przykład w przypadku klucza wygenerowanego na Ostatnia aktualizacja urządzenia z Androidem 5 czerwca 2018 roku to 20180605.

HAL IKeymasterDevice musi odczytywać z systemu bieżący poziom poprawek dostawcy usługi ro.vendor.build.security_patch i prześlij ją do w bezpiecznym środowisku podczas pierwszego wczytywania HAL (mechanizm to jest zdefiniowana w implementacji). Bezpieczne środowisko nie może akceptować innego poziomu poprawek do czasu następnego rozruchu.

Musi być wymuszane sprzętowo.