Функции мастера ключей

На этой странице представлены сведения, которые помогут разработчикам уровней аппаратной абстракции Keymaster (HAL). В нем описывается каждая функция API, а также версия Keymaster, в которой эта функция доступна, и описывается реализация по умолчанию. Информацию о тегах см. на странице «Теги Keymaster» .

Общие рекомендации по внедрению

Следующие рекомендации применимы ко всем функциям API.

Входные параметры указателя

Версия : 1, 2

Параметры входного указателя, которые не используются для данного вызова, могут иметь значение NULL . Вызывающий объект не обязан предоставлять заполнители. Например, некоторые типы и режимы ключей могут не использовать значения из аргумента inParams для начала , поэтому вызывающая сторона может установить для inParams значение NULL или предоставить пустой набор параметров. Вызывающие программы также могут предоставлять неиспользуемые параметры, а методы Keymaster не должны выдавать ошибки.

Если обязательный входной параметр имеет значение NULL, методы Keymaster должны возвращать ErrorCode::UNEXPECTED_NULL_POINTER .

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

Параметры выходного указателя

Версия : 1, 2

Подобно параметрам входного указателя, неиспользуемые параметры выходного указателя могут иметь значение NULL . Если методу необходимо вернуть данные в выходном параметре, который имеет значение NULL , он должен вернуть ErrorCode::OUTPUT_PARAMETER_NULL .

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

неправильное использование API

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

Существует множество способов, с помощью которых вызывающие абоненты могут отправлять запросы, которые не имеют смысла или глупы, но не являются технически неправильными. В таких случаях реализации Keymaster не обязаны давать сбой или выдавать диагностику. Использование слишком маленьких ключей, указание нерелевантных входных параметров, повторное использование IV или одноразовых номеров, генерация ключей без цели (следовательно, бесполезно) и тому подобное не должны диагностироваться реализациями. Необходимо диагностировать пропуск обязательных параметров, указание неверных обязательных параметров и подобные ошибки.

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

Функции

getHardwareFeatures

Версия : 3

Новый метод getHardwareFeatures предоставляет клиентам некоторые важные характеристики базового защищенного оборудования. Метод не принимает аргументов и возвращает четыре значения, все логические:

  • isSecure имеет true , если ключи хранятся на защищенном оборудовании (TEE и т. д.) и никогда не покидают его.
  • supportsEllipticCurve имеет true , если оборудование поддерживает криптографию эллиптических кривых с кривыми NIST (P-224, P-256, P-384 и P-521).
  • supportsSymmetricCryptography имеет true , если оборудование поддерживает симметричную криптографию, включая AES и HMAC.
  • supportsAttestation имеет true , если оборудование поддерживает создание сертификатов аттестации открытого ключа Keymaster, подписанных ключом, внедренным в защищенную среду.

Единственные коды ошибок, которые может возвращать этот метод, — это ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED или один из кодов ошибок, указывающих на сбой связи с защищенным оборудованием.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

настроить

Версия : 2

Эта функция была введена в Keymaster 2 и устарела в Keymaster 3, поскольку эта информация доступна в файлах свойств системы, а реализации производителя читают эти файлы во время запуска.

Настраивает мастер ключей. Этот метод вызывается один раз после открытия устройства и перед его использованием. Он используется для предоставления 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 .

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

добавитьRngEntropy

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

Эта функция была представлена ​​в Keymaster 1 как add_rng_entropy и переименована в Keymaster 3.

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

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

Реализации Keymaster, которые пытаются оценить энтропию в своем внутреннем пуле, предполагают, что данные, предоставляемые addRngEntropy , не содержат энтропии. Реализации Keymaster могут возвращать ErrorCode::INVALID_INPUT_LENGTH , если им передается более 2 КиБ данных за один вызов.

генерировать ключ

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

Эта функция была представлена ​​в Keymaster 1 generate_key и переименована в Keymaster 3.

Создает новый криптографический ключ, определяя связанные авторизации, которые постоянно привязаны к ключу. Реализации Keymaster делают невозможным использование ключа каким-либо образом, несовместимым с авторизацией, указанной во время генерации. Что касается авторизаций, которые защищенное оборудование не может обеспечить, обязательства защищенного оборудования ограничиваются обеспечением того, чтобы неисполнимые авторизации, связанные с ключом, не могли быть изменены, чтобы каждый вызов getKeyCharacteristics возвращал исходное значение. Кроме того, характеристики, возвращаемые generateKey , правильно распределяют авторизации между аппаратными и программными списками. Дополнительные сведения см. в разделе getKeyCharacteristics .

