Теги авторизации Keymaster

На этой странице представлены сведения, которые помогут разработчикам Keymaster HAL. Он охватывает каждый тег в HAL, в какой версии Keymaster доступен этот тег и является ли этот тег повторяемым. За исключением случаев, указанных в описаниях тегов, все приведенные ниже теги используются во время генерации ключа для указания ключевых характеристик.

Для Keymaster 4 теги определяются в platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , например 3.0/types.hal для Keymaster 3 и 4.0/types.hal для Keymaster 4. Для Keymaster 2 и ниже: теги определены в platform/hardware/libhardware/include/hardware/keymaster_defs.h .

Функции см. на странице «Функции Keymaster» .

Тег::ACTIVE_DATETIME

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает дату и время, когда ключ становится активным. До этого времени любая попытка использовать ключ завершается неудачей с ErrorCode::KEY_NOT_YET_VALID .

Значение представляет собой 64-битное целое число, представляющее миллисекунды с 1 января 1970 года.

Тег::АЛГОРИТМ

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает криптографический алгоритм, с которым используется ключ.

Возможные значения определяются следующим перечислением:

Ключник 3
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 и более ранние версии 
typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Тег::ALL_APPLICATIONS

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Зарезервировано для будущего использования.

Тег::ALLOW_WHILE_ON_BODY

Версия : 2, 3, 4

Повторяемый ? Нет

Этот тег применим только к устройствам Android Wear с датчиками, находящимися на теле. На данный момент не ожидается, что какой-либо TEE сможет обеспечить безопасный доступ к датчику на теле или что датчики на теле будут очень безопасными, поэтому ожидается, что это будет чисто программная функция.

Тег::ALL_USERS

Версия : 3, 4

Повторяемый ? Нет

Зарезервировано для будущего использования.

Тег::APPLICATION_DATA

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Если этот тег предоставлен дляgenerateKey или importKey , он определяет данные, необходимые во время любого использования ключа. В частности, вызовы ExportKey и getKeyCharacteristics должны предоставить одно и то же значение параметра clientId , а вызовы Begin должны предоставить этот тег и те же связанные данные как часть набора inParams . Если правильные данные не предоставлены, функция возвращает ErrorCode::INVALID_KEY_BLOB .

Содержимое этого тега криптографически привязано к ключу. Это означает, что злоумышленник, имеющий доступ ко всем секретам безопасного мира, но не имеющий доступа к содержимому тега, не должен иметь возможности расшифровать ключ без грубого взлома. тегируйте контент, который приложения могут предотвратить, указав контент с достаточно высокой энтропией.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::APPLICATION_ID

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Если этот тег предоставлен дляgenerateKey или importKey , он определяет данные, необходимые во время любого использования ключа. В частности, вызовы ExportKey и getKeyCharacteristics должны предоставить одно и то же значение в параметре clientId , а вызовы Begin должны предоставить этот тег и те же связанные данные как часть набора inParams . Если правильные данные не предоставлены, функция возвращает ErrorCode::INVALID_KEY_BLOB .

Содержимое этого тега криптографически привязано к ключу, что означает, что злоумышленник, который может получить доступ ко всем секретам безопасного мира, но не имеет доступа к содержимому тега, не может расшифровать ключ (без перебора тега). содержание).

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ASSOCIATED_DATA

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Предоставляет «связанные данные» для шифрования или дешифрования AES-GCM. Этот тег предназначен для обновления и определяет данные, которые не зашифрованы/расшифрованы, но используются при вычислении тега GCM.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_APPLICATION_ID

Версия : 3, 4

Повторяемый ? Нет

Используется для определения набора возможных приложений, для которых инициирована ключевая аттестация.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_CHALLENGE

Версия : 3, 4

Повторяемый ? Нет

Используется для вызова проверки при аттестации.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_BRAND

Версия : 3, 4

Повторяемый ? Нет

Предоставляет торговую марку устройства, возвращаемую Build.BRAND в Android. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_DEVICE

Версия : 3, 4

Повторяемый ? Нет

Предоставляет имя устройства, возвращаемое Build.DEVICE в Android. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_IMEI

Версия : 3, 4

Повторяемый ? Да

Предоставляет IMEI для всех радиомодулей на устройстве. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_MANUFACTURER

Версия : 3, 4

