keymaster2_device Справочник по структуре

keymaster2_device Справочник по структуре

#include < keymaster2.h >

Поля данных

структура hw_device_t общий
пустота * контекст
uint32_t флаги
keymaster_error_t (* настроить )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy )(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
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_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)
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_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)
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)
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_error_t (* delete_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)
keymaster_error_t (* delete_all_keys )(const struct keymaster2_device *dev)
keymaster_error_t (* begin )(const struct keymaster2_device *dev, keymaster_цель_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)
keymaster_error_t (* update )(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)
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)
keymaster_error_t (* abort )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

Подробное описание

Определение устройства 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 (* begin)(const struct keymaster2_device *dev, keymaster_purpose_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. Для операций, требующих одноразового номера или IV, для ключей, сгенерированных с помощью KM_TAG_CALLER_NONCE, in_params может содержать тег KM_TAG_NONCE.
[вне] out_params Выходные параметры. Используется для возврата дополнительных данных из инициализации операции, в частности, для возврата IV или одноразового номера из операций, которые генерируют IV или одноразовый номер. Вызывающий становится владельцем массива выходных параметров и должен освободить его с помощью 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_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) (конструкция 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)

Создает ключ или пару ключей, возвращая большой двоичный объект ключа и/или описание ключа.

Параметры генерации ключей определяются как пары тег/значение мастера ключей, указанные в params . См. keymaster_tag_t для полного списка. Вот некоторые значения, которые всегда требуются для генерации полезных ключей:

  • KM_TAG_ALGORITHM;
  • 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 должны быть указаны для алгоритмов, которые их требуют.

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

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Параметры
[в] разработчик Структура устройства keymaster.
[в] параметры Массив параметров генерации ключа
[вне] key_blob возвращает сгенерированный ключ. key_blob не должен быть NULL. Вызывающий объект принимает на себя владение key_blob->key_material и должен использовать его free().
[вне] характеристики возвращает характеристики сгенерированного ключа, если он не равен 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, если они не связаны.
[вне] характеристики Ключевые характеристики. Не должно быть 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)

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

Большинство ключевых параметров импорта определяются как пары тег/значение мастера ключей, указанные в «params». См. keymaster_tag_t для полного списка. Значения, которые всегда требуются для импорта полезных ключей:

  • KM_TAG_ALGORITHM;
  • 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).

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

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Параметры
[в] разработчик Структура устройства keymaster.
[в] параметры Параметры, определяющие импортируемый ключ.
[в] params_count Количество записей в params .
[в] key_format определяет формат данных ключа в 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 (* update)(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() может не предоставлять никакого вывода, и в этом случае output->data_length будет равен нулю, а output->data может быть либо NULL, либо нулевой длины (поэтому вызывающая сторона всегда должна использовать free()).

Определение в строке 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 потребуются, если они были определены для ключа.
[вне] модернизированный_ключ Обновленный ключевой BLOB-объект.

Определение в строке 260 файла keymaster2.h .


Документация для этой структуры была сгенерирована из следующего файла:
  • оборудование/libhardware/include/оборудование/ keymaster2.h