Параметры, предоставляемые для generateKey , зависят от типа генерируемого ключа. В этом разделе приведены необходимые и дополнительные теги для каждого типа ключей. Тег::АЛГОРИТМ всегда необходим для указания типа.

Ключи RSA

Следующие параметры необходимы для генерации ключа RSA.

  • Tag::KEY_SIZE определяет размер общедоступного модуля в битах. Если этот параметр опущен, метод возвращает ErrorCode::UNSUPPORTED_KEY_SIZE . Поддерживаемые значения: 1024, 2048, 3072 и 4096. Рекомендуемые значения — это все размеры ключей, кратные 8.
  • Tag::RSA_PUBLIC_EXPONENT указывает значение публичного показателя степени RSA. Если этот параметр опущен, метод возвращает ErrorCode::INVALID_ARGUMENT . Поддерживаемые значения: 3 и 65537. Рекомендуемые значения — все простые значения до 2^64.

Следующие параметры не являются необходимыми для создания ключа RSA, но создание ключа RSA без них приводит к созданию непригодного для использования ключа. Однако generateKey не возвращает ошибку, если эти параметры опущены.

  • Тег::PURPOSE указывает разрешенные цели. Ключи RSA должны поддерживать все цели в любой комбинации.
  • Tag::DIGEST определяет алгоритмы дайджеста, которые можно использовать с новым ключом. Реализации, которые не поддерживают все алгоритмы дайджеста, должны принимать запросы на создание ключей, которые включают неподдерживаемые дайджесты. Неподдерживаемые дайджесты следует поместить в список «программно-принудительных» в возвращаемых ключевых характеристиках. Это связано с тем, что ключ можно использовать с другими дайджестами, но дайджест выполняется программно. Затем вызывается аппаратное обеспечение для выполнения операции с Digest::NONE .
  • Tag::PADDING определяет режимы заполнения, которые можно использовать с новым ключом. Реализации, которые не поддерживают все алгоритмы дайджеста, должны поместить PaddingMode::RSA_PSS и PaddingMode::RSA_OAEP в программно-обеспечиваемый список ключевых характеристик, если указаны какие-либо неподдерживаемые алгоритмы дайджеста.

Ключи ECDSA

Для генерации ключа ECDSA необходим только Tag::KEY_SIZE . Используется для выбора группы EC. Поддерживаемые значения: 224, 256, 384 и 521, что соответствует кривым NIST p-224, p-256, p-384 и p521 соответственно.

Tag::DIGEST также необходим для полезного ключа ECDSA, но не требуется для генерации.

Ключи AES

Для генерации ключа AES необходим только Tag::KEY_SIZE . Если этот параметр опущен, метод возвращает ErrorCode::UNSUPPORTED_KEY_SIZE . Поддерживаемые значения: 128 и 256, с дополнительной поддержкой 192-битных ключей AES.

Следующие параметры особенно важны для ключей AES, но не обязательны для их создания:

  • Tag::BLOCK_MODE определяет режимы блокировки, с которыми может использоваться новый ключ.
  • Tag::PADDING определяет режимы заполнения, которые можно использовать. Это актуально только для режимов ECB и CBC.

Если указан режим блока GCM, укажите Tag::MIN_MAC_LENGTH . Если этот параметр опущен, метод возвращает ErrorCode::MISSING_MIN_MAC_LENGTH . Значение тега кратно 8 и находится в диапазоне от 96 до 128.

HMAC-ключи

Для генерации ключа HMAC необходимы следующие параметры:

  • Тег::KEY_SIZE определяет размер ключа в битах. Значения меньше 64 и значения, не кратные 8, не поддерживаются. Поддерживаются все числа, кратные 8, от 64 до 512. Могут поддерживаться большие значения.
  • Tag::MIN_MAC_LENGTH определяет минимальную длину MAC-адресов, которые могут быть сгенерированы или проверены с помощью этого ключа. Значение кратно 8 и не менее 64.
  • Tag::DIGEST определяет алгоритм дайджеста для ключа. Указывается ровно один дайджест, в противном случае возвращается ErrorCode::UNSUPPORTED_DIGEST . Если дайджест не поддерживается трастлетом, верните ErrorCode::UNSUPPORTED_DIGEST .

Ключевые характеристики

