classe ara::crypto::cryp::RandomGeneratorCtx

O método AddEntropy da classe ara::crypto::cryp::RandomGeneratorCtx serve para atualizar o estado interno de um gerador de números aleatórios (RNG) através da mistura de valores de entropia adicionais transmitidos [SWS_CRYPT_22914]. A declaração está disponível através do arquivo de cabeçalho ara/crypto/cryp/random_generator_ctx.h [SWS_CRYPT_22914]. Como parâmetro de entrada, a função espera um objeto do tipo ReadOnlyMemRegion chamado entropy, que encapsula a área de memória com o valor de entropia a ser adicionado [SWS_CRYPT_22914].

A chamada é executada sincronicamente (interpretação: a interface retorna o resultado diretamente sem um tipo de resultado assíncrono). Pergunta Q-6e56e1daaa526bf8 (aberta) O resultado é retornado como ara::core::Result<void>, que está vazio em caso de sucesso se o método for suportado e a entropia tiver sido misturada com sucesso [SWS_CRYPT_22914]. Se, por outro lado, o contexto concreto do gerador de números aleatórios não suportar a adição de entropia, a chamada falha e retorna o código de erro ara::crypto::CryptoErrc::kUnsupported com semântica de rollback garantida [SWS_CRYPT_22914].

Em relação à concorrência e à segurança contra falhas, a interface é especificada como segura para threads (thread-safe) e segura contra exceções (exception safe), e provida com o identificador noexcept [SWS_CRYPT_22914]. Os chamadores podem, assim, chamar a função com segurança a partir de múltiplas threads, mas devem sempre avaliar o ara::core::Result retornado a fim de interceptar uma eventual falta de suporte à adição de entropia no respectivo contexto [SWS_CRYPT_22914].

A função Generate da interface ara::crypto::cryp::RandomGeneratorCtx serve para preencher um buffer de saída fornecido com uma sequência (pseudo)aleatória [SWS_CRYPT_22915]. Como parâmetro de passagem, o método recebe a área de memória gravável output do tipo ReadWriteMemRegion, na qual os bytes aleatórios gerados são gravados diretamente [SWS_CRYPT_22915].

Em termos de segurança de execução e concorrência, o método é declarado como noexcept, considerado exception-safe e especificado explicitamente como thread-safe [SWS_CRYPT_22915]. Isso permite a chamada concorrente a partir de múltiplas threads.

Tratamento de erros

O tipo de retorno ara::core::Result<void> sinaliza o sucesso da operação através de um resultado vazio ou retorna, em caso de erro, um código de erro correspondente com semântica de rollback [SWS_CRYPT_22915]:

• ara::crypto::CryptoErrc::kUninitializedContext: Ocorre caso o contexto precise previamente ser inicializado ou alimentado com entropia («seeded») pela aplicação [SWS_CRYPT_22915].
• ara::crypto::CryptoErrc::kBusyResource: É retornado quando o contexto está atualmente sem entropia («out-of-entropy») e, portanto, não pode fornecer a quantidade solicitada de bytes aleatórios [SWS_CRYPT_22915].

Interação e distinção

Enquanto RandomGeneratorCtx::Generate escreve bytes de dados aleatórios brutos em buffers [SWS_CRYPT_22915], existem no módulo crypt outras funções de geração com foco diferente: assim, CryptoProvider::GenerateSymmetricKey [SWS_CRYPT_20721] serve para a instanciação de chaves simétricas e CryptoProvider::GeneratePrivateKey [SWS_CRYPT_20722] para a geração de pares de chaves assimétricas. Além disso, o método não deve ser confundido com a função homônima Generate de MessageAuthnCodeCtx, a qual serve para o cálculo de um digest de MAC [SWS_CRYPT_50029].

usar

O método puramente virtual Seed da interface ara::crypto::cryp::RandomGeneratorCtx serve para definir o estado interno do gerador de números aleatórios (RNG) através de uma região de memória fornecida [SWS_CRYPT_22911]. A declaração ocorre no cabeçalho ara/crypto/cryp/random_generator_ctx.h com a assinatura virtual ara::core::Result<void> Seed(ReadOnlyMemRegion seed) noexcept = 0; [SWS_CRYPT_22911].

Como parâmetro de entrada, a função síncrona recebe seed do tipo ReadOnlyMemRegion, que contém a região de memória com o valor de semente (seed) [SWS_CRYPT_22911]. Em caso de execução bem-sucedida e suporte pelo contexto, o método retorna um ara::core::Result<void> vazio [SWS_CRYPT_22911].

Tratamento de erros

Em caso de erro, o ara::core::Result retornado contém um código de erro correspondente [SWS_CRYPT_22911]:

• ara::crypto::CryptoErrc::kUnsupported: ocorre se o RandomGeneratorCtx concreto não suportar a semeadura (seeding); para este caso de erro, está especificada a semântica de rollback [SWS_CRYPT_22911].

Simultaneidade e restrições

A interface é declarada como noexcept e classificada como exception safe, bem como thread-safe, no que diz respeito à segurança de execução [SWS_CRYPT_22911].

Interação

Como complemento a esta função baseada em região de memória, [SWS_CRYPT_22912] define uma sobrecarga Seed(SymmetricKey::Sptr seed), que inicializa o estado do RNG por meio de uma chave simétrica e avalia restrições de uso como kAllowRngInit.

O método Seed inicializa o estado interno de um gerador de números aleatórios no contexto de ara::crypto::cryp::RandomGeneratorCtx com o uso de uma chave simétrica [SWS_CRYPT_22912]. A chamada é síncrona e está especificada como segura para threads, bem como segura contra exceções (exception safe e noexcept) [SWS_CRYPT_22912]. Como parâmetro de entrada, utiliza-se um smart pointer para uma chave (SymmetricKey::Sptr), cujo valor de chave é adotado como semente (seed) [SWS_CRYPT_22912].

No tratamento de erros, a função retorna um ara::core::Result<void>, que fica vazio em caso de sucesso [SWS_CRYPT_22912]. Se a operação falhar, atua uma semântica de rollback; isto se aplica especialmente aos seguintes códigos de erro:

• ara::crypto::CryptoErrc::kUsageViolation: ocorre quando o uso permitido da chave passada não abrange o sinalizador kAllowRngInit [SWS_CRYPT_22912].
• ara::crypto::CryptoErrc::kUnsupported: é reportado quando a instância concreta de contexto não suporta a definição de uma semente por meio de uma chave simétrica [SWS_CRYPT_22912].

Na interação com a família de interfaces, esta função representa a variante baseada em chave, enquanto a sobrecarga conforme [SWS_CRYPT_22911] cobre a inicialização através de uma região de memória não estruturada (ReadOnlyMemRegion). Devido à semântica de rollback, o estado interno do gerador provavelmente permanece no estado anterior em caso de erro (interpretação). Pergunta Q-970cbedd1843b26a (aberta)