На этой странице представлены сведения, которые помогут разработчикам HAL Keymaster. Он охватывает каждый тег в 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
Повторяемый ? Нет
Указывает криптографический алгоритм, с которым используется ключ.
Возможные значения определяются следующим перечислением:
Keymaster 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
Повторяемый ? Нет
Предоставляет токен аутентификации для begin , update или finish , чтобы подтвердить аутентификацию пользователя для операции с ключом, для которой он требуется (ключ имеет Tag::USER_SECURE_ID ).
Значение представляет собой большой двоичный объект, содержащий структуру hw_auth_token_t .
Тег::BLOB_USAGE_REQUIREMENTS
Версия : 1, 2, 3, 4
Повторяемый ? Нет
Указывает необходимые условия системной среды для использования сгенерированного ключа.
Возможные значения определяются следующим перечислением:
Keymaster 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 , трастлет возвращает ключевой BLOB-объект, который можно использовать без поддержки файловой системы. Это очень важно для устройств с зашифрованными дисками, где файловая система может быть недоступна до тех пор, пока для расшифровки диска не будет использован мастер-ключ.
Тег::BLOCK_MODE
Версия : 1, 2, 3, 4
Повторяемый ? Да
Определяет режим(ы) блочного шифра, с которым может использоваться ключ. Этот тег относится только к ключам AES.
Возможные значения определяются следующим перечислением:
Keymaster 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 функции begin . Если указанный режим не находится в режимах, связанных с ключом, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Тег::BOOT_PATCHLEVEL
Версия : 4
Tag::BOOT_PATCHLEVEL указывает уровень исправления безопасности загрузочного образа (ядра), с которым может использоваться ключ. Этот тег никогда не отправляется мастеру ключей TA, но добавляется TA в список аппаратно-принудительной авторизации. Любая попытка использовать ключ со значением 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.
Возможные значения определяются следующим перечислением:
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 и более ранние версии
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 функции begin . Если указанный дайджест отсутствует в дайджестах, связанных с ключом, операция завершается с ошибкой ErrorCode::INCOMPATIBLE_DIGEST .
Тег::EC_CURVE
Версия : 2, 3, 4
Повторяемый ? Нет
В Keymaster 1 кривая, используемая для ключей EC, была угадана по указанному размеру ключа. Чтобы улучшить гибкость в будущем, Keymaster 2 представила явный способ указания кривых. Запросы на создание ключа EC могут иметь Tag::EC_CURVE , Tag::KEY_SIZE или оба.
Возможные значения определяются следующим перечислением:
Keymaster 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-разрядное целое число, представляющее секунды между разрешенными операциями.
Когда ключ с этим тегом используется в операции, запускайте таймер во время завершения или прерывания вызова. Любой вызов begin , полученный до того, как таймер укажет, что интервал, указанный 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 (если тег отсутствует).
Тег:: НЕТ
Версия : 1, 2, 3, 4
Повторяемый ? Нет
Предоставляет или возвращает одноразовый номер или вектор инициализации (IV) для шифрования или дешифрования AES GCM, CBC или CTR. Этот тег предоставляется для начала во время операций шифрования и дешифрования. Он предоставляется только для начала , если ключ имеет Tag::CALLER_NONCE . Если он не указан, Keymaster случайным образом сгенерирует соответствующий одноразовый номер или 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
Повторяемый ? Нет
Этот тег никогда не отправляется мастеру ключей TA, но добавляется TA в список аппаратно-принудительной авторизации.
Значение тега представляет собой целое число в формате ГГГГММ, где ГГГГ — четырехзначный год последнего обновления, а ММ — двузначный месяц последнего обновления. Например, для ключа, сгенерированного на устройстве Android, последний раз обновленного в декабре 2015 года, значение будет 201512.
Ключи с уровнем исправления, отличным от текущего уровня исправления, использовать нельзя. Попытка использовать такой ключ приводит к тому, что begin , getKeyCharacteristics или exportKey возвращают ErrorCode::KEY_REQUIRES_UPGRADE . Дополнительные сведения см. в разделе Привязка версий .
Тег::OS_VERSION
Версия : 2, 3, 4
Повторяемый ? Нет
Этот тег никогда не отправляется мастеру ключей TA, но добавляется TA в список аппаратно-принудительной авторизации.
Значение тега представляет собой целое число в форме MMmmss, где MM — основной номер версии, mm — дополнительный номер версии, а ss — дополнительный дополнительный номер версии. Например, для ключа, сгенерированного на Android версии 4.0.3, значение будет 040003.
Тег::ЗАПОЛНЕНИЕ
Версия : 1, 2, 3, 4
Повторяемый ? Да
Определяет режимы заполнения, которые могут использоваться с ключом. Этот тег относится к ключам RSA и AES.
Возможные значения определяются следующим перечислением:
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 и более ранние версии
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 и определяют заполнение OAEP RSA PKCS#1v2 и рандомизированное заполнение 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
Повторяемый ? Да
Определяет набор целей, для которых может использоваться ключ.
Возможные значения определяются следующим перечислением:
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 и более ранние версии
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-битную целочисленную битовую маску значений из перечисления:
Keymaster 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
Этот тег указывает уровень исправления безопасности образа поставщика, с которым может использоваться ключ. Этот тег никогда не отправляется мастеру ключей TA, но добавляется TA в список аппаратно-принудительной авторизации. Любая попытка использовать ключ со значением Tag::VENDOR_PATCHLEVEL , отличным от текущего уровня исправлений системы, должна привести к тому, что begin() , getKeyCharacteristics() или exportKey() вернут ErrorCode::KEY_REQUIRES_UPGRADE . Подробности смотрите в разделе upgradeKey() .
Значение тега представляет собой целое число в форме ГГГГММДД, где ГГГГ — четырехзначный год последнего обновления, ММ — двузначный месяц и ДД — двузначный день последнего обновления. Например, для ключа, созданного на устройстве Android и последний раз обновленного 5 июня 2018 г., значение будет 20180605.
HAL IKeymasterDevice должен прочитать текущий уровень исправления поставщика из системного свойства ro.vendor.build.security_patch и доставить его в безопасную среду при первой загрузке HAL (механизм определяется реализацией). Безопасная среда не должна принимать другой уровень исправлений до следующей загрузки.
Должен быть аппаратным.