class ara::crypto::cryp::CryptoProvider

The method CreateAuthCipherCtx serves to create a context for symmetric authenticated ciphering ([SWS_CRYPT_20745]). It is defined as a pure virtual interface in class ara::crypto::cryp::CryptoProvider and is to be included via header file ara/crypto/cryp/crypto_provider.h ([SWS_CRYPT_20745]).

Usage and Semantics

algId is passed as an input parameter, which identifies the target crypto algorithm ([SWS_CRYPT_20745]). The function operates synchronously and does not throw any exceptions (noexcept) ([SWS_CRYPT_20745]). Upon successful execution, it returns a ara::core::Result with a smart pointer to the created instance AuthCipherCtx::Sptr ([SWS_CRYPT_20745]).

Error handling

In the event of an error, a corresponding error code is returned in the ara::core::Result with rollback semantics ([SWS_CRYPT_20745]):

• ara::crypto::CryptoErrc::kInvalidArgument: If algId does not specify an algorithm for a symmetric authenticated stream cipher ([SWS_CRYPT_20745]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: If an unsupported value was passed for algId ([SWS_CRYPT_20745]).

Concurrency

The call to CreateAuthCipherCtx is thread-safe and specified as exception safe ([SWS_CRYPT_20745]).

use

The method CreateDecryptorPrivateCtx of interface ara::crypto::cryp::CryptoProvider serves to create a context for asymmetric decryption using a private key according to [SWS_CRYPT_20751]. As an input parameter, the function expects algId, which defines the identifier of the desired asymmetric encryption or decryption algorithm. Interpretation: The call is likely executed synchronously, since the signature directly returns a ara::core::Result that, in the event of success, contains a smart pointer to the created context (DecryptorPrivateCtx::Sptr) [SWS_CRYPT_20751]. Question Q-45d1c4a1b2133f4c (open)

Error handling

If the context cannot be created, the error is transported in the returned ara::core::Result. If an unsupported value was passed for the parameter algId, this specifically results in the error code ara::crypto::CryptoErrc::kUnknownIdentifier with rollback semantics [SWS_CRYPT_20751].

Concurrency and Limitations

The function is defined as noexcept and guarantees exception safety (exception safe) [SWS_CRYPT_20751]. For simultaneous access from multiple threads, the method is specified as thread-safe [SWS_CRYPT_20751]. Since the signature in header ara/crypto/cryp/crypto_provider.h is declared as a pure virtual method, the concrete implementation is the responsibility of the respective provider implementation [SWS_CRYPT_20751].

The pure virtual interface method CreateEncryptorPublicCtx belongs to class ara::crypto::cryp::CryptoProvider and is declared via header file ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20750]. Its task is to instantiate a new context for asymmetric encryption operations with a public key [SWS_CRYPT_20750].

Usage: The call takes place synchronously specifying the parameter algId of type AlgId, which specifies the identifier of the desired asymmetric encryption or decryption algorithm [SWS_CRYPT_20750]. The method returns the result in a ara::core::Result, which provides a smart pointer of type EncryptorPublicCtx::Sptr to the created context in the event of success [SWS_CRYPT_20750].

Error handling: If the argument algId contains an unsupported algorithm value, the call fails and returns the error code ara::crypto::CryptoErrc::kUnknownIdentifier in ara::core::Result [SWS_CRYPT_20750]. Explicit rollback semantics are specified for this error case [SWS_CRYPT_20750].

Concurrency and exception safety: The interface is declared as noexcept, is considered exception safe (exception safe), and is explicitly specified as thread-safe (thread-safe) [SWS_CRYPT_20750].

The method CreateHashFunctionCtx serves to instantiate a cryptographic hash context ([SWS_CRYPT_20747]). It is provided as a pure virtual interface of class ara::crypto::cryp::CryptoProvider via the header ara/crypto/cryp/crypto_provider.h.

Usage and Parameters

The call takes place synchronously and expects algId (of type AlgId) as an input parameter, which identifies the desired cryptographic algorithm ([SWS_CRYPT_20747]). As return value, the function returns a ara::core::Result<HashFunctionCtx::Sptr>, which contains a smart pointer to the created context in the event of success.

Error handling

If the creation fails, the ara::core::Result contains a corresponding error code with rollback semantics ([SWS_CRYPT_20747]):

• ara::crypto::CryptoErrc::kInvalidArgument: Returned if the passed algId is specified for an algorithm type other than a hash function ([SWS_CRYPT_20747]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Occurs if an unsupported identifier was passed for algId ([SWS_CRYPT_20747]).

Concurrency and Limitations

The function is declared as noexcept and specified as exception safe (“exception safe”) ([SWS_CRYPT_20747]). In addition, the call is thread-safe (“thread-safe”), so that simultaneous calls from multiple threads on the same instance of CryptoProvider are permissible ([SWS_CRYPT_20747]).

The method CreateKeyAgreementPrivateCtx of class ara::crypto::cryp::CryptoProvider serves to create a private key context for key agreements (KeyAgreementPrivateCtx) according to [SWS_CRYPT_20758]. The declaration is provided via header file #include "ara/crypto/cryp/crypto_provider.h".

Usage and Invocation

As input parameter, the synchronous method expects the identifier algId of type AlgId, which specifies the desired crypto algorithm for key agreement. As return value, the function returns a ara::core::Result<KeyAgreementPrivateCtx::Sptr>, which encapsulates a smart pointer to the newly created context instance in the event of success [SWS_CRYPT_20758].

Error handling

If the instantiation fails, the returned ara::core::Result contains an error code with rollback semantics [SWS_CRYPT_20758]:

• ara::crypto::CryptoErrc::kInvalidArgument: Occurs if the argument algId specifies a crypto algorithm that differs from key agreement schemes.
• ara::crypto::CryptoErrc::kUnknownIdentifier: Returned if the identifier algId has an unsupported value.

Concurrency and Safety

The interface is declared as noexcept and defined as exception safe (exception safe). In addition, the call is specified as thread-safe (thread-safe), so that simultaneous calls on the same instance of CryptoProvider are permissible [SWS_CRYPT_20758].

use

The CreateKeyDecapsulatorPrivateCtx method of the ara::crypto::cryp::CryptoProvider interface serves to create a private context for key decapsulation for a Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20753]. As an input parameter, it expects algId of type AlgId, which identifies the desired KEM cryptographic algorithm [SWS_CRYPT_20753]. The function operates synchronously and returns the result in a ara::core::Result<KeyDecapsulatorPrivateCtx::Sptr>, which encapsulates a smart pointer to the newly instantiated context in case of success [SWS_CRYPT_20753].

Error handling

If an error occurs during context creation, it is reported via the ara::core::Result with rollback semantics [SWS_CRYPT_20753]:

• ara::crypto::CryptoErrc::kInvalidArgument: The argument algId specifies a crypto algorithm that is not an asymmetric KEM scheme [SWS_CRYPT_20753].
• ara::crypto::CryptoErrc::kUnknownIdentifier: The argument algId has an unsupported value [SWS_CRYPT_20753].

Concurrency and Execution Safety

The interface is declared as noexcept and specified as exception-safe [SWS_CRYPT_20753]. In addition, execution is designed to be thread-safe [SWS_CRYPT_20753].

The CreateKeyDerivationFunctionCtx method of class ara::crypto::cryp::CryptoProvider serves to create an execution context for key derivation functions ([SWS_CRYPT_20748]). The identifier algId of type AlgId, which specifies the desired cryptographic target algorithm, is passed as an input parameter. The synchronous call returns a ara::core::Result that provides a smart pointer to the created context (KeyDerivationFunctionCtx::Sptr) upon successful execution ([SWS_CRYPT_20748]).

If an error occurs during instantiation, the result is returned with a corresponding error code under rollback semantics ([SWS_CRYPT_20748]):

• ara::crypto::CryptoErrc::kInvalidArgument: The argument algId specifies a cryptographic algorithm that is not a key derivation function ([SWS_CRYPT_20748]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: The passed identifier algId has an unsupported value ([SWS_CRYPT_20748]).

The interface is declared as a pure virtual function, designated as noexcept, and classified as mandatory thread-safe and exception safe ([SWS_CRYPT_20748]). Inclusion is performed via header file #include "ara/crypto/cryp/crypto_provider.h". The function addresses the higher-level requirements [RS_CRYPTO_02103] and [RS_AP_00144].

use

The method CreateKeyEncapsulatorPublicCtx of interface ara::crypto::cryp::CryptoProvider serves to create a public context for a Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20752]. For this purpose, the header file #include "ara/crypto/cryp/crypto_provider.h" must be included [SWS_CRYPT_20752]. The call takes place synchronously: algId is passed as an input parameter, which specifies the target crypto algorithm of the KEM. Upon successful execution, the method returns a smart pointer to the created context (KeyEncapsulatorPublicCtx::Sptr), encapsulated in a ara::core::Result [SWS_CRYPT_20752].

Error handling

If an error occurs during creation, rollback semantics take effect and the ara::core::Result contains a specific error code from ara::crypto::CryptoErrc [SWS_CRYPT_20752]:

• ara::crypto::CryptoErrc::kInvalidArgument: Returned if the argument algId designates a cryptographic algorithm that is not an asymmetric KEM [SWS_CRYPT_20752].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported if the argument algId has an unsupported value [SWS_CRYPT_20752].

Concurrency and Safety

The interface function is declared with noexcept and classified as exception safe (exception safe) as well as thread-safe (thread-safe) [SWS_CRYPT_20752]. It can therefore be called safely from concurrent contexts without external synchronization [SWS_CRYPT_20752].

use

The pure virtual method CreateMessageAuthnCodeCtx of interface ara::crypto::cryp::CryptoProvider requires the header file ara/crypto/cryp/crypto_provider.h and serves to synchronously create a context for symmetric message authentication codes [SWS_CRYPT_20746]. As input value, the function accepts parameter algId of type AlgId, which specifies the target crypto algorithm [SWS_CRYPT_20746]. Upon successful execution, the method returns a ara::core::Result<MessageAuthnCodeCtx::Sptr>, which encapsulates a smart pointer to the newly instantiated context instance [SWS_CRYPT_20746].

Error handling

In the event of an error, the returned Result object provides specific error codes with rollback semantics [SWS_CRYPT_20746]:

• ara::crypto::CryptoErrc::kInvalidArgument: The argument algId specifies a cryptographic algorithm that is not a symmetric message authentication code [SWS_CRYPT_20746].
• ara::crypto::CryptoErrc::kUnknownIdentifier: An unknown or unsupported identifier was passed for argument algId [SWS_CRYPT_20746].

Concurrency and Execution Safety

The interface is provided with the specifier noexcept and guarantees complete exception safety (exception safe) [SWS_CRYPT_20746]. Furthermore, the function is explicitly specified as thread-safe (thread-safe), so that calls can take place in parallel and without external synchronization from concurrent threads [SWS_CRYPT_20746].

use

The interface CreateProtectedKeyImportCtx of class ara::crypto::cryp::CryptoProvider (defined in ara/crypto/cryp/crypto_provider.h) serves for the synchronous creation of a context for protected key import ([SWS_CRYPT_50017]). The identifier of the desired wrapping algorithm is passed via the input parameter algId ([SWS_CRYPT_50017]). Upon successful instantiation, the method returns a ara::core::Result that provides a smart pointer ProtectedKeyImportCtx::Sptr to the created context ([SWS_CRYPT_50017]).

Error handling

If creation fails, the method returns an error code with rollback semantics in ara::core::Result ([SWS_CRYPT_50017]):

• ara::crypto::CryptoErrc::kInvalidArgument: Occurs if the cryptographic algorithm specified by algId is not supported for wrapping by the CryptoProvider ([SWS_CRYPT_50017]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported if the argument algId contains an unknown or unsupported identifier value ([SWS_CRYPT_50017]).

Concurrency and Limitations

The pure virtual method is declared as noexcept, provides exception safety, and is explicitly specified as thread-safe ([SWS_CRYPT_50017]). It can thus be called in parallel from multiple threads without external synchronization ([SWS_CRYPT_50017]).

The method CreateRandomGeneratorCtx serves to create a context for random number generators (RNG) within the class ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20741].

Usage and Call Context

The function is called synchronously and requires header file ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20741]:

• Parameters: algId of type AlgId is passed, which identifies the desired RNG algorithm. If no specific algId is specified, the method returns the default RNG [SWS_CRYPT_20741].
• Return value: A ara::core::Result<RandomGeneratorCtx::Sptr> that, in the event of success, contains a shared pointer to the created instance of RandomGeneratorCtx [SWS_CRYPT_20741].

Error handling

The method throws no exceptions (noexcept) and is specified as exception-safe [SWS_CRYPT_20741]. If the operation fails, the ara::core::Result returns an error code:

• ara::crypto::CryptoErrc::kUnknownIdentifier: Occurs if the argument algId has an unsupported value (with rollback semantics) [SWS_CRYPT_20741].

Concurrency and Limitations

The method is classified as thread-safe (thread-safe), so that parallel calls via the same instance of the CryptoProvider are permissible [SWS_CRYPT_20741].

The method CreateSignerPrivateCtx of class ara::crypto::cryp::CryptoProvider serves to create a context for signature operations with a private key ([SWS_CRYPT_20756]).

Usage and parameters: The call requires inclusion of the header file ara/crypto/cryp/crypto_provider.h. The cryptographic target signature algorithm is specified via the input parameter algId. In the event of success, the function returns a smart pointer to the created context instance ([SWS_CRYPT_20756]) via return type ara::core::Result<SignerPrivateCtx::Sptr>. Interpretation: Since the method directly returns a ara::core::Result, the call is likely executed synchronously. Question Q-8480f3cf5cef5f49 (open)

Concurrency and safety: The method is specified as thread-safe (thread-safe) as well as exception-safe (exception safe) and declared with noexcept ([SWS_CRYPT_20756]). It can therefore be called from concurrent contexts without additional synchronization.

Error handling: In the event of an error, the result delivers an error code of type ara::crypto::CryptoErrc with rollback semantics ([SWS_CRYPT_20756]):

• ara::crypto::CryptoErrc::kInvalidArgument: Occurs if the argument algId specifies a cryptographic algorithm that differs from a private key signature ([SWS_CRYPT_20756]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Occurs if algId contains an unknown or unsupported value ([SWS_CRYPT_20756]).

use

The virtual method CreateSymmetricCipherCtx of interface ara::crypto::cryp::CryptoProvider serves to create a context for symmetric cipher operations ([SWS_CRYPT_20742]). It is included via the header file #include "ara/crypto/cryp/crypto_provider.h" ([SWS_CRYPT_20742]).

As an input parameter, the function expects algId of type AlgId, which specifies the identifier of the desired target cryptographic algorithm ([SWS_CRYPT_20742]). The call takes place synchronously and returns a ara::core::Result<SymmetricCipherCtx::Sptr> as result, which provides a smart pointer to the newly instantiated context instance in the event of success ([SWS_CRYPT_20742]).

Error handling

If the creation fails, the returned ara::core::Result contains a corresponding error code ([SWS_CRYPT_20742]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported with rollback semantics if the passed value for algId references an unsupported algorithm ([SWS_CRYPT_20742]).

Concurrency and Limitations

The function is declared as noexcept and explicitly specified as exception safe (exception safe) ([SWS_CRYPT_20742]). In addition, the call is thread-safe (thread-safe), so that parallel context creations via the same CryptoProvider instance are permissible ([SWS_CRYPT_20742]).

use

The method CreateSymmetricKeyWrapperCtx of class ara::crypto::cryp::CryptoProvider serves to create a context for symmetric key wrap algorithms ([SWS_CRYPT_20743]). As an input parameter, algId is passed, which uniquely identifies the target cryptographic algorithm ([SWS_CRYPT_20743]). The call is synchronous and, in case of success, returns a ara::core::Result that encapsulates a smart pointer to the created context (SymmetricKeyWrapperCtx::Sptr) ([SWS_CRYPT_20743]).

Error handling

If creation fails, the function returns the error object within the ara::core::Result ([SWS_CRYPT_20743]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported if the argument algId has an unsupported value; rollback semantics apply ([SWS_CRYPT_20743]).

Concurrency and Limitations

The interface is declared as noexcept, is considered exception safe, and is thread-safe ([SWS_CRYPT_20743]). It can therefore be called safely from concurrent contexts, provided that the provided algId is supported by the underlying CryptoProvider ([SWS_CRYPT_20743]).

Usage and Call Context

The pure virtual method CreateVerifierPublicCtx of class ara::crypto::cryp::CryptoProvider is declared via the header file ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20757]. It serves to synchronously create a context for signature verification with public keys (public-key signature verification) [SWS_CRYPT_20757].

The caller passes the identifier of the desired crypto signature algorithm via the parameter algId (type AlgId) [SWS_CRYPT_20757]. In the event of success, the function returns a ara::core::Result that contains a smart pointer to the created verification context (VerifierPublicCtx::Sptr) [SWS_CRYPT_20757].

Error handling

In the event of an error, rollback semantics apply, and the resulting ara::core::Result transports a corresponding error code [SWS_CRYPT_20757]:

• ara::crypto::CryptoErrc::kInvalidArgument: Reported if the argument algId designates a cryptographic algorithm that is not intended for signature verification with public keys [SWS_CRYPT_20757].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported if an unknown or unsupported identifier was passed for algId [SWS_CRYPT_20757].

Concurrency and Limitations

The method is declared as noexcept, completely exception safe (exception safe), and explicitly specified as thread-safe (thread-safe) [SWS_CRYPT_20757]. Parallel calls from multiple execution contexts are therefore permissible without external synchronization.

The method ExportSecuredKey of interface ara::crypto::cryp::CryptoProvider exports a cryptographic key object into a secured, serialized format [SWS_CRYPT_20728]. The passed key object key is prepared according to the format implicitly defined by algId, cryptographically wrapped, and serialized into the output buffer resultBuffer [SWS_CRYPT_20728]. A key encryption key (kek) can optionally be passed for the wrapping; if no kek is provided, the method falls back to a KEK implicitly determined by algId or to the standard KEK of the CryptoProvider [SWS_CRYPT_20728].

The function is classified as thread-safe and exception safe and annotated with noexcept [SWS_CRYPT_20728]. Interpretation: Since the signature directly returns a ara::core::Result without asynchronous return types such as futures, the entire wrapping and serialization process is likely executed synchronously in the caller context. Question Q-3fb89afcc9300695 (open)

Upon successful completion, the returned ara::core::Result<std::size_t> provides the number of bytes written to resultBuffer [SWS_CRYPT_20728]. If the operation fails, rollback semantics take effect and one of the following errors is reported [SWS_CRYPT_20728]:

• UnknownIdentifier: The passed algId value is not supported [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInvalidArgument: The key object cannot be wrapped (e.g., invalid size or unsuitable type) or a mandatory expected kek was not passed [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kUsageViolation: The permissible usage of key or kek is incompatible with the selected algorithm [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kIncompatibleArguments: The passed kek is incompatible with the export algorithm [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer resultBuffer is too small for the result [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kBusyResource: A resource required for the export is busy [SWS_CRYPT_20728].

The method GeneratePrivateKey of class ara::crypto::cryp::CryptoProvider (declared in ara/crypto/cryp/crypto_provider.h) synchronously generates a new asymmetric key pair and returns the created private key as PrivateKey::Sptr within a ara::core::Result [SWS_CRYPT_20722]. The associated public key is not returned directly, but can be retrieved subsequently via the method PrivateKey::GetPublicKey() of the resulting key [SWS_CRYPT_20722].

Upon invocation, the parameter algId specifies the cryptographic algorithm, while privateKeyAllowedUsage defines the permissible transformation types for the private key [SWS_CRYPT_20722]. The permissible usage flags of the public key are mapped based on the permissions of the private key as follows [SWS_CRYPT_20722]:

• kAllowDataDecryption results in kAllowDataEncryption
• kAllowSigGeneration results in kAllowSigVerification
• kAllowKeyAgreement results in kAllowKeyAgreement
• kAllowKeyUnwrapping results in kAllowKeyWrapping

In addition, the usage flags kAllowPlaintextExport and kAllowPersist are automatically assigned to the public key [SWS_CRYPT_20722].

Regarding concurrency and execution, the function is specified as thread-safe and exception-safe [SWS_CRYPT_20722]. If an error occurs during key generation, the result is handled with rollback semantics [SWS_CRYPT_20722]. The following error codes can be returned:

• ara::crypto::CryptoErrc::kUnknownIdentifier, if an unsupported algorithm is passed for algId,
• ara::crypto::CryptoErrc::kIncompatibleArguments, if the specified privateKeyAllowedUsage flags are incompatible with the selected algorithm or key type,
• ara::crypto::CryptoErrc::kBusyResource, if generation is temporarily not possible due to temporarily occupied resources [SWS_CRYPT_20722].

The pure virtual method GenerateRandomData of interface ara::crypto::cryp::CryptoProvider serves to fill a memory region provided by the caller with cryptographic random data [SWS_CRYPT_30098]. The declaration is located in the header file ara/crypto/cryp/crypto_provider.h.

As output parameter, randomData of type ReadWriteMem Region is passed, which represents the buffer to be filled and whose size determines the number of generated random bytes [SWS_CRYPT_30098]. Interpretation: Since the function uses ara::core::Result<void> directly as return type rather than a future object, the generation of the data is likely to be synchronous and blocking [SWS_CRYPT_30098]. Question Q-315c0492dcf7f37d (open) The return value is empty on success or contains a corresponding error code in case of an error [SWS_CRYPT_30098].

If a problem occurs during execution, rollback semantics are applied so that no partial or invalid states remain [SWS_CRYPT_30098]. The following error states are specified:

• ara::crypto::CryptoErrc::kBusyResource: The underlying random number generator (RNG) currently has insufficient entropy and cannot provide the requested amount of random bytes [SWS_CRYPT_30098].
• ara::crypto::CryptoErrc::kUnsupported: The concrete implementation of CryptoProvider does not support a default random number generator [SWS_CRYPT_30098].

Regarding concurrency and robustness, the method is specified as thread-safe and exception safe [SWS_CRYPT_30098]. Multiple threads can thus call the function in parallel, and the noexcept specification guarantees that no C++ exceptions are thrown across the interface boundary.

use

The pure virtual method GenerateSymmetricKey is provided via interface ara::crypto::cryp::CryptoProvider (header file #include "ara/crypto/cryp/crypto_provider.h") and serves to generate a new symmetric key [SWS_CRYPT_20721]. The synchronous call expects as parameter algId the identifier of the target symmetric cryptographic algorithm and as allowedUsage bit flags that define the permitted transformation types for the generated key [SWS_CRYPT_20721]. Upon successful execution, the method delivers a ara::core::Result containing a SymmetricKey::Sptr, that is, a shared pointer to the newly generated symmetric key object [SWS_CRYPT_20721].

Error handling

If an error occurs during key generation, it is transmitted in ara::core::Result. Rollback semantics apply to all specified error cases [SWS_CRYPT_20721]:

• ara::crypto::CryptoErrc::kUnknownIdentifier: Reported if an unsupported value was passed for algId [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kIncompatibleArguments: Occurs if the specified allowedUsage flags are incompatible with the selected algId algorithm or key type [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kBusyResource: Indicates that the operation temporarily cannot be performed due to temporarily busy resources [SWS_CRYPT_20721].

Concurrency and Limitations

The operation is declared as noexcept and possesses the properties of being exception safe and thread-safe [SWS_CRYPT_20721]. It can therefore be called concurrently from multiple threads, whereby error kBusyResource can occur under high system load to signal temporary bottlenecks [SWS_CRYPT_20721].

The method GetSecureCounter() of class ara::crypto::cryp::CryptoProvider (declared in #include "ara/crypto/cryp/crypto_provider.h") queries the current counter value of the provider instance's secure counter [SWS_CRYPT_20098]. The function operates synchronously and requires no input parameters [SWS_CRYPT_20098]. In the event of success, it returns the structure SecureCounter via ara::core::Result<SecureCounter>, which consists of two unsigned 64-bit values (LSQW for Least Significant Quad Word and MSQW for Most Significant Quad Word) [SWS_CRYPT_20098]. It is guaranteed that each returned counter value is strictly greater than all values previously delivered via this instance [SWS_CRYPT_20098].

If the counter value cannot be determined, the call fails and returns an error code with rollback semantics in the Result object [SWS_CRYPT_20098]:

• ara::crypto::CryptoErrc::kUnsupported: The specific CryptoProvider does not support a secure counter [SWS_CRYPT_20098].
• ara::crypto::CryptoErrc::kBusyResource: A resource required for accessing or updating the counter is currently busy [SWS_CRYPT_20098].

Regarding concurrency and robustness, the function is specified as thread-safe and declared as exception safe with noexcept [SWS_CRYPT_20098]. Parallel calls from multiple threads are therefore permissible without external synchronization, while the strict monotonicity of the delivered counter values remains guaranteed [SWS_CRYPT_20098].

use

The method ImportPrivateKey of class ara::crypto::cryp::CryptoProvider serves to synchronously import a serialized private key [SWS_CRYPT_50132]. Upon calling, the payload data is passed via the memory region serialized (ReadOnlyMemRegion), supplemented by the desired usage restrictions (allowedUsage) and the serialization format (formatId). The parameter algId is optional (ara::core::Optional<AlgId>) and only needs to be set if the selected format does not already uniquely define the required key properties itself [SWS_CRYPT_50132]. As return value, the function provides a ara::core::Result<PrivateKey::Sptr>, which contains a shared pointer to the created key object in case of success.

Error handling

In case of error, the method ensures that rollback semantics take effect [SWS_CRYPT_50132]. The following error codes can be returned via the Result:

• InvalidArgument: The serialized data in serialized does not conform to the specified format [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kIncompatibleArguments: The passed allowedUsage are incompatible with the algId [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupported: The function is not supported by the concrete provider [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be executed temporarily due to busy resources [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupportedFormat: The formatId is not supported for this object type [SWS_CRYPT_50132].

Concurrency and Limitations

The interface is declared as noexcept and provides exception safety (exception safe) as well as thread safety (thread-safe) [SWS_CRYPT_50132]. Calls can thus be made concurrently from different threads.

use

The method ImportPublicKey serves to import a serialized public key into the respective ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20732]. The call takes place synchronously and returns a ara::core::Result<PublicKey::Sptr>, which contains a smart pointer to the created key object in the event of success [SWS_CRYPT_20732].

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

• serialized: A ReadOnlyMemRegion memory area that provides the raw data of the serialized key.
• allowedUsage: The permissible usage flags (AllowedUsageFlags) for the imported key.
• formatId: The identifier of the serialization format (FormatId).
• algId: An optional algorithm ID (ara::core::Optional<AlgId>). It is not required if the serialization format already uniquely determines the properties of the key.

Error handling

If an error occurs during processing, it is encapsulated in the returned ara::core::Result. The following error codes are specified [SWS_CRYPT_20732]:

• InvalidArgument: The passed data in serialized does not correspond to the specified format.
• ara::crypto::CryptoErrc::kIncompatibleArguments: The usage flags allowedUsage are incompatible with algId.
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified formatId is not supported for this object type.
• ara::crypto::CryptoErrc::kUnsupported: The requested function is not supported by the CryptoProvider.
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be executed temporarily.

Concurrency and Safety

The method is declared as noexcept, is considered exception-safe, and is specified as thread-safe according to the specification [SWS_CRYPT_20732]. Error cases follow defined rollback semantics [SWS_CRYPT_20732].

use

The ImportSymmetricKey method of interface ara::crypto::cryp::CryptoProvider is used to import a serialized symmetric key [SWS_CRYPT_50014]. As its return value, it provides a ara::core::Result<SymmetricKey::Sptr> that, in case of success, provides a smart pointer to the newly instantiated key object [SWS_CRYPT_50014]. Since no asynchronous return type such as a future is used, execution is presumably synchronous. Question Q-720a495b07c4f31d (open)

The following parameters must be passed during the call [SWS_CRYPT_50014]:

• serialized (ReadOnlyMemRegion): The memory area containing the serialized key data.
• allowedUsage (AllowedUsageFlags): Bitmask of the operations and usages permitted for this key.
• formatId (FormatId): Identifier of the serialization format of the key data.
• algId (ara::core::Optional<AlgId>): Optional algorithm identifier; it is not required if the specified serialization format already uniquely determines all required properties of the key.

Error Handling and Boundary Conditions

The method is specified as thread-safe and exception safe [SWS_CRYPT_50014]. In case of an error, the implementation guarantees rollback semantics and returns a corresponding error code in ara::core::Result [SWS_CRYPT_50014]:

• InvalidArgument: The passed binary data in serialized do not conform to the specified format.
• ara::crypto::CryptoErrc::kIncompatibleArguments: The specified allowedUsage flags are incompatible with the specified algId.
• ara::crypto::CryptoErrc::kUnsupported: The function is not supported by the concrete instance of the CryptoProvider.
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified format is not supported for this key type.
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot currently be executed due to temporarily busy resources.

use

The LoadPrivateKey method of the ara::crypto::cryp::CryptoProvider interface loads a private key from a provided key slot ([SWS_CRYPT_20764]). The call is executed synchronously and accepts a shared pointer to the source resource (keySlot) as a parameter. In case of success, the function provides a shared pointer to the loaded key object (PrivateKey::Sptr), which is returned inside a ara::core::Result ([SWS_CRYPT_20764]).

Error handling

If an error occurs during the operation, rollback semantics apply and the ara::core::Result contains a specific error code ([SWS_CRYPT_20764]):

• ara::crypto::CryptoErrc::kEmptyKeySlot: The passed key slot is empty ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kIncompatibleObject: The underlying resource belongs to another, incompatible CryptoProvider or contains a differing key type ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kBusyResource: The operation cannot be executed temporarily ([SWS_CRYPT_20764]).

Concurrency and Safety

The specification classifies the function as thread-safe and exception-safe; the signature is declared as noexcept ([SWS_CRYPT_20764]). Multiple threads can invoke the method in parallel, but must handle a possible return of kBusyResource in case of temporary resource conflicts.

use

The LoadPublicKey method of the ara::crypto::cryp::CryptoProvider interface loads a public key from the provided key slot [SWS_CRYPT_20763]. As parameter keySlot, it expects a KeySlot::Sptr referencing the slot with the key to be loaded [SWS_CRYPT_20763]. As a return value, the function returns a ara::core::Result<PublicKey::Sptr>, which in case of success contains a shared pointer to the loaded public key object [SWS_CRYPT_20763]. The direct provision of the result value is likely to indicate synchronous invocation behavior. Question Q-e0d2480909b1398a (open)

Error handling

If the loading procedure fails, the ara::core::Result contains a corresponding error code of the domain ara::crypto::CryptoErrc, with rollback semantics being defined for all specified error cases [SWS_CRYPT_20763]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Occurs when the passed KeySlot is empty [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kIncompatibleObject: Is returned when the underlying resource belongs to another, incompatible CryptoProvider or contains a differing key type [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kBusyResource: Occurs if the operation cannot be executed temporarily because the resource is otherwise occupied [SWS_CRYPT_20763].

Concurrency and Safety

The method is declared with noexcept and specified as exception-safe [SWS_CRYPT_20763]. With regard to concurrency, the operation is explicitly classified as thread-safe, meaning that parallel calls from multiple threads are permissible [SWS_CRYPT_20763].

The pure virtual method LoadSymmetricKey of class ara::crypto::cryp::CryptoProvider serves to load a symmetric key from a provided key slot [SWS_CRYPT_20762]. As a parameter, the function accepts a shared pointer to the relevant slot (keySlot) and synchronously returns a ara::core::Result<SymmetricKey::Sptr>, which provides a shared pointer to the loaded key object upon successful execution [SWS_CRYPT_20762].

With regard to concurrency and execution safety, the method is specified as thread-safe and exception safe and declared with noexcept [SWS_CRYPT_20762].

If an error occurs during loading, the method returns specific error codes from the domain ara::crypto::CryptoErrc with defined rollback semantics via the result object [SWS_CRYPT_20762]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Occurs when the passed KeySlot is empty [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kIncompatibleObject: Is returned if the underlying resource belongs to another, incompatible Crypto-Provider or contains another key type [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kBusyResource: Signals that the operation temporarily cannot be executed [SWS_CRYPT_20762].