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

Метод CalculateHashDigest выполняет синхронное one-shot-вычисление криптографического хеш-значения и записывает результат в предоставленный выходной буфер [SWS_CRYPT_50060]. В качестве параметров передаются обрабатываемое входное сообщение data, целевой буфер digest, а также необязательный вектор инициализации iv. При успешном выполнении функция через объект результата ara::core::Result<std::size_t> возвращает фактическое количество записанных байтов дайджеста [SWS_CRYPT_50060].

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

Если вычисление завершается сбоем, интерфейс гарантирует семантику отката [SWS_CRYPT_50060]. Результат может содержать следующие коды ошибок:

• ara::crypto::CryptoErrc::kInvalidInputSize: размер переданных данных или вектора инициализации не поддерживается [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: вычисление single-call не поддерживается контекстом или передача вектора инициализации не соответствует конфигурации контекста (IV требуется, но отсутствует, либо IV передан, хотя не поддерживается) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: емкости выходного буфера digest недостаточно для вычисленного дайджеста [SWS_CRYPT_50060].

Параллелизм и взаимодействие

Функция объявлена как безопасная к исключениям (exception safe) и потокобезопасная (thread-safe) [SWS_CRYPT_50060]. Чтобы заранее избежать ошибок, связанных с недопустимой длиной входных данных, максимально допустимый для одиночного вызова размер буфера контекста можно определить через GetMaximumChunkSize [SWS_CRYPT_50062].

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

Метод Cancel() служит для целенаправленного прерывания выполняющейся потоковой операции, которая ранее была начата через метод Start() и ещё не завершена штатным образом [SWS_CRYPT_50058]. Вызов выполняется синхронно и без параметров на экземпляре ara::crypto::cryp::HashFunctionCtx из заголовочного файла ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. При успешном выполнении операция возвращает пустой ara::core::Result<void> [SWS_CRYPT_50058].

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

Если во время выполнения возникает проблема, возвращаемый ara::core::Result содержит соответствующее значение ошибки [SWS_CRYPT_50058]. Если обработка перед вызовом Cancel() не была инициирована через Start(), прерывание завершается сбоем и возвращает специфический код ошибки ara::crypto::CryptoErrc::kProcessingNotStarted с семантикой отката [SWS_CRYPT_50058].

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

Интерфейс определён как thread-safe и exception safe и объявлен с noexcept [SWS_CRYPT_50058]. Важным функциональным предусловием является то, что обработка данных должна находиться в активном состоянии, созданном предшествующим вызовом Start() [SWS_CRYPT_50058].

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

Шаблон, реализованный посредством Cancel(), стандартизирован для различных потоковых контекстов стека Crypto. Точно совпадающую семантику и сигнализацию об ошибках имеют также контексты VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] и EncryptorPublicCtx [SWS_CRYPT_50089].

Метод Compare класса ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) синхронно сравнивает размер и содержимое предварительно вычисленного хэш-дайджеста с ожидаемым эталонным значением. Заданное значение передается через параметр expected типа ReadOnlyMemRegion. В случае успеха функция возвращает ara::core::Result<bool>, который содержит true тогда и только тогда, когда ожидаемая последовательность байтов идентична вычисленному дайджесту.

Предварительным условием для вызова является предварительное завершение вычисления дайджеста методом Finish(). Если это не так, вызов завершается с ошибкой и возвращает ошибку ara::crypto::CryptoErrc::kProcessingNotFinished с семантикой отката ([SWS_CRYPT_50154]). Интерпретация: отличающаяся длина или несовпадающее содержимое expected, предположительно, приводит не к коду ошибки, а к регулярному false в объекте результата. Вопрос Q-fdd0ecaec22f6985 (открытый)

Что касается параллелизма, метод специфицирован как thread-safe и exception safe ([SWS_CRYPT_50154]). Благодаря объявлению как noexcept он не генерирует исключений C++.

В родственных криптографических контекстах применяется тот же шаблон проверки: для Message Authentication Codes метод ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) сравнивает размер и содержимое вычисленного значения MAC, тогда как CompareSubspan ([SWS_CRYPT_50028]) проверяет старшие биты. Оба метода одинаково требуют предварительно завершенного вычисления.

Метод [SWS_CRYPT_50064] класса ara::crypto::cryp::HashFunctionCtx синхронно записывает текущее состояние контекста хеширования в переданный выходной буфер contextState типа ReadWriteMem Region. Это позволяет приложениям прерывать текущую операцию криптографического хеширования и возобновлять ее позднее. При успешном выполнении вызов возвращает пустой ara::core::Result<void>.

Взаимодействие и определение размера буфера

