classe ara::crypto::cryp::MessageAuthnCodeCtx

O método virtual puro Cancel serve, na interface ara::crypto::cryp::MessageAuthnCodeCtx, para cancelar uma operação de streaming em andamento, iniciada anteriormente por meio de Start() e ainda não concluída [SWS_CRYPT_50027]. A chamada ocorre de forma síncrona, não aceita parâmetros de entrada e retorna, em caso de sucesso, um ara::core::Result<void> vazio, o qual confirma o cancelamento bem-sucedido da operação [SWS_CRYPT_50027].

Se o processamento de dados não tiver sido iniciado adequadamente pelo método Start() antes da chamada, a execução falhará. Neste caso, a função fornece um resultado com o código de erro específico ara::crypto::CryptoErrc::kProcessingNotStarted sob garantia de uma semântica de rollback [SWS_CRYPT_50027]. Em relação à segurança de execução, a interface é especificada como segura para threads (thread-safe) e garante segurança contra exceções (exception safe), uma vez que está declarada como noexcept e não lança exceções [SWS_CRYPT_50027].

O comportamento de cancelamento idêntico para processamentos de streaming ainda não finalizados é compartilhado por todas as interfaces de contexto relacionadas do módulo de criptografia:

• VerifierPublicCtx para a verificação de assinaturas digitais [SWS_CRYPT_50023],
• SignerPrivateCtx para a geração de assinaturas digitais [SWS_CRYPT_50041],
• SymmetricCipherCtx para cifragens simétricas [SWS_CRYPT_50046],
• HashFunctionCtx para cálculos de valor de hash [SWS_CRYPT_50058],
• DecryptorPrivateCtx para decifragens assimétricas [SWS_CRYPT_50069],
• AuthCipherCtx para cifragens autenticadas [SWS_CRYPT_50077] e
• EncryptorPublicCtx para cifragens assimétricas [SWS_CRYPT_50089].

Interpretação: Com o cancelamento da operação não concluída, o contexto deverá ser revertido para um estado limpo, que permite uma reinicialização posterior via Start(). Pergunta Q-a8fa5cb85c3dab50 (aberta)

usar

O método puramente virtual Compare da classe ara::crypto::cryp::MessageAuthnCodeCtx serve para comparar o tamanho e o conteúdo de um Message Authentication Code (MAC) calculado com um digest esperado [SWS_CRYPT_50133]. O digest de MAC esperado é passado como parâmetro através de ReadOnlyMemRegion expected. A função retorna um ara::core::Result<bool> que contém true se o valor MAC calculado corresponder exatamente ao valor esperado, e false caso contrário [SWS_CRYPT_50133].

Tratamento de erros

Em caso de erro, é retornado um código de erro no objeto de resultado, aplicando-se uma semântica de rollback [SWS_CRYPT_50133]:

• ara::crypto::CryptoErrc::kProcessingNotFinished: É reportado se o cálculo do digest não tiver sido previamente concluído através da chamada do método Finish() [SWS_CRYPT_50133].
• ara::crypto::CryptoErrc::kInvalidInputSize: Ocorre se o tamanho de buffer passado do digest de MAC esperado não for suportado pelo contexto [SWS_CRYPT_50133].

Simultaneidade e restrições

O método está declarado como const e noexcept e, de acordo com a especificação, é seguro para threads (thread-safe) e seguro para exceções (exception safe) [SWS_CRYPT_50133]. Uma pré-condição essencial é o cálculo do digest previamente concluído com sucesso através de Finish() [SWS_CRYPT_50133].

Interação

Em contraste com Compare, que valida a correspondência completa de todo o digest MAC [SWS_CRYPT_50133], CompareSubspan compara no mesmo contexto apenas os bits mais significativos (most significant bits) com o valor esperado [SWS_CRYPT_50028]. Para funções hash sem chave, existe uma função Compare com o mesmo nome em ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50154].

O método síncrono CompareSubspan da classe ara::crypto::cryp::MessageAuthnCodeCtx compara os bits mais significativos (Most Significant Bits) de um valor MAC calculado com uma referência predefinida [SWS_CRYPT_50028]. O valor de comparação esperado é passado por meio do parâmetro expected como ReadOnlyMemRegion [SWS_CRYPT_50028]. O resultado é retornado como ara::core::Result<bool> e contém true em caso de identidade dos bits mais significativos, bem como false em caso de divergências [SWS_CRYPT_50028].

Tratamento de erros e condições de fluxo

