keymaster2_device Справочник по структуре
#include < keymaster2.h >
Подробное описание
Определение устройства Keymaster2
Определение в строке 28 файла keymaster2.h .
Полевая документация
| keymaster_error_t (* abort)(const struct keymaster2_device *dev, keymaster_operation_handle_t Operation_handle) |
Прерывает криптографическую операцию, начатую с помощью Begin() , освобождая все внутренние ресурсы и делая недействительной operation_handle .
Определение в строке 415 файла keymaster2.h .
| keymaster_error_t (* add_rng_entropy) (const struct keymaster2_device *dev, const uint8_t *data, size_t data_length) |
Добавляет энтропию к ГСЧ, используемому мастером ключей. Энтропия, добавляемая с помощью этого метода, гарантированно не будет единственным используемым источником энтропии, а функция смешивания должна быть безопасной в том смысле, что если в ГСЧ (из любого источника) заполняют любые данные, которые злоумышленник не может предсказать (или контроль), то выходной сигнал ГСЧ неотличим от случайного. Таким образом, если энтропия из любого источника хороша, выход будет хорошим.
- Параметры
[в] разработчик Структура устройства keymaster. [в] данные Случайные данные для смешивания. [в] длина_данных Длина data.
Определение в строке 74 файла keymaster2.h .
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
Создает подписанную цепочку сертификатов X.509, подтверждающую наличие key_to_attest в мастере ключей (TODO(swillden): опишите содержимое сертификата более подробно). Сертификат будет содержать расширение с OID 1.3.6.1.4.1.11129.2.1.17 и значением, определенным в <TODO:swillden – вставьте ссылку здесь>, которое содержит описание ключа.
- Параметры
[в] разработчик Структура устройства keymaster. [в] key_to_attest Главный ключ, для которого будет создан сертификат аттестации. [в] attest_params Параметры, определяющие способ выполнения аттестации. В настоящее время единственным параметром является KM_TAG_ALGORITHM, который должен быть либо KM_ALGORITHM_EC, либо KM_ALGORITHM_RSA. При этом выбирается, какой из предоставленных ключей аттестации будет использоваться для подписи сертификата. [вне] cert_chain Массив сертификатов X.509 в кодировке DER. Первым будет сертификат для key_to_attest. Остальные записи вернутся к корню. Вызывающий объект становится владельцем и должен освободить его с помощью keymaster_free_cert_chain.
Определение в строке 239 файла keymaster2.h .
| keymaster_error_t (* начало)(const struct keymaster2_device *dev, keymaster_member_t Цель, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle) |
Начинает криптографическую операцию с использованием указанного ключа. Если все в порядке, метод Begin() вернет KM_ERROR_OK и создаст дескриптор операции, который необходимо будет передать последующим вызовам функций update() , Finish() или Abort() .
Крайне важно, чтобы каждый вызов Begin() был связан с последующим вызовом Finish() или Abort() , чтобы позволить реализации мастера ключей очистить любое внутреннее состояние операции. Невыполнение этого требования может привести к утечке внутреннего пространства состояний или других внутренних ресурсов и в конечном итоге может привести к тому, что метод Begin() вернет KM_ERROR_TOO_MANY_OPERATIONS, когда ему не хватает места для операций. Любой результат, отличный от KM_ERROR_OK от Begin() , update() или Finish() , неявно прерывает операцию, и в этом случае abort() не нужно вызывать (и при вызове она вернет KM_ERROR_INVALID_OPERATION_HANDLE).
- Параметры
[в] разработчик Структура устройства keymaster. [в] цель Цель операции: одна из KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN или KM_PURPOSE_VERIFY. Обратите внимание, что для режимов AEAD шифрование и дешифрование подразумевают подписание и проверку соответственно, но их следует указывать как KM_PURPOSE_ENCRYPT и KM_PURPOSE_DECRYPT. [в] ключ Ключ, который будет использоваться для операции. keyдолжен иметь назначение, совместимое сpurpose, и все требования к его использованию должны быть удовлетворены, иначе метод Begin() вернет соответствующий код ошибки.[в] in_params Дополнительные параметры для операции. Обычно это используется для предоставления данных аутентификации с помощью KM_TAG_AUTH_TOKEN. Если KM_TAG_APPLICATION_ID или KM_TAG_APPLICATION_DATA были предоставлены во время генерации, их необходимо указать здесь, иначе операция завершится неудачей с KM_ERROR_INVALID_KEY_BLOB. Для операций, требующих nonce или IV, для ключей, сгенерированных с помощью KM_TAG_CALLER_NONCE, in_params может содержать тег KM_TAG_NONCE. [вне] out_params Выходные параметры. Используется для возврата дополнительных данных из инициализации операции, в частности, для возврата IV или nonce из операций, которые генерируют IV или nonce. Вызывающая сторона становится владельцем массива выходных параметров и должна освободить его с помощью keymaster_free_param_set() . out_params может быть установлено в NULL, если выходные параметры не ожидаются. Если out_params имеет значение NULL и выходные параметры генерируются, метод Begin() вернет KM_ERROR_OUTPUT_PARAMETER_NULL. [вне] дескриптор операции Вновь созданный дескриптор операции, который необходимо передать в update() , Finish() или Abort() . Если Operation_handle имеет значение NULL, функция Begin() вернет KM_ERROR_OUTPUT_PARAMETER_NULL.
Определение в строке 332 файла keymaster2.h .
| структура hw_device_t общая |
Общие методы устройства keymaster. Это должен быть первый член keymaster_device, поскольку пользователи этой структуры будут приводить hw_device_t к указателю keymaster_device в контекстах, где известно, что hw_device_t ссылается на keymaster_device.
Определение в строке 35 файла keymaster2.h .
| keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
Настраивает мастер ключей. Этот метод необходимо вызвать один раз после открытия устройства и перед его использованием. Он используется для предоставления KM_TAG_OS_VERSION и KM_TAG_OS_PATCHLEVEL мастеру ключей. Пока этот метод не будет вызван, все остальные методы будут возвращать KM_ERROR_KEYMASTER_NOT_CONFIGURED. Значения, предоставленные этим методом, принимаются мастером ключей только один раз за загрузку. Последующие вызовы вернут KM_ERROR_OK, но ничего не сделают.
Если реализация мастера ключей находится на защищенном оборудовании и предоставленные значения версии ОС и уровня исправления не соответствуют значениям, предоставленным загрузчиком безопасному оборудованию (или если загрузчик не предоставил значения), тогда этот метод вернет KM_ERROR_INVALID_ARGUMENT, и все другие методы будут продолжать возвращать KM_ERROR_KEYMASTER_NOT_CONFIGURED.
Определение в строке 58 файла keymaster2.h .
| пустота* контекст |
Определение в строке 37 файла keymaster2.h .
| keymaster_error_t (* delete_all_keys) (const struct keymaster2_device *dev) |
Удаляет все ключи в аппаратном хранилище ключей. Используется при полном сбросе хранилища ключей. После вызова этой функции будет невозможно использовать ранее сгенерированные или импортированные объекты ключей для каких-либо операций.
Эта функция является необязательной и должна иметь значение NULL, если она не реализована.
- Параметры
[в] разработчик Структура устройства keymaster.
Определение в строке 288 файла keymaster2.h .
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
Удаляет ключ или пару ключей, связанные с большим количеством ключей. После вызова этой функции использовать ключ для каких-либо других операций будет невозможно. Может применяться к ключам из внешних корней доверия (ключи, которые нельзя использовать в текущем корне доверия).
Эта функция является необязательной и должна иметь значение NULL, если она не реализована.
- Параметры
[в] разработчик Структура устройства keymaster. [в] ключ Ключ, который нужно удалить.
Определение в строке 276 файла keymaster2.h .
| keymaster_error_t (*export_key)(const struct keymaster2_device *dev, keymaster_key_format_t Export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data) |
Экспортирует открытый или симметричный ключ, возвращая массив байтов в указанном формате.
Обратите внимание, что экспорт симметричного ключа разрешен только в том случае, если ключ был создан с помощью KM_TAG_EXPORTABLE и только в том случае, если соблюдены все требования к использованию ключа (например, аутентификация).
- Параметры
[в] разработчик Структура устройства keymaster. [в] экспортный_формат Формат, который будет использоваться для экспорта ключа. [в] key_to_export Ключ к экспорту. [в] ID клиента Большой двоичный объект идентификатора клиента, который должен совпадать с большим двоичным объектом, указанным в KM_TAG_APPLICATION_ID во время генерации ключа (если таковой имеется). [в] данные приложения Большой двоичный объект данных приложения, который должен соответствовать большому двоичному объекту, указанному в KM_TAG_APPLICATION_DATA во время генерации ключа (если таковой имеется). [вне] экспорт данных Экспортированный ключевой материал. Вызывающий принимает на себя право собственности.
Определение в строке 213 файла keymaster2.h .
| keymaster_error_t (* Finish) (const struct keymaster2_device *dev, keymaster_operation_handle_t Operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
Завершает криптографическую операцию, начатую с помощью Begin() , и делает недействительной operation_handle .
- Параметры
[в] разработчик Структура устройства keymaster. [в] дескриптор операции Дескриптор операции, возвращаемый функцией Begin() . Этот дескриптор будет признан недействительным. [в] in_params Дополнительные параметры для операции. Для режимов AEAD это используется для указания KM_TAG_ADDITIONAL_DATA, но только если для update() не было предоставлено входных данных. [в] вход Данные, подлежащие обработке, в соответствии с параметрами, установленными при вызове Begin() . Finish() должен использовать все предоставленные данные или вернуть KM_ERROR_INVALID_INPUT_LENGTH. [в] подпись Подпись, подлежащая проверке, если целью, указанной в вызове Begin(), была KM_PURPOSE_VERIFY. [вне] выход Выходные данные, если таковые имеются. Вызывающая сторона принимает на себя владение выделенным буфером.
Если завершаемая операция представляет собой проверку подписи или расшифровку в режиме AEAD и проверка не удалась, то метод Finish() вернет KM_ERROR_VERIFICATION_FAILED.
Определение в строке 405 файла keymaster2.h .
| uint32_t флаги |
См. флаги, определенные для keymaster0_devices::flags в keymaster_common.h . Используется только для обратной совместимости; Аппаратные устройства keymaster2 должны установить это значение на ноль.
Определение в строке 43 файла keymaster2.h .
| keymaster_error_t (*generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
Создает ключ или пару ключей, возвращая большой объект ключа и/или описание ключа.
Параметры генерации ключей определяются как пары тег/значение keymaster, указанные в params . Полный список см. в keymaster_tag_t. Некоторые значения, которые всегда необходимы для генерации полезных ключей:
- KM_TAG_АЛГОРИТМ;
- KM_TAG_PURPOSE; и
- (KM_TAG_USER_SECURE_ID и KM_TAG_USER_AUTH_TYPE) или KM_TAG_NO_AUTH_REQUIRED.
KM_TAG_AUTH_TIMEOUT обычно следует указывать, если не присутствует KM_TAG_NO_AUTH_REQUIRED, иначе пользователю придется проходить аутентификацию при каждом использовании.
KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH и KM_TAG_DIGEST должны быть указаны для алгоритмов, которые их требуют.
Следующие теги можно не указывать; их значения будут предоставлены реализацией.
- КМ_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Параметры
[в] разработчик Структура устройства keymaster. [в] параметры Массив параметров генерации ключей [вне] key_blob возвращает сгенерированный ключ. key_blobне должен иметь значение NULL. Вызывающая сторона принимает на себя владение ключом key_blob->key_material и должна освободить его().[вне] характеристики возвращает характеристики сгенерированного ключа, если оно не равно NULL. Если значение не NULL, вызывающая сторона принимает на себя владение и должна освободить память с помощью keymaster_free_characteristics() . Обратите внимание, что KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID и KM_TAG_APPLICATION_DATA никогда не возвращаются.
Определение в строке 112 файла keymaster2.h .
| keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *characteristics) |
Возвращает характеристики указанного ключа или KM_ERROR_INVALID_KEY_BLOB, если key_blob недействителен (реализации должны полностью проверять целостность ключа). client_id и app_data должны быть идентификатором и данными, предоставленными при создании или импорте ключа, или пустыми, если KM_TAG_APPLICATION_ID и/или KM_TAG_APPLICATION_DATA не были предоставлены во время генерации. Эти значения не включены в возвращаемые характеристики. Вызывающая сторона принимает на себя владение выделенным объектом характеристик, который необходимо освободить с помощью keymaster_free_characteristics() .
Обратите внимание, что KM_TAG_APPLICATION_ID и KM_TAG_APPLICATION_DATA никогда не возвращаются.
- Параметры
[в] разработчик Структура устройства keymaster. [в] key_blob Ключ для получения характеристик. [в] ID клиента Данные идентификатора клиента или NULL, если они не связаны. [в] app_id Данные приложения или NULL, если они не связаны. [вне] характеристики Ключевые характеристики. Не должно быть НУЛЕМ. Вызывающая сторона принимает на себя владение содержимым и должна освободить его с помощью keymaster_free_characteristics() .
Определение в строке 139 файла keymaster2.h .
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
Импортирует ключ или пару ключей, возвращая объект ключа и/или описание ключа.
Большинство ключевых параметров импорта определяются как пары тег/значение keymaster, указанные в разделе «params». Полный список см. в keymaster_tag_t. Значения, которые всегда необходимы для импорта полезных ключей:
- KM_TAG_АЛГОРИТМ;
- KM_TAG_PURPOSE; и
- (KM_TAG_USER_SECURE_ID и KM_TAG_USER_AUTH_TYPE) или KM_TAG_NO_AUTH_REQUIRED.
KM_TAG_AUTH_TIMEOUT обычно следует указывать. Если не указано, пользователю придется проходить аутентификацию при каждом использовании.
Следующие теги будут принимать значения по умолчанию, если они не указаны:
- KM_TAG_KEY_SIZE по умолчанию будет соответствовать размеру предоставленного ключа.
- KM_TAG_RSA_PUBLIC_EXPONENT по умолчанию будет использовать значение предоставленного ключа (для ключей RSA).
Следующие теги можно не указывать; их значения будут предоставлены реализацией.
- КМ_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Параметры
[в] разработчик Структура устройства keymaster. [в] параметры Параметры, определяющие импортируемый ключ. [в] params_count Количество записей в params.[в] ключевой_формат определяет формат ключевых данных в key_data. [вне] key_blob Используется для возврата непрозрачного ключа. Должно быть не NULL. Вызывающая сторона принимает на себя право собственности на содержащийся key_material. [вне] характеристики Используется для возврата характеристик импортированного ключа. Может быть NULL, и в этом случае никакие характеристики не будут возвращены. Если значение не NULL, вызывающая сторона принимает на себя право собственности на содержимое и должна освободить его с помощью keymaster_free_characteristics() . Обратите внимание, что KM_TAG_APPLICATION_ID и KM_TAG_APPLICATION_DATA никогда не возвращаются.
Определение в строке 186 файла keymaster2.h .
| keymaster_error_t (* обновление)(const struct keymaster2_device *dev, keymaster_operation_handle_t Operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
Предоставляет данные и, возможно, получает выходные данные для текущей криптографической операции, начатой с помощью Begin() .
Если Operation_handle недействителен, update() вернет KM_ERROR_INVALID_OPERATION_HANDLE.
update() может не использовать все данные, содержащиеся в буфере данных. update() вернет сумму, израсходованную в *data_consumed. Вызывающая сторона должна предоставить неиспользованные данные при последующем вызове.
- Параметры
[в] разработчик Структура устройства keymaster. [в] дескриптор операции Дескриптор операции, возвращаемый функцией Begin() . [в] in_params Дополнительные параметры для операции. Для режимов AEAD это используется для указания KM_TAG_ADDITIONAL_DATA. Обратите внимание, что дополнительные данные могут быть предоставлены в нескольких вызовах update() , но только до тех пор, пока не будут предоставлены входные данные. [в] вход Данные, подлежащие обработке, в соответствии с параметрами, установленными при вызове Begin() . Обратите внимание, что update() может использовать или не использовать все предоставленные данные. См. input_consumed.[вне] input_consumed Объем данных, который был использован update() . Если это меньше предоставленной суммы, вызывающая сторона должна предоставить остаток при последующем вызове update() . [вне] out_params Выходные параметры. Используется для возврата дополнительных данных из операции. Вызывающий становится владельцем массива выходных параметров и должен освободить его с помощью keymaster_free_param_set() . out_params может быть установлено в NULL, если выходные параметры не ожидаются. Если out_params имеет значение NULL и выходные параметры генерируются, метод Begin() вернет KM_ERROR_OUTPUT_PARAMETER_NULL. [вне] выход Выходные данные, если таковые имеются. Вызывающая сторона принимает на себя владение выделенным буфером. вывод не должен быть NULL.
Обратите внимание, что update() может не предоставлять никаких выходных данных, и в этом случае выход->data_length будет нулевым, а выход->данные могут иметь либо NULL, либо нулевую длину (поэтому вызывающий всегда должен освободить() его).
Определение в строке 376 файла keymaster2.h .
| keymaster_error_t (*upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key) |
Обновляет старый ключ. Ключи могут стать «старыми» двумя способами: Keymaster можно обновить до новой версии или систему можно обновить, чтобы сделать недействительной версию ОС и/или уровень исправления. В любом случае попытки использовать старый ключ приведут к тому, что мастер ключей вернет KM_ERROR_KEY_REQUIRES_UPGRADE. Затем этот метод следует вызвать для обновления ключа.
- Параметры
[в] разработчик Структура устройства keymaster. [в] key_to_upgrade Главный ключ для обновления. [в] update_params Параметры, необходимые для завершения обновления. В частности, KM_TAG_APPLICATION_ID и KM_TAG_APPLICATION_DATA потребуются, если они были определены для ключа. [вне] обновленный_ключ Обновленный ключевой блок.
Определение в строке 260 файла keymaster2.h .
Документация для этой структуры была создана из следующего файла:
- Аппаратное обеспечение/libhardware/include/hardware/ keymaster2.h