class ara::crypto::x509::X509Provider

use

The synchronous method ClearCertificateSlot of class ara::crypto::x509::X509Provider clears the certificate slot specified via parameter instanceSpecifier [SWS_CRYPT_40622]. It returns a ara::core::Result<bool>: The return value is true if an existing certificate was successfully deleted, and false if the slot was already unoccupied [SWS_CRYPT_40622].

Error Handling and Restrictions

If the operation cannot be executed temporarily, the function returns error code ara::crypto::CryptoErrc::kBusyResource with rollback semantics [SWS_CRYPT_40622]. In addition, specific modeling and access prerequisites are defined:

• ProcessMappingViolation: Occurs when InstanceSpecifier does not point to a PortPrototype modeled for the current process with interface CryptoCertificateInterface [SWS_CRYPT_40622].
• InsufficientPermissionsViolation: Occurs when the current process lacks write permissions, i.e. CryptoCertificateToPortPrototypeMapping.writeAccess != True is set [SWS_CRYPT_40622].

Concurrency

The interface is designated as noexcept, specified as exception-safe (exception safe), and specified as thread-safe (thread-safe) for concurrent calls [SWS_CRYPT_40622].

use

The synchronous method CreateCertSignRequest of interface ara::crypto::x509::X509Provider from header ara/crypto/x509/x509_provider.h creates a certificate signing request (CSR) according to the RFC 2986 standard [SWS_CRYPT_40640]. As parameters, the function expects a fully configured signing context signerCtx, the distinguished name of the subject subjectDn, the associated public key publicKey, and optional DER-encoded attributes attributes [SWS_CRYPT_40640]. The passed public key must strictly correspond to the private key configured in the signing context. In case of success, a smart pointer to the created CSR (CertSignRequest::Sptrc) packaged in a ara::core::Result is returned [SWS_CRYPT_40640].

Error handling

In case of an error, the method returns a ara::core::Result with a corresponding error code according to rollback semantics [SWS_CRYPT_40640]:

• ara::crypto::CryptoErrc::kInvalidArgument: If the passed attribute data is invalid or the public key does not match the private key of the signing context.
• ara::crypto::CryptoErrc::kUninitializedContext: If the signing context was not initialized with a key value.
• ara::crypto::CryptoErrc::kEmptyKeySlot: If a configured KeySlot is currently empty.
• ara::crypto::CryptoErrc::kUsageViolation: When the permitted key usage does not include signature generation (kAllowSigGeneration).
• ara::crypto::CryptoErrc::kBusyResource: If a resource required for the operation is busy.

Concurrency and Limitations

The method is specified as const, noexcept, exception-safe (exception safe), and thread-safe (thread-safe) [SWS_CRYPT_40640]. Parallel calls via the same provider instance are likely permitted as long as the passed context and key objects are not concurrently modified by other threads. Question Q-aef8777dce55a033 (open)

The method CreateCertificateValidationCtx is a functional interface of class ara::crypto::x509::X509Provider and, according to [SWS_CRYPT_50125], serves to create a certificate validation context. It is declared in the header #include "ara/crypto/x509/x509_provider.h" and defined as a parameterless, pure virtual function [SWS_CRYPT_50125].

The synchronous call returns the type ara::core::Result<CertificateValidationCtx::Sptr> as return value, which provides a smart pointer to the created context in case of success [SWS_CRYPT_50125]. No standardized error codes are defined in the specification for this function [SWS_CRYPT_50125]. However, since the return occurs via the result type ara::core::Result, any provider-specific errors during context creation are expected to be represented via the error component of this Result object. Question Q-f81f52d8e3d73bcf (open)

Regarding the calling context and concurrency, the method is explicitly specified as thread-safe (thread-safe) and declared as exception safe (exception safe) and noexcept [SWS_CRYPT_50125]. Callers can therefore execute the function safely and concurrently from multiple threads without having to provide additional synchronization for the creation process [SWS_CRYPT_50125].

use