Повторяемый ? Нет

Предоставляет название производителя устройства, возвращаемое Build.MANUFACTURER в Android. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_MEID

Версия : 3, 4

Повторяемый ? Да

Предоставляет MEID для всех радиомодулей на устройстве. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_MODEL

Версия : 3, 4

Повторяемый ? Нет

Предоставляет название модели устройства, возвращаемое Build.MODEL в Android. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_PRODUCT

Версия : 3, 4

Повторяемый ? Нет

Предоставляет название продукта устройства, возвращаемое Build.PRODUCT в Android. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::ATTESTATION_ID_SERIAL

Версия : 3, 4

Повторяемый ? Нет

Предоставляет серийный номер устройства. Это поле задается только при запросе подтверждения идентификаторов устройства.

Если устройство не поддерживает аттестацию идентификатора (или ранее был вызван destroyAttestationIds() , и устройство больше не может подтверждать свои идентификаторы), любой запрос на аттестацию ключа, включающий этот тег, завершается с ошибкой ErrorCode::CANNOT_ATTEST_IDS .

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::AUTH_TIMEOUT

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает время в секундах, в течение которого ключ разрешен для использования после аутентификации. Если Tag::USER_SECURE_ID присутствует, а этот тег отсутствует, то для каждого использования ключа требуется аутентификация (подробности о процессе аутентификации для каждой операции см. в начале ).

Значение представляет собой 32-битное целое число, указывающее время в секундах после успешной аутентификации пользователя, указанного Tag::USER_SECURE_ID, с методом аутентификации, указанным Tag::USER_AUTH_TYPE , в течение которого можно использовать ключ.

Тег::AUTH_TOKEN

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Предоставляет токен аутентификации для начала , обновления или завершения , чтобы подтвердить аутентификацию пользователя для ключевой операции, которая требует этого (ключ имеет Tag::USER_SECURE_ID ).

Значением является большой двоичный объект, содержащий структуру hw_auth_token_t .

Тег::BLOB_USAGE_REQUIREMENTS

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает необходимые условия системной среды для использования сгенерированного ключа.

Возможные значения определяются следующим перечислением:

Ключник 3
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 и более ранние версии
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Этот тег можно указать во время генерации ключа, чтобы потребовать, чтобы ключ можно было использовать в указанном состоянии. Его необходимо вернуть с ключевыми характеристиками изgenerateKey и getKeyCharacteristics . Если вызывающая сторона указывает Tag::BLOB_USAGE_REQUIREMENTS со значением KeyBlobUsageRequirements::STANDALONE трастлет возвращает ключевой объект, который можно использовать без поддержки файловой системы. Это критично для устройств с зашифрованными дисками, где файловая система может быть недоступна до тех пор, пока ключ Keymaster не будет использован для расшифровки диска.

Тег::BLOCK_MODE

Версия : 1, 2, 3, 4

Повторяемый ? Да

Указывает режимы блочного шифрования, с которыми можно использовать ключ. Этот тег относится только к ключам AES.

Возможные значения определяются следующим перечислением:

Ключник 3
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 и более ранние версии
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Этот тег является повторяемым, и для операций с ключами AES укажите режим в аргументе additionalParams команды start . Если указанный режим не входит в режимы, связанные с ключом, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Тег::BOOT_PATCHLEVEL

Версия : 4

Тег::BOOT_PATCHLEVEL указывает уровень исправлений безопасности загрузочного образа (ядра), с которым можно использовать ключ. Этот тег никогда не отправляется ТА мастера ключей, но добавляется ТА в список аппаратной авторизации. Любая попытка использовать ключ со значением Tag::BOOT_PATCHLEVEL отличным от текущего уровня исправления системы, приводит к тому, что begin() , getKeyCharacteristics() или exportKey() возвращают ErrorCode::KEY_REQUIRES_UPGRADE . Подробности смотрите в upgradeKey() .

Значение тега — целое число в формате ГГГГММДД, где ГГГГ — четырехзначный год последнего обновления, ММ — двухзначный месяц, а ДД — двухзначный день последнего обновления. Например, для ключа, созданного на устройстве Android, последний раз обновленного 5 июня 2018 г., значение будет 20180605. Если день неизвестен, можно заменить 00.

Во время каждой загрузки загрузчик должен предоставлять уровень исправления загрузочного образа в безопасную среду (механизм определяется реализацией).