Если аргумент характеристики не равен NULL, generateKey возвращает характеристики вновь сгенерированного ключа, разделенные соответствующим образом на списки, реализованные аппаратно и программно. См. getKeyCharacteristics для описания того, какие характеристики входят в какой список. Возвращаемые характеристики включают все параметры, указанные для генерации ключа, кроме Tag::APPLICATION_ID и Tag::APPLICATION_DATA . Если эти теги были включены в ключевые параметры, они удаляются из возвращаемых характеристик, чтобы невозможно было найти их значения, исследуя возвращенный ключевой объект. Однако они криптографически привязаны к ключевому блоку, поэтому, если при использовании ключа не будут предоставлены правильные значения, использование не удастся. Аналогично, Tag::ROOT_OF_TRUST криптографически привязан к ключу, но его нельзя указывать во время создания или импорта ключа и он никогда не возвращается.

В дополнение к предоставленным тегам трастлет также добавляет Tag::ORIGIN со значением KeyOrigin::GENERATED , и если ключ устойчив к откату,

Тег::ROLLBACK_RESISTANT .

Сопротивление откату

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

Ключ устойчив к откату, если защищенное оборудование гарантирует, что удаленные ключи не могут быть восстановлены позже. Обычно это делается путем хранения дополнительных метаданных ключа в надежном месте, которым злоумышленник не сможет манипулировать. На мобильных устройствах для этого обычно используется механизм Replay Protected Memory Blocks (RPMB). Поскольку количество ключей, которые могут быть созданы, по существу не ограничено, а размер доверенного хранилища, используемого для сопротивления откату, может быть ограничен, этот метод должен работать успешно, даже если для нового ключа невозможно обеспечить устойчивость к откату. В этом случае Tag::ROLLBACK_RESISTANT не следует добавлять к ключевым характеристикам.

getKeyCharacteristics

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

Эта функция была представлена ​​в Keymaster 1 как get_key_characteristics и переименована в Keymaster 3.

Возвращает параметры и полномочия, связанные с предоставленным ключом, разделенные на два набора: аппаратные и программные. Приведенное здесь описание в равной степени применимо к спискам ключевых характеристик, возвращаемым методамиgenerateKey и importKey .

Если Tag::APPLICATION_ID был указан во время создания или импорта ключа, то же значение передается этому методу в аргументе clientId . В противном случае метод возвращает ErrorCode::INVALID_KEY_BLOB . Аналогично, если Tag::APPLICATION_DATA был указан во время создания или импорта, то же значение передается этому методу в аргументе appData .

Характеристики, возвращаемые этим методом, полностью описывают тип и использование указанного ключа.

Общее правило принятия решения о том, принадлежит ли данный тег к списку с аппаратной или программной поддержкой, заключается в том, что если значение тега полностью гарантируется безопасным оборудованием, то он применяется аппаратно. В противном случае это принудительное программное обеспечение. Ниже приведен список конкретных тегов, правильное размещение которых может быть неясным:

  • Tag::ALGORITHM , Tag::KEY_SIZE и Tag::RSA_PUBLIC_EXPONENT являются внутренними свойствами ключа. Для любого ключа, защищенного аппаратно, эти теги будут в списке, защищенном аппаратно.
  • Значения Tag::DIGEST , поддерживаемые безопасным оборудованием, помещаются в список поддерживаемых оборудованием. Неподдерживаемые дайджесты попадают в список поддерживаемых программным обеспечением.
  • Значения Tag::PADDING обычно включаются в список, поддерживаемый аппаратным обеспечением, за исключением случаев, когда существует вероятность того, что определенный режим заполнения может потребоваться программно. В этом случае они попадают в список программно-принудительных действий. Такая возможность возникает для ключей RSA, которые допускают заполнение PSS или OAEP алгоритмами дайджеста, которые не поддерживаются защищенным оборудованием.
  • Tag::USER_SECURE_ID и Tag::USER_AUTH_TYPE применяются аппаратно, только если аутентификация пользователя осуществляется аппаратно. Для этого и трастлет Keymaster, и соответствующий трастлет аутентификации должны быть безопасными и совместно использовать секретный ключ HMAC, используемый для подписи и проверки токенов аутентификации. Подробности смотрите на странице Аутентификация .
  • Теги Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME и Tag ::USAGE_EXPIRE_DATETIME требуют доступа к проверяемым настенным часам. Большинство защищенного оборудования имеет доступ только к информации о времени, предоставляемой незащищенной ОС, что означает, что теги применяются программно.
  • Tag::ORIGIN всегда находится в списке оборудования для аппаратно-привязанных ключей. Его присутствие в этом списке — это способ, которым более высокие уровни определяют, что ключ поддерживается аппаратно.

importKey

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

Эта функция была представлена ​​в Keymaster 1 как import_key и переименована в Keymaster 3.