Para uma comparação válida, o cálculo do valor de verificação deve estar concluído. Se não houver uma chamada prévia do método Finish(), a chamada falha com o código de erro ara::crypto::CryptoErrc::kProcessingNotFinished [SWS_CRYPT_50028]. Se o tamanho do buffer do parâmetro passado expected for inválido para o procedimento utilizado, o método reporta ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50028]. Ambos os tipos de erro garantem semântica de rollback [SWS_CRYPT_50028].

Concorrência e contexto de execução

A operação é especificada como noexcept (exception-safe) e classificada como thread-safe [SWS_CRYPT_50028]. Interpretação: a segurança de threads declarada provavelmente se refere ao estado após a execução de Finish(), permitindo que múltiplas threads verifiquem o mesmo digest calculado em paralelo. Pergunta Q-ac8b7ead6a5b508e (aberta)

O método Finish() conclui de forma definitiva o cálculo em andamento de um Message Authentication Code (MAC) dentro da interface MessageAuthnCodeCtx [SWS_CRYPT_22115]. A chamada é feita de forma síncrona, não recebe parâmetros e retorna ara::core::Result<void>, o que representa um resultado vazio no caso regular de sucesso [SWS_CRYPT_22115].

Em caso de erro, a função retorna o código de erro ara::crypto::CryptoErrc::kProcessingNotStarted caso o cálculo de MAC não tenha sido iniciado com sucesso antes da chamada; neste caso, aplica-se uma semântica de rollback [SWS_CRYPT_22115]. A operação é declarada como noexcept e, conforme a especificação, é especificada tanto como segura contra exceções (exception safe) quanto como segura para threads (thread-safe) [SWS_CRYPT_22115].

No fluxo de processamento, Finish() forma a ligação entre o processamento de dados e a avaliação: após a chamada, o digest de MAC gerado pode ser transferido para um buffer fornecido através de GetDigest() [SWS_CRYPT_22116] ou verificado diretamente contra um valor de referência com CompareSubspan() [SWS_CRYPT_50028]. Enquanto GetMaximumChunkSize() [SWS_CRYPT_50033] descreve genericamente tamanhos de buffer para Update() ou Finish(), Finish() aqui não processa dados diretamente; a menção no requisito provavelmente reflete um padrão uniforme entre todos os contextos criptográficos. Pergunta Q-79b4f4ecf3998e48 (aberta)

A função de membro síncrona Generate da classe ara::crypto::cryp::MessageAuthnCodeCtx serve, de acordo com [SWS_CRYPT_50029], para o cálculo de um Message Authentication Code (MAC) num único passo e escreve o digest calculado no buffer de saída disponibilizado.

Para a chamada, são passados os seguintes parâmetros:

• data: dados de entrada para o cálculo do MAC como ReadOnlyMemRegion.
• digest: área de memória de destino do tipo ReadWriteMemRegion, na qual o digest é escrito.
• iv: um vetor de inicialização opcional como ara::core::Optional<ReadOnlyMemRegion>.

Em caso de sucesso, a função retorna um ara::core::Result<std::size_t> que contém o tamanho do digest de MAC escrito em bytes [SWS_CRYPT_50029].

Se ocorrer um erro, é retornado um código de erro com semântica de rollback [SWS_CRYPT_50029]:

• UninitializedContext: o contexto ainda não foi inicializado pela atribuição de uma chave.
• ara::crypto::CryptoErrc::kUsageViolation: a chave utilizada não possui a flag de uso necessária kAllowMac. Interpretação: uma chave simétrica adequada presumivelmente deverá ser gerada e configurada previamente via GenerateSymmetricKey [SWS_CRYPT_20721]. Pergunta Q-d22f397bbc02487b (aberta)
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está atualmente vazio.
• ara::crypto::CryptoErrc::kUnsupported: o processamento em chamada única não é suportado ou a indicação do vetor de inicialização não cumpre os requisitos do algoritmo (IV em falta ou indicado de forma não permitida).
• ara::crypto::CryptoErrc::kInvalidInputSize: o tamanho do buffer dos dados de entrada ou do IV não é suportado.
• ara::crypto::CryptoErrc::kInsufficientCapacity: o buffer de destino digest é demasiado pequeno para o digest de MAC.
• ara::crypto::CryptoErrc::kBusyResource: um recurso de sistema necessário está ocupado.