Должно быть реализовано аппаратно.

Тег::BOOTLOADER_ONLY

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает, что ключ может использовать только загрузчик.

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Любая попытка использовать ключ с Tag::BOOTLOADER_ONLY из системы Android завершается неудачей с ErrorCode::INVALID_KEY_BLOB .

Тег::CALLER_NONCE

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает, что вызывающая сторона может предоставить одноразовый номер для операций, требующих одноразового номера.

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Этот тег используется только для ключей AES и актуален только для режимов блоков CBC, CTR и GCM. Если тег отсутствует, реализации должны отклонять любую операцию, в которой Tag::NONCE начинается с ErrorCode::CALLER_NONCE_PROHIBITED .

Тег::CREATION_DATETIME

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает дату и время создания ключа в миллисекундах с 1 января 1970 года. Этот тег является необязательным и предназначен только для информационных целей.

Тег::ДАЖЕСТ

Версия : 1, 2, 3, 4

Повторяемый ? Да

Указывает алгоритмы дайджеста, которые можно использовать с ключом для выполнения операций подписи и проверки. Этот тег относится к ключам RSA, ECDSA и HMAC.

Возможные значения определяются следующим перечислением:

Ключник 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 и более ранние версии
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;

Этот тег повторяемый. Для операций подписи и проверки укажите дайджест в аргументе additionalParams функции start . Если указанный дайджест отсутствует в дайджестах, связанных с ключом, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_DIGEST .

Тег::EC_CURVE

Версия : 2, 3, 4

Повторяемый ? Нет

В Keymaster 1 кривая, используемая для ключей EC, была угадана на основе указанного размера ключа. Чтобы повысить гибкость в дальнейшем, Keymaster 2 представил явный способ задания кривых. Запросы на создание ключей EC могут иметь Tag::EC_CURVE , Tag::KEY_SIZE или оба.

Возможные значения определяются следующим перечислением:

Ключник 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 и более ранние версии
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Если запрос на создание содержит только Tag::KEY_SIZE , вернитесь к логике Keymaster 1, выбрав соответствующую кривую NIST.

Если запрос содержит только Tag::EC_CURVE , используйте указанную кривую. Для Keymaster 3 и более поздних версий кривые определяются в EcCurve . Для Keymaster 2 и более ранних версий кривые определяются в keymaster_ec_curve_t .

Если запрос содержит и то, и другое, используйте кривую, указанную Tag::EC_CURVE , и убедитесь, что указанный размер ключа соответствует этой кривой. Если нет, верните ErrorCode::INVALID_ARGUMENT .

Тег::INCLUDE_UNIQUE_ID

Версия : 2, 3, 4

Повторяемый ? Нет

Этот тег указывается во время создания ключа, чтобы указать, что сертификат аттестации для сгенерированного ключа должен содержать уникальный идентификатор устройства в области приложения и с ограниченным временем, как указано в Tag::UNIQUE_ID .

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Тег::KEY_SIZE

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает размер ключа в битах, измеряемый обычным способом для алгоритма ключа. Например, для ключей RSA Tag::KEY_SIZE указывает размер общедоступного модуля. Для ключей AES он определяет длину материала секретного ключа.

Тег::MAC_LENGTH

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Предоставляет запрошенную длину тега аутентификации MAC или GCM в битах.

Значение представляет собой длину MAC в битах. Оно кратно 8 и по крайней мере равно значению Tag::MIN_MAC_LENGTH, связанному с ключом.

Тег::MAX_USES_PER_BOOT

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает максимальное количество раз, которое ключ можно использовать между перезагрузками системы. Это еще один механизм ограничения скорости использования ключей.

Значение представляет собой 32-битное целое число, обозначающее использование за одну загрузку.

Когда ключ с этим тегом используется в операции, счетчик, связанный с ключом, должен быть увеличен во время начального вызова. После того, как счетчик ключа превысил это значение, все последующие попытки использовать ключ завершаются с ошибкой ErrorCode::MAX_OPS_EXCEEDED до тех пор, пока устройство не будет перезапущено. Это означает, что трастлет хранит таблицу счетчиков использования ключей с этим тегом. Поскольку память Keymaster часто ограничена, эта таблица может иметь фиксированный максимальный размер, и Keymaster может не выполнить операции, пытающиеся использовать ключи с этим тегом, когда таблица заполнена. Стол должен вмещать не менее 16 ключей. Если операция завершается неудачно из-за того, что таблица заполнена, Keymaster возвращает ErrorCode::TOO_MANY_OPERATIONS .

