classe ara::crypto::cryp::HashFunctionCtx

O método CalculateHashDigest executa um cálculo one-shot síncrono de um valor de hash criptográfico e escreve o resultado no buffer de saída fornecido [SWS_CRYPT_50060]. Como parâmetros, são transmitidos a mensagem de entrada a ser processada data, o buffer de destino digest bem como, opcionalmente, um vetor de inicialização iv. Em caso de execução bem-sucedida, a função retorna, por meio do objeto de resultado ara::core::Result<std::size_t>, o número real de bytes de digest gravados [SWS_CRYPT_50060].

Tratamento de erros

Se o cálculo falhar, a interface garante semântica de rollback [SWS_CRYPT_50060]. Os seguintes códigos de erro podem estar contidos no resultado:

• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho dos dados transmitidos ou do vetor de inicialização não é suportado [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: O cálculo single-call não é suportado pelo contexto, ou a passagem do vetor de inicialização não corresponde à configuração do contexto (IV obrigatório, mas ausente, ou IV transmitido embora não seja suportado) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: A capacidade do buffer de saída digest não é suficiente para o digest calculado [SWS_CRYPT_50060].

Concorrência e interação

A função é declarada como segura contra exceções (exception safe) e segura para threads (thread-safe) [SWS_CRYPT_50060]. Para evitar previamente erros relativos a comprimentos de entrada inválidos, o tamanho máximo de buffer permitido pelo contexto para uma chamada única pode ser determinado através de GetMaximumChunkSize [SWS_CRYPT_50062].

usar

O método Cancel() serve para o cancelamento direcionado de uma operação de streaming em andamento que foi iniciada previamente pelo método Start() e ainda não concluída de forma regular [SWS_CRYPT_50058]. A chamada ocorre de forma síncrona e sem parâmetros em uma instância de ara::crypto::cryp::HashFunctionCtx do arquivo de cabeçalho ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. Em caso de execução bem-sucedida, a operação retorna um ara::core::Result<void> vazio [SWS_CRYPT_50058].

Tratamento de erros

Se ocorrer um problema durante a execução, o ara::core::Result retornado conterá um valor de erro correspondente [SWS_CRYPT_50058]. Se o processamento não tiver sido iniciado por Start() antes da chamada de Cancel(), o cancelamento falha e retorna o código de erro específico ara::crypto::CryptoErrc::kProcessingNotStarted com semântica de rollback [SWS_CRYPT_50058].

Simultaneidade e restrições

A interface é definida como thread-safe e exception safe e declarada com noexcept [SWS_CRYPT_50058]. Como pré-condição funcional essencial, aplica-se que o processamento de dados deve se encontrar em um estado ativo gerado por uma chamada anterior a Start() [SWS_CRYPT_50058].

Interação

O padrão implementado por Cancel() é padronizado através de diversos contextos de streaming da pilha criptográfica. Uma semântica e uma sinalização de erros exatamente coincidentes são apresentadas também pelos contextos VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] e EncryptorPublicCtx [SWS_CRYPT_50089].

O método Compare da classe ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) compara sincronicamente o tamanho e o conteúdo de um digest hash previamente calculado com um valor de referência esperado. O valor nominal é passado através do parâmetro expected do tipo ReadOnlyMemRegion. Em caso de sucesso, a função retorna um ara::core::Result<bool>, que contém true se e só se a sequência de bytes esperada for idêntica ao digest calculado.

O pré-requisito para a chamada é que o cálculo do digest tenha sido previamente concluído com o método Finish(). Se não for esse o caso, a chamada falha e retorna o erro ara::crypto::CryptoErrc::kProcessingNotFinished com semântica de rollback ([SWS_CRYPT_50154]). Interpretação: Um comprimento divergente ou um conteúdo diferente de expected provavelmente não resulta num código de erro, mas sim num false regular no objeto de resultado. Pergunta Q-fdd0ecaec22f6985 (aberta)

No que diz respeito à concorrência, o método está especificado como thread-safe e exception safe ([SWS_CRYPT_50154]). Devido à declaração como noexcept, não lança exceções C++.

Em contextos criptográficos relacionados, é utilizado o mesmo padrão de verificação: Para Message Authentication Codes, ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) compara o tamanho e o conteúdo do valor MAC calculado, enquanto CompareSubspan ([SWS_CRYPT_50028]) verifica os bits mais significativos. Ambos os métodos exigem igualmente um cálculo previamente terminado.

O método [SWS_CRYPT_50064] da classe ara::crypto::cryp::HashFunctionCtx grava sincronicamente o estado atual de um contexto de hash no buffer de saída transmitido contextState do tipo ReadWriteMem Region. Isso permite que as aplicações interrompam uma operação de hash criptográfico em andamento e a retomem em um momento posterior. Em caso de execução bem-sucedida, a chamada retorna um ara::core::Result<void> vazio.

Interação e dimensionamento de buffer