The pure virtual method CreateDn is provided via the interface ara::crypto::x509::X509Provider from the header file ara/crypto/x509/x509_provider.h [SWS_CRYPT_50186]. It serves to instantiate an X.509 distinguished name object (X509DN::Sptrc) based on a string representation [SWS_CRYPT_50186]. As an input parameter, it expects dnString of type ara::core::StringView, which must represent a distinguished name according to RFC 4514 [SWS_CRYPT_50186]. Interpretation: Since the function is declared as const noexcept and directly returns a ara::core::Result, the call is likely to occur in a synchronous, blocking manner without any state change of the provider. Question Q-c7e3ab6b4f34ad0f (open)

Error handling

If the passed string cannot be processed successfully because it does not represent a valid DN according to RFC 4514, the function returns a ara::core::Result with the error code ara::crypto::CryptoErrc::kInvalidArgument [SWS_CRYPT_50186]. Rollback semantics are specified for this error case [SWS_CRYPT_50186].

Concurrency and Limitations

The method is explicitly specified as exception safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_50186]. It can therefore be called from concurrent threads without additional external synchronization.

Interaction

As an alternative to string-based creation, ara::crypto::x509::X509Provider provides another overload of CreateDn [SWS_CRYPT_50187]. This allows the construction of a X509DN from a serialized buffer (ReadOnlyMemRegion) specifying a format specifier (FormatId) [SWS_CRYPT_50187].

use

The method CreateDn according to [SWS_CRYPT_50187] serves to create a Distinguished Name (DN) from a serialized buffer. It is called synchronously on an instance of ara::crypto::x509::X509Provider. As inputs, the function expects a memory region dn of type ReadOnlyMemRegion containing the serialized data, as well as a format identifier formatId of type FormatId. Upon successful execution, the method returns a ara::core::Result<X509DN::Sptrc>, which provides a shared pointer to the created X509DN object.

Error handling

If the creation fails, the method returns a corresponding error code within the ara::core::Result ([SWS_CRYPT_50187]):

• ara::crypto::CryptoErrc::kInvalidArgument: Occurs with rollback semantics if the passed buffer dn is invalid.
• ara::crypto::CryptoErrc::kUnsupportedFormat: Reported with rollback semantics if the specified formatId is unknown or not supported.

Concurrency and Interaction

The interface is specified as thread-safe as well as exception safe and declared with noexcept ([SWS_CRYPT_50187]). It can therefore safely be called in parallel from multiple execution contexts.

In contrast to the alternative overload [SWS_CRYPT_50186], which creates a DN from a character string (ara::core::StringView) according to RFC 4514, this function processes serialized binary data. The concrete characteristics for FormatId are expected to be defined elsewhere across the module. Question Q-dd7cbf35ba6fa7d1 (open)

use

The method CreateOcspRequest of the class ara::crypto::x509::X509Provider synchronously generates an OCSP (Online Certificate Status Protocol) check request for a single certificate according to RFC 6960 [SWS_CRYPT_40626]. The certificate to be checked cert and its issuer certificate issuerCert are each passed as parameters as Certificate::Sptrc [SWS_CRYPT_40626]. A pointer to a signing context can be provided via the optional parameter signerCtx if the request is to be cryptographically signed [SWS_CRYPT_40626]. The function returns a ara::core::Result with a ara::core::Vector<std::uint8_t>; the contained raw data likely corresponds to the DER-encoded request structure according to RFC 6960 [SWS_CRYPT_40626]. Question Q-c43cf023ee5eddd9 (open)

Error handling

If an error occurs during creation, the ara::core::Result returns specific error codes with rollback semantics [SWS_CRYPT_40626]:

• ara::crypto::CryptoErrc::kUninitializedContext: Occurs if the passed signing context is not initialized with a key [SWS_CRYPT_40626].
• ara::crypto::CryptoErrc::kBusyResource: Occurs if the operation cannot be performed due to temporarily busy resources [SWS_CRYPT_40626].

Concurrency and Interaction