Тег::MIN_MAC_LENGTH

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Этот тег определяет минимальную длину MAC, который может быть запрошен или проверен с помощью этого ключа для ключей HMAC и ключей AES, поддерживающих режим GCM.

Это значение представляет собой минимальную длину MAC в битах. Оно кратно 8. Для ключей HMAC значение не менее 64. Для ключей GCM значение не менее 96 и не более 128.

Тег::MIN_SECONDS_BETWEEN_OPS

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает минимальное время, которое проходит между разрешенными операциями с использованием ключа. Это можно использовать для ограничения скорости использования ключей в контекстах, где неограниченное использование может привести к атакам методом перебора.

Значение представляет собой 32-битное целое число, представляющее секунды между разрешенными операциями.

Если ключ с этим тегом используется в операции, запустите таймер во время вызова завершения или отмены . Любой вызов начала , полученный до того, как таймер укажет, что интервал, указанный Tag::MIN_SECONDS_BETWEEN_OPS , истек, завершается с ошибкой ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Это означает, что трастлет хранит таблицу счетчиков использования ключей с этим тегом. Поскольку память Keymaster часто ограничена, эта таблица может иметь фиксированный максимальный размер, и Keymaster может не выполнить операции, пытающиеся использовать ключи с этим тегом, когда таблица заполнена. Таблица должна вмещать как минимум 32 используемых ключа и активно повторно использовать слоты таблицы по истечении минимального интервала использования ключей. Если операция завершается неудачно из-за того, что таблица заполнена, Keymaster возвращает ErrorCode::TOO_MANY_OPERATIONS .

Тег::NO_AUTH_REQUIRED

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает, что для использования этого ключа аутентификация не требуется. Этот тег является взаимоисключающим с Tag::USER_SECURE_ID .

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Тег::NONCE

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Предоставляет или возвращает одноразовый номер или вектор инициализации (IV) для шифрования или дешифрования AES GCM, CBC или CTR. Этот тег предоставляется для начала операций шифрования и дешифрования. Это возможно только в том случае, если ключ имеет Tag::CALLER_NONCE . Если он не указан, Keymaster случайным образом генерирует соответствующий nonce или IV и возвращает его с начала.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины. Допустимая длина зависит от режима: одноразовые номера GCM имеют длину 12 байт; CBC и CTR IV имеют длину 16 байт.

Тег::ОРИГИН

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает, где был создан ключ, если он известен. Этот тег нельзя указать во время создания или импорта ключа, и он должен быть добавлен трастлетом к ключевым характеристикам.

Ключник 3

Возможные значения определены в android::hardware::keymaster::v3_0::KeyOrigin : 

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 и более ранние версии

Возможные значения определены в keymaster_origin_t : 

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

Полное значение значения зависит не только от значения, но и от того, находится ли оно в списке характеристик, реализованных аппаратно или программно.

GENERATED указывает, что Keymaster сгенерировал ключ. Если ключ находится в списке аппаратно принудительного применения, значит, ключ был сгенерирован на защищенном оборудовании и постоянно привязан к оборудованию. Если он находится в программно-принудительном списке, значит, ключ был сгенерирован в SoftKeymaster и не привязан к аппаратному обеспечению.

DERIVED указывает, что ключ был получен внутри Keymaster. Вероятно, существует за пределами устройства.

IMPORTED указывает, что ключ был сгенерирован вне Keymaster и импортирован в Keymaster. Если он находится в списке принудительного аппаратного обеспечения, он постоянно привязан к аппаратному обеспечению, хотя могут существовать копии за пределами защищенного оборудования. Если в списке принудительного применения программного обеспечения ключ был импортирован в SoftKeymaster и не привязан к аппаратному обеспечению.

UNKNOWN должно появляться только в списке аппаратных ограничений. Это указывает на то, что ключ привязан к аппаратному обеспечению, но неизвестно, был ли ключ изначально сгенерирован на защищенном оборудовании или был импортирован. Это происходит только в том случае, если оборудование keymaster0 используется для эмуляции служб keymaster1.