Импортирует ключевой материал в оборудование Keymaster. Параметры определения ключа и выходные характеристики обрабатываются так же, как и generateKey , со следующими исключениями:

  • Tag::KEY_SIZE и Tag::RSA_PUBLIC_EXPONENT (только для ключей RSA) не требуются во входных параметрах. Если он не указан, трастлет выводит значения из предоставленного ключевого материала и добавляет соответствующие теги и значения к ключевым характеристикам. Если параметры предоставлены, трастлет проверяет их на соответствие ключевому материалу. В случае несоответствия метод возвращает ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Возвращенный Tag::ORIGIN имеет то же значение, что и KeyOrigin::IMPORTED .

экспортный ключ

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

Эта функция была представлена ​​в Keymaster 1 как export_key и переименована в Keymaster 3.

Экспортирует открытый ключ из пары ключей Keymaster RSA или EC.

Если Tag::APPLICATION_ID был указан во время создания или импорта ключа, то же значение передается этому методу в аргументе clientId . В противном случае метод возвращает ErrorCode::INVALID_KEY_BLOB . Аналогично, если Tag::APPLICATION_DATA был указан во время создания или импорта, то же значение передается этому методу в аргументе appData .

удалить ключ

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

Эта функция была представлена ​​в Keymaster 1 как delete_key и переименована в Keymaster 3.

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

удалитьAllKeys

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

Эта функция была представлена ​​в Keymaster 1 как delete_all_keys и переименована в Keymaster 3.

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

уничтожитьAttestationIds

Версия : 3

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

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

начинать

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

Начинает криптографическую операцию с использованием указанного ключа для указанной цели с указанными параметрами (при необходимости) и возвращает дескриптор операции, который используется с обновлением и завершением для завершения операции. Дескриптор операции также используется в качестве токена «вызова» в операциях с аутентификацией и для таких операций включается в поле challenge токена аутентификации.

Реализация Keymaster поддерживает как минимум 16 одновременных операций. Хранилище ключей использует до 15, оставляя один для использования для шифрования пароля. Когда в хранилище ключей выполняется 15 операций ( begin было вызвано, но finish или abort еще не были вызваны) и он получает запрос на начало 16-й операции, он вызывает abort последней использованной операции, чтобы уменьшить количество активных операций. до 14, прежде чем вызов begin запускать новую запрошенную операцию.

Если Tag::APPLICATION_ID или Tag::APPLICATION_DATA были указаны во время создания или импорта ключа, вызовы begin включают те теги с первоначально указанными значениями в аргументе inParams этого метода.

Обеспечение выполнения разрешений

Во время этого метода следующие авторизации ключей применяются трастлетом, если реализация поместила их в «аппаратно-принудительные» характеристики и если операция не является операцией с открытым ключом. Операции с открытым ключом, то есть KeyPurpose::ENCRYPT и KeyPurpose::VERIFY с ключами RSA или EC, могут выполняться успешно, даже если требования авторизации не выполнены.

  • Tag::PURPOSE : Цель, указанная в вызове begin() должна соответствовать одной из целей авторизации ключа, если только запрошенная операция не является операцией с открытым ключом. Если указанная цель не совпадает и операция не является операцией с открытым ключом, begin вернет ErrorCode::UNSUPPORTED_PURPOSE . Операции с открытым ключом — это операции асимметричного шифрования или проверки.
  • Tag::ACTIVE_DATETIME можно применить только в том случае, если доступен надежный источник времени в формате UTC. Если текущая дата и время предшествуют значению тега, метод возвращает ErrorCode::KEY_NOT_YET_VALID .
  • Tag::ORIGINATION_EXPIRE_DATETIME может быть применен только в том случае, если доступен надежный источник времени в формате UTC. Если текущая дата и время позже значения тега и целью является KeyPurpose::ENCRYPT или KeyPurpose::SIGN , метод возвращает ErrorCode::KEY_EXPIRED .
  • Tag::USAGE_EXPIRE_DATETIME может быть применен только в том случае, если доступен надежный источник времени в формате UTC. Если текущая дата и время позже значения тега и целью является KeyPurpose::DECRYPT или KeyPurpose::VERIFY , метод возвращает ErrorCode::KEY_EXPIRED .
  • Tag::MIN_SECONDS_BETWEEN_OPS сравнивается с доверенным относительным таймером, указывающим последнее использование ключа. Если время последнего использования плюс значение тега меньше текущего времени, метод возвращает ErrorCode::KEY_RATE_LIMIT_EXCEEDED . См. описание тега для получения важных деталей реализации.
  • Tag::MAX_USES_PER_BOOT сравнивается с безопасным счетчиком, который отслеживает использование ключа с момента загрузки. Если количество предыдущих использований превышает значение тега, метод возвращает ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Tag::USER_SECURE_ID применяется этим методом только в том случае, если ключ также имеет Tag::AUTH_TIMEOUT . Если ключ имеет оба, этот метод должен получить действительный Tag::AUTH_TOKEN в inParams . Чтобы токен аутентификации был действительным, должно выполняться все следующее:
    • Поле HMAC проверяется правильно.
    • По крайней мере одно из значений Tag::USER_SECURE_ID из ключа соответствует хотя бы одному из значений безопасного идентификатора в токене.
    • Ключ имеет тег::USER_AUTH_TYPE , соответствующий типу аутентификации в токене.

    Если какое-либо из этих условий не выполнено, метод возвращает ErrorCode::KEY_USER_NOT_AUTHENTICATED .

  • Tag::CALLER_NONCE позволяет вызывающей стороне указать nonce или вектор инициализации (IV). Если ключ не имеет этого тега, но вызывающая сторона предоставила этому методу Tag::NONCE , возвращается ErrorCode::CALLER_NONCE_PROHIBITED .
  • Тег::BOOTLOADER_ONLY указывает, что ключ может использовать только загрузчик. Если этот метод вызывается с ключом, предназначенным только для загрузчика, после завершения работы загрузчика, он возвращает ErrorCode::INVALID_KEY_BLOB .