Чтобы предотвратить ошибки памяти, строго необходимый размер буфера в байтах следует предварительно запросить через функцию [SWS_CRYPT_50063]. Экспортированное состояние впоследствии может быть снова загружено в контекст хеширования с помощью [SWS_CRYPT_50065]. Необходимым условием для этого является то, чтобы целевой контекст имел ту же AlgorithmId и предоставлялся тем же Crypto Provider, что и исходный контекст. При импорте любое существующее состояние вычислений полностью перезаписывается.

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

Если операция завершается неудачно, ошибка возвращается в ara::core::Result. Специфицированы следующие коды ошибок из ara::crypto::CryptoErrc:

• ara::crypto::CryptoErrc::kUnsupported: конкретный контекст не поддерживает экспорт или импорт состояний.
• ara::crypto::CryptoErrc::kInsufficientCapacity: емкости переданного буфера contextState недостаточно для размещения состояния.

Для обоих случаев ошибок определена семантика отката, благодаря чему состояние объекта остается неизменным.

Параллелизм и надёжность выполнения

Интерфейс объявлен как const и noexcept. Согласно спецификации, вызов является как потокобезопасным (thread-safe), так и безопасным к исключениям (exception-safe).

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

Синхронный метод Finish() завершает вычисление хеш-значения в ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_21115]. Беспараметрический вызов возвращает ara::core::Result<void>, который сигнализирует об успешном завершении или инкапсулирует ошибку [SWS_CRYPT_21115]. Интерфейс объявлен как noexcept, а также специфицирован как безопасный к исключениям (exception safe) и потокобезопасный (thread-safe) [SWS_CRYPT_21115].

Обработка ошибок и параллелизм

Если вычисление хеша перед вызовом не было успешно запущено, метод завершается с ошибкой ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. Для этого случая ошибки определена семантика отката (rollback), поэтому вызывающие стороны перед финализацией обязательно должны следить за надлежащим запуском контекста [SWS_CRYPT_21115].

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

После успешного вызова Finish() вычисленный хеш-дайджест обычно переносится с помощью GetDigest() в предоставленный буфер [SWS_CRYPT_21116], [SWS_CRYPT_50059]. Для разграничения служит GetIntermediateDigest(): эта функция возвращает то же хеш-значение, что и последовательность Finish() и GetDigest(), однако затем допускает передачу дальнейших данных [SWS_CRYPT_50059]. Интерпретация: после вызова Finish() вычисление, вероятно, окончательно завершено, и контекст больше не принимает дополнительных данных. Вопрос Q-f4daf29364f45fd5 (открытый) Допустимые размеры буфера для шагов обработки в контексте можно запросить через GetMaximumChunkSize() [SWS_CRYPT_50062].

Метод ImportContextState класса ara::crypto::cryp::HashFunctionCtx (определенный в ara/crypto/cryp/hash_function_ctx.h) служит для восстановления внутреннего состояния контекста хэширования из переданного буфера и тем самым продолжения ранее прерванной операции хэширования [SWS_CRYPT_50065]. Любое текущее состояние вычисления текущего контекста при этом полностью заменяется импортированным состоянием [SWS_CRYPT_50065].

Вызов и предварительные условия

Синхронный вызов выполняется через сигнатуру ImportContextState(ReadOnlyMem Region contextState) noexcept и возвращает ara::core::Result<void> [SWS_CRYPT_50065]. К параметру contextState предъявляются следующие обязательные требования:

• Буфер данных должен быть предварительно экспортирован с помощью метода ExportContextState() из экземпляра HashFunctionCtx [SWS_CRYPT_50065].
• Исходный контекст должен был обладать тем же AlgorithmId и быть предоставлен тем же Crypto Provider, что и целевой контекст [SWS_CRYPT_50065].

Обработка ошибок и параллелизм