Тег::ORIGINATION_EXPIRE_DATETIME

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает дату и время истечения срока действия ключа для целей подписи и шифрования. По истечении этого времени любая попытка использовать ключ с KeyPurpose::SIGN или KeyPurpose::ENCRYPT, предоставленный для начала, завершается неудачно с ErrorCode::KEY_EXPIRED .

Значение представляет собой 64-битное целое число, представляющее миллисекунды с 1 января 1970 года.

Тег::OS_PATCHLEVEL

Версия : 2, 3, 4

Повторяемый ? Нет

Этот тег никогда не отправляется ТА мастера ключей, но добавляется ТА в список аппаратной авторизации.

Значение тега — целое число в формате ГГГГММ, где ГГГГ — четырехзначный год последнего обновления, а ММ — двухзначный месяц последнего обновления. Например, для ключа, созданного на устройстве Android, последний раз обновленного в декабре 2015 года, значение будет 201512.

Ключи, уровень исправления которых отличается от текущего уровня исправления, использовать нельзя. Попытка использовать такой ключ приводит к тому, что Begin , getKeyCharacteristics или ExportKey возвращают ErrorCode::KEY_REQUIRES_UPGRADE . Дополнительные сведения см. в разделе Привязка версий .

Тег::OS_VERSION

Версия : 2, 3, 4

Повторяемый ? Нет

Этот тег никогда не отправляется ТА мастера ключей, но добавляется ТА в список аппаратной авторизации.

Значение тега представляет собой целое число в форме MMmmss, где MM — основной номер версии, mm — дополнительный номер версии, а ss — дополнительный номер версии. Например, для ключа, созданного в Android версии 4.0.3, значение будет 040003.

Тег::ПАДИНГ

Версия : 1, 2, 3, 4

Повторяемый ? Да

Указывает режимы заполнения, которые можно использовать с ключом. Этот тег относится к ключам RSA и AES.

Возможные значения определяются следующим перечислением:

Ключник 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 и более ранние версии
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 и PaddingMode::RSA_PKCS1_1_5_ENCRYPT используются только для ключей шифрования/дешифрования RSA и определяют заполнение RSA PKCS#1v2 OAEP и рандомизированное заполнение RSA PKCS#1 v1.5 соответственно. PaddingMode::RSA_PSS и PaddingMode::RSA_PKCS1_1_5_SIGN используются только для ключей подписи/проверки RSA и определяют заполнение PSS RSA PKCS#1v2 и детерминированное заполнение RSA PKCS#1 v1.5 соответственно.

PaddingMode::NONE можно использовать с ключами RSA или AES. Для ключей AES, если PaddingMode::NONE используется с блочным режимом ECB или CBC, а длина данных, подлежащих шифрованию или дешифрованию, не кратна размеру блока AES, вызов завершения завершается с ошибкой ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 можно использовать только с ключами AES и только с режимами ECB и CBC.

Этот тег повторяемый. Режим заполнения должен быть указан в вызове Begin . Если указанный режим не авторизован для ключа, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Тег::ЦЕЛЬ

Версия : 1, 2, 3, 4

Повторяемый ? Да

Указывает набор целей, для которых можно использовать ключ.

Возможные значения определяются следующим перечислением:

Ключник 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 и более ранние версии
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Этот тег повторяемый; ключи могут генерироваться с несколькими значениями, хотя операция имеет одну цель. Когда функция Begin вызывается для запуска операции, указывается цель операции. Если цель, указанная в операции, не авторизована ключом, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_PURPOSE .

Тег::RESET_SINCE_ID_ROTATION

Версия : 3, 4

Повторяемый ? Нет

Указывает, был ли выполнен сброс настроек устройства до заводских настроек с момента последней смены уникального идентификатора. Используется для аттестации ключей.

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Тег::ROLLBACK_RESISTANT

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает, что ключ устойчив к откату. Это означает, что при удалении с помощью deleteKey или deleteAllKeys ключ гарантированно будет удален навсегда и станет непригодным для использования. Возможно, ключи без этого тега можно будет удалить, а затем восстановить из резервной копии.

Этот тег является логическим, поэтому возможные значения — true (если тег присутствует) и false (если тег отсутствует).