Para evitar erros de memória, o tamanho de buffer em bytes estritamente necessário deve ser consultado previamente através da função [SWS_CRYPT_50063]. O estado exportado pode posteriormente ser importado novamente em um contexto de hash por meio de [SWS_CRYPT_50065]. O pré-requisito para isso é que o contexto de destino apresente a mesma AlgorithmId e seja fornecido pelo mesmo Crypto Provider que o contexto de origem. Durante a importação, um eventual estado de cálculo existente é completamente sobrescrito.

Tratamento de erros

Se a operação falhar, é retornado um erro em ara::core::Result. Os seguintes códigos de erro de ara::crypto::CryptoErrc estão especificados:

• ara::crypto::CryptoErrc::kUnsupported: O contexto concreto não suporta a exportação ou importação de estados.
• ara::crypto::CryptoErrc::kInsufficientCapacity: A capacidade do buffer transmitido contextState não é suficiente para acomodar o estado.

Para ambos os casos de erro, é definida uma semântica de rollback, de modo que o estado do objeto permanece inalterado.

Simultaneidade e segurança de execução

A interface é declarada como const e noexcept. Conforme a especificação, a chamada é tanto thread-safe quanto exception-safe.

usar

O método síncrono Finish() conclui o cálculo de um valor de hash em ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_21115]. A chamada sem parâmetros retorna um ara::core::Result<void>, que sinaliza a conclusão bem-sucedida ou encapsula um erro [SWS_CRYPT_21115]. A interface é declarada como noexcept e especificada como segura contra exceções (exception safe) e segura para threads (thread-safe) [SWS_CRYPT_21115].

Tratamento de erros e simultaneidade

Se o cálculo de hash não tiver sido iniciado com sucesso antes da chamada, o método falhará com o erro ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. Para esse caso de erro, está definida uma semântica de reversão (rollback), de modo que os chamadores devem obrigatoriamente atentar para um contexto devidamente iniciado antes da finalização [SWS_CRYPT_21115].

Interação

Após a chamada bem-sucedida de Finish(), o digest de hash calculado é tipicamente transferido com GetDigest() para um buffer fornecido [SWS_CRYPT_21116], [SWS_CRYPT_50059]. GetIntermediateDigest() serve para diferenciação: essa função fornece o mesmo valor de hash que a sequência de Finish() e GetDigest(), mas permite subsequentemente a passagem de dados adicionais [SWS_CRYPT_50059]. Interpretação: após a chamada de Finish(), o cálculo deve estar definitivamente concluído e o contexto não deve mais aceitar dados adicionais. Pergunta Q-f4daf29364f45fd5 (aberta) Os tamanhos de buffer permitidos para as etapas de processamento no contexto podem ser consultados por meio de GetMaximumChunkSize() [SWS_CRYPT_50062].

O método ImportContextState da classe ara::crypto::cryp::HashFunctionCtx (definido em ara/crypto/cryp/hash_function_ctx.h) serve para restaurar o estado interno de um contexto de hash a partir de um buffer passado e, com isso, prosseguir uma operação de hash previamente interrompida [SWS_CRYPT_50065]. Um eventual estado de cálculo em curso do contexto atual é aqui integralmente substituído pelo estado importado [SWS_CRYPT_50065].

Chamada e pré-condições

A chamada síncrona ocorre através da assinatura ImportContextState(ReadOnlyMem Region contextState) noexcept e retorna um ara::core::Result<void> [SWS_CRYPT_50065]. Ao parâmetro contextState aplicam-se os seguintes requisitos obrigatórios:

• O buffer de dados deve ter sido previamente exportado a partir de uma instância de HashFunctionCtx com o método ExportContextState() [SWS_CRYPT_50065].
• O contexto de origem deve ter possuído a mesma AlgorithmId e ter sido disponibilizado pelo mesmo Crypto Provider que o contexto de destino [SWS_CRYPT_50065].

Tratamento de erros e simultaneidade

