Эта страница переведена с помощью Cloud Translation API.

Ключевые функции

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

Примечание. Для поддержки перехода Keymaster 3 от старой структуры HAL C к интерфейсу C++ HAL, сгенерированному из определения на новом языке определения аппаратного интерфейса (HIDL), в Android 8.0 имена функций были изменены. Чтобы поддержать это, функции теперь в верблюжьем регистре. Например, get_key_characteristics теперь getKeyCharacteristics .

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

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

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

Версия : 1, 2

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

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

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

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

Версия : 1, 2

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

неправильное использование 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);

addRngEntropy

Версия : 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 зависят от типа генерируемого ключа. В этом разделе приведены необходимые и необязательные теги для каждого типа ключа. Tag::ALGORITHM всегда необходим для указания типа.

RSA-ключи

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

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

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

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

Ключи ECDSA

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

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

AES-ключи

Только Tag::KEY_SIZE необходим для генерации ключа AES. Если он опущен, метод возвращает 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 необходимы следующие параметры:

Tag::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 не следует добавлять к ключевым характеристикам.

получить ключевые характеристики

Версия : 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 всегда находится в списке оборудования для аппаратно-привязанных ключей. Его присутствие в этом списке — это то, как более высокие уровни определяют, что ключ имеет аппаратную поддержку.

импортКлюч

Версия : 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.

удалитьКлюч

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

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

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

удалить все ключи

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

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

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

уничтожить аттестационные идентификаторы

Версия : 3

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

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

начинать

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

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

Реализация Keymaster поддерживает не менее 16 одновременных операций. Хранилище ключей использует до 15, оставляя один для vold для шифрования паролей. Когда в хранилище ключей выполняется 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 .
Тег::ORIGINATION_EXPIRE_DATETIME можно применять только в том случае, если доступен надежный источник времени UTC. Если текущая дата и время позже значения тега и целью является KeyPurpose::ENCRYPT или KeyPurpose::SIGN , метод возвращает ErrorCode::KEY_EXPIRED .
Тег::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 из ключа соответствует хотя бы одному из значений безопасного идентификатора в маркере.
- Ключ имеет Tag::USER_AUTH_TYPE , который соответствует типу аутентификации в токене.
Если какое-либо из этих условий не выполняется, метод возвращает ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Tag::CALLER_NONCE позволяет вызывающей стороне указать одноразовый номер или вектор инициализации (IV). Если ключ не имеет этого тега, но вызывающий объект предоставил Tag::NONCE этому методу, возвращается ErrorCode::CALLER_NONCE_PROHIBITED .
Tag::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 или одноразовый номер и возвращает его через Tag::NONCE в outParams . CBC и CTR IV имеют размер 16 байт. Одноразовые номера GCM составляют 12 байтов. Если авторизация ключа содержит Tag::CALLER_NONCE , вызывающая сторона может предоставить IV/nonce с Tag::NONCE в inParams . Если одноразовый номер предоставляется, когда Tag::CALLER_NONCE не авторизован, вернуть ErrorCode::CALLER_NONCE_PROHIBITED . Если одноразовый номер не предоставляется при авторизации Tag::CALLER_NONCE , сгенерируйте случайный IV/одноразовый номер.

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 .

Обеспечение авторизации

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

Один или несколько Tag::USER_SECURE_ID и
Не имеет тега::AUTH_TIMEOUT

В этом случае ключ требует авторизации для каждой операции, а метод обновления получает 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 данных, предоставленные последнему вызову обновления, являются тегом. Поскольку данный вызов обновления не может знать, является ли он последним вызовом, он обрабатывает все, кроме длины тега, и буферизует возможные данные тега во время финиша .

финиш

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

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

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

One or more Tag::USER_SECURE_IDs , and
Does not have a Tag::AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is at least 20 bytes in length and randomly generated. The salt may be longer; the reference implementation uses maximally sized salt. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest algorithm.
PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
PKCS#1 v1.5 encryption and signing padding modes
PSS with a minimum salt length of 20
OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

generate_keypair
import_keypair
get_keypair_public
delete_keypair
delete_all
sign_data
Verify_data

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

get_supported_algorithms
get_supported_block_modes
get_supported_padding_modes
get_supported_digests
get_supported_import_formats
get_supported_export_formats

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

configure