The method is declared as noexcept, is considered exception safe, and is specified as thread-safe [SWS_CRYPT_40626]. For scenarios in which multiple certificates are to be bundled simultaneously in a shared OCSP request, the overloaded interface [SWS_CRYPT_40627] for certificate lists is available.

use

The method CreateOcspRequest of interface ara::crypto::x509::X509Provider ([SWS_CRYPT_40627]) serves to synchronously create an OCSP (Online Certificate Status Protocol) check request according to RFC 6960 for multiple certificates. The call is provided via header #include "ara/crypto/x509/x509_provider.h".

As input parameter, the function expects:

• certList: A list of the certificates to be validated as ara::core::Span<Certificate::Sptrc>.
• issuerCertList: A list of the associated issuer certificates as ara::core::Span<Certificate::Sptrc>. Interpretation: A pairwise assignment by index is likely assumed between the entries of both lists. Question Q-9132b017c2c4be75 (open)
• signerCtx: An optional pointer to an initialized signing context (ara::core::Optional<cryp::SignerPrivateCtx::Sptr>) if the request is to be cryptographically signed.

As return value, the function returns a ara::core::Result, which provides the binary data of the OCSP request in a ara::core::Vector<std::uint8_t> upon successful creation ([SWS_CRYPT_40627]).

Error handling

In case of an error, ara::core::Result provides error codes with rollback semantics ([SWS_CRYPT_40627]):

• ara::crypto::CryptoErrc::kUninitializedContext: Occurs when the passed signing context has not been initialized with a key.
• ara::crypto::CryptoErrc::kBusyResource: Occurs when the operation temporarily cannot be executed due to temporarily busy resources.

Concurrency and Interaction

The method is specified as thread-safe and exception safe and declared with noexcept ([SWS_CRYPT_40627]). In contrast to [SWS_CRYPT_40626], where the OCSP request is generated for a single certificate, this interface allows bundling multiple certificates into a single request.

use

The DeleteCrl method of interface ara::crypto::x509::X509Provider serves to delete a persistently stored certificate revocation list (CRL) [SWS_CRYPT_50184]. The crlInstanceSpecifier is passed as a parameter, referencing a RPortPrototype of a CryptoCertificateInterface that identifies the associated certificate [SWS_CRYPT_50184]. The function operates synchronously and returns a ara::core::Result<void>; this is empty if the CRL was deleted successfully or if no CRL was stored beforehand [SWS_CRYPT_50184].

Error Handling and Concurrency

If a temporary resource conflict occurs during execution, the function reports error ara::crypto::CryptoErrc::kBusyResource with rollback semantics [SWS_CRYPT_50184]. The method is declared as noexcept and specified as exception safe and thread-safe [SWS_CRYPT_50184].

Restrictions and configuration conditions

The following configuration and permission prerequisites apply to the call [SWS_CRYPT_50184]:

• ProcessMappingViolation: Occurs when InstanceSpecifier does not point to a PortPrototype modeled for the current process that is typed by a CryptoCertificateInterface [SWS_CRYPT_50184].
• InsufficientPermissionsViolation: Occurs when the current process does not have write permissions, that is, CryptoCertificateToPortPrototypeMapping.writeAccess != True [SWS_CRYPT_50184].

use

The ImportCertificate method of the ara::crypto::x509::X509Provider interface (declared in ara/crypto/x509/x509_provider.h) serves to persistently store an X.509 certificate in a defined certificate slot [SWS_CRYPT_40621]. The target slot is addressed via instanceSpecifier (type ara::core::InstanceSpecifier), while the certificate to be imported is passed via the argument certificate (type Certificate::Sptrc) [SWS_CRYPT_40621]. Interpretation: Execution is likely to be synchronous, as the interface directly returns a ara::core::Result<void> [SWS_CRYPT_40621]. Question Q-514863e9a90f1c72 (open)

Error Handling and Modeling Rules

In case of an error, an erroneous ara::core::Result is returned. If the operation temporarily cannot be executed, the method returns ara::crypto::CryptoErrc::kBusyResource with rollback semantics [SWS_CRYPT_40621]. In addition, configuration and modeling requirements must be satisfied, as runtime violations are reported otherwise [SWS_CRYPT_40621]:

• ProcessMappingViolation: Is triggered if the instanceSpecifier does not point to a PortPrototype modeled for the current process that is typed by a CryptoCertificateInterface [SWS_CRYPT_40621].
• InsufficientPermissionsViolation: Occurs when write permission is not present for the current process (CryptoCertificateToPortPrototypeMapping.writeAccess != True) [SWS_CRYPT_40621].

Concurrency and Execution Context

The operation is specified as thread-safe and exception safe (noexcept=0), whereby concurrent calls are safeguarded without external locks [SWS_CRYPT_40621].

use

The method ImportCertificateInGroup of class ara::crypto::x509::X509Provider persistently stores a provided certificate in a certificate group identified via instanceSpecifier [SWS_CRYPT_50127]. A reference to the ara::core::InstanceSpecifier of the target group and a smart pointer to the certificate (Certificate::Sptrc certificate) are passed as parameters [SWS_CRYPT_50127]. The call is declared via the header ara/crypto/x509/x509_provider.h and synchronously returns a ara::core::Result<void>, which signals successful import or encapsulates an error status [SWS_CRYPT_50127].

Error Handling and Violations

In the regular error case, the operation provides rollback semantics and returns specific error codes in the Result object [SWS_CRYPT_50127]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of the addressed certificate group is insufficient to accommodate the certificate [SWS_CRYPT_50127].
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be performed temporarily because the required resource is busy [SWS_CRYPT_50127].

Furthermore, mandatory modeling and permission requirements are defined, non-compliance with which is classified as violations [SWS_CRYPT_50127]:

• ProcessMappingViolation: Occurs when the InstanceSpecifier does not point to a PortPrototype modeled for the current process that is typed by a CryptoCertificateGroupInterface [SWS_CRYPT_50127].
• InsufficientPermissionsViolation: Occurs when the calling process does not possess write permission, which is characterized by CryptoCertificateGroupToPortPrototypeMapping.writeAccess != True [SWS_CRYPT_50127].

Concurrency and Execution Context

The interface is specified as thread-safe (thread-safe) as well as exception-safe (exception safe) and declared with noexcept [SWS_CRYPT_50127].

The method ImportCrl of class ara::crypto::x509::X509Provider parses and persists a Certificate Revocation List (CRL) or Delta CRL issued by the CA certificate identified via crlInstanceSpecifier [SWS_CRYPT_50183]. Execution is expected to occur synchronously, as a ara::core::Result is returned immediately. Question Q-648a00ec967c7524 (open)

Upon invocation, the following parameters are passed [SWS_CRYPT_50183]:

• crlInstanceSpecifier: ara::core::InstanceSpecifier to the RPortPrototype of a CryptoCertificateInterface identifying the certificate.
• crl: ReadOnlyMemRegion containing the serialized CRL or Delta CRL data.
• formatId: Format of the serialized CRL.

The operation is specified as thread-safe as well as exception safe [SWS_CRYPT_50183]. In case of success, it returns a ara::core::Result with the status CertificateValidationStatus::kValid or the validation result of the CRL [SWS_CRYPT_50183].

In case of error, the return values possess rollback semantics [SWS_CRYPT_50183]:

• ara::crypto::CryptoErrc::kInvalidArgument: The CRL does not conform to the specified format.
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified FormatId is unknown or not supported.
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be executed temporarily.

Additionally, configuration preconditions must be adhered to [SWS_CRYPT_50183]: A ProcessMappingViolation occurs if the instance identifier does not refer to a port modeled for the current process, and a InsufficientPermissionsViolation if CryptoCertificateToPortPrototypeMapping.writeAccess != True is set.

The LoadCertificate method of the ara::crypto::x509::X509Provider interface serves to load a certificate from persistent certificate storage [SWS_CRYPT_40641]. The call is executed synchronously (interpretation: direct return of ara::core::Result without an asynchronous future object such as ara::core::Future). Question Q-a2e3c23a02b4f8a1 (open) As an input parameter, the function expects an ara::core::InstanceSpecifier that identifies the specific storage location of the certificate [SWS_CRYPT_40641].

Upon successful execution, the return value encapsulates a smart pointer to the instantiated certificate (Certificate::Sptrc) in a ara::core::Result [SWS_CRYPT_40641]. If loading fails, the result contains an error code:

• ara::crypto::CryptoErrc::kEmptyCertificateSlot: Occurs with rollback semantics if the CryptoCertificate identified by the specified instanceSpecifier does not contain a persisted certificate [SWS_CRYPT_40641].

With regard to concurrency and exception safety, LoadCertificate is specified as thread-safe as well as exception-safe and declared as noexcept [SWS_CRYPT_40641]. During configuration and process assignment, a modeling condition must be observed: If the passed instanceSpecifier does not refer to a PortPrototype modeled for the current process that is typed by a CryptoCertificateInterface, an ProcessMappingViolation is present [SWS_CRYPT_40641].

The method ara::crypto::x509::X509Provider::LoadCertificateGroup serves to load a group of certificates from persistent certificate storage according to [SWS_CRYPT_50126].

Usage and Call Context

The call is made via an instance of X509Provider from the header ara/crypto/x509/x509_provider.h. As input parameter, the function expects an instanceSpecifier of type const ara::core::InstanceSpecifier&, which identifies the logical storage location of the desired certificate group [SWS_CRYPT_50126]. As a result, the interface returns a ara::core::Result<ara::core::Vector<Certificate::Sptrc>>, which in case of success provides a vector of smart pointers to the loaded certificates [SWS_CRYPT_50126]. In the absence of asynchronous return types such as ara::core::Future, access to persistent storage is expected to be synchronous blocking. Question Q-b743367ccc9904ab (open)

Error Handling and Modeling Constraints

In the specification, no standardized error codes are defined for the return value [SWS_CRYPT_50126]. However, a runtime check is prescribed: If the passed instanceSpecifier does not refer to a PortPrototype modeled for the current process that is typed by a CryptoCertificateGroupInterface, a ProcessMappingViolation is present [SWS_CRYPT_50126].

Concurrency and Exception Safety

The pure virtual method is annotated with noexcept and specified as exception safe (exception safe). In addition, the call is explicitly declared as thread-safe (thread-safe), so that concurrent read accesses from multiple threads are harmless [SWS_CRYPT_50126].

The method ParseCert is part of class ara::crypto::x509::X509Provider (defined in header ara/crypto/x509/x509_provider.h) and serves to parse a serialized representation of an X.509v3 certificate and instantiate a corresponding certificate object [SWS_CRYPT_40614].

Call and parameters: The function is called synchronously and is specified as noexcept [SWS_CRYPT_40614]. It accepts two input parameters:

• cert: A memory region of type ReadOnlyMemRegion that provides the certificate data encoded in the specified format [SWS_CRYPT_40614].
• formatId: The identifier of the input format for determining the parsing procedure [SWS_CRYPT_40614].

Return value and error handling: The result is returned as ara::core::Result<Certificate::Sptrc>, which in case of success contains a shared pointer to the created certificate object [SWS_CRYPT_40614]. If an error occurs, rollback semantics apply with the following specific error codes [SWS_CRYPT_40614]:

• ara::crypto::CryptoErrc::kInvalidArgument: The argument cert cannot be parsed as a valid certificate [SWS_CRYPT_40614].
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified formatId is unknown or not supported [SWS_CRYPT_40614].

Concurrency and implementation: The interface is explicitly specified as exception-safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_40614]. Since ParseCert is declared pure virtual, the actual parsing logic is likely provided by a platform-specific crypto driver or provider [SWS_CRYPT_40614]. Question Q-d3239d62d2e7d831 (open)

use

The method ParseCertChain of interface ara::crypto::x509::X509Provider from header ara/crypto/x509/x509_provider.h parses a serialized representation of a certificate chain [SWS_CRYPT_40616]. As parameters, it accepts the memory region of the encoded certificate chain certChain as ReadOnlyMemRegion and the format identifier formatId of type FormatId [SWS_CRYPT_40616]. For each successfully parsed certificate, a new Certificate instance is created. In case of success, the synchronous function returns a ara::core::Result with a ara::core::Vector<Certificate::Sptrc>, in which the certificates are arranged in the same order as in the passed chain [SWS_CRYPT_40616].

Error handling

In case of an error, the returned ara::core::Result contains a specific error code with rollback semantics [SWS_CRYPT_40616]:

• ara::crypto::CryptoErrc::kInvalidArgument: The argument certChain cannot be parsed [SWS_CRYPT_40616].
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified identifier formatId is unknown or not supported [SWS_CRYPT_40616].

Concurrency and Constraints

The method is declared as noexcept, specified as thread-safe (thread-safe), and ensures exception safety (exception safe) [SWS_CRYPT_40616].

Usage and Call Context

The synchronous method ParseOcspResponse is part of the interface ara::crypto::x509::X509Provider (defined in ara/crypto/x509/x509_provider.h) and serves for reading in and parsing serialized OCSP responses [SWS_CRYPT_50185]. The caller passes the raw data of the response as ReadOnlyMemRegion via the parameter response and the expected data format by means of formatId of type FormatId [SWS_CRYPT_50185]. Upon successful validation and processing, the function returns a ara::core::Result encapsulating a smart pointer OcspResponse::Sptrc to the newly created OCSP response object [SWS_CRYPT_50185].

Error handling

Error cases are signaled without throwing exceptions via the return type ara::core::Result with rollback semantics [SWS_CRYPT_50185]:

• ara::crypto::CryptoErrc::kInvalidArgument: Occurs if the bytes provided in the buffer response cannot be parsed as a valid OCSP response [SWS_CRYPT_50185].
• ara::crypto::CryptoErrc::kUnsupportedFormat: Reported if the passed identifier formatId is unknown or not supported by the provider [SWS_CRYPT_50185].

Concurrency and Thread Safety

The pure virtual method is declared as noexcept, classified as exception safe (exception safe), and explicitly specified as thread-safe (thread-safe) [SWS_CRYPT_50185]. Thanks to the const declaration, ParseOcspResponse can be called concurrently on the same provider instance in multithreading environments without modifying the internal state of the object [SWS_CRYPT_50185].

use

The synchronous interface method RemoveCertificateFromGroup from the scope ara::crypto::x509::X509Provider serves to specifically remove a certificate from an existing certificate group [SWS_CRYPT_50128]. The relevant certificate group is identified via the parameter instanceSpecifier, while certificate provides the certificate to be removed as a smart pointer (Certificate::Sptrc) [SWS_CRYPT_50128]. The call returns a ara::core::Result<void>, which acknowledges successful completion without a return value or encapsulates an error that occurred [SWS_CRYPT_50128].

Error handling

If an error occurs during execution, defined rollback semantics take effect so that the state of the certificate group remains unchanged [SWS_CRYPT_50128]. The following error codes are specified:

• ara::crypto::CryptoErrc::kNoSuchValue: The specified certificate group does not contain the certificate to be removed [SWS_CRYPT_50128].
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be performed temporarily because required resources are busy [SWS_CRYPT_50128].

Concurrency and Configuration Constraints

The method is specified as thread-safe and exception safe as well as declared with noexcept [SWS_CRYPT_50128]. Before the call, the following prerequisites must mandatorily be met for the process in the system model [SWS_CRYPT_50128]:

• To avoid a ProcessMappingViolation, the passed InstanceSpecifier must point to a PortPrototype that is typed by a CryptoCertificateGroupInterface modeled for the current process [SWS_CRYPT_50128].
• To avoid a InsufficientPermissionsViolation, the current process must have write permissions, which means that CryptoCertificateGroupToPortPrototypeMapping.writeAccess must be configured to True [SWS_CRYPT_50128].