类 ara::crypto::x509::X509Provider

使用

类 ara::crypto::x509::X509Provider 的同步方法 ClearCertificateSlot 清空通过参数 instanceSpecifier 指定的证书存储位置 [SWS_CRYPT_40622]。它返回一个 ara::core::Result<bool>：如果成功删除了现有证书，则返回值是 true；如果该插槽原本就未被占用，则返回值为 false [SWS_CRYPT_40622]。

错误处理与限制

如果该操作暂时无法执行，该函数将提供具有回滚语义的错误代码 ara::crypto::CryptoErrc::kBusyResource [SWS_CRYPT_40622]。此外，还定义了特定的建模和访问前提条件：

• ProcessMappingViolation：当 InstanceSpecifier 未指向针对当前进程建模且具有接口 CryptoCertificateInterface 的 PortPrototype 时出现 [SWS_CRYPT_40622]。
• InsufficientPermissionsViolation：当当前进程缺少写权限时发生，即设置了 CryptoCertificateToPortPrototypeMapping.writeAccess != True [SWS_CRYPT_40622]。

并发性

该接口标明为 noexcept，被指定为异常安全（exception safe），并针对并发调用被指定为线程安全（thread-safe）[SWS_CRYPT_40622]。

使用

来自头文件 ara/crypto/x509/x509_provider.h 的接口 ara::crypto::x509::X509Provider 的同步方法 CreateCertSignRequest 根据 RFC 2986 标准创建证书签名请求（Certificate Signing Request，CSR）[SWS_CRYPT_40640]。作为参数，该函数需要一个完整配置的签名上下文 signerCtx、主题的可分辨名称 subjectDn、关联的公钥 publicKey 以及可选的 DER 编码属性 attributes [SWS_CRYPT_40640]。传入的公钥必须与签名上下文中配置的私钥严格对应。成功时，将返回打包在 ara::core::Result 中的指向已创建 CSR（CertSignRequest::Sptrc）的智能指针 [SWS_CRYPT_40640]。

错误处理

出错时，该方法将根据回滚语义返回带有相应错误代码的 ara::core::Result [SWS_CRYPT_40640]：

• ara::crypto::CryptoErrc::kInvalidArgument：如果传入的属性数据无效，或者公钥与签名上下文的私钥不匹配。
• ara::crypto::CryptoErrc::kUninitializedContext：如果签名上下文未用密钥值进行初始化。
• ara::crypto::CryptoErrc::kEmptyKeySlot：如果配置的 KeySlot 当前为空。
• ara::crypto::CryptoErrc::kUsageViolation：如果允许的密钥用法不包含签名生成（kAllowSigGeneration）。
• ara::crypto::CryptoErrc::kBusyResource：如果操作所需的资源被占用。

并发性与限制

该方法被指定为 const、noexcept、异常安全（exception safe）以及线程安全（thread-safe）[SWS_CRYPT_40640]。只要传入的上下文和密钥对象不同时被其他线程修改，通过同一提供程序实例进行的并行调用很可能是允许的。 问题 Q-aef8777dce55a033 (未决)

方法 CreateCertificateValidationCtx 是类 ara::crypto::x509::X509Provider 的功能接口，根据 [SWS_CRYPT_50125] 用于创建证书验证上下文。它在头文件 #include "ara/crypto/x509/x509_provider.h" 中声明，并定义为无参数的纯虚函数 [SWS_CRYPT_50125]。

同步调用返回类型 ara::core::Result<CertificateValidationCtx::Sptr> 作为返回值，该类型在成功时提供一个指向所创建上下文的智能指针 [SWS_CRYPT_50125]。规范中未为此函数定义标准化的错误代码 [SWS_CRYPT_50125]。但由于通过结果类型 ara::core::Result 进行返回，因此在上下文创建期间任何 provider 特定的错误大概都会通过此 Result 对象的错误组件反映出来。 问题 Q-f81f52d8e3d73bcf (未决)

关于调用上下文和并发性，该方法被明确规范定义为线程安全（thread-safe），并被声明为异常安全（exception safe）和 noexcept [SWS_CRYPT_50125]。因此，调用者可以安全地从多个线程并发执行该函数，而无需为创建过程提供额外的同步 [SWS_CRYPT_50125]。

