класс ara::crypto::cryp::RandomGeneratorCtx

Метод AddEntropy класса ara::crypto::cryp::RandomGeneratorCtx служит для обновления внутреннего состояния генератора случайных чисел (RNG) путем подмешивания дополнительно переданных значений энтропии [SWS_CRYPT_22914]. Объявление доступно через заголовочный файл ara/crypto/cryp/random_generator_ctx.h [SWS_CRYPT_22914]. В качестве входного параметра функция ожидает объект типа ReadOnlyMemRegion с именем entropy, который инкапсулирует область памяти с добавляемым значением энтропии [SWS_CRYPT_22914].

Вызов выполняется синхронно (интерпретация: интерфейс возвращает результат напрямую без асинхронного типа результата). Вопрос Q-6e56e1daaa526bf8 (открытый) Результат возвращается в виде ara::core::Result<void>, которое в случае успеха является пустым, если метод поддерживается и энтропия была успешно подмешана [SWS_CRYPT_22914]. Если же конкретный контекст генератора случайных чисел не поддерживает добавление энтропии, вызов завершается сбоем и возвращает код ошибки ara::crypto::CryptoErrc::kUnsupported с гарантированной семантикой отката [SWS_CRYPT_22914].

Что касается параллелизма и отказоустойчивости, интерфейс специфицирован как потокобезопасный (thread-safe), а также безопасный относительно исключений (exception safe) и снабжен идентификатором noexcept [SWS_CRYPT_22914]. Таким образом, вызывающие стороны могут безопасно вызывать функцию из нескольких потоков, однако всегда должны анализировать возвращаемое ara::core::Result для обработки отсутствия поддержки ввода энтропии в соответствующем контексте [SWS_CRYPT_22914].

Функция Generate интерфейса ara::crypto::cryp::RandomGeneratorCtx служит для заполнения предоставленного выходного буфера (псевдо)случайной последовательностью [SWS_CRYPT_22915]. В качестве входного параметра метод принимает доступную для записи область памяти output типа ReadWriteMemRegion, в которую непосредственно записываются сгенерированные случайные байты [SWS_CRYPT_22915].

Что касается безопасности выполнения и параллелизма, метод объявлен как noexcept, считается Exception-safe и явно специфицирован как thread-safe [SWS_CRYPT_22915]. Это допускает параллельный вызов из нескольких потоков.

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

Тип возвращаемого значения ara::core::Result<void> сигнализирует об успехе операции пустым результатом или возвращает в случае ошибки соответствующий код ошибки с семантикой отката [SWS_CRYPT_22915]:

• ara::crypto::CryptoErrc::kUninitializedContext: возникает, если контекст предварительно должен быть инициализирован или снабжен энтропией («seeded») приложением [SWS_CRYPT_22915].
• ara::crypto::CryptoErrc::kBusyResource: возвращается, если в контексте в данный момент исчерпана энтропия («out-of-entropy») и поэтому он не может предоставить запрошенное количество случайных байтов [SWS_CRYPT_22915].

Взаимодействие и разграничение

В то время как RandomGeneratorCtx::Generate записывает необработанные байты случайных данных в буфер [SWS_CRYPT_22915], в модуле crypt существуют другие функции генерации с иной направленностью: так, CryptoProvider::GenerateSymmetricKey [SWS_CRYPT_20721] служит для инстанцирования симметричных ключей, а CryptoProvider::GeneratePrivateKey [SWS_CRYPT_20722] — для генерации пар асимметричных ключей. Кроме того, метод не следует путать с одноименной функцией Generate из MessageAuthnCodeCtx, которая служит для вычисления MAC-дайджеста [SWS_CRYPT_50029].

Использование

Чисто виртуальный метод Seed интерфейса ara::crypto::cryp::RandomGeneratorCtx служит для установки внутреннего состояния генератора случайных чисел (RNG) через предоставленную область памяти [SWS_CRYPT_22911]. Объявление находится в заголовке ara/crypto/cryp/random_generator_ctx.h с сигнатурой virtual ara::core::Result<void> Seed(ReadOnlyMemRegion seed) noexcept = 0; [SWS_CRYPT_22911].

В качестве входного параметра синхронная функция принимает seed типа ReadOnlyMemRegion, содержащий область памяти со значением затравки (seed) [SWS_CRYPT_22911]. При успешном выполнении и поддержке контекстом метод возвращает пустой ara::core::Result<void> [SWS_CRYPT_22911].

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

В случае ошибки возвращенный ara::core::Result содержит соответствующий код ошибки [SWS_CRYPT_22911]:

• ara::crypto::CryptoErrc::kUnsupported: возникает, если конкретный RandomGeneratorCtx не поддерживает установку начального значения (seeding); для этого случая ошибки специфицирована семантика отката [SWS_CRYPT_22911].

Параллелизм и ограничения

Интерфейс объявлен как noexcept и с точки зрения безопасности выполнения классифицирован как exception safe, а также thread-safe [SWS_CRYPT_22911].

Взаимодействие

В дополнение к этой функции на основе диапазона памяти [SWS_CRYPT_22912] определяет перегрузку Seed(SymmetricKey::Sptr seed), которая инициализирует состояние RNG с помощью симметричного ключа, проверяя при этом ограничения использования, такие как kAllowRngInit.

Метод Seed инициализирует внутреннее состояние генератора случайных чисел в контексте ara::crypto::cryp::RandomGeneratorCtx с использованием симметричного ключа [SWS_CRYPT_22912]. Вызов выполняется синхронно и специфицирован как потокобезопасный и исключениебезопасный (exception safe и noexcept) [SWS_CRYPT_22912]. В качестве входного параметра выступает смарт-указатель на ключ (SymmetricKey::Sptr), значение которого принимается в качестве начального значения (seed) [SWS_CRYPT_22912].

При обработке ошибок функция возвращает ara::core::Result<void>, который в случае успеха пуст [SWS_CRYPT_22912]. Если операция завершается неудачно, действует семантика отката; в частности, это касается следующих кодов ошибок:

• ara::crypto::CryptoErrc::kUsageViolation: возникает, если разрешенное использование переданного ключа не включает флаг kAllowRngInit [SWS_CRYPT_22912].
• ara::crypto::CryptoErrc::kUnsupported: возвращается, если конкретный экземпляр контекста не поддерживает установку seed с помощью симметричного ключа [SWS_CRYPT_22912].

Во взаимодействии с семейством интерфейсов эта функция представляет собой вариант на основе ключа, тогда как перегрузка согласно [SWS_CRYPT_22911] охватывает инициализацию через неструктурированную область памяти (ReadOnlyMemRegion). Вследствие семантики отката внутреннее состояние генератора в случае ошибки, по-видимому, остается в предыдущем состоянии (интерпретация). Вопрос Q-970cbedd1843b26a (открытый)