class ara::crypto::cryp::RandomGeneratorCtx

The AddEntropy method of class ara::crypto::cryp::RandomGeneratorCtx serves to update the internal state of a random number generator (RNG) by mixing in additionally passed entropy values [SWS_CRYPT_22914]. The declaration is available via header file ara/crypto/cryp/random_generator_ctx.h [SWS_CRYPT_22914]. As an input parameter, the function expects an object of type ReadOnlyMemRegion named entropy, which encapsulates the memory region with the entropy value to be added [SWS_CRYPT_22914].

The call is executed synchronously (interpretation: the interface returns the result directly without an asynchronous result type). Question Q-6e56e1daaa526bf8 (open) The result is returned as ara::core::Result<void>, which is empty in case of success if the method is supported and the entropy could be successfully mixed in [SWS_CRYPT_22914]. If the concrete random number generator context does not support adding entropy, however, the call fails and returns the error code ara::crypto::CryptoErrc::kUnsupported with guaranteed rollback semantics [SWS_CRYPT_22914].

With regard to concurrency and failure safety, the interface is specified as thread-safe (thread-safe) as well as exception-safe (exception safe) and provided with the identifier noexcept [SWS_CRYPT_22914]. Callers can thus safely call the function from multiple threads, but should always evaluate the returned ara::core::Result to handle a lack of support for entropy addition in the respective context [SWS_CRYPT_22914].

The Generate function of the ara::crypto::cryp::RandomGeneratorCtx interface serves to fill a provided output buffer with a (pseudo-)random sequence [SWS_CRYPT_22915]. As a transfer parameter, the method accepts the writable memory area output of type ReadWriteMemRegion into which the generated random bytes are written directly [SWS_CRYPT_22915].

Regarding execution safety and concurrency, the method is declared as noexcept, is considered exception-safe, and is explicitly specified as thread-safe [SWS_CRYPT_22915]. This permits concurrent invocation from multiple threads.

Error handling

The return type ara::core::Result<void> signals the success of the operation through an empty result or returns a corresponding error code with rollback semantics in case of an error [SWS_CRYPT_22915]:

• ara::crypto::CryptoErrc::kUninitializedContext: Occurs if the context must previously be initialized or seeded with entropy by the application [SWS_CRYPT_22915].
• ara::crypto::CryptoErrc::kBusyResource: Is returned if the context has currently run out of entropy (\"out-of-entropy\") and therefore cannot provide the requested amount of random bytes [SWS_CRYPT_22915].

Interaction and Distinction

While RandomGeneratorCtx::Generate writes raw random data bytes into buffers [SWS_CRYPT_22915], further generation functions with a different focus exist in module crypt: thus, CryptoProvider::GenerateSymmetricKey [SWS_CRYPT_20721] serves to instantiate symmetric keys and CryptoProvider::GeneratePrivateKey [SWS_CRYPT_20722] to generate asymmetric key pairs. In addition, the method is not to be confused with the same-named function Generate of MessageAuthnCodeCtx, which serves to compute a MAC digest [SWS_CRYPT_50029].

use

The pure virtual method Seed of interface ara::crypto::cryp::RandomGeneratorCtx serves to set the internal state of the random number generator (RNG) via a provided memory region [SWS_CRYPT_22911]. The declaration is located in header ara/crypto/cryp/random_generator_ctx.h with the signature virtual ara::core::Result<void> Seed(ReadOnlyMemRegion seed) noexcept = 0; [SWS_CRYPT_22911].

As input parameter, the synchronous function accepts seed of type ReadOnlyMemRegion, which contains the memory region with the seed value [SWS_CRYPT_22911]. Upon successful execution and support by the context, the method returns an empty ara::core::Result<void> [SWS_CRYPT_22911].

Error handling

In case of an error, the returned ara::core::Result contains a corresponding error code [SWS_CRYPT_22911]:

• ara::crypto::CryptoErrc::kUnsupported: Occurs when the concrete RandomGeneratorCtx does not support seeding; rollback semantics are specified for this error case [SWS_CRYPT_22911].

Concurrency and Limitations

The interface is declared as noexcept and classified as exception-safe as well as thread-safe regarding execution safety [SWS_CRYPT_22911].

Interaction

In addition to this memory-region-based function, [SWS_CRYPT_22912] defines an overload Seed(SymmetricKey::Sptr seed), which initializes the state of the RNG by means of a symmetric key while evaluating usage restrictions such as kAllowRngInit.

The method Seed initializes the internal state of a random number generator in the context of ara::crypto::cryp::RandomGeneratorCtx using a symmetric key [SWS_CRYPT_22912]. The call is synchronous and specified as thread-safe and exception-safe (exception safe and noexcept) [SWS_CRYPT_22912]. A smart pointer to a key (SymmetricKey::Sptr), whose key value is adopted as seed, serves as input parameter [SWS_CRYPT_22912].

For error handling, the function returns a ara::core::Result<void>, which is empty in case of success [SWS_CRYPT_22912]. If the operation fails, rollback semantics take effect; this particularly concerns the following error codes:

• ara::crypto::CryptoErrc::kUsageViolation: Occurs when the allowed key usage of the passed key does not include the flag kAllowRngInit [SWS_CRYPT_22912].
• ara::crypto::CryptoErrc::kUnsupported: Reported when the concrete context instance does not support setting a seed using a symmetric key [SWS_CRYPT_22912].

In interaction with the interface family, this function represents the key-based variant, whereas the overload according to [SWS_CRYPT_22911] covers initialization via an unstructured memory region (ReadOnlyMemRegion). Due to rollback semantics, the internal generator state presumably remains in the previous state in case of an error (interpretation). Question Q-970cbedd1843b26a (open)