Ключи RSA

Все ключевые операции RSA указывают ровно один режим заполнения в inParams . Если не указано или указано более одного раза, метод возвращает ErrorCode::UNSUPPORTED_PADDING_MODE .

Для операций подписи и проверки RSA требуется дайджест, как и для операций шифрования и дешифрования RSA с режимом заполнения OAEP. В этих случаях вызывающая сторона указывает ровно один дайджест в inParams . Если не указано или указано более одного раза, метод возвращает ErrorCode::UNSUPPORTED_DIGEST .

Операции с закрытым ключом ( KeyPurpose::DECYPT и KeyPurpose::SIGN ) требуют авторизации дайджеста и заполнения, что означает, что авторизация ключа должна содержать указанные значения. Если нет, метод возвращает ErrorCode::INCOMPATIBLE_DIGEST или ErrorCode::INCOMPATIBLE_PADDING в зависимости от ситуации. Операции с открытым ключом ( KeyPurpose::ENCRYPT и KeyPurpose::VERIFY ) разрешены с несанкционированным дайджестом или дополнением.

За исключением PaddingMode::NONE , все режимы заполнения RSA применимы только для определенных целей. В частности, PaddingMode::RSA_PKCS1_1_5_SIGN и PaddingMode::RSA_PSS поддерживают только подписывание и проверку, тогда как PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT и PaddingMode::RSA_OAEP поддерживают только шифрование и дешифрование. Метод возвращает ErrorCode::UNSUPPORTED_PADDING_MODE , если указанный режим не поддерживает указанную цель.

Между режимами заполнения и дайджестами существует несколько важных взаимодействий:

  • PaddingMode::NONE указывает, что выполняется «необработанная» операция RSA. При подписании или проверке для дайджеста указывается Digest::NONE . Для незаполненного шифрования или дешифрования дайджест не требуется.
  • Для заполнения PaddingMode::RSA_PKCS1_1_5_SIGN требуется дайджест. Дайджестом может быть Digest::NONE , и в этом случае реализация Keymaster не сможет создать правильную структуру подписи PKCS#1 v1.5, поскольку она не может добавить структуру DigestInfo. Вместо этого реализация создает 0x00 || 0x01 || PS || 0x00 || M , где M — предоставленное сообщение, а PS — строка заполнения. Размер ключа RSA должен быть как минимум на 11 байт больше размера сообщения, иначе метод вернет ErrorCode::INVALID_INPUT_LENGTH .
  • Заполнение PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT не требует дайджеста.
  • Для заполнения PaddingMode::RSA_PSS требуется дайджест, который может отличаться от Digest::NONE . Если указан Digest::NONE , метод возвращает ErrorCode::INCOMPATIBLE_DIGEST . Кроме того, размер ключа RSA должен быть как минимум на 2 + D байта больше выходного размера дайджеста, где D — размер дайджеста в байтах. В противном случае метод возвращает ErrorCode::INCOMPATIBLE_DIGEST . Размер соли D.
  • Для заполнения PaddingMode::RSA_OAEP требуется дайджест, который может отличаться от Digest::NONE . Если указан Digest::NONE , метод возвращает ErrorCode::INCOMPATIBLE_DIGEST .

ЕС-ключи

Ключевые операции EC указывают ровно один режим заполнения в inParams . Если не указано или указано более одного раза, метод возвращает ErrorCode::UNSUPPORTED_PADDING_MODE .

Операции с закрытым ключом ( KeyPurpose::SIGN ) требуют авторизации дайджеста и заполнения, что означает, что авторизация ключа должна содержать указанные значения. Если нет, верните ErrorCode::INCOMPATIBLE_DIGEST . Операции с открытым ключом ( KeyPurpose::VERIFY ) разрешены с несанкционированным дайджестом или дополнением.

Ключи AES

Ключевые операции AES определяют ровно один режим блока и один режим заполнения в inParams . Если какое-либо значение не указано или указано более одного раза, верните ErrorCode::UNSUPPORTED_BLOCK_MODE или ErrorCode::UNSUPPORTED_PADDING_MODE . Указанные режимы должны быть авторизованы ключом, в противном случае метод возвращает ErrorCode::INCOMPATIBLE_BLOCK_MODE или ErrorCode::INCOMPATIBLE_PADDING_MODE .

Если режим блокировки — BlockMode::GCM , inParams указывает Tag::MAC_LENGTH , а указанное значение кратно 8 и не превышает 128 или меньше значения Tag::MIN_MAC_LENGTH в авторизации ключа. Если длина MAC превышает 128 или не кратна 8, верните ErrorCode::UNSUPPORTED_MAC_LENGTH . Для значений, меньших минимальной длины ключа, верните ErrorCode::INVALID_MAC_LENGTH .

Если режим блока — BlockMode::GCM или BlockMode::CTR , указанный режим заполнения должен быть PaddingMode::NONE . Для BlockMode::ECB или BlockMode::CBC режимом может быть PaddingMode::NONE или PaddingMode::PKCS7 . Если режим заполнения не соответствует этим условиям, верните ErrorCode::INCOMPATIBLE_PADDING_MODE .

Если режим блока — BlockMode::CBC , BlockMode::CTR или BlockMode::GCM , необходим вектор инициализации или одноразовый номер. В большинстве случаев вызывающим объектам не следует предоставлять IV или одноразовый номер. В этом случае реализация Keymaster генерирует случайный IV или nonce и возвращает его через Tag::NONCE в outParams . IV CBC и CTR имеют размер 16 байт. Одноразовые номера GCM имеют размер 12 байт. Если ключ авторизации содержит Tag::CALLER_NONCE , то вызывающая сторона может предоставить IV/nonce с помощью Tag::NONCE в inParams . Если nonce предоставляется, когда Tag::CALLER_NONCE не авторизован, верните ErrorCode::CALLER_NONCE_PROHIBITED . Если nonce не указан при авторизации Tag::CALLER_NONCE , сгенерируйте случайный IV/nonce.

HMAC-ключи

Ключевые операции HMAC указывают Tag::MAC_LENGTH в inParams . Указанное значение должно быть кратно 8 и не превышать длину дайджеста или меньше значения Tag::MIN_MAC_LENGTH в авторизации ключа. Если длина MAC превышает длину дайджеста или не кратна 8, верните ErrorCode::UNSUPPORTED_MAC_LENGTH . Для значений, меньших минимальной длины ключа, верните ErrorCode::INVALID_MAC_LENGTH .

обновлять

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

Предоставляет данные для обработки в текущей операции, начинающейся с Begin . Операция указывается параметром operationHandle .

Чтобы обеспечить большую гибкость обработки буфера, реализации этого метода имеют возможность потреблять меньше данных, чем было предоставлено. Вызывающий отвечает за цикл для передачи остальных данных в последующие вызовы. Количество потребляемых входных данных возвращается в параметре inputConsumed . Реализации всегда потребляют как минимум один байт, если только операция не может принять больше; если предоставлено более нуля байтов и использовано ноль байтов, вызывающая сторона считает это ошибкой и прерывает операцию.

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

Обработка ошибок

Если этот метод возвращает код ошибки, отличный от ErrorCode::OK , операция прерывается, а дескриптор операции становится недействительным. Любое будущее использование дескриптора с помощью этого метода Finish или Abort возвращает ErrorCode::INVALID_OPERATION_HANDLE .

Обеспечение выполнения разрешений

Принудительная авторизация ключей выполняется в основном в начале . Единственным исключением является случай, когда ключ имеет:

В этом случае ключ требует авторизации для каждой операции, а метод обновления получает Tag::AUTH_TOKEN в аргументе inParams . HMAC проверяет, что токен действителен и содержит соответствующий безопасный идентификатор пользователя, соответствует тегу ключа Tag::USER_AUTH_TYPE и содержит дескриптор текущей операции в поле запроса. Если эти условия не выполняются, верните ErrorCode::KEY_USER_NOT_AUTHENTICATED .

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

Ключи RSA

Для операций подписи и проверки с помощью Digest::NONE этот метод принимает весь блок для подписи или проверки за одно обновление. Он не может занимать только часть блока. Однако если вызывающая сторона решает предоставить данные в нескольких обновлениях, этот метод примет их. Если вызывающая сторона предоставляет для подписи больше данных, чем можно использовать (длина данных превышает размер ключа RSA), верните ErrorCode::INVALID_INPUT_LENGTH .

Ключи ECDSA

Для операций подписи и проверки с помощью Digest::NONE этот метод принимает весь блок для подписи или проверки за одно обновление. Этот метод не может использовать только часть блока.

Однако если вызывающая сторона решает предоставить данные в нескольких обновлениях, этот метод примет их. Если вызывающая сторона предоставляет для подписи больше данных, чем можно использовать, данные автоматически усекаются. (Это отличается от обработки избыточных данных, предоставляемых в аналогичных операциях RSA. Причиной этого является совместимость с устаревшими клиентами.)

Ключи AES

Режим AES GCM поддерживает «связанные данные аутентификации», предоставляемые через тег Tag::ASSOCIATED_DATA в аргументе inParams . Соответствующие данные могут предоставляться при повторных вызовах (это важно, если данные слишком велики для отправки одним блоком), но всегда предшествуют данным, подлежащим шифрованию или расшифровке. Вызов обновления может получать как связанные данные, так и данные для шифрования/дешифрования, но последующие обновления могут не включать связанные данные. Если вызывающая сторона предоставляет связанные данные для вызова обновления после вызова, который включает данные для шифрования/дешифрования, верните ErrorCode::INVALID_TAG .

Для шифрования GCM тег добавляется к зашифрованному тексту с помощью Finish . Во время расшифровки последние байты Tag::MAC_LENGTH данных, предоставленных последнему вызову обновления, являются тегом. Поскольку данный вызов update не может знать, является ли он последним вызовом, он обрабатывает все, кроме длины тега, и буферизует возможные данные тега во время завершения .

заканчивать

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

Завершает текущую операцию, начатую с помощью Begin , обрабатывая все еще необработанные данные, предоставленные обновлением (ями).

Этот метод является последним, вызванным в операции, поэтому все обработанные данные возвращаются.

Заканчивается ли он успешно или возвращает ошибку, этот метод завершает операцию и, следовательно, недействительно предоставлена ​​предоставленная операция. Любое будущее использование ручки с этим методом или обновлением или прерванным возвращает ErrorCode::INVALID_OPERATION_HANDLE .

Операции подписания возвращают подпись в качестве вывода. Операции проверки принимают подпись в параметре signature и возвращают нет вывода.

Правоприменение авторизации

Ключевое правоприменение выполняется в основном в начале . Единственным исключением является случай, когда ключ имеет:

В этом случае ключ требует разрешения на операцию, а метод обновления получает тег :: auth_token в аргументе inParams . HMAC проверяет, что токен действителен и содержит соответствующий безопасный идентификатор пользователя, соответствует теге клавиши :: user_auth_type и содержит дескриптор операции текущей операции в поле Challenge. Если эти условия не выполнены, верните ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Абонент предоставляет токен аутентификации каждому вызову для обновления и завершения . Реализация должна проверять токен только один раз, если он предпочитает.

Ключи RSA

Некоторые дополнительные требования, в зависимости от режима накладки:

  • PaddingMode::NONE . Для операций без подписания и шифрования, если предоставленные данные короче, чем ключ, данные составляются с нулевым прибором слева перед подписью/шифрованием. Если данные та же длины, что и ключ, но численно больше, верните ErrorCode::INVALID_ARGUMENT . Для операций проверки и дешифрования данные должны быть точно такими же, как ключ. В противном случае, возвращайте ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . Для PSS-плановых операций SIGNATURE SALE PSS соль-это размер расваивания сообщений и случайным образом генерируется. Дайджест, указанный с Tag :: Digest в inputParams на Begin , используется в качестве алгоритма Digest PSS, и в качестве алгоритма дигеста MGF1.
  • PaddingMode::RSA_OAEP . Дайджест, указанный с Tag :: Digest в inputParams на Begin , используется в качестве алгоритма Digest OAEP, а SHA1 используется в качестве алгоритма Digest MGF1.

Ключи ECDSA

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

AES ключи

Некоторые дополнительные условия, в зависимости от режима блока:

  • BlockMode::ECB или BlockMode::CBC . Если прокладка является PaddingMode::NONE , а длина данных не является кратным размером блока AES, верните ErrorCode::INVALID_INPUT_LENGTH . Если прокладка является PaddingMode::PKCS7 , накладывайте данные на спецификацию PKCS#7. Обратите внимание, что PKCS#7 рекомендует добавлять дополнительный блок заполнения, если данные кратны длиной блока.
  • BlockMode::GCM . Во время шифрования, после обработки всего открытого текста вычислите тег ( Tag :: Mac_length Bytes) и добавьте его в возвращенный зашифрованный текст. Во время дешифрования обрабатывайте последний тег :: Mac_length Byts в качестве тега. Если проверка тега не удается, верните ErrorCode::VERIFICATION_FAILED .

прерывать

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

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

get_supported_algorithms

Версия : 1

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

Реализации Keymaster 1 поддерживают RSA, EC, AES и HMAC.

get_supported_block_modes

Версия : 1

Возвращает список режимов блоков AES, поддерживаемых аппаратной реализацией Keymaster для указанного алгоритма и цели.

Для RSA, EC и HMAC, которые не являются блокированными шифрами, метод возвращает пустой список для всех действительных целей. Неверные цели должны привести к возвращению метода ErrorCode::INVALID_PURPOSE .

Реализации Keymaster 1 поддерживают ECB, CBC, CTR и GCM для шифрования и дешифрования AES.

get_supported_padding_modes

Версия : 1

Возвращает список режимов прокладки, поддерживаемых аппаратной реализацией Keymaster для указанного алгоритма и цели.

HMAC и EC не имеют представления о заполнении, поэтому метод возвращает пустой список для всех действительных целей. Неверные цели должны привести к возвращению метода ErrorCode::INVALID_PURPOSE .

Для RSA, Keymaster 1 реализации поддержка:

  • Невозможное шифрование, дешифрование, подписание и проверка. Для невозможного шифрования и подписания, если сообщение короче, чем общественный модуль, реализации должны оставить его с помощью нулей. Для невозможного дешифрования и проверки длина ввода должна соответствовать размеру общественного модуля.
  • PKCS#1 v1.5 Шифрование и подписание режимов заполнения
  • PSS с минимальной длиной соли 20
  • Оаэп

Для AES в режимах ECB и CBC реализации Keymaster 1 не поддерживают без прокладки и PKCS#7. Режимы CTR и GCM не поддерживают только прокладки.

get_supported_digests

Версия : 1

Возвращает список режимов дигест, поддерживаемых аппаратной реализацией Keymaster для указанного алгоритма и цели.

Не поддерживает режимы AES или требует переваривания, поэтому метод возвращает пустой список для действительных целей.

Реализации Keymaster 1 могут реализовать подмножество определенных дайджестов. Реализации предоставляют SHA-256 и могут предоставить MD5, SHA1, SHA-224, SHA-256, SHA384 и SHA512 (полный набор определенных дайджестов).

get_supported_import_formats

Версия : 1

Возвращает список импортных форматов, поддерживаемых аппаратной реализацией Keymaster указанного алгоритма.

Реализации Keymaster 1 поддерживают формат PKCS#8 (без защиты паролей) для импорта пар RSA и EC клавиш, а также поддерживают необработанный импорт материала ключа AES и HMAC.

get_supported_export_formats

Версия : 1

Возвращает список экспортных форматов, поддерживаемых аппаратной реализацией Keymaster указанного алгоритма.

Реализации KeyMaster1 поддерживают формат X.509 для экспорта RSA и EC Public Keys. Экспорт частных ключей или асимметричных ключей не поддерживается.

Исторические функции

Keymaster 0

Следующие функции принадлежат исходному определению Keymaster 0. Они присутствовали в Keymaster 1 struct keymaster1_device_t. Однако в Keymaster 1.0 они не были реализованы, и их указатели функции были установлены на NULL.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Кеймастер 1

Следующие функции принадлежат определению Keymaster 1, но были удалены в Keymaster 2, вместе с функциями Keymaster 0, перечисленными выше.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

Следующие функции принадлежат определению Keymaster 2, но были удалены в Keymaster 3, вместе с функциями Keymaster 1, перечисленными выше.

  • configure