На этой странице представлены дополнительные сведения и рекомендации для разработчиков, использующих уровень аппаратной абстракции KeyMint (HAL). Основной документацией по HAL является спецификация интерфейса AIDL .
злоупотребление API
Пользователи могут создавать ключи KeyMint с авторизациями, которые допустимы в качестве параметров API, но делают полученные ключи небезопасными или непригодными для использования. Реализации KeyMint не обязаны выдавать ошибку в таких случаях или диагностическое сообщение. Использование слишком маленьких ключей, указание нерелевантных входных параметров, повторное использование векторов инициализации или одноразовых чисел, генерация ключей без какого-либо назначения (следовательно, бесполезных) и тому подобное не должны диагностироваться реализациями.
Ответственность за то, чтобы вызовы модулей KeyMint были осмысленными и полезными, лежит на приложениях, фреймворке и Android Keystore.
точка входа addRngEntropy
Функция addRngEntropy добавляет предоставленную вызывающей стороной энтропию в пул, используемый реализацией KeyMint для генерации случайных чисел для ключей и векторов инициализации (IV).
Реализации KeyMint должны обеспечивать безопасное смешивание предоставленной энтропии со своим пулом, который также должен содержать внутренне сгенерированную энтропию от аппаратного генератора случайных чисел. Смешивание должно осуществляться таким образом, чтобы злоумышленник, имеющий полный контроль либо над битами, предоставленными функцией addRngEntropy , либо над битами, сгенерированными аппаратным генератором (но не над обоими одновременно), не имел существенного преимущества в предсказании битов, сгенерированных из пула энтропии.
Основные характеристики
Каждый из механизмов ( generateKey , importKey и importWrappedKey ), создающих ключи KeyMint, возвращает характеристики вновь созданного ключа, соответствующим образом разделенные на уровни безопасности, которые обеспечивают соблюдение каждой характеристики. Возвращаемые характеристики включают все параметры, указанные при создании ключа, за исключением Tag::APPLICATION_ID и Tag::APPLICATION_DATA . Если эти теги включены в параметры ключа, они удаляются из возвращаемых характеристик, так что невозможно найти их значения, изучив возвращаемый keyblob. Однако они криптографически связаны с keyblob, поэтому, если при использовании ключа не указаны правильные значения, использование ключа завершится неудачей. Аналогично, Tag::ROOT_OF_TRUST криптографически связан с ключом, но его нельзя указать при создании или импорте ключа, и он никогда не возвращается.
В дополнение к предоставленным тегам, реализация KeyMint также добавляет Tag::ORIGIN , указывающий способ создания ключа ( KeyOrigin::GENERATED , KeyOrigin::IMPORTED или KeyOrigin::SECURELY_IMPORTED ).
сопротивление откату
Устойчивость к откату обозначается Tag::ROLLBACK_RESISTANCE и означает, что после удаления ключа с помощью deleteKey или deleteAllKeys защищенное оборудование гарантирует, что он никогда больше не будет пригоден для использования.
Реализации KeyMint возвращают сгенерированный или импортированный ключевой материал вызывающей стороне в виде keyblob — зашифрованного и аутентифицированного файла. Когда Keystore удаляет keyblob, ключ исчезает, но злоумышленник, которому ранее удалось получить доступ к ключевому материалу, потенциально может восстановить его на устройстве.
Ключ устойчив к откату, если защищенное оборудование гарантирует невозможность восстановления удаленных ключей в дальнейшем. Обычно это достигается путем хранения дополнительных метаданных ключа в доверенном месте, недоступном для злоумышленника. На мобильных устройствах для этого обычно используются блоки памяти, защищенные от повторного воспроизведения (RPMB). Поскольку количество создаваемых ключей практически неограничено, а размер доверенного хранилища, используемого для защиты от отката, может быть ограничен, реализация может отклонять запросы на создание ключей, устойчивых к откату, когда хранилище заполнено.
начинать
Функция begin() запускает криптографическую операцию с использованием указанного ключа, для указанной цели и с указанными параметрами (при необходимости). Она возвращает новый объект IKeyMintOperation Binder, который используется для завершения операции. Кроме того, возвращается значение запроса, которое используется в качестве части токена аутентификации в аутентифицированных операциях.
Реализация KeyMint поддерживает как минимум 16 одновременных операций. Keystore использует до 15, оставляя одну для использования vold для шифрования паролей. Когда Keystore выполняет 15 операций (вызван begin() , но finish или abort еще не вызваны) и получает запрос на начало 16-й, он вызывает abort() для наименее часто используемой операции, чтобы уменьшить количество активных операций до 14, прежде чем вызвать begin() для начала новой запрошенной операции.
Если при генерации или импорте ключей были указаны Tag::APPLICATION_ID или Tag::APPLICATION_DATA , вызовы метода begin() должны включать эти теги с исходно указанными значениями в аргументе params этого метода.
Обработка ошибок
Если метод объекта IKeyMintOperation возвращает код ошибки, отличный от ErrorCode::OK , операция прерывается, и объект Binder операции становится недействительным. Любое последующее использование объекта возвращает ErrorCode::INVALID_OPERATION_HANDLE .
Обеспечение соблюдения авторизации
Проверка авторизации по ключу выполняется преимущественно в begin() . Единственное исключение — случай, когда ключ имеет одно или несколько значений Tag::USER_SECURE_ID и не имеет значения Tag::AUTH_TIMEOUT .
В этом случае для каждой операции требуется авторизация, а методы update() или finish() получают токен авторизации в аргументе authToken . Для обеспечения действительности токена используется следующая реализация KeyMint:
- Проверяет HMAC-подпись токена аутентификации.
- Проверяет, содержит ли токен защищенный идентификатор пользователя, совпадающий с идентификатором, связанным с ключом.
- Проверяет, соответствует ли тип аутентификации токена значению
Tag::USER_AUTH_TYPEключа. - Проверяет, что токен содержит значение запроса для текущей операции в поле запроса.
Если эти условия не выполняются, KeyMint возвращает ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Вызывающая сторона предоставляет токен аутентификации при каждом вызове методов update() и finish() . Реализация может проверить токен только один раз.