类 ara::crypto::cryp::VerifierPublicCtx

用法与语义

方法 Cancel() 中止之前由 Start() 发起且尚未完成的正在运行的流式操作 [SWS_CRYPT_50023]。它在头文件 ara/crypto/cryp/verifier_public_ctx.h 中被定义为上下文 ara::crypto::cryp::VerifierPublicCtx 的纯虚方法 [SWS_CRYPT_50023]。该调用同步进行且不带参数。返回值使用 ara::core::Result<void>，成功时该值为空，并确认操作已成功中止 [SWS_CRYPT_50023]。

错误处理

如果数据处理尚未通过调用方法 Start() 启动，则中止操作失败。在这种情况下，该函数在保证回滚语义的同时返回带有错误代码 ara::crypto::CryptoErrc::kProcessingNotStarted 的错误结果 [SWS_CRYPT_50023]。

并发性与限制

该规范将该方法标明为线程安全（thread-safe）和带有标识 noexcept 的异常安全（exception safe）[SWS_CRYPT_50023]。理解：成功中止后，上下文应该恢复到处理开始之前的初始状态，以便可以启动新的流式处理过程。 问题 Q-d80d09c8a8311bbc (未决)

crypt 模块内的协同工作

这种具有相同签名和错误处理的统一中止模式一致适用于模块 crypt 的所有流式上下文：

• 用于消息身份验证码的 MessageAuthnCodeCtx [SWS_CRYPT_50027]，
• 用于生成数字签名的 SignerPrivateCtx [SWS_CRYPT_50041]，
• 用于对称加密和解密的 SymmetricCipherCtx [SWS_CRYPT_50046]，
• 用于加密哈希操作的 HashFunctionCtx [SWS_CRYPT_50058]，
• 用于非对称解密的 DecryptorPrivateCtx [SWS_CRYPT_50069]，
• 用于经过身份验证的加密的 AuthCipherCtx [SWS_CRYPT_50077]，以及
• 用于非对称加密的 EncryptorPublicCtx [SWS_CRYPT_50089]。

ara::crypto::cryp::VerifierPublicCtx 中的方法 Finish 完成签名验证并返回验证结果 [SWS_CRYPT_50022]。它通过输入缓冲区 signature（类型 ReadOnlyMemRegion）接收待验证的签名，并通过 signatureFormat（类型 FormatId）接收其格式 [SWS_CRYPT_50022]。该调用为同步调用，根据规范被声明为线程安全以及异常安全 [SWS_CRYPT_50022]。

返回值采用 ara::core::Result<bool> [SWS_CRYPT_50022]：签名验证成功时结果包含 true，签名在内容上无效时包含 false。若发生处理错误，则返回相应的错误代码 [SWS_CRYPT_50022]：

• ara::crypto::CryptoErrc::kProcessingNotStarted：操作此前未成功启动（回滚语义）[SWS_CRYPT_50022]。
• ara::crypto::CryptoErrc::kInvalidInputSize：signature 的缓冲区大小无效（回滚语义）[SWS_CRYPT_50022]。
• ara::crypto::CryptoErrc::kUnsupportedFormat：不支持指定的格式 signatureFormat（回滚语义）[SWS_CRYPT_50022]。
• ara::crypto::CryptoErrc::kInvalidArgument：签名不符合指定的格式（回滚语义）[SWS_CRYPT_50022]。

在加密流程中，该函数与通过 ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040] 进行的签名生成相对应，后者将签名写入输出缓冲区。所有报告的错误均具有回滚语义 [SWS_CRYPT_50022]，从而在失败时保持上下文状态的一致性。

方法 SetKey 配置 VerifierPublicCtx 的实例以使用特定公钥进行签名验证（[SWS_CRYPT_24115]）。通过参数 key 传递类型为 PublicKey::Sptr 的指针。该调用同步进行，并返回一个 ara::core::Result<void>，该返回值在成功时为空，或封装特定的错误代码。

根据规范，该操作被设计为线程安全且异常安全（exception safe）（[SWS_CRYPT_24115]）。如果在密钥绑定期间发生错误，回滚语义对所有错误情况均生效，从而使上下文保持在一致状态：

• CryptoErrc::kIncompatibleObject：传入的密钥与签名验证上下文不兼容（[SWS_CRYPT_24115]）。
• CryptoErrc::kUsageViolation：密钥的权限不允许签名验证（缺少用于签名验证的使用标志）（[SWS_CRYPT_24115]）。
• ara::crypto::CryptoErrc::kUnsupported：上下文实现仅支持通过 KeySlot 绑定密钥（[SWS_CRYPT_24115]）。

在加密工作流中，SetKey 构成了 SignerPrivateCtx::SetKey 的公开对应部分（[SWS_CRYPT_23515]）。只要上下文不允许通过 PublicKey::Sptr 直接传递密钥，或者密钥在安全槽中进行管理，则可以使用通过 KeySlot::Sptr 的重载作为替代方案（[SWS_CRYPT_50018]）。

使用