Em caso de erro, é retornado um código de erro com semântica de rollback, de modo a que o estado existente do contexto permaneça inalterado em caso de insucesso [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: o argumento contextState contém dados inválidos [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: o contexto específico não suporta a exportação e importação de estados de contexto [SWS_CRYPT_50065].

A operação está especificada como thread-safe e exception safe [SWS_CRYPT_50065].

O método Start() da interface ara::crypto::cryp::HashFunctionCtx inicializa o contexto para o cálculo passo a passo de um valor de hash sem vetor de inicialização (IV) [SWS_CRYPT_50152]. Uma nova chamada aborta um cálculo de hash eventualmente já em curso e redefine o contexto para um novo cálculo [SWS_CRYPT_50152].

A função é síncrona, não recebe parâmetros e retorna um ara::core::Result<void> [SWS_CRYPT_50152]. Se ocorrer um erro durante a inicialização, aplica-se a semântica de rollback com os seguintes códigos de erro específicos [SWS_CRYPT_50152]:

• ara::crypto::CryptoErrc::kUnsupported: A função de hash utilizada espera obrigatoriamente um vetor de inicialização [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: Um recurso interno obrigatoriamente necessário para a operação está ocupado [SWS_CRYPT_50152].

No que diz respeito à concorrência, o método está especificado como thread-safe bem como exception safe e declarado como noexcept [SWS_CRYPT_50152]. Após a inicialização bem-sucedida, partes da mensagem podem ser inseridas sequencialmente através do método Update() do contexto [SWS_CRYPT_21113]. Como a chamada aborta cálculos em curso, a função deverá servir na prática também como mecanismo de reset antes de um reinício. Pergunta Q-9c369489a6c6e8cb (aberta)

usar

A função Start da interface ara::crypto::cryp::HashFunctionCtx inicializa o contexto para o cálculo de um digest de hash utilizando um vetor de inicialização (IV) [SWS_CRYPT_50153]. Como parâmetro, o vetor de inicialização iv é passado através de uma ReadOnlyMemRegion [SWS_CRYPT_50153]. A chamada síncrona retorna um ara::core::Result<void>, que em caso de sucesso não contém valor de retorno [SWS_CRYPT_50153]. Além disso, uma chamada cancela um cálculo de hash eventualmente já em execução neste contexto [SWS_CRYPT_50153].

Tratamento de erros

Se ocorrer um erro durante a inicialização, é retornado um código de erro correspondente, sendo garantida uma semântica de rollback para todos os casos de erro [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do vetor de inicialização fornecido não é suportado [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: A função de hash subjacente não utiliza nenhum vetor de inicialização [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: Um recurso necessário para a inicialização está ocupado [SWS_CRYPT_50153].

Concorrência e interação

A interface está declarada como noexcept bem como especificada como segura para threads (thread-safe) e segura contra exceções (exception safe) [SWS_CRYPT_50153]. No fluxo típico, a chamada constitui a pré-condição para o posterior processamento passo a passo da mensagem de entrada através do método Update [SWS_CRYPT_21113].

O método síncrono Update serve em [SWS_CRYPT_21113] para a atualização incremental de um contexto de cálculo de hash em execução (ara::crypto::cryp::HashFunctionCtx). Por meio do parâmetro data (ReadOnlyMemRegion) é passada uma parte da mensagem de entrada a ser processada. A função retorna um ara::core::Result<void>, que está vazio em caso de sucesso ou encapsula um código de erro correspondente.

Em relação ao comportamento de falha, o método oferece semântica de rollback em dois estados de erro específicos:

• ara::crypto::CryptoErrc::kProcessingNotStarted: O cálculo não foi iniciado previamente por uma chamada do método Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho dos dados passados não é suportado pelo contexto [SWS_CRYPT_21113].

Para o contexto de chamada aplicam-se condições claras de ordem e de tamanho: antes da passagem de dados, o processo de hash deve ter sido inicializado [SWS_CRYPT_21113]. Para evitar kInvalidInputSize, o tamanho máximo de bloco permitido para uma única chamada de Update pode ser determinado previamente via GetMaximumChunkSize [SWS_CRYPT_50062]. Conforme a especificação, a função é declarada como segura contra exceções (exception safe) e segura para threads (thread-safe) [SWS_CRYPT_21113].

Na interação com outras interfaces, existe dentro de HashFunctionCtx uma sobrecarga para a transmissão de objetos de chave via Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. Após o fornecimento de todos os blocos de dados, a finalização do checksum provavelmente ocorre por meio de Finish() [SWS_CRYPT_50062]. Pergunta Q-dcac20f353ca55f4 (aberta)

O método síncrono Update serve, em [SWS_CRYPT_50057], para expandir passo a passo o contexto de um cálculo de valor de hash em ara::crypto::cryp::HashFunctionCtx com uma nova secção de mensagem sob a forma de um objeto de chave. Como parâmetro, é passado um smart pointer para o objeto de chave (CryptoObject::Sptr key). A chamada fornece como valor de retorno um ara::core::Result<void> que, em caso de processamento bem-sucedido, está vazio ou, em caso de erro, encapsula um código de erro correspondente [SWS_CRYPT_50057].

Como condição de ordem aplica-se que o cálculo tem de ter sido obrigatoriamente iniciado previamente pela chamada de Start(); caso contrário, é reportado o erro ProcessingNotStarted [SWS_CRYPT_50057]. Outros casos de erro específicos abrangem (cada um com semântica de rollback) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, se o contexto de hash em geral não suportar a aplicação de hash a chaves,
• ara::crypto::CryptoErrc::kIncompatibleObject, caso o objeto de chave passado não seja compatível com o contexto,
• ara::crypto::CryptoErrc::kUsageViolation, desde que a utilização permitida da chave não abranja kAllowHash Calculation,
• ara::crypto::CryptoErrc::kInvalidInputSize, se o tamanho de dados da chave passada não for suportado.

O método está declarado como thread-safe, bem como exception safe (noexcept) [SWS_CRYPT_50057]. Na interação com outras interfaces do módulo, o tamanho de buffer máximo permitido para chamadas Update individuais pode ser determinado através de GetMaximumChunkSize() [SWS_CRYPT_50062]. Para partes regulares de mensagem sem objeto de chave, existe em paralelo em HashFunctionCtx a sobrecarga Update(ReadOnlyMemRegion data) [SWS_CRYPT_21113].