类 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 的结果，同时确保回滚语义 [SWS_CRYPT_50027]。关于执行安全性，该接口被规范为线程安全（thread-safe），并且由于被声明为 noexcept 且不抛出异常而保证异常安全性（exception safe）[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]。

Interpretation：通过中止未完成的操作，上下文有望恢复到清理后的状态，从而允许稍后通过 Start() 重新初始化。 问题 Q-a8fa5cb85c3dab50 (未决)

使用

类 ara::crypto::cryp::MessageAuthnCodeCtx 的纯虚方法 Compare 用于将计算得出的消息验证码（MAC）的尺寸和内容与期望的摘要进行比对 [SWS_CRYPT_50133]。期望的 MAC 摘要作为参数通过 ReadOnlyMemRegion expected 传递。该函数返回一个 ara::core::Result<bool>，若计算得出的 MAC 值与期望值完全匹配，则包含 true，否则包含 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]。

相互作用

与验证整个 MAC 摘要完全匹配的 Compare 不同 [SWS_CRYPT_50133]，CompareSubspan 在相同上下文中仅将最高有效位（most significant bits）与期望值进行比较 [SWS_CRYPT_50028]。对于非密钥哈希函数，在 ara::crypto::cryp::HashFunctionCtx 中存在同名的 Compare 函数 [SWS_CRYPT_50154]。

类 ara::crypto::cryp::MessageAuthnCodeCtx 的同步方法 CompareSubspan 将已计算 MAC 值的最高有效位（Most Significant Bits）与给定的参考值进行比对 [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() 强制性完成接口 MessageAuthnCodeCtx 内正在进行的消息认证码（MAC）计算 [SWS_CRYPT_22115]。该调用同步执行，不接收任何参数，并返回 ara::core::Result<void>，在正常成功情况下表示一个空结果 [SWS_CRYPT_22115]。

如果发生错误，且 MAC 计算在调用前未成功启动，则该函数返回错误码 ara::crypto::CryptoErrc::kProcessingNotStarted；此时回滚语义生效 [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 (未决)

根据 [SWS_CRYPT_50029]，类 ara::crypto::cryp::MessageAuthnCodeCtx 的同步成员函数 Generate 用于在单步中计算 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：不支持单次调用（Single-Call）处理，或初始化向量的指定不符合算法要求（缺少或无效指定的 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，并在执行时不会改变上下文的状态。

类 ara::crypto::cryp::MessageAuthnCodeCtx 的方法 GenerateSubspan 在单步操作中计算输入数据 data 的消息认证码（MAC），并将计算出的摘要的起始部分（最高有效字节，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]。

关于执行环境，该方法被指定为 thread-safe 并提供异常安全性（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]。

使用

来自头文件 ara/crypto/cryp/message_authn_code_ctx.h 的接口 ara::crypto::cryp::MessageAuthnCodeCtx 的虚成员函数 SetKey 配置用于计算或验证消息认证码（MAC）的上下文 [SWS_CRYPT_50026]。作为参数，该同步方法接收一个持有对称密钥的类型为 KeySlot::Sptr 的智能指针 keySlot，并返回一个 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]。

ara::crypto::cryp::MessageAuthnCodeCtx 的方法 Start 为新的 MAC 计算初始化上下文，并通过参数 iv 设置初始化向量或 Nonce 值（[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>，其在错误情况下具有回滚语义（[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：该上下文不支持流式处理，或该算法强制要求初始化向量（IV）[SWS_CRYPT_22111]。
• ara::crypto::CryptoErrc::kBusyResource：所需资源被占用 [SWS_CRYPT_22111]。
• ara::crypto::CryptoErrc::kEmptyKeySlot：配置的 KeySlot 为空 [SWS_CRYPT_22111]。
• ara::crypto::CryptoErrc::kUsageViolation：在未设置 kAllowMac 的情况下，该密钥不允许进行 MAC 计算 [SWS_CRYPT_22111]。

该函数被指定为线程安全且异常安全 (exception safe) [SWS_CRYPT_22111]。

流式处理流程中的配合

如果算法需要 IV（例如 GMAC），则必须改用重载 Start(ReadOnlyMemRegion iv) [SWS_CRYPT_22110]。成功调用后，可以通过 Update() 逐步传递消息数据 [SWS_CRYPT_22113]。尚未完成的流式操作可以通过 Cancel() 放弃 [SWS_CRYPT_50027]。

使用

上下文 ara::crypto::cryp::MessageAuthnCodeCtx 的同步方法 Update 用于通过输入消息的另一个片段来补充正在进行的消息验证码（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 (未决)

使用

ara::crypto::cryp::MessageAuthnCodeCtx 中的方法 Verify ([SWS_CRYPT_50031]) 用于通过输入缓冲区 data 同步计算 MAC 摘要，并将其直接与预期值 expected 进行比较。可选地可以通过 iv 传递初始化向量。函数返回一个 ara::core::Result<bool> 作为结果，如果计算出的 MAC 与预期的字节序列匹配，则包含 true，否则包含 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：如果不支持单次调用（Single-Call）执行，或者提供 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 (未决)

类 ara::crypto::cryp::MessageAuthnCodeCtx 的方法 VerifySubspan 用于同步计算 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]。