В случае ошибки возвращается код ошибки с семантикой отката (rollback), благодаря чему текущее состояние контекста при неудаче остаётся неизменным [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: аргумент contextState содержит недопустимые данные [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: данный контекст не поддерживает экспорт и импорт состояний контекста [SWS_CRYPT_50065].

Операция специфицирована как thread-safe и exception safe [SWS_CRYPT_50065].

Метод Start() интерфейса ara::crypto::cryp::HashFunctionCtx инициализирует контекст для пошагового вычисления хеш-значения без вектора инициализации (IV) [SWS_CRYPT_50152]. Повторный вызов прерывает возможное уже выполняющееся вычисление хеша и настраивает контекст для нового вычисления [SWS_CRYPT_50152].

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

• ara::crypto::CryptoErrc::kUnsupported: используемая хеш-функция обязательно ожидает вектор инициализации [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: внутренний ресурс, обязательно необходимый для операции, занят [SWS_CRYPT_50152].

В отношении параллелизма метод специфицирован как thread-safe, а также exception safe и объявлен как noexcept [SWS_CRYPT_50152]. После успешной инициализации части сообщения могут последовательно подаваться через метод Update() контекста [SWS_CRYPT_21113]. Поскольку вызов прерывает выполняющиеся вычисления, на практике функция, вероятно, служит также механизмом сброса перед перезапуском. Вопрос Q-9c369489a6c6e8cb (открытый)

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

Функция Start интерфейса ara::crypto::cryp::HashFunctionCtx инициализирует контекст для вычисления хеш-дайджеста с использованием вектора инициализации (IV) [SWS_CRYPT_50153]. В качестве параметра вектор инициализации iv передается через ReadOnlyMemRegion [SWS_CRYPT_50153]. Синхронный вызов возвращает ara::core::Result<void>, которое в случае успеха не содержит возвращаемого значения [SWS_CRYPT_50153]. Вызов также прерывает возможное уже выполняющееся вычисление хеша в этом контексте [SWS_CRYPT_50153].

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

Если при инициализации возникает ошибка, возвращается соответствующий код ошибки, причем для всех случаев ошибок гарантируется семантика отката [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: размер предоставленного вектора инициализации не поддерживается [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: базовая хеш-функция не использует вектор инициализации [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: ресурс, необходимый для инициализации, занят [SWS_CRYPT_50153].

Параллелизм и взаимодействие

Интерфейс объявлен как noexcept, а также специфицирован как потокобезопасный (thread-safe) и безисключительный (exception safe) [SWS_CRYPT_50153]. В типичном сценарии вызов образует предварительное условие для последующей пошаговой обработки входного сообщения через метод Update [SWS_CRYPT_21113].

Синхронный метод Update служит в [SWS_CRYPT_21113] для инкрементного обновления текущего контекста вычисления хеша (ara::crypto::cryp::HashFunctionCtx). Через параметр data (ReadOnlyMemRegion) передаётся часть обрабатываемого входного сообщения. Функция возвращает ara::core::Result<void>, который в случае успеха пуст или инкапсулирует соответствующий код ошибки.

Что касается обработки ошибок, метод обеспечивает семантику отката при двух специфических состояниях ошибки:

• ara::crypto::CryptoErrc::kProcessingNotStarted: вычисление ранее не было инициировано вызовом метода Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: размер переданных данных не поддерживается контекстом [SWS_CRYPT_21113].

Для контекста вызова действуют чёткие условия порядка и размера: перед передачей данных операция хеширования должна быть инициализирована [SWS_CRYPT_21113]. Чтобы избежать kInvalidInputSize, максимально допустимый размер блока для одного вызова Update может быть предварительно определён через GetMaximumChunkSize [SWS_CRYPT_50062]. Согласно спецификации функция объявлена как безопасная относительно исключений (exception safe) и потокобезопасная (thread-safe) [SWS_CRYPT_21113].

Во взаимодействии с другими интерфейсами внутри HashFunctionCtx существует перегрузка для передачи объектов ключей через Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. После передачи всех блоков данных финализация контрольной суммы, предположительно, выполняется через Finish() [SWS_CRYPT_50062]. Вопрос Q-dcac20f353ca55f4 (открытый)

Синхронный метод Update служит в [SWS_CRYPT_50057] для пошагового расширения контекста вычисления хэш-значения в ara::crypto::cryp::HashFunctionCtx новым фрагментом сообщения в виде объекта ключа. В качестве параметра передается умный указатель на объект ключа (CryptoObject::Sptr key). В качестве возвращаемого значения вызов возвращает ara::core::Result<void>, который пуст при успешной обработке или инкапсулирует соответствующий код ошибки в случае сбоя [SWS_CRYPT_50057].

В качестве условия очередности действует требование, согласно которому вычисление обязательно должно быть предварительно инициировано вызовом Start(); в противном случае сообщается об ошибке ProcessingNotStarted [SWS_CRYPT_50057]. Другие специфические случаи ошибок включают (каждый с семантикой отката) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, если контекст хэширования вообще не поддерживает хэширование ключей,
• ara::crypto::CryptoErrc::kIncompatibleObject, если переданный объект ключа несовместим с контекстом,
• ara::crypto::CryptoErrc::kUsageViolation, если разрешенное использование ключа не включает kAllowHash Calculation,
• ara::crypto::CryptoErrc::kInvalidInputSize, если размер данных переданного ключа не поддерживается.

Метод объявлен как thread-safe, а также exception safe (noexcept) [SWS_CRYPT_50057]. Во взаимодействии с другими интерфейсами модуля максимально допустимый размер буфера для отдельных вызовов Update может быть определен через GetMaximumChunkSize() [SWS_CRYPT_50062]. Для регулярных частей сообщения без объекта ключа в HashFunctionCtx параллельно существует перегрузка Update(ReadOnlyMemRegion data) [SWS_CRYPT_21113].