类 ara::crypto::cryp::VerifierPublicCtx 的方法 SetKey 配置验证上下文，以使用存储在传入的 KeySlot 中的密钥 [SWS_CRYPT_50018]。该密钥在签名验证启动时被使用 [SWS_CRYPT_50018]。

参数是包含公钥的 KeySlot::Sptr 类型的智能指针 keySlot [SWS_CRYPT_50018]。该函数同步工作并返回 ara::core::Result<void>，以指示成功完成或错误 [SWS_CRYPT_50018]。

错误处理与语义

该操作被指定为 noexcept 且 exception safe [SWS_CRYPT_50018]。如果发生错误，将应用回滚语义 [SWS_CRYPT_50018]：

• ara::crypto::CryptoErrc::kIncompatibleObject：提供的 KeySlot 与此上下文不兼容 [SWS_CRYPT_50018]。
• ara::crypto::CryptoErrc::kUnsupported：该上下文仅支持直接设置 PublicKey [SWS_CRYPT_50018]。

并发性与交互

该方法被指定为线程安全 [SWS_CRYPT_50018]。作为 KeySlot 的替代方案，VerifierPublicCtx 提供了直接设置 PublicKey 的重载 [SWS_CRYPT_24115]。通过 KeySlot 的相应密钥配置也类似地存在于其他上下文中，例如 SignerPrivateCtx [SWS_CRYPT_50036] 或 MessageAuthnCodeCtx [SWS_CRYPT_50026]。

使用

接口 ara::crypto::cryp::VerifierPublicCtx（[SWS_CRYPT_50019]）的同步方法 Start() 初始化用于流式模式下新加密签名校验的上下文。该函数不接受任何传入参数，声明为 noexcept，并返回一个在成功时为空的 ara::core::Result<void>。

错误处理与回滚

若在执行时发生错误，则生效回滚语义（[SWS_CRYPT_50019]），从而使上下文保持一致状态。可能的错误原因包括：

• UninitializedContext：事先未为上下文分配加密密钥。
• ara::crypto::CryptoErrc::kUsageViolation：所分配的密钥未获准用于签名校验（kAllowSig Verification）。
• ara::crypto::CryptoErrc::kEmptyKeySlot：配置用于验证的 KeySlot 当前为空。
• ara::crypto::CryptoErrc::kUnsupported：上下文不支持流式处理，或该过程强制要求上下文值。
• ara::crypto::CryptoErrc::kBusyResource：该操作所需的一项资源当前被占用。

并发性与交互

尽管规范将该方法标明为线程安全（[SWS_CRYPT_50019]），但在正在进行验证期间对同一上下文实例进行并行调用，很可能会重置现有操作或由于资源被占用而失败。 问题 Q-af5e08ff9d905a29 (未决)

成功初始化后，消息部分通过 Update()（[SWS_CRYPT_50021]）按顺序传递。如有需要，可使用 Cancel()（[SWS_CRYPT_50023]）提前中止正在进行的流式操作。若算法强制要求上下文值，则必须改为调用重载函数 Start(ReadOnlyMemRegion context)（[SWS_CRYPT_50020]）。

使用

函数 Start 根据 [SWS_CRYPT_50020] 初始化类 ara::crypto::cryp::VerifierPublicCtx 的验证上下文，以用于新的签名校验。它接收类型为 ReadOnlyMemRegion 的 context 作为输入参数，该参数提供应用程序特定的上下文值。作为无上下文数据的替代方案，存在重载 [SWS_CRYPT_50019]。返回值为 ara::core::Result<void>；解释：由于既未定义回调也未定义 Future 对象，该调用大概率以纯同步方式处理。 问题 Q-4e10cdb1a4343a3a (未决)

错误处理

出错时，该函数返回一个带有来自 ara::crypto::CryptoErrc 的相应错误码的 ara::core::Result，并指定了回滚语义 [SWS_CRYPT_50020]：

• kUninitializedContext：上下文尚未通过分配密钥进行初始化。
• kEmptyKeySlot：配置的 KeySlot 当前为空。
• kUsageViolation：所分配密钥的允许用途不包含 kAllowSigVerification。
• kInvalidInputSize：传入的上下文值的缓冲区大小对该算法无效。
• kUnsupported：上下文不支持流式处理，或该算法不支持设置上下文值。
• kBusyResource：所需资源已被占用。

并发性与限制

根据 [SWS_CRYPT_50020]，该方法被归类为线程安全且异常安全。它不会引发异常（noexcept）。

相互作用

在成功执行 Start 后，可通过重复调用 Update 逐步传输输入消息 [SWS_CRYPT_50021]。由 Start 发起的正在进行的流式处理过程，可根据需要在必要时通过 Cancel 提前终止 [SWS_CRYPT_50023]。

使用

方法 Update() 用于通过输入消息的下一部分逐步更新签名校验上下文 [SWS_CRYPT_50021]。作为参数传入类型为 ReadOnlyMemRegion 的存储区 data。该函数返回一个 ara::core::Result<void>；解释：由于该返回类型，处理大概率以同步方式进行。 问题 Q-f98391030b3b4684 (未决)

错误处理

出错时，将返回具有回滚语义的相应错误码 [SWS_CRYPT_50021]：

• ara::crypto::CryptoErrc::kProcessingNotStarted：签名校验之前未通过调用方法 Start() 发起 [SWS_CRYPT_50021]。
• ara::crypto::CryptoErrc::kInvalidInputSize：不支持 data 中所提供数据的大小 [SWS_CRYPT_50021]。

并发性与交互

该操作在规范中被归类为 thread-safe 和 exception safe [SWS_CRYPT_50021]。在调用之前必须已通过 Start() 完成初始化 [SWS_CRYPT_50021]。为防止出现 kInvalidInputSize，可通过同一上下文的方法 GetMaximumChunkSize() 查询单个调用所允许的最大缓冲区大小 [SWS_CRYPT_50025]。SignerPrivateCtx 中的 Update() 构成了按消息生成签名的对应补充操作 [SWS_CRYPT_50039]。

使用

上下文 ara::crypto::cryp::VerifierPublicCtx 的方法 Verify 用于在单次调用中验证所提供消息的签名 [SWS_CRYPT_24112]。消息缓冲区 message、签名 signature 以及格式 signatureFormat 作为参数传递 [SWS_CRYPT_24112]。返回值 ara::core::Result<bool> 在校验成功时包含 true，在不匹配时包含 false，或者包含错误代码 [SWS_CRYPT_24112]。解读：鉴于同步结果类型，校验过程很可能会在调用线程中阻塞运行。 问题 Q-671054c6e2b581c6 (未决)

错误处理与并发

该函数被指定为 exception safe 和 thread-safe [SWS_CRYPT_24112]。在出错时，错误代码适用回滚语义 [SWS_CRYPT_24112]。可能的错误原因包括：

• UninitializedContext，如果上下文未用密钥初始化 [SWS_CRYPT_24112]，
• ara::crypto::CryptoErrc::kEmptyKeySlot（密钥槽为空时）或 kUsageViolation（密钥缺少权限 kAllowSig Verification 时）[SWS_CRYPT_24112]，
• ara::crypto::CryptoErrc::kInvalidInputSize（缓冲区大小不允许时）[SWS_CRYPT_24112]，
• ara::crypto::CryptoErrc::kUnsupportedFormat 或 kInvalidArgument（签名格式错误或不兼容时）[SWS_CRYPT_24112]，
• ara::crypto::CryptoErrc::kBusyResource，如果所需资源被占用 [SWS_CRYPT_24112]。

相互作用

单次调用的最大缓冲区大小可通过 GetMaximumChunkSize() 查询 [SWS_CRYPT_50025]。若算法强制要求上下文值，则返回 ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_24112]；在这种情况下，应选择带有附加 context 参数的重载 [SWS_CRYPT_50024]。对于消息验证码的校验，存在作为区别的 ara::crypto::cryp::MessageAuthnCodeCtx::Verify [SWS_CRYPT_50031]。

同步方法 Verify 在单次调用中考虑用户自定义上下文值来校验传入消息的数字签名（[SWS_CRYPT_50024]）。作为输入参数，该方法需要缓冲区 message、context 和 signature（各自作为 ReadOnlyMemRegion）以及通过 signatureFormat 指定的签名格式（[SWS_CRYPT_50024]）。返回值是一个 ara::core::Result<bool>：它在验证成功时包含 true，在签名错误时包含 false，或者包含相应的错误码（[SWS_CRYPT_50024]）。

出错时适用回滚语义（[SWS_CRYPT_50024]）。具体错误码尤其包括：

• UninitializedContext，如果验证上下文尚未用密钥值初始化（[SWS_CRYPT_50024]），
• ara::crypto::CryptoErrc::kInvalidInputSize，在缓冲区大小不允许时（[SWS_CRYPT_50024]），
• ara::crypto::CryptoErrc::kUnsupported，如果所选签名算法不支持指定上下文值（[SWS_CRYPT_50024]），
• ara::crypto::CryptoErrc::kUnsupportedFormat 或 ara::crypto::CryptoErrc::kInvalidArgument，如果指定的签名格式不受支持或签名不符合该格式（[SWS_CRYPT_50024]），
• ara::crypto::CryptoErrc::kUsageViolation，如果允许的密钥用途不包含 kAllowSigVerification，以及 ara::crypto::CryptoErrc::kEmptyKeySlot 和 ara::crypto::CryptoErrc::kBusyResource（[SWS_CRYPT_50024]）。

该方法声明为 const noexcept，被视为异常安全，并被指定为 thread-safe（[SWS_CRYPT_50024]）。在与上下文的交互中，可通过 GetMaximumChunkSize 确定单次调用的最大缓冲区大小（[SWS_CRYPT_50025]）。对于无上下文的验证，可以使用 Verify 的替代重载（[SWS_CRYPT_24112]）。