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

Чисто виртуальный метод Cancel служит в интерфейсе ara::crypto::cryp::MessageAuthnCodeCtx для отмены текущей, ранее инициированной с помощью Start() и еще не завершенной потоковой операции [SWS_CRYPT_50027]. Вызов выполняется синхронно, не принимает входных параметров и в случае успеха возвращает пустой ara::core::Result<void>, подтверждающий успешную отмену операции [SWS_CRYPT_50027].

Если обработка данных перед вызовом не была надлежащим образом начата с помощью метода Start(), выполнение завершается ошибкой. В этом случае функция возвращает результат со специфическим кодом ошибки ara::crypto::CryptoErrc::kProcessingNotStarted с обеспечением семантики отката (rollback) [SWS_CRYPT_50027]. С точки зрения безопасности выполнения интерфейс специфицирован как потокобезопасный (thread-safe) и гарантирует безопасность исключений (exception safe), так как он объявлен как noexcept и не генерирует исключений [SWS_CRYPT_50027].

Идентичное поведение при отмене еще не завершенных потоковых обработок характерно для всех связанных контекстных интерфейсов криптографического модуля:

• VerifierPublicCtx для проверки цифровых подписей [SWS_CRYPT_50023],
• SignerPrivateCtx для формирования цифровых подписей [SWS_CRYPT_50041],
• SymmetricCipherCtx для симметричного шифрования [SWS_CRYPT_50046],
• HashFunctionCtx для вычисления хеш-значений [SWS_CRYPT_50058],
• DecryptorPrivateCtx для асимметричного расшифрования [SWS_CRYPT_50069],
• AuthCipherCtx для аутентифицированного шифрования [SWS_CRYPT_50077], а также
• EncryptorPublicCtx для асимметричного шифрования [SWS_CRYPT_50089].

Интерпретация: благодаря отмене незавершенной операции контекст, по-видимому, возвращается в исходное очищенное состояние, допускающее последующую повторную инициализацию через Start(). Вопрос Q-a8fa5cb85c3dab50 (открытый)

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

Чисто виртуальный метод Compare класса ara::crypto::cryp::MessageAuthnCodeCtx служит для сопоставления размера и содержимого вычисленного Message Authentication Code (MAC) с ожидаемым дайджестом [SWS_CRYPT_50133]. В качестве параметра ожидаемый MAC-дайджест передается через ReadOnlyMemRegion expected. Функция возвращает ara::core::Result<bool>, содержащий true, если вычисленное значение MAC точно совпадает с ожидаемым значением, и false в противном случае [SWS_CRYPT_50133].

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

В случае ошибки в объекте результата возвращается код ошибки, при этом действует семантика отката [SWS_CRYPT_50133]:

• ara::crypto::CryptoErrc::kProcessingNotFinished: возвращается, если вычисление дайджеста предварительно не было завершено вызовом метода Finish() [SWS_CRYPT_50133].
• ara::crypto::CryptoErrc::kInvalidInputSize: возникает, если переданный размер буфера ожидаемого MAC-дайджеста не поддерживается контекстом [SWS_CRYPT_50133].

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

Метод объявлен как const, а также noexcept и в соответствии со спецификацией является потокобезопасным (thread-safe), а также безопасным относительно исключений (exception safe) [SWS_CRYPT_50133]. Существенным предварительным условием является предварительно успешно завершенное вычисление дайджеста через Finish() [SWS_CRYPT_50133].

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

В отличие от Compare, который проверяет полное совпадение всего MAC-дайджеста [SWS_CRYPT_50133], CompareSubspan в том же контексте сравнивает с ожидаемым значением только старшие биты (most significant bits) [SWS_CRYPT_50028]. Для неключевых хэш-функций существует одноименная функция Compare в ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50154].

Синхронный метод CompareSubspan класса ara::crypto::cryp::MessageAuthnCodeCtx сопоставляет наиболее значимые биты (Most Significant Bits) вычисленного значения MAC с заданной эталонной последовательностью [SWS_CRYPT_50028]. Ожидаемое значение для сравнения передается через параметр expected как ReadOnlyMemRegion [SWS_CRYPT_50028]. Результат возвращается как ara::core::Result<bool> и содержит true при идентичности старших битов, а также false при расхождениях [SWS_CRYPT_50028].

