类 ara::crypto::cryp::SignerPrivateCtx

方法 Cancel() 用于在类 ara::crypto::cryp::SignerPrivateCtx 内部同步中止正在进行且尚未完成的流式传输操作，该操作先前通过调用 Start() 启动 [SWS_CRYPT_50041]。纯虚接口 virtual ara::core::Result<void> Cancel() noexcept = 0; 在头文件 ara/crypto/cryp/signer_private_ctx.h 中声明，不接受任何传入参数，并通过空的 ara::core::Result<void> [SWS_CRYPT_50041] 指示成功中止。对于调用方而言，该方法被指定为异常安全的（exception safe）且并发线程安全的（thread-safe）[SWS_CRYPT_50041]。

关于调用顺序和错误处理，Cancel() 强制要求必须存在活动处理：如果此前未通过调用方法 Start() 启动数据处理，则中止将失败，并返回具有定义的回滚语义的错误代码 ara::crypto::CryptoErrc::kProcessingNotStarted [SWS_CRYPT_50041]。解释：在成功调用 Cancel() 之后，上下文推测会恢复到未启动的初始状态，以便可以开始新的签名或流过程。 问题 Q-348fb3ae43e424c9 (未决)

该设计遵循加密模块中所有流操作的统一原则。对于相关上下文，存在完全相同的签名和错误语义，如 VerifierPublicCtx [SWS_CRYPT_50023]、MessageAuthnCodeCtx [SWS_CRYPT_50027]、SymmetricCipherCtx [SWS_CRYPT_50046]、HashFunctionCtx [SWS_CRYPT_50058]、DecryptorPrivateCtx [SWS_CRYPT_50069]、AuthCipherCtx [SWS_CRYPT_50077] 以及 EncryptorPublicCtx [SWS_CRYPT_50089]。

使用

方法 ara::crypto::cryp::SignerPrivateCtx::Finish 同步完成签名生成，并将计算出的签名直接写入所提供的输出缓冲区 signature [SWS_CRYPT_50040]。该函数期待可写内存区域 signature（类型 ReadWriteMemRegion）和所需格式 signatureFormat（类型 FormatId）作为传入参数 [SWS_CRYPT_50040]。ara::core::Result<size_t> 返回所写入签名数据的实际字节大小作为返回值；该数据量可以小于目标缓冲区的容量 [SWS_CRYPT_50040]。

错误处理

针对所有发生的错误情况，均指定了回滚语义 [SWS_CRYPT_50040]。可以通过结果返回以下错误代码：

• ara::crypto::CryptoErrc::kProcessingNotStarted：签名生成此前未成功启动 [SWS_CRYPT_50040]。
• ara::crypto::CryptoErrc::kInsufficientCapacity：传入的输出缓冲区 signature 的容量过小 [SWS_CRYPT_50040]。
• ara::crypto::CryptoErrc::kUnsupportedFormat：signatureFormat 的值未知或不受支持 [SWS_CRYPT_50040]。

并发性与限制

该方法被指定为 thread-safe 和 exception safe，且不得抛出异常 (noexcept) [SWS_CRYPT_50040]。有效调用的绝对先决条件是上下文中的生成过程此前已成功启动 [SWS_CRYPT_50040]。

相互作用

验证所生成签名的直接功能对应项是方法 ara::crypto::cryp::VerifierPublicCtx::Finish [SWS_CRYPT_50022]。与哈希或 MAC 计算的上下文相比（在这些上下文中 Finish() 仅完成计算，而中间或最终结果是单独获取的 [SWS_CRYPT_21115] [SWS_CRYPT_21116]），SignerPrivateCtx::Finish 会将签名直接写入缓冲区 [SWS_CRYPT_50040]。

使用

类 ara::crypto::cryp::SignerPrivateCtx 的虚方法 SetKey（#include "ara/crypto/cryp/signer_private_ctx.h"）配置签名上下文以使用提供的私钥 [SWS_CRYPT_23515]。类型为 PrivateKey::Sptr 的 key 作为源密钥对象被传递为参数 [SWS_CRYPT_23515]。该方法同步执行并返回一个 ara::core::Result<void>，其在成功时为空，或在失败时传递发生的错误码 [SWS_CRYPT_23515]。

错误处理

如果在配置期间发生错误，将应用回滚语义 [SWS_CRYPT_23515]。指定了以下错误码：

• ara::crypto::CryptoErrc::kIncompatibleObject：传入的密钥对象与当前上下文不兼容 [SWS_CRYPT_23515]。
• ara::crypto::CryptoErrc::kUsageViolation：该密钥的允许用途不包括签名生成（kAllowSig Generation）[SWS_CRYPT_23515]。
• ara::crypto::CryptoErrc::kUnsupported：特定上下文仅支持通过 KeySlot 进行设置 [SWS_CRYPT_23515]。

并发性与限制

该接口被声明为 noexcept，并根据规范被归类为既异常安全（“exception safe”）又线程安全（“thread-safe”）[SWS_CRYPT_23515]。

相互作用

在 SignerPrivateCtx 中或者存在重载 SetKey(KeySlot::Sptr)，它对上下文进行配置，使得存储在 KeySlot 中的密钥直到签名计算开始时才被使用 [SWS_CRYPT_50036]。在验证端，ara::crypto::cryp::VerifierPublicCtx 内带有 PublicKey::Sptr 的功能对应项 SetKey 用于检查签名 [SWS_CRYPT_24115]。

使用

方法 SetKey 配置签名上下文 [SWS_CRYPT_50036] 以使用位于所传递 KeySlot::Sptr 中的密钥。该密钥仅在实际启动签名计算的时间点才被使用 [SWS_CRYPT_50036]。该调用同步进行，声明为 noexcept，并返回一个 ara::core::Result<void> [SWS_CRYPT_50036]。

错误处理

若配置失败，则在返回对象中传递错误，此时适用回滚语义 [SWS_CRYPT_50036]：

• ara::crypto::CryptoErrc::kIncompatibleObject：在所提供的 keySlot 与此签名上下文不兼容时发生 [SWS_CRYPT_50036]。
• ara::crypto::CryptoErrc::kUnsupported：如果上下文仅支持直接设置 PrivateKey，则会报告该错误 [SWS_CRYPT_50036]。

并发性与交互

该接口属于类 ara::crypto::cryp::SignerPrivateCtx，并被指定为 thread-safe 以及 exception-safe [SWS_CRYPT_50036]。除了这种基于插槽的变体之外，SignerPrivateCtx 还提供了一个直接接收 PrivateKey::Sptr 对象的重载 [SWS_CRYPT_23515]。类似的插槽绑定也存在于其他密码上下文中，例如在 VerifierPublicCtx 中用于带有 KeySlot 的签名校验 [SWS_CRYPT_50018]，或在 KeyDerivationFunctionCtx 中用于密钥派生 [SWS_CRYPT_50010]。

方法 Sign 按照 [SWS_CRYPT_23512] 在单一步骤中对消息进行同步签名。它接收待签名的输入消息（message）、目标缓冲区（signature）、所需的签名格式（signatureFormat）以及可选的上下文值（context）。成功时，该函数通过 ara::core::Result<std::size_t> 返回生成的签名的实际字节大小，该大小可能小于目标缓冲区的容量 [SWS_CRYPT_23512]。

在并发性和异常安全性方面，该方法声明为 noexcept，视为 exception safe，并显式指定为 thread-safe [SWS_CRYPT_23512]。

在调用之前，必须使用密钥值正确初始化上下文；否则将报告 UninitializedContext [SWS_CRYPT_23512]。关于输入长度，Sign 与 [SWS_CRYPT_50042] 协同配合：可以通过 GetMaximumChunkSize 确定用于单步处理的最大支持缓冲区大小，以防范如 ara::crypto::CryptoErrc::kInvalidInputSize 之类的错误 [SWS_CRYPT_23512] [SWS_CRYPT_50042]。

错误处理为特定错误码规定了回滚语义 [SWS_CRYPT_23512]：

• ara::crypto::CryptoErrc::kInsufficientCapacity：输出缓冲区 signature 过小。
• ara::crypto::CryptoErrc::kUnsupported：不支持单步处理，或者上下文规范 context 不符合规定。
• ara::crypto::CryptoErrc::kUnsupportedFormat：指定的 FormatId 未知或不受支持。
• ara::crypto::CryptoErrc::kUsageViolation：允许的密钥用途不包含 kAllowSig Generation。
• ara::crypto::CryptoErrc::kEmptyKeySlot 或 ara::crypto::CryptoErrc::kBusyResource：配置的 KeySlot 为空，或所需资源被占用。

无参数方法 Start 初始化类 ara::crypto::cryp::SignerPrivateCtx 的上下文以进行新的签名生成 [SWS_CRYPT_50037]。该调用同步进行，声明为 noexcept，并在初始化成功时返回一个空的 ara::core::Result<void>，或者在出错时返回一个错误代码 [SWS_CRYPT_50037]。

在出错时，该操作支持回滚语义 [SWS_CRYPT_50037]。来自 ara::crypto::CryptoErrc 的已定义错误原因包括：

• kUninitializedContext：上下文事先未通过提供密钥进行初始化 [SWS_CRYPT_50037]。
• kEmptyKeySlot：配置的密钥插槽当前为空 [SWS_CRYPT_50037]。
• kUsageViolation：所分配密钥的权限不包含 kAllowSigGeneration [SWS_CRYPT_50037]。
• kBusyResource：该操作所需的一项资源被占用 [SWS_CRYPT_50037]。
• kUnsupported：上下文不支持流式处理，或者签名算法强制要求指定上下文值 [SWS_CRYPT_50037]。

根据规范，该函数是 thread-safe 以及 exception safe 的 [SWS_CRYPT_50037]。若算法需要特定的上下文值，则必须改用重载变体 Start(ReadOnlyMemRegion context) [SWS_CRYPT_50038]。在成功调用 Start 后，可以通过 Update 连续处理待签名的消息部分 [SWS_CRYPT_50039]。

方法 Start 用于在提供上下文值的情况下，同步初始化用于新签名生成的上下文 ara::crypto::cryp::SignerPrivateCtx ([SWS_CRYPT_50038])。它接收类型为 ReadOnlyMemRegion 的参数 context，并返回一个 ara::core::Result<void>。该函数被指定为 noexcept=0，并被声明为异常安全以及线程安全 ([SWS_CRYPT_50038])。

在发生错误时，上下文状态通过回滚语义保持不变 ([SWS_CRYPT_50038])。指定的错误原因包括：

• UninitializedContext：如果上下文之前未通过提供密钥进行初始化。
• ara::crypto::CryptoErrc::kUnsupported：如果上下文不支持流式处理，或者算法不允许上下文值。
• ara::crypto::CryptoErrc::kInvalidInputSize：如果传入的上下文值的缓冲区大小无效。
• ara::crypto::CryptoErrc::kEmptyKeySlot：如果配置的密钥槽当前为空。
• ara::crypto::CryptoErrc::kUsageViolation：如果密钥的允许用途不包含签名生成 (kAllowSig Generation)。
• ara::crypto::CryptoErrc::kBusyResource：如果所需资源被占用。

在典型的处理流程中，待签名的数据在成功启动后大概会相继通过 Update ([SWS_CRYPT_50039]) 传递。 问题 Q-7b821391730c9d38 (未决)若加密方案不需要上下文值，则可替代使用无参数重载 Start() ([SWS_CRYPT_50037])。

方法 Update 在 [SWS_CRYPT_50039] 中用于通过消息的另一个分段连续扩展签名计算的内部状态。该调用同步进行，并处理类型为 ReadOnlyMemRegion 的所传递内存区域 data。作为结果，该函数提供一个 ara::core::Result<void>，其在成功处理时不包含任何值，或者在其他情况下封装一个错误代码 [SWS_CRYPT_50039]。

在出错时，返回值具有回滚语义 [SWS_CRYPT_50039]：

• ara::crypto::CryptoErrc::kProcessingNotStarted：在签名计算事先未通过调用方法 Start() 启动时发生 [SWS_CRYPT_50039]。
• ara::crypto::CryptoErrc::kInvalidInputSize：如果上下文不支持所提供输入数据的大小，则会报告该错误 [SWS_CRYPT_50039]。

关于并发性与安全性，该方法被声明为 thread-safe 以及 exception safe [SWS_CRYPT_50039]。在与签名上下文的交互中，计算强制要求该流程已通过 Start() 启动。单个调用的最大允许缓冲区大小可通过 GetMaximumChunkSize() 查询 [SWS_CRYPT_50042]；该限值预计表示上限，超过该上限会导致 kInvalidInputSize。 问题 Q-cf204a853a730365 (未决)