Тег::ROOT_OF_TRUST

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает корень доверия — ключ, используемый проверяемой загрузкой для проверки загруженной операционной системы (если таковая имеется). Этот тег никогда не передается и не возвращается от Keymaster в ключевых характеристиках.

Тег::RSA_PUBLIC_EXPONENT

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает значение общедоступного показателя степени для пары ключей RSA. Этот тег относится только к ключам RSA и необходим для всех ключей RSA.

Значение представляет собой 64-битное целое число без знака, которое удовлетворяет требованиям общедоступного показателя RSA. Это значение должно быть простым числом. Трастлеты поддерживают значение 2^16+1 и могут поддерживать другие разумные значения, в частности значение 3. Если показатель степени не указан или если указанный показатель степени не поддерживается, генерация ключа завершается с ошибкой ErrorCode::INVALID_ARGUMENT .

Тег::UNIQUE_ID

Версия : 3, 4

Повторяемый ? Нет

Используется для предоставления уникального идентификатора при подтверждении.

Значение представляет собой большой двоичный объект, массив байтов произвольной длины.

Тег::USAGE_EXPIRE_DATETIME

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает дату и время истечения срока действия ключа для целей проверки и дешифрования. По истечении этого времени любая попытка использовать ключ с KeyPurpose::VERIFY или KeyPurpose::DECRYPT, предоставленный для начала, завершается неудачей с ErrorCode::KEY_EXPIRED .

Значение представляет собой 64-битное целое число, представляющее миллисекунды с 1 января 1970 года.

Тег::USER_AUTH_TYPE

Версия : 1, 2, 3, 4

Повторяемый ? Нет

Указывает типы средств аутентификации пользователей, которые можно использовать для авторизации этого ключа. Когда Keymaster запрашивают выполнение операции с ключом с этим тегом, он получает токен аутентификации, а поле authenticator_type токена должно совпадать со значением в теге. Например, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , где ntoh — это функция, которая преобразует целые числа, упорядоченные по сети, в целые числа, упорядоченные по хосту, а auth_type_tag_value — это значение этого тега.

Значение представляет собой 32-битную целочисленную битовую маску значений из перечисления:

Ключник 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 и более ранние версии 
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;

Тег::USER_SECURE_ID

Версия : 1, 2, 3, 4

Повторяемый ? Да

Указывает, что ключ можно использовать только в определенном безопасном состоянии аутентификации пользователя. Этот тег является взаимоисключающим с Tag::NO_AUTH_REQUIRED .

Значение представляет собой 64-битное целое число, определяющее значение состояния политики аутентификации, которое должно присутствовать в токене аутентификации (предоставляемом в начале Tag::AUTH_TOKEN ), чтобы авторизовать использование ключа. Любой вызов, начинающийся с ключа с этим тегом, который не предоставляет токен аутентификации или предоставляет токен аутентификации без соответствующего значения состояния политики, завершается неудачно.

Этот тег повторяемый. Если какое-либо из предоставленных значений соответствует любому значению состояния политики в токене аутентификации, ключ разрешен для использования. В противном случае операция завершается с ошибкой ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Тег::VENDOR_PATCHLEVEL

Версия : 4

Этот тег определяет уровень исправления безопасности образа поставщика, с которым можно использовать ключ. Этот тег никогда не отправляется ТА мастера ключей, но добавляется ТА в список аппаратной авторизации. Любая попытка использовать ключ со значением Tag::VENDOR_PATCHLEVEL отличным от текущего уровня исправления системы, должна привести к тому, что begin() , getKeyCharacteristics() или exportKey() вернет ErrorCode::KEY_REQUIRES_UPGRADE . Подробности смотрите в upgradeKey() .

Значение тега — целое число в формате ГГГГММДД, где ГГГГ — четырехзначный год последнего обновления, ММ — двухзначный месяц, а ДД — двухзначный день последнего обновления. Например, для ключа, созданного на устройстве Android, последний раз обновленного 5 июня 2018 г., значение будет 20180605.

IKeymasterDevice HAL должен прочитать текущий уровень исправлений поставщика из системного свойства ro.vendor.build.security_patch и доставить его в безопасную среду при первой загрузке HAL (механизм определяется реализацией). Безопасная среда не должна принимать новый уровень исправлений до следующей загрузки.

Должно быть реализовано аппаратно.