Обработка ошибок и условия выполнения

Для корректного сравнения вычисление контрольного значения должно быть завершено. Если предшествующий вызов метода Finish() отсутствует, вызов завершается с кодом ошибки ara::crypto::CryptoErrc::kProcessingNotFinished [SWS_CRYPT_50028]. Если размер буфера переданного параметра expected недопустим для используемого метода, метод сообщает ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50028]. Оба типа ошибок гарантируют семантику отката [SWS_CRYPT_50028].

Параллелизм и контекст выполнения

Операция специфицирована как noexcept (exception-safe) и классифицирована как thread-safe [SWS_CRYPT_50028]. Интерпретация: заявленная потокобезопасность, вероятно, относится к состоянию после выполнения Finish(), так что несколько потоков могут параллельно верифицировать один и тот же вычисленный дайджест. Вопрос Q-ac8b7ead6a5b508e (открытый)

Метод Finish() в обязательном порядке завершает текущее вычисление Message Authentication Code (MAC) в рамках интерфейса MessageAuthnCodeCtx [SWS_CRYPT_22115]. Вызов выполняется синхронно, не принимает параметров и возвращает ara::core::Result<void>, что в штатном успешном случае представляет собой пустой результат [SWS_CRYPT_22115].

В случае ошибки функция возвращает код ошибки ara::crypto::CryptoErrc::kProcessingNotStarted, если вычисление MAC не было успешно запущено до вызова; при этом действует семантика отката [SWS_CRYPT_22115]. Операция объявлена как noexcept и согласно спецификации специфицирована как безопасная относительно исключений (exception safe), так и потокобезопасная (thread-safe) [SWS_CRYPT_22115].

В процессе обработки Finish() образует связующее звено между обработкой данных и оценкой: после вызова сгенерированный MAC-дайджест может быть передан через GetDigest() в предоставленный буфер [SWS_CRYPT_22116] или непосредственно верифицирован относительно эталонного значения с помощью CompareSubspan() [SWS_CRYPT_50028]. В то время как GetMaximumChunkSize() [SWS_CRYPT_50033] обобщенно описывает размеры буфера для Update() или Finish(), Finish() здесь не обрабатывает данные напрямую; его упоминание в требовании, вероятно, отражает единый шаблон для всех криптографических контекстов. Вопрос Q-79b4f4ecf3998e48 (открытый)

Синхронная функция-член Generate класса ara::crypto::cryp::MessageAuthnCodeCtx служит согласно [SWS_CRYPT_50029] для вычисления Message Authentication Code (MAC) за один шаг и записывает вычисленный дайджест в предоставленный выходной буфер.

Для вызова передаются следующие параметры:

• data: входные данные для вычисления MAC в виде ReadOnlyMemRegion.
• digest: целевая область памяти типа ReadWriteMemRegion, в которую записывается дайджест.
• iv: опциональный вектор инициализации в виде ara::core::Optional<ReadOnlyMemRegion>.

В случае успеха функция возвращает ara::core::Result<std::size_t>, содержащий размер записанного MAC-дайджеста в байтах [SWS_CRYPT_50029].

При возникновении ошибки возвращается код ошибки с семантикой отката [SWS_CRYPT_50029]:

• UninitializedContext: контекст еще не был инициализирован путем назначения ключа.
• ara::crypto::CryptoErrc::kUsageViolation: используемый ключ не имеет требуемого флага использования kAllowMac. Интерпретация: подходящий симметричный ключ предположительно должен быть предварительно создан и сконфигурирован через GenerateSymmetricKey [SWS_CRYPT_20721]. Вопрос Q-d22f397bbc02487b (открытый)
• ara::crypto::CryptoErrc::kEmptyKeySlot: Сконфигурированный KeySlot в данный момент пуст.
• ara::crypto::CryptoErrc::kUnsupported: обработка за один вызов не поддерживается или указание вектора инициализации не соответствует требованиям алгоритма (IV отсутствует или указан недопустимо).
• ara::crypto::CryptoErrc::kInvalidInputSize: размер буфера входных данных или IV не поддерживается.
• ara::crypto::CryptoErrc::kInsufficientCapacity: целевой буфер digest слишком мал для MAC-дайджеста.
• ara::crypto::CryptoErrc::kBusyResource: необходимый системный ресурс занят.

В отношении параллелизма метод специфицирован как thread-safe и exception safe [SWS_CRYPT_50029]. Он объявлен как const noexcept и не изменяет состояние контекста при выполнении.

Метод GenerateSubspan класса ara::crypto::cryp::MessageAuthnCodeCtx за один шаг вычисляет код аутентификации сообщений (MAC) для входных данных data и записывает начало (наиболее значащие байты, MSB) вычисленного дайджеста в выходной буфер truncatedDigest [SWS_CRYPT_50030]. Через необязательный параметр iv при необходимости может быть передан вектор инициализации [SWS_CRYPT_50030]. Прямой возврат ara::core::Result<std::size_t>, вероятно, указывает на синхронное выполнение; при успешном выполнении возвращается количество записанных байтов дайджеста MAC [SWS_CRYPT_50030]. Вопрос Q-167c6d44b9f39fed (открытый)

Спецификация определяет для случая ошибки семантику отката и предусматривает следующие коды ошибок [SWS_CRYPT_50030]:

• UninitializedContext: Контекст не был предварительно инициализирован назначением ключа [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Сконфигурированный KeySlot в данный момент пуст [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUsageViolation: разрешенное использование ключа не включает kAllowMac [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUnsupported: одношаговая обработка не поддерживается или конфигурация IV не соответствует контексту (требуемый IV отсутствует либо передан недопустимый IV) [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kInvalidInputSize: размер переданных данных data или iv не поддерживается [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kBusyResource: необходимый ресурс занят [SWS_CRYPT_50030].

Что касается среды выполнения, метод специфицирован как потокобезопасный и обеспечивает безопасность исключений (noexcept) [SWS_CRYPT_50030]. Необходимым условием для безошибочного вызова является предварительное предоставление ключа с соответствующими правами в контексте [SWS_CRYPT_50030].

Метод SetKey конфигурирует экземпляр ara::crypto::cryp::MessageAuthnCodeCtx для последующего вычисления MAC с предоставленным симметричным ключом [SWS_CRYPT_22118]. Вызов выполняется синхронно и принимает объект ключа в виде смарт-указателя SymmetricKey::Sptr. В качестве результата функция возвращает ara::core::Result<void>, который пуст в случае успеха или инкапсулирует специфический код ошибки в случае ошибки [SWS_CRYPT_22118].

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

• kUnsupported: контекст поддерживает привязку исключительно через KeySlot вместо прямых объектов ключей [SWS_CRYPT_22118].
• kIncompatibleObject: переданный объект симметричного ключа несовместим с целевым контекстом [SWS_CRYPT_22118].
• kUsageViolation: флаги полномочий ключа не содержат обязательно требуемого использования kAllowMac [SWS_CRYPT_22118].

С точки зрения безопасности выполнения интерфейс определен как thread-safe и exception safe (с noexcept) [SWS_CRYPT_22118]. Во взаимодействии с управлением ключами он представляет собой прямой аналог назначения на основе слотов: если реализация или сценарий использования поддерживает применение постоянных (персистентных) слотов, вместо этого используется перегрузка для KeySlot::Sptr [SWS_CRYPT_50026].

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

Виртуальная функция-член SetKey интерфейса ara::crypto::cryp::MessageAuthnCodeCtx из заголовочного файла ara/crypto/cryp/message_authn_code_ctx.h конфигурирует контекст для вычисления или проверки Message Authentication Code (MAC) [SWS_CRYPT_50026]. В качестве параметра синхронный метод принимает смарт-указатель keySlot типа KeySlot::Sptr, предоставляющий симметричный ключ, и возвращает ara::core::Result<void> [SWS_CRYPT_50026]. Привязка ключа семантически отложена: сохранённый в слоте ключ привлекается только в тот момент, когда вычисление MAC фактически запускается [SWS_CRYPT_50026]. Интерпретация: последующие обновления содержимого слота вплоть до запуска вычисления, таким образом, должны оставаться действенными. Вопрос Q-d1886811d8af71e3 (открытый)

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

Интерфейс определён как noexcept, обеспечивает безопасность исключений (exception safe) и явно специфицирован для параллельного вызова (thread-safe) [SWS_CRYPT_50026].

Обработка ошибок и взаимодействие

В случае ошибки метод гарантирует строгую семантику отката, благодаря чему полностью сохраняется предыдущее состояние контекста [SWS_CRYPT_50026]. В объекте результата могут возникать следующие коды ошибок:

• ara::crypto::CryptoErrc::kIncompatibleObject: переданный KeySlot несовместим с этим контекстом симметричного ключа [SWS_CRYPT_50026].
• ara::crypto::CryptoErrc::kUnsupported: конкретная реализация контекста не поддерживает установку через KeySlot [SWS_CRYPT_50026]. В этом случае альтернативно необходимо использовать перегрузку SetKey(SymmetricKey::Sptr) для прямой передачи ключа [SWS_CRYPT_22118].

Метод Start из ara::crypto::cryp::MessageAuthnCodeCtx инициализирует контекст для нового вычисления MAC и при этом задает вектор инициализации или значение nonce через параметр iv ([SWS_CRYPT_22110]). Это применяется, например, в таких алгоритмах, как GMAC ([SWS_CRYPT_22110]). Для вычислений без явного вектора инициализации в качестве альтернативы доступна перегрузка без параметров Start() ([SWS_CRYPT_22111]).

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

Вызов происходит синхронно и специфицирован как thread-safe, а также exception safe ([SWS_CRYPT_22110]). После успешного вызова контексту можно последовательно передавать части сообщения с помощью Update ([SWS_CRYPT_22113]). Выполняющуюся, еще не завершенную потоковую операцию при необходимости можно прервать через Cancel ([SWS_CRYPT_50027]).

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

Метод возвращает ara::core::Result<void>, имеющий семантику отката (rollback) в случае ошибки ([SWS_CRYPT_22110]). Возможными состояниями ошибки являются:

• UninitializedContext: Контексту предварительно не был назначен ключ ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Сконфигурированный KeySlot пуст ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUsageViolation: Права ключа не содержат kAllowMac ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kInvalidInputSize: Переданный размер IV не поддерживается ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUnsupported: Потоковая обработка или установка IV не поддерживается алгоритмом либо контекстом ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kBusyResource: Необходимый ресурс занят ([SWS_CRYPT_22110]).

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

Метод Start() инициализирует экземпляр ara::crypto::cryp::MessageAuthnCodeCtx для нового вычисления MAC [SWS_CRYPT_22111]. Вызов не принимает параметров и возвращает ara::core::Result<void> [SWS_CRYPT_22111]. Выполнение, вероятно, происходит синхронно, так как объект результата предоставляется напрямую. Вопрос Q-1e6e36f4ed1176d3 (открытый)

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

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

• UninitializedContext: контексту предварительно не был назначен ключ [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUnsupported: контекст не поддерживает потоковый режим (streaming) или алгоритм строго требует вектор инициализации (IV) [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kBusyResource: необходимый ресурс занят [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kEmptyKeySlot: сконфигурированный KeySlot пуст [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUsageViolation: ключ не разрешает вычисление MAC без установленного kAllowMac [SWS_CRYPT_22111].

Функция специфицирована как потокобезопасная и безопасная относительно исключений (exception safe) [SWS_CRYPT_22111].

Взаимодействие в потоковом процессе

Если алгоритм требует IV (например, GMAC), вместо этого должна использоваться перегрузка Start(ReadOnlyMemRegion iv) [SWS_CRYPT_22110]. После успешного вызова данные сообщения могут передаваться пошагово через Update() [SWS_CRYPT_22113]. Еще не завершенную потоковую операцию можно сбросить через Cancel() [SWS_CRYPT_50027].

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

Синхронный метод Update контекста ara::crypto::cryp::MessageAuthnCodeCtx служит для дополнения текущего вычисления Message Authentication Code (MAC) очередным фрагментом входного сообщения [SWS_CRYPT_22113]. Обрабатываемый фрагмент данных передается через параметр data в форме ReadOnlyMemRegion. В качестве возвращаемого значения функция возвращает ara::core::Result<void>, которое либо подтверждает успешный промежуточный шаг, либо в случае ошибки дает информацию о ее причине [SWS_CRYPT_22113].

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

В случае ошибки гарантируется семантика отката, так что предыдущее состояние вычисления остается неизменным [SWS_CRYPT_22113]. Возможные причины ошибок:

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

Метод объявлен как noexcept, а также специфицирован как потокобезопасный и безопасный относительно исключений (exception safe) [SWS_CRYPT_22113].

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

Чтобы избежать ошибок буфера с ara::crypto::CryptoErrc::kInvalidInputSize, максимально допустимый размер входных данных для отдельных вызовов можно предварительно запросить через метод GetMaximumChunkSize() [SWS_CRYPT_50033]. После последовательной обработки всех частей сообщения вычисление MAC-тега, согласно интерпретации, обычно завершается с помощью метода Finish() [SWS_CRYPT_50033]. Вопрос Q-7f8eaf8ebbf30d55 (открытый)

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

Метод Verify в ara::crypto::cryp::MessageAuthnCodeCtx ([SWS_CRYPT_50031]) служит для синхронного вычисления MAC-дайджеста по входному буферу data и прямого сравнения с ожидаемым значением expected. Опционально через iv может быть передан вектор инициализации. В качестве результата функция возвращает ara::core::Result<bool>, который содержит true, если вычисленный MAC совпадает с ожидаемой последовательностью байтов, и false в противном случае.

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

Если верификация завершается сбоем по системным или криптографическим причинам, метод возвращает ara::core::Result с соответствующим кодом ошибки ([SWS_CRYPT_50031]):

• UninitializedContext: если контекст не был предварительно инициализирован путем назначения ключа.
• ara::crypto::CryptoErrc::kEmptyKeySlot: если сконфигурированный KeySlot пуст.
• ara::crypto::CryptoErrc::kUsageViolation: если разрешенное использование ключа не включает kAllowMac.
• ara::crypto::CryptoErrc::kInvalidInputSize: если размер буфера data, expected или iv недопустим.
• ara::crypto::CryptoErrc::kUnsupported: если выполнение за один вызов не поддерживается или предоставление iv не соответствует требованиям алгоритма.
• ara::crypto::CryptoErrc::kBusyResource: при конфликтах ресурсов.

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

Метод специфицирован как thread-safe и exception safe ([SWS_CRYPT_50031]). В случае ошибки действует семантика отката. В отличие от асимметричных проверок подписи в ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_24112], [SWS_CRYPT_50024]), Verify работает с симметричными контекстами MAC. Максимальный размер буфера, обрабатываемый за один вызов, вероятно, ограничен реализацией контекста — аналогично запросу буфера у верификаторов подписи ([SWS_CRYPT_50025]). Вопрос Q-51e7427e4e082881 (открытый)

Метод VerifySubspan класса ara::crypto::cryp::MessageAuthnCodeCtx служит для синхронного вычисления дайджеста MAC и последующего сравнения его наиболее значащих битов с ожидаемой последовательностью байтов [SWS_CRYPT_50032]. Он обрабатывает входные данные через data, ожидаемые старшие биты через expected, а также необязательный вектор инициализации через iv [SWS_CRYPT_50032]. Результат возвращается как ara::core::Result<bool> и при успешном совпадении сигнализирует true, а иначе — false [SWS_CRYPT_50032].

Интерфейс специфицирован как noexcept, является exception safe, а также thread-safe и применяет семантику отката в случае ошибки [SWS_CRYPT_50032]. Неудачные вызовы возвращают специфические коды ошибок в возвращаемом значении [SWS_CRYPT_50032]:

• UninitializedContext: контекст ранее не был инициализирован назначением ключа [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUsageViolation: допустимое использование ключа не включает kAllowMac [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Сконфигурированный KeySlot в данный момент пуст [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kInvalidInputSize: размер переданных данных, ожидаемого контрольного значения или IV не поддерживается [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUnsupported: операция single-call не поддерживается или предоставление IV противоречит требованиям контекста [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kBusyResource: необходимый ресурс занят [SWS_CRYPT_50032].