Relativamente à concorrência, o método está especificado como thread-safe e exception safe [SWS_CRYPT_50029]. Está declarado como const noexcept e não altera o estado do contexto durante a execução.

O método GenerateSubspan da classe ara::crypto::cryp::MessageAuthnCodeCtx calcula em uma única etapa um Message Authentication Code (MAC) para os dados de entrada data e escreve o início (os bytes mais significativos, MSB) do digest calculado no buffer de saída truncatedDigest [SWS_CRYPT_50030]. Através do parâmetro opcional iv, pode ser transmitido um vetor de inicialização, se necessário [SWS_CRYPT_50030]. O retorno direto de ara::core::Result<std::size_t> provavelmente indica uma execução síncrona; em caso de sucesso, é retornado o número de bytes gravados do digest de MAC [SWS_CRYPT_50030]. Pergunta Q-167c6d44b9f39fed (aberta)

A especificação define para o caso de erro uma semântica de rollback e prevê os seguintes códigos de erro [SWS_CRYPT_50030]:

• UninitializedContext: O contexto não foi inicializado previamente através da atribuição de uma chave [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está atualmente vazio [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUsageViolation: O uso permitido da chave não inclui kAllowMac [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUnsupported: O processamento em etapa única não é suportado, ou a configuração do IV não corresponde ao contexto (IV necessário ausente ou IV inadmissível transmitido) [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho dos dados transmitidos data ou do iv não é suportado [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário está ocupado [SWS_CRYPT_50030].

Em relação ao ambiente de execução, o método é especificado como thread-safe e oferece segurança contra exceções (noexcept) [SWS_CRYPT_50030]. O pré-requisito para uma chamada sem erros é o fornecimento prévio de uma chave com a respectiva permissão no contexto [SWS_CRYPT_50030].

O método SetKey configura uma instância de ara::crypto::cryp::MessageAuthnCodeCtx para o subsequente cálculo de MAC com uma chave simétrica fornecida [SWS_CRYPT_22118]. A chamada é realizada de forma síncrona e recebe o objeto de chave como smart pointer SymmetricKey::Sptr. Como resultado, a função retorna um ara::core::Result<void>, que fica vazio em caso de sucesso ou encapsula um código de erro específico em caso de falha [SWS_CRYPT_22118].

Se a atribuição falhar, aplica-se uma semântica de rollback que preserva o estado anterior do contexto [SWS_CRYPT_22118]. Os seguintes estados de erro de ara::crypto::CryptoErrc estão especificados:

• kUnsupported: o contexto suporta exclusivamente a vinculação via KeySlot em vez de objetos de chave diretos [SWS_CRYPT_22118].
• kIncompatibleObject: o objeto de chave simétrica passado é incompatível com o contexto de destino [SWS_CRYPT_22118].
• kUsageViolation: os sinalizadores de permissão da chave não contêm o uso obrigatoriamente exigido kAllowMac [SWS_CRYPT_22118].

Em termos de segurança de execução, a interface é definida como thread-safe e exception safe (com noexcept) [SWS_CRYPT_22118]. Na interação com o gerenciamento de chaves, ela representa o equivalente direto à atribuição baseada em slots: caso uma implementação ou um caso de uso suporte o uso de slots persistidos, utiliza-se em seu lugar a sobrecarga para KeySlot::Sptr [SWS_CRYPT_50026].

usar

A função-membro virtual SetKey da interface ara::crypto::cryp::MessageAuthnCodeCtx do arquivo de cabeçalho ara/crypto/cryp/message_authn_code_ctx.h configura o contexto para o cálculo ou a verificação de um Message Authentication Code (MAC) [SWS_CRYPT_50026]. Como parâmetro, o método síncrono recebe um smart pointer keySlot do tipo KeySlot::Sptr, que disponibiliza uma chave simétrica, e retorna um ara::core::Result<void> [SWS_CRYPT_50026]. A vinculação da chave é semanticamente postergada: a chave armazenada no slot só é utilizada no momento em que o cálculo do MAC é efetivamente iniciado [SWS_CRYPT_50026]. Interpretação: atualizações posteriores do conteúdo do slot até o início do cálculo devem, assim, permanecer efetivas. Pergunta Q-d1886811d8af71e3 (aberta)

Simultaneidade e segurança de execução

A interface está definida como noexcept, assegura segurança contra exceções (exception safe) e está explicitamente especificada para chamada concorrente (thread-safe) [SWS_CRYPT_50026].

Tratamento de erros e interação

Em caso de erro, o método garante uma semântica estrita de rollback, de modo que o estado anterior do contexto seja totalmente preservado [SWS_CRYPT_50026]. Os seguintes códigos de erro podem ocorrer no objeto de resultado:

• ara::crypto::CryptoErrc::kIncompatibleObject: O KeySlot transmitido é incompatível com este contexto de chave simétrica [SWS_CRYPT_50026].
• ara::crypto::CryptoErrc::kUnsupported: A implementação concreta do contexto não suporta a definição via KeySlot [SWS_CRYPT_50026]. Neste caso, deve-se utilizar como alternativa a sobrecarga SetKey(SymmetricKey::Sptr) para a transferência direta de uma chave [SWS_CRYPT_22118].

O método Start de ara::crypto::cryp::MessageAuthnCodeCtx inicializa o contexto para um novo cálculo de MAC, definindo um vetor de inicialização ou valor de nonce através do parâmetro iv ([SWS_CRYPT_22110]). Isto é utilizado, por exemplo, em algoritmos como o GMAC ([SWS_CRYPT_22110]). Para cálculos sem vetor de inicialização explícito, está disponível alternativamente a sobrecarga sem parâmetros Start() ([SWS_CRYPT_22111]).

Uso e concorrência

A chamada é síncrona e está especificada como thread-safe e exception safe ([SWS_CRYPT_22110]). Após uma chamada bem-sucedida, partes da mensagem podem ser passadas sucessivamente para o contexto por meio de Update ([SWS_CRYPT_22113]). Uma operação de streaming em andamento e ainda não concluída pode ser cancelada, se necessário, através de Cancel ([SWS_CRYPT_50027]).

Tratamento de erros

O método retorna um ara::core::Result<void> que possui semântica de rollback em caso de erro ([SWS_CRYPT_22110]). Os estados de erro possíveis são:

• UninitializedContext: Nenhuma chave foi atribuída previamente ao contexto ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está vazio ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUsageViolation: As permissões da chave não contêm kAllowMac ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho de IV fornecido não é suportado ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUnsupported: O streaming ou a definição de um IV não é suportado pelo algoritmo ou contexto ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kBusyResource: Um recurso necessário está ocupado ([SWS_CRYPT_22110]).

usar

O método Start() inicializa uma instância de ara::crypto::cryp::MessageAuthnCodeCtx para um novo cálculo de MAC [SWS_CRYPT_22111]. A chamada não recebe parâmetros e retorna um ara::core::Result<void> [SWS_CRYPT_22111]. A execução deve ocorrer de forma síncrona, visto que um objeto de resultado é fornecido diretamente. Pergunta Q-1e6e36f4ed1176d3 (aberta)

Tratamento de erros e simultaneidade

Se ocorrer um erro na inicialização, a semântica de rollback entra em ação e um dos seguintes códigos de erro é retornado [SWS_CRYPT_22111]:

• UninitializedContext: nenhuma chave foi atribuída previamente ao contexto [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUnsupported: o contexto não suporta streaming ou o algoritmo exige obrigatoriamente um vetor de inicialização (IV) [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário está ocupado [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kEmptyKeySlot: um KeySlot configurado está vazio [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUsageViolation: a chave não permite cálculo de MAC sem kAllowMac definido [SWS_CRYPT_22111].

A função está especificada como segura para threads e segura contra exceções (exception safe) [SWS_CRYPT_22111].

Interação no fluxo de streaming

Se o algoritmo exigir um IV (por exemplo, GMAC), deve-se usar a sobrecarga Start(ReadOnlyMemRegion iv) em seu lugar [SWS_CRYPT_22110]. Após uma chamada bem-sucedida, dados de mensagem podem ser passados gradualmente via Update() [SWS_CRYPT_22113]. Uma operação de streaming ainda não concluída pode ser descartada através de Cancel() [SWS_CRYPT_50027].

usar

O método síncrono Update do contexto ara::crypto::cryp::MessageAuthnCodeCtx serve para adicionar um fragmento adicional da mensagem de entrada ao cálculo em andamento de um Message Authentication Code (MAC) [SWS_CRYPT_22113]. A seção de dados a ser processada é passada através do parâmetro data na forma de uma ReadOnlyMemRegion. Como valor de retorno, a função fornece um ara::core::Result<void> que confirma o passo intermediário bem-sucedido ou, em caso de erro, esclarece a causa do erro [SWS_CRYPT_22113].

Tratamento de erros e simultaneidade

Em caso de erro, uma semântica de rollback é garantida, de modo que o estado de cálculo anterior permanece inalterado [SWS_CRYPT_22113]. Possíveis causas de erro são:

• ara::crypto::CryptoErrc::kProcessingNotStarted: o cálculo não foi iniciado previamente pela chamada do método Start() [SWS_CRYPT_22113].
• ara::crypto::CryptoErrc::kInvalidInputSize: o tamanho do bloco de dados passado não é suportado pelo contexto [SWS_CRYPT_22113].

O método está declarado como noexcept e especificado como seguro para threads e seguro contra exceções (exception safe) [SWS_CRYPT_22113].

Interação

Para evitar erros de buffer com ara::crypto::CryptoErrc::kInvalidInputSize, o tamanho máximo de entrada permitido para chamadas individuais pode ser consultado previamente por meio do método GetMaximumChunkSize() [SWS_CRYPT_50033]. Após o processamento sucessivo de todas as partes da mensagem, a interpretação sugere que o cálculo da tag de MAC seja tipicamente finalizado através do método Finish() [SWS_CRYPT_50033]. Pergunta Q-7f8eaf8ebbf30d55 (aberta)

usar

O método Verify em ara::crypto::cryp::MessageAuthnCodeCtx ([SWS_CRYPT_50031]) serve para o cálculo síncrono de um digest de MAC através do buffer de entrada data e para a comparação direta com o valor esperado expected. Opcionalmente, pode ser passado um vetor de inicialização através de iv. Como resultado, a função fornece um ara::core::Result<bool>, o qual contém true quando o MAC calculado coincide com a sequência de bytes esperada; caso contrário, false.

Tratamento de erros

Se a verificação falhar por motivos sistémicos ou criptográficos, o método fornece um ara::core::Result com um código de erro correspondente ([SWS_CRYPT_50031]):

• UninitializedContext: se o contexto não tiver sido inicializado previamente pela atribuição de uma chave.
• ara::crypto::CryptoErrc::kEmptyKeySlot: se o KeySlot configurado estiver vazio.
• ara::crypto::CryptoErrc::kUsageViolation: se a utilização permitida da chave não abranger kAllowMac.
• ara::crypto::CryptoErrc::kInvalidInputSize: se o tamanho do buffer de data, expected ou iv for inadmissível.
• ara::crypto::CryptoErrc::kUnsupported: se a execução em chamada única não for suportada ou a disponibilização do iv não corresponder aos requisitos do algoritmo.
• ara::crypto::CryptoErrc::kBusyResource: em caso de conflitos de recursos.

Concorrência e interação

O método está especificado como thread-safe e exception safe ([SWS_CRYPT_50031]). Em caso de erro, aplica-se uma semântica de rollback. Ao contrário das verificações de assinatura assimétrica em ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_24112], [SWS_CRYPT_50024]), o Verify opera em contextos de MAC simétrico. O tamanho máximo de buffer processável numa única chamada presumivelmente deverá estar limitado pela implementação do contexto — de forma análoga à consulta de buffer em verificadores de assinatura ([SWS_CRYPT_50025]). Pergunta Q-51e7427e4e082881 (aberta)

O método VerifySubspan da classe ara::crypto::cryp::MessageAuthnCodeCtx serve para o cálculo síncrono de um digest de MAC e a comparação subsequente de seus bits mais significativos com uma sequência de bytes esperada [SWS_CRYPT_50032]. Ele processa dados de entrada através de data, os bits mais significativos esperados através de expected e um vetor de inicialização opcional através de iv [SWS_CRYPT_50032]. O resultado é retornado como ara::core::Result<bool> e sinaliza true em caso de correspondência bem-sucedida; caso contrário, false [SWS_CRYPT_50032].

A interface é especificada como noexcept, é exception safe bem como thread-safe e aplica semântica de rollback em caso de falha [SWS_CRYPT_50032]. Chamadas com falha fornecem códigos de erro específicos no valor de retorno [SWS_CRYPT_50032]:

• UninitializedContext: O contexto não foi previamente inicializado pela atribuição de uma chave [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUsageViolation: o uso permitido da chave não inclui kAllowMac [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está atualmente vazio [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho dos dados transmitidos, do valor de verificação esperado ou do IV não é suportado [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUnsupported: A operação single-call não é suportada ou o fornecimento do IV contradiz os requisitos do contexto [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário está ocupado [SWS_CRYPT_50032].