使用

纯虚方法 CreateDn 通过来自头文件 ara/crypto/x509/x509_provider.h 的接口 ara::crypto::x509::X509Provider 提供 [SWS_CRYPT_50186]。它用于根据字符串表示实例化 X.509 识别名对象（X509DN::Sptrc）[SWS_CRYPT_50186]。作为输入参数，它需要类型为 ara::core::StringView 的 dnString，该参数必须表示符合 RFC 4514 的识别名 [SWS_CRYPT_50186]。解释：由于该函数声明为 const noexcept 并直接返回 ara::core::Result，因此该调用大概率以同步阻塞方式发生，且不会改变提供程序的状态。 问题 Q-c7e3ab6b4f34ad0f (未决)

错误处理

如果由于传入的字符串不表示符合 RFC 4514 的有效 DN 而导致无法成功处理，该函数将返回带有错误码 ara::crypto::CryptoErrc::kInvalidArgument 的 ara::core::Result [SWS_CRYPT_50186]。已为此错误情况指定了回滚语义 [SWS_CRYPT_50186]。

并发性与限制

该方法被明确指定为异常安全（exception safe）和线程安全（thread-safe）[SWS_CRYPT_50186]。因此，可以从并发线程调用它而无需额外的外部同步。

相互作用

作为基于字符串生成的替代方案，ara::crypto::x509::X509Provider 提供了 CreateDn 的另一重载 [SWS_CRYPT_50187]。该重载允许通过指定格式标识符（FormatId）从序列化缓冲区（ReadOnlyMemRegion）构造 X509DN [SWS_CRYPT_50187]。

使用

符合 [SWS_CRYPT_50187] 的方法 CreateDn 用于从序列化缓冲区创建专有名称（DN）。它在 ara::crypto::x509::X509Provider 的实例上同步调用。作为输入，该函数需要包含序列化数据的类型为 ReadOnlyMemRegion 的内存区域 dn，以及类型为 FormatId 的格式标识符 formatId。在成功执行时，该方法返回一个 ara::core::Result<X509DN::Sptrc>，其提供指向所创建 X509DN 对象的共享指针（Shared Pointer）。

错误处理

若创建失败，该方法在 ara::core::Result 内返回相应的错误代码（[SWS_CRYPT_50187]）：

• ara::crypto::CryptoErrc::kInvalidArgument：在传入的缓冲区 dn 无效时发生，具有回滚语义。
• ara::crypto::CryptoErrc::kUnsupportedFormat：在指定的 formatId 未知或不受支持时报告，具有回滚语义。

并发性与交互

该接口被指定为 thread-safe 以及 exception safe，并声明为 noexcept（[SWS_CRYPT_50187]）。因此，它可以安全地从多个执行上下文中并行调用。

与依据 RFC 4514 从字符串（ara::core::StringView）创建 DN 的备选重载 [SWS_CRYPT_50186] 不同，此函数处理序列化的二进制数据。FormatId 的具体表现形式推测在模块范围的其他位置定义。 问题 Q-dd7cbf35ba6fa7d1 (未决)

使用

类 ara::crypto::x509::X509Provider 的方法 CreateOcspRequest 根据 RFC 6960 为单个证书同步生成 OCSP（联机证书状态协议）检查请求 [SWS_CRYPT_40626]。作为参数，待检查证书 cert 及其签发者证书 issuerCert 分别作为 Certificate::Sptrc 传递 [SWS_CRYPT_40626]。如果请求需要进行密码学签名，则可以通过可选参数 signerCtx 提供指向签名上下文的指针 [SWS_CRYPT_40626]。该函数返回包含 ara::core::Vector<std::uint8_t> 的 ara::core::Result；所包含的原始数据可能对应于符合 RFC 6960 的 DER 编码请求结构 [SWS_CRYPT_40626]。 问题 Q-c43cf023ee5eddd9 (未决)

错误处理

如果在生成过程中发生错误，ara::core::Result 将提供具有回滚语义的特定错误码 [SWS_CRYPT_40626]：

• ara::crypto::CryptoErrc::kUninitializedContext：当传入的签名上下文未用密钥初始化时发生 [SWS_CRYPT_40626]。
• ara::crypto::CryptoErrc::kBusyResource：当由于资源暂时被占用而无法执行操作时发生 [SWS_CRYPT_40626]。

并发性与交互

该方法声明为 noexcept，被视为异常安全（exception safe），并被指定为 thread-safe [SWS_CRYPT_40626]。对于需要在单个公共 OCSP 请求中同时打包多个证书的场景，提供了针对证书列表的重载接口 [SWS_CRYPT_40627]。

使用

接口 ara::crypto::x509::X509Provider（[SWS_CRYPT_40627]）的方法 CreateOcspRequest 用于根据 RFC 6960 为多个证书同步创建 OCSP 检查请求（联机证书状态协议）。该调用通过头文件 #include "ara/crypto/x509/x509_provider.h" 提供。

该函数需要的输入参数如下：

• certList：要验证的证书列表，作为 ara::core::Span<Certificate::Sptrc>。
• issuerCertList：关联的颁发者证书列表，作为 ara::core::Span<Certificate::Sptrc>。解释：两个列表的条目之间很可能预设了按索引成对对应。 问题 Q-9132b017c2c4be75 (未决)
• signerCtx：指向已初始化签名上下文（ara::core::Optional<cryp::SignerPrivateCtx::Sptr>）的可选指针，用于需要对请求进行加密签名的情况。

作为返回值，该函数提供一个 ara::core::Result，成功生成时，它会在 ara::core::Vector<std::uint8_t> 中提供 OCSP 请求的二进制数据（[SWS_CRYPT_40627]）。

错误处理

出错时，ara::core::Result 会提供具有回滚语义的错误代码（[SWS_CRYPT_40627]）：

• ara::crypto::CryptoErrc::kUninitializedContext：当传入的签名上下文未通过密钥初始化时发生。
• ara::crypto::CryptoErrc::kBusyResource：由于资源暂时被占用导致操作暂时无法执行时发生。

并发性与交互

该方法被指定为 thread-safe 以及 exception safe，并声明为 noexcept（[SWS_CRYPT_40627]）。与为单个证书生成 OCSP 请求的 [SWS_CRYPT_40626] 相比，该接口允许将多个证书捆绑在单个请求中。

使用

接口ara::crypto::x509::X509Provider的方法DeleteCrl用于删除持久化保存的证书吊销列表（Certificate Revocation List，CRL）[SWS_CRYPT_50184]。作为参数传入crlInstanceSpecifier，该参数指向标识相应证书的CryptoCertificateInterface的RPortPrototype[SWS_CRYPT_50184]。该函数同步工作并返回一个ara::core::Result<void>；若 CRL 已成功删除或先前根本未保存 CRL，则该结果为空[SWS_CRYPT_50184]。

错误处理与并发

若执行期间发生临时资源冲突，该函数将以回滚语义报告错误ara::crypto::CryptoErrc::kBusyResource[SWS_CRYPT_50184]。该方法声明为noexcept，并指定为异常安全（exception safe）和线程安全（thread-safe）[SWS_CRYPT_50184]。

限制和配置条件

调用适用以下配置与权限前提条件[SWS_CRYPT_50184]：

• ProcessMappingViolation：当InstanceSpecifier未指向针对当前进程建模且由CryptoCertificateInterface类型化的PortPrototype时发生[SWS_CRYPT_50184]。
• InsufficientPermissionsViolation：当当前进程没有写权限时发生，即CryptoCertificateToPortPrototypeMapping.writeAccess != True[SWS_CRYPT_50184]。

使用

接口 ara::crypto::x509::X509Provider 的方法 ImportCertificate（声明于 ara/crypto/x509/x509_provider.h）用于将 X.509 证书持久存储在定义的证书槽位中 [SWS_CRYPT_40621]。目标槽位通过 instanceSpecifier（类型 ara::core::InstanceSpecifier）寻址，而要导入的证书则通过参数 certificate（类型 Certificate::Sptrc）传递 [SWS_CRYPT_40621]。解释：执行大概是同步进行的，因为接口直接返回 ara::core::Result<void> [SWS_CRYPT_40621]。 问题 Q-514863e9a90f1c72 (未决)

错误处理和建模规则

发生错误时，将返回错误的 ara::core::Result。如果操作暂时无法执行，该方法将返回具有回滚语义的 ara::crypto::CryptoErrc::kBusyResource [SWS_CRYPT_40621]。此外，还必须满足配置和建模规范，否则将报告运行时违规 [SWS_CRYPT_40621]：

• ProcessMappingViolation：如果 instanceSpecifier 未指向为当前进程建模的、由 CryptoCertificateInterface 类型化的 PortPrototype，则触发 [SWS_CRYPT_40621]。
• InsufficientPermissionsViolation：在当前进程没有写权限（CryptoCertificateToPortPrototypeMapping.writeAccess != True）时发生 [SWS_CRYPT_40621]。

并发性与执行上下文

该操作被指定为 thread-safe 和 exception safe（noexcept=0），从而确保了无外部锁并发调用的安全性 [SWS_CRYPT_40621]。

使用

类 ara::crypto::x509::X509Provider 的方法 ImportCertificateInGroup 将提供的证书持久存储在通过 instanceSpecifier 标识的证书组中 [SWS_CRYPT_50127]。作为参数，传递对目标组 ara::core::InstanceSpecifier 的引用以及指向该证书的智能指针（Certificate::Sptrc certificate）[SWS_CRYPT_50127]。该调用通过头文件 ara/crypto/x509/x509_provider.h 声明，并同步返回一个 ara::core::Result<void>，其指示成功导入或封装错误状态 [SWS_CRYPT_50127]。

错误处理与违规

在常规错误情况下，该操作提供回滚语义，并在 Result 对象中返回特定错误代码 [SWS_CRYPT_50127]：

• ara::crypto::CryptoErrc::kInsufficientCapacity：所寻址证书组的容量不足以容纳该证书 [SWS_CRYPT_50127]。
• ara::crypto::CryptoErrc::kBusyResource：由于所需资源被占用，操作暂时无法执行 [SWS_CRYPT_50127]。

此外，还定义了约束性的建模与权限要求，不遵守这些要求将被归类为违规（Violations）[SWS_CRYPT_50127]：

• ProcessMappingViolation：当 InstanceSpecifier 未指向为当前进程建模且由 CryptoCertificateGroupInterface 进行类型化的 PortPrototype 时发生 [SWS_CRYPT_50127]。
• InsufficientPermissionsViolation：当调用进程不具备写权限（以 CryptoCertificateGroupToPortPrototypeMapping.writeAccess != True 为特征）时发生 [SWS_CRYPT_50127]。

并发性与执行上下文

该接口被指定为线程安全（thread-safe）以及异常安全（exception safe），并声明为 noexcept [SWS_CRYPT_50127]。

类 ara::crypto::x509::X509Provider 的方法 ImportCrl 解析并持久化由通过 crlInstanceSpecifier 识别的 CA 证书签发的证书吊销列表（CRL）或增量 CRL（Delta CRL）[SWS_CRYPT_50183]。执行应当是同步进行的，因为会立即返回一个 ara::core::Result。 问题 Q-648a00ec967c7524 (未决)

调用时会传递以下参数[SWS_CRYPT_50183]：

• crlInstanceSpecifier：指向用于标识证书的 CryptoCertificateInterface 的 RPortPrototype 的 ara::core::InstanceSpecifier。
• crl：包含序列化 CRL 或增量 CRL 数据的 ReadOnlyMemRegion。
• formatId：序列化 CRL 的格式。

该操作被指定为 thread-safe 以及 exception safe [SWS_CRYPT_50183]。在成功情况下，它返回状态为 CertificateValidationStatus::kValid 的 ara::core::Result 或 CRL 的验证结果 [SWS_CRYPT_50183]。

在错误情况下，返回值具有回滚语义 [SWS_CRYPT_50183]：

• ara::crypto::CryptoErrc::kInvalidArgument：CRL 不符合指定的格式。
• ara::crypto::CryptoErrc::kUnsupportedFormat：指定的 FormatId 未知或不受支持。
• ara::crypto::CryptoErrc::kBusyResource：该操作暂时无法执行。

此外还必须遵守配置前提条件 [SWS_CRYPT_50183]：若实例标识符未指向为当前进程建模的端口，则发生 ProcessMappingViolation；若设置了 CryptoCertificateToPortPrototypeMapping.writeAccess != True，则发生 InsufficientPermissionsViolation。

方法 ara::crypto::x509::X509Provider::LoadCertificateGroup 用于根据 [SWS_CRYPT_50126] 从持久证书存储中加载一组证书。

用法与调用上下文

调用通过来自头文件 ara/crypto/x509/x509_provider.h 的 X509Provider 实例进行。作为输入参数，该函数需要类型为 const ara::core::InstanceSpecifier& 的 instanceSpecifier，其标识目标证书组的逻辑存储位置 [SWS_CRYPT_50126]。作为结果，该接口返回一个 ara::core::Result<ara::core::Vector<Certificate::Sptrc>>，其在成功时提供一个包含指向已加载证书的智能指针的 vector [SWS_CRYPT_50126]。由于缺少诸如 ara::core::Future 之类的异步返回类型，对持久存储的访问大概是以同步阻塞方式进行的。 问题 Q-b743367ccc9904ab (未决)

错误处理与建模限制

规范中未对返回值定义标准化的错误代码 [SWS_CRYPT_50126]。然而，规定了运行时检查：如果传入的 instanceSpecifier 未指向针对当前进程建模且由 CryptoCertificateGroupInterface 确定类型的 PortPrototype，则存在 ProcessMappingViolation [SWS_CRYPT_50126]。

并发与异常安全性

纯虚方法带有 noexcept 注解，并被规范定义为异常安全（exception safe）。此外，该调用被明确声明为线程安全（thread-safe），因此来自多个线程的并行读取访问是安全的 [SWS_CRYPT_50126]。

方法 ParseCert 是类 ara::crypto::x509::X509Provider 的组成部分（定义在头文件 ara/crypto/x509/x509_provider.h 中），用于分析 X.509v3 证书的序列化表示并实例化相应的证书对象 [SWS_CRYPT_40614]。

调用与参数：该函数被同步调用，并被指定为 noexcept [SWS_CRYPT_40614]。它接收两个输入参数：

• cert：类型为 ReadOnlyMemRegion 的内存区域，提供按指定格式编码的证书数据 [SWS_CRYPT_40614]。
• formatId：用于确定解析过程的输入格式标识符 [SWS_CRYPT_40614]。

返回值与错误处理：结果作为 ara::core::Result<Certificate::Sptrc> 返回，成功时包含指向所创建证书对象的共享指针 [SWS_CRYPT_40614]。如果发生错误，将采用回滚语义并带有以下特定错误代码 [SWS_CRYPT_40614]：

• ara::crypto::CryptoErrc::kInvalidArgument：参数 cert 无法解析为有效证书 [SWS_CRYPT_40614]。
• ara::crypto::CryptoErrc::kUnsupportedFormat：指定的 formatId 未知或不受支持 [SWS_CRYPT_40614]。

并发性与实现：该接口明确被指定为异常安全（exception safe）和线程安全（thread-safe）[SWS_CRYPT_40614]。由于 ParseCert 声明为纯虚方法，实际的解析逻辑很可能由平台特定的加密驱动程序或提供程序提供 [SWS_CRYPT_40614]。 问题 Q-d3239d62d2e7d831 (未决)

使用

来自头文件 ara/crypto/x509/x509_provider.h 的接口 ara::crypto::x509::X509Provider 的方法 ParseCertChain 解析证书链的序列化表示 [SWS_CRYPT_40616]。作为参数，它接收作为 ReadOnlyMemRegion 的已编码证书链内存区域 certChain，以及类型为 FormatId 的格式标识符 formatId [SWS_CRYPT_40616]。对于每个成功解析的证书，都会创建一个新的 Certificate 实例。在成功情况下，该同步函数返回一个带有 ara::core::Vector<Certificate::Sptrc> 的 ara::core::Result，其中证书的排列顺序与传入链中的顺序相同 [SWS_CRYPT_40616]。

错误处理

出错时，返回的 ara::core::Result 包含具有回滚语义的特定错误代码 [SWS_CRYPT_40616]：

• ara::crypto::CryptoErrc::kInvalidArgument：无法解析参数 certChain [SWS_CRYPT_40616]。
• ara::crypto::CryptoErrc::kUnsupportedFormat：指定的标识符 formatId 未知或不受支持 [SWS_CRYPT_40616]。

并发性与边界条件

该方法声明为 noexcept，被指定为线程安全（thread-safe），并保证异常安全（exception safe）[SWS_CRYPT_40616]。

用法与调用上下文

同步方法 ParseOcspResponse 是接口 ara::crypto::x509::X509Provider（定义于 ara/crypto/x509/x509_provider.h 中）的一部分，用于读取和解析序列化的 OCSP 响应 [SWS_CRYPT_50185]。调用方通过参数 response 将响应的原始数据作为 ReadOnlyMemRegion 传递，并通过类型为 FormatId 的 formatId 传递期望的数据格式 [SWS_CRYPT_50185]。在成功验证和处理后，该函数返回一个 ara::core::Result，其封装了指向新创建的 OCSP 响应对象的智能指针 OcspResponse::Sptrc [SWS_CRYPT_50185]。

错误处理

错误情况通过具有回滚语义的返回类型 ara::core::Result 指示，且不抛出异常 [SWS_CRYPT_50185]：

• ara::crypto::CryptoErrc::kInvalidArgument：在缓冲区 response 中提供的字节无法解析为有效 OCSP 响应时发生 [SWS_CRYPT_50185]。
• ara::crypto::CryptoErrc::kUnsupportedFormat：在传入的标识符 formatId 未知或不受 Provider 支持时报告 [SWS_CRYPT_50185]。

并发与线程安全

该纯虚方法声明为 noexcept，归类为异常安全（exception safe），并显式指定为线程安全（thread-safe）[SWS_CRYPT_50185]。得益于 const 声明，在多线程环境中可以在同一 Provider 实例上并发调用 ParseOcspResponse，而不会修改对象的内部状态 [SWS_CRYPT_50185]。

使用

来自作用域 ara::crypto::x509::X509Provider 的同步接口方法 RemoveCertificateFromGroup 用于有针对性地从现有证书组中移除证书 [SWS_CRYPT_50128]。通过参数 instanceSpecifier 标识相关证书组，而 certificate 作为智能指针（Certificate::Sptrc）提供待移除的证书 [SWS_CRYPT_50128]。该调用返回一个 ara::core::Result<void>，其确认成功完成且无返回值，或封装所发生的错误 [SWS_CRYPT_50128]。

错误处理

若在执行时发生错误，则会应用定义的回滚语义，从而使证书组的状态保持不变 [SWS_CRYPT_50128]。指定了以下错误代码：

• ara::crypto::CryptoErrc::kNoSuchValue：指定的证书组不包含待移除的证书 [SWS_CRYPT_50128]。
• ara::crypto::CryptoErrc::kBusyResource：由于所需资源被占用，操作暂时无法执行 [SWS_CRYPT_50128]。

并发与配置条件

该方法被指定为 thread-safe 与 exception safe，并声明为 noexcept [SWS_CRYPT_50128]。在调用之前，系统模型中进程必须满足以下前提条件 [SWS_CRYPT_50128]：

• 为避免 ProcessMappingViolation，传入的 InstanceSpecifier 必须指向由为当前进程建模的 CryptoCertificateGroupInterface 进行类型化的 PortPrototype [SWS_CRYPT_50128]。
• 为避免 InsufficientPermissionsViolation，当前进程必须拥有写权限，即 CryptoCertificateGroupToPortPrototypeMapping.writeAccess 必须配置为 True [SWS_CRYPT_50128]。