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

На этой странице представлены сведения, которые помогут разработчикам уровней аппаратной абстракции 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 returna 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 . CBC и CTR IV имеют размер 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 , обрабатывая все еще необработанные данные, предоставленные обновлением (ями).

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

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

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

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

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

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

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

Ключи RSA

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

  • PaddingMode::NONE . Для операций подписи и шифрования без дополнений, если предоставленные данные короче ключа, данные дополняются нулями слева перед подписанием/шифрованием. Если данные имеют ту же длину, что и ключ, но численно больше, верните ErrorCode::INVALID_ARGUMENT . Для операций проверки и дешифрования данные должны быть точно такой же длины, как ключ. В противном случае верните ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . Для операций с подписями, дополненными PSS, соль PSS представляет собой размер дайджеста сообщения и генерируется случайным образом. Дайджест, указанный с помощью Tag::DIGEST в inputParams в начале, используется как алгоритм дайджеста PSS и как алгоритм дайджеста MGF1.
  • PaddingMode::RSA_OAEP . Дайджест, указанный с помощью Tag::DIGEST в inputParams в начале, используется в качестве алгоритма дайджеста OAEP, а SHA1 используется в качестве алгоритма дайджеста 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 ) и добавьте его к возвращенному зашифрованному тексту. Во время расшифровки обрабатывайте последние байты Tag::MAC_LENGTH как тег. Если проверка тега не удалась, верните ErrorCode::VERIFICATION_FAILED .

прерывать

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

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

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, а также поддерживают импорт RAW материалов ключей AES и HMAC.

get_supported_export_formats

Версия : 1

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

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

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

Ключник 0

Следующие функции относятся к исходному определению Keymaster 0. Они присутствовали в структуре Keymaster1_device_t Keymaster1. Однако в 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

Ключник 2

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

  • configure