classe ara::crypto::cryp::AuthCipherCtx

usar

O método Cancel() da interface ara::crypto::cryp::AuthCipherCtx cancela uma operação de streaming ativa que foi previamente iniciada por meio de Start() e ainda não concluída [SWS_CRYPT_50077]. A função é disponibilizada através do cabeçalho ara/crypto/cryp/auth_cipher_ctx.h e opera de forma síncrona sem parâmetros de entrada [SWS_CRYPT_50077]. Ela retorna um ara::core::Result<void>, que está vazio em caso de sucesso.

Tratamento de erros e condições de contorno

Um cancelamento pressupõe que o processamento de dados tenha sido de fato iniciado previamente por Start(). Se a operação de streaming não foi iniciada, a chamada falha e retorna o código de erro ara::crypto::CryptoErrc::kProcessingNotStarted com semântica de rollback [SWS_CRYPT_50077].

simultaneidade

A operação está declarada como noexcept e, de acordo com a especificação, é classificada tanto como thread-safe quanto como exception safe [SWS_CRYPT_50077].

Interação

O padrão de cancelamento implementado por Cancel() é padronizado no módulo crypt. Uma semântica de interface idêntica e o mesmo código de erro ara::crypto::CryptoErrc::kProcessingNotStarted estão definidos para contextos de streaming correspondentes:

• ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]
• ara::crypto::cryp::MessageAuthnCodeCtx [SWS_CRYPT_50027]
• ara::crypto::cryp::SignerPrivateCtx [SWS_CRYPT_50041]
• ara::crypto::cryp::SymmetricCipherCtx [SWS_CRYPT_50046]
• ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50058]
• ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50069]
• ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50089]

O método síncrono EncryptSingleCallWithOutputIv da interface ara::crypto::cryp::AuthCipherCtx executa uma cifragem autenticada num único passo e gera autonomamente um vetor de inicialização [SWS_CRYPT_50080]. Processa dados de entrada de dataIn bem como dados adicionais opcionais authenticatedData e escreve o criptograma no buffer dataOut. O vetor de inicialização gerado é armazenado no buffer ivOut, enquanto a tag de autenticação é emitida através de tag [SWS_CRYPT_50080]. O tamanho do buffer para ivOut pode ser determinado previamente através do método GetOutputIvSize [SWS_CRYPT_50165]. Apesar da componente do nome Encrypt, o método provavelmente também pode ser utilizado para a desencriptação, uma vez que a especificação de erros indica explicitamente o comportamento para transformDirection == kDecrypt [SWS_CRYPT_50080]. Pergunta Q-66618567b20f99b9 (aberta)

Aplicam-se à chamada pré-condições e restrições essenciais:

• O contexto tem de ter sido previamente inicializado com sucesso com SetKey; caso contrário, é reportado kUninitializedContext [SWS_CRYPT_50080].
• A chave no Key-Slot configurado tem de ser compatível e apresentar a autorização adequada (por exemplo, kAllowDataEncrypt), caso contrário será retornado kUsageViolation ou kIncompatibleObject [SWS_CRYPT_50080].
• Se os buffers de saída dataOut ou ivOut não forem suficientes, a chamada falha com kInsufficientCapacity [SWS_CRYPT_50080].
• Se o contexto não suportar o processamento de passo único ou exigir a especificação externa de um IV, é retornado kUnsupported [SWS_CRYPT_50080].

A operação está especificada como thread-safe e segura para exceções, e garante semântica de rollback em caso de erro [SWS_CRYPT_50080]. Para cifragens simétricas puras sem processamento de tag, existe uma contraparte separada em SymmetricCipherCtx [SWS_CRYPT_50049].

Utilização e semântica

O método Finish conclui sincronicamente a encriptação ou desencriptação dentro de um ara::crypto::cryp::AuthCipherCtx e calcula ou verifica a tag de autenticação, sem retornar um vetor de inicialização (IV) [SWS_CRYPT_50075]. O chamador passa os dados restantes através do buffer in e do buffer de destino out. Através do buffer tag, a tag calculada é emitida na encriptação, enquanto na desencriptação é passada a tag a verificar [SWS_CRYPT_50075]. O valor de retorno ara::core::Result<std::size_t> quantifica os bytes efetivamente escritos em out, que podem ser menores do que a capacidade do buffer de saída [SWS_CRYPT_50075].

Sequência e interação

Antes da chamada, o processamento de dados tem de ter sido obrigatoriamente iniciado por Start() [SWS_CRYPT_50075]. Se blocos de dados tiverem sido previamente processados através de UpdateConfidentialData, uma aplicação só pode utilizar o texto em claro resultante na desencriptação após autenticação bem-sucedida por Finish [SWS_CRYPT_50074]. O tamanho de buffer máximo necessário para out pode ser determinado previamente através de GetRequiredOutputBufferSize, especificando isFinal = true [SWS_CRYPT_50081].

Tratamento de erros e simultaneidade

O método está especificado como seguro para threads e seguro para exceções [SWS_CRYPT_50075]. Os erros são reportados através de ara::core::Result com semântica de rollback [SWS_CRYPT_50075]:

• ProcessingNotStarted: O processamento de dados não foi iniciado previamente com Start() [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kInsufficientCapacity: o buffer de saída out é demasiado pequeno [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do buffer de in ou tag é inválido [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kAuthTagNotValid: A autenticidade dos dados não pode ser confirmada na desencriptação [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kUnsupported: O processamento em streaming não é suportado pelo contexto [SWS_CRYPT_50075].

usar

O método FinishEncrypt conclui síncronamente uma operação de encriptação autenticada em ara::crypto::cryp::AuthCipherCtx, calcula a tag de autenticação e devolve o vetor de inicialização gerado pelo contexto através de ivOut [SWS_CRYPT_50076]. A chamada está especificada como thread-safe bem como segura contra exceções (exception safe) [SWS_CRYPT_50076]. Como resultado, a função retorna um ara::core::Result<std::size_t> com o número de bytes efetivamente gravados no buffer de saída out, podendo o tamanho de saída ser inferior à capacidade do buffer [SWS_CRYPT_50076]. Interpretação: Embora o nome aponte para encriptação, a especificação do parâmetro tag bem como o código de erro ara::crypto::CryptoErrc::kAuthTagNotValid indicam que a assinatura no contexto também deverá poder ser utilizada simetricamente para operações de desencriptação. Pergunta Q-6b924f12c32e0f33 (aberta)

Interação e dimensionamento de buffer

O processamento de dados tem de ter sido obrigatoriamente iniciado previamente com Start(); caso contrário, a função reporta o erro ProcessingNotStarted [SWS_CRYPT_50076]. Para o dimensionamento dos buffers, deve ser observada a interação com as seguintes funções de contexto:

• A capacidade máxima necessária para out pode ser calculada previamente através de [SWS_CRYPT_50081] com o parâmetro isFinal = true, a fim de evitar o erro ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50076].
• O tamanho de buffer mínimo e máximo para os dados de entrada in é determinado por [SWS_CRYPT_50162] bem como [SWS_CRYPT_50082].
• O tamanho de buffer necessário para receber o vetor de inicialização gerado em ivOut pode ser consultado através de [SWS_CRYPT_50165].

Tratamento de erros e condições de contorno

Em caso de erro, todos os retornos possuem uma semântica de rollback definida [SWS_CRYPT_50076]. No caso de tamanhos de buffer inválidos para dados de entrada ou para a tag de autenticação, é retornado ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50076]. Além disso, a função fornece ara::crypto::CryptoErrc::kUnsupported caso o processamento de stream não seja suportado, nenhum IV seja utilizado ou o IV já tenha sido predefinido pela aplicação no arranque [SWS_CRYPT_50076].

O método síncrono e definido como thread-safe ProcessSingleCall de ara::crypto::cryp::AuthCipherCtx executa a cifragem ou decifragem de dados úteis e o cálculo ou verificação simultâneo da tag de autenticação em uma única operação sem vetor de inicialização (IV) [SWS_CRYPT_50078]. Por meio do buffer opcional authenticatedData, podem ser disponibilizados dados autenticados adicionais [SWS_CRYPT_50078]. O buffer tag serve como entrada para verificação na decifragem e como saída para armazenamento da tag de autenticação gerada na cifragem [SWS_CRYPT_50078]. Em caso de processamento bem-sucedido, ara::core::Result<std::size_t> retorna o número efetivo de bytes gravados em dataOut, que pode ser menor que a capacidade do buffer de destino [SWS_CRYPT_50078].

Antes da chamada, o contexto criptográfico deve ter sido inicializado por meio de uma chamada bem-sucedida de SetKey; caso contrário, a função falha com ara::crypto::CryptoErrc::kUninitializedContext [SWS_CRYPT_50078]. Além disso, a chave utilizada deve estar liberada para a direção de transformação solicitada (kAllowDataEncrypt ou kAllowDataDecrypt), pois, caso contrário, ara::crypto::CryptoErrc::kUsageViolation é reportado [SWS_CRYPT_50078]. Se o processamento em etapa única não for suportado ou se o contexto exigir um IV, a função retorna ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_50078]. Se a autenticação falhar na decifragem, ara::crypto::CryptoErrc::kAuthTagNotValid é disparado [SWS_CRYPT_50078]. Erros no slot de chave associado são sinalizados via EmptyKeySlot, ara::crypto::CryptoErrc::kBusyResource ou ara::crypto::CryptoErrc::kIncompatibleObject [SWS_CRYPT_50078].

Para o gerenciamento de buffers, o tamanho de saída máximo necessário para dataOut pode ser calculado previamente via GetRequiredOutputBufferSize com a flag isFinal = true definida [SWS_CRYPT_50081]; um buffer de saída pequeno demais resulta em ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50078]. Adicionalmente, o tamanho de dataIn deve estar em conformidade com os limites de GetMinimumChunkSize [SWS_CRYPT_50162] e GetMaximumChunkSize [SWS_CRYPT_50082] para evitar ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50078].

O método [SWS_CRYPT_50079] da classe ara::crypto::cryp::AuthCipherCtx executa um processamento síncrono de passo único (single-call) para encriptação ou desencriptação de dados, com cálculo ou verificação simultânea da tag de autenticação.

Na chamada, os dados de entrada são passados através de dataIn e a direção através de transformDirection. O vetor de inicialização é passado através de iv, e dados de autenticação opcionais podem ser fornecidos através de authenticatedData [SWS_CRYPT_50079]. O buffer tag serve, no caso de encriptação, como saída para a tag calculada e, no caso de desencriptação, como entrada para a verificação [SWS_CRYPT_50079]. Em caso de sucesso, o valor de retorno ara::core::Result<std::size_t> fornece o número de bytes escritos em dataOut, que pode ser menor do que a capacidade do buffer [SWS_CRYPT_50079].

Em caso de erro, todos os códigos de erro possuem semântica de rollback [SWS_CRYPT_50079]:

• ara::crypto::CryptoErrc::kUninitializedContext: Nenhuma chave foi previamente configurada via SetKey [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kUsageViolation: A chave não possui a permissão necessária kAllowDataEncrypt ou kAllowDataDecrypt [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kEmptyKeySlot, ara::crypto::CryptoErrc::kBusyResource ou ara::crypto::CryptoErrc::kIncompatibleObject: Um KeySlot configurado está vazio, ocupado ou não contém um SymmetricKey compatível [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kInvalidInputSize ou ara::crypto::CryptoErrc::kInsufficientCapacity: Os buffers de entrada, tag ou IV estão dimensionados de forma inválida ou dataOut oferece capacidade insuficiente [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kAuthTagNotValid: Na desencriptação, a autenticação falha [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kUnsupported: O processamento single-shot não é suportado pelo contexto ou o contexto requer a definição ou emissão de um IV [SWS_CRYPT_50079].

A operação está definida como thread-safe e exception safe [SWS_CRYPT_50079]. Os comprimentos permitidos para iv podem ser consultados dinamicamente através de GetMinimumInputIvSize [SWS_CRYPT_50163] e GetMaximumInputIvSize [SWS_CRYPT_50164]. Em comparação com a cifra de bloco pura em SymmetricCipherCtx [SWS_CRYPT_50048], esta interface combina transformação criptográfica e verificação de integridade numa única chamada.

O método SetKey configura a instância de ara::crypto::cryp::AuthCipherCtx para o uso de uma chave simétrica passada [SWS_CRYPT_23911]. Como parâmetro, é passado um shared pointer key (do tipo SymmetricKey::Sptr), que é utilizado para a criptografia ou descriptografia autenticada [SWS_CRYPT_23911]. A chamada ocorre de forma síncrona, está declarada como noexcept e retorna um ara::core::Result<void> [SWS_CRYPT_23911].

Em caso de erro, o resultado é revertido com semântica de rollback e fornece códigos de erro específicos [SWS_CRYPT_23911]:

• ara::crypto::CryptoErrc::kUnsupported: caso o contexto suporte exclusivamente a configuração por meio de um KeySlot [SWS_CRYPT_23911].
• ara::crypto::CryptoErrc::kIncompatibleObject: quando o tipo de chave passado não for compatível com o contexto atual [SWS_CRYPT_23911].
• ara::crypto::CryptoErrc::kUsageViolation: se as flags de uso permitidas da chave não contiverem kAllowDataEncrypt para cifragem ou kAllowDataDecrypt para decifragem [SWS_CRYPT_23911].

De acordo com a especificação, a interface é classificada como segura para threads (thread-safe) e segura contra exceções (exception safe) [SWS_CRYPT_23911]. Na interação com o contexto do módulo, a chave presumivelmente deve ser definida via Start [SWS_CRYPT_24715] antes da inicialização de uma nova transformação. Pergunta Q-11f7daa370f5d438 (aberta)

A função SetKey na interface ara::crypto::cryp::AuthCipherCtx configura o contexto para operações criptográficas de forma a utilizar a chave simétrica armazenada num key slot fornecido, assim que a encriptação ou desencriptação autenticada for executada [SWS_CRYPT_50072].

Utilização: A chamada síncrona é efetuada através da interface de ara/crypto/cryp/auth_cipher_ctx.h. Como parâmetro keySlot é passada uma instância de KeySlot::Sptr, que encapsula uma chave simétrica [SWS_CRYPT_50072]. A função retorna um ara::core::Result<void>, que confirma o sucesso ou contém um código de erro [SWS_CRYPT_50072].

Tratamento de erros: Caso a implementação concreta do contexto suporte exclusivamente a configuração direta através de um objeto SymmetricKey e não disponibilize a definição via KeySlot, a chamada falha. Neste caso, é retornado o erro ara::crypto::CryptoErrc::kUnsupported com semântica de rollback [SWS_CRYPT_50072].

Concorrência e restrições: A função está especificada como thread-safe e exception safe [SWS_CRYPT_50072]. Ela pode ser chamada concorrentemente e assegura que, em situações de exceção, não permaneça nenhum estado inconsistente.

Interação: Como alternativa funcional, está disponível a sobrecarga SetKey com um SymmetricKey::Sptr direto [SWS_CRYPT_23911]. Após a vinculação bem-sucedida da chave, o contexto é inicializado através de Start com a direção da operação bem como com o vetor de inicialização [SWS_CRYPT_24715]. Assinaturas análogas com KeySlot::Sptr existem adicionalmente em MessageAuthnCodeCtx [SWS_CRYPT_50026] e SymmetricKeyWrapperCtx [SWS_CRYPT_50034].

O método Start inicializa o contexto ara::crypto::cryp::AuthCipherCtx para uma nova cifragem ou decifragem e define o vetor de inicialização (IV) ou valor nonce a ser utilizado [SWS_CRYPT_24715]. Por meio do parâmetro transformDirection, a direção da transformação é definida, enquanto iv passa o vetor como ReadOnlyMemRegion [SWS_CRYPT_24715]. O tamanho de IV permitido pode ser determinado via GetMinimumInputIvSize() bem como GetMaximumInputIvSize(); em caso de comprimento divergente, a função reporta o erro ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_24715].

Antes da chamada, SetKey deve ter sido executado com sucesso; caso contrário, ara::crypto::CryptoErrc::kUninitializedContext é retornado [SWS_CRYPT_24715]. Um KeySlot configurado não pode estar vazio (EmptyKeySlot) nem ocupado (ara::crypto::CryptoErrc::kBusyResource) [SWS_CRYPT_24715]. Além disso, a chave armazenada deve ser um SymmetricKey adequado (caso contrário, ara::crypto::CryptoErrc::kIncompatibleObject) e estar autorizada para a direção desejada (kAllowDataEncrypt ou kAllowDataDecrypt, caso contrário, ara::crypto::CryptoErrc::kUsageViolation) [SWS_CRYPT_24715]. Se faltar o suporte para processamento contínuo (streaming) ou para a definição de um IV na direção selecionada, a chamada falha com ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_24715]. Todos os erros apresentam semântica de rollback [SWS_CRYPT_24715].

A operação é declarada como thread-safe bem como exception-safe (noexcept) [SWS_CRYPT_24715]. Na interação de fluxos criptográficos, após uma inicialização bem-sucedida, deve seguir tipicamente a passagem de dados autenticados adicionais via UpdateAuthenticatedData [SWS_CRYPT_20313]. Pergunta Q-e023e27f1cd24507 (aberta)

usar

O método puramente virtual Start da classe ara::crypto::cryp::AuthCipherCtx inicializa o contexto de forma síncrona para uma encriptação ou desencriptação iminente [SWS_CRYPT_50073]. Através do parâmetro transformDirection, indica-se se o contexto é preparado para encriptação ou desencriptação. Esta sobrecarga sem vetor de inicialização (IV) só pode ser utilizada se o contexto criptográfico não pressupuser um IV na direção de transformação selecionada ou se o determinar por si próprio [SWS_CRYPT_50073]. O valor de retorno é um ara::core::Result<void> vazio em caso de sucesso ou um código de erro correspondente.

Tratamento de erros e pré-requisitos

Antes da chamada, o contexto tem de ter sido configurado com sucesso através de SetKey com uma chave; caso contrário, a função falha com ara::crypto::CryptoErrc::kUninitializedContext [SWS_CRYPT_50073]. Além disso, ocorrem em caso de erro os seguintes valores de retorno:

• ara::crypto::CryptoErrc::kUnsupported, se o processamento de stream não for suportado pelo contexto ou se o contexto exigir obrigatoriamente a indicação explícita de um IV na direção de transformação selecionada [SWS_CRYPT_50073].
• ara::crypto::CryptoErrc::kUsageViolation, se a utilização permitida da chave no KeySlot configurado no momento da chamada não incluir a permissão necessária kAllowDataEncrypt para encriptação ou kAllowDataDecrypt para desencriptação [SWS_CRYPT_50073].
• EmptyKeySlot ou ara::crypto::CryptoErrc::kBusyResource, caso um KeySlot configurado esteja atualmente vazio ou bloqueado [SWS_CRYPT_50073].
• ara::crypto::CryptoErrc::kIncompatibleObject, se o KeySlot configurado não contiver nenhum SymmetricKey ou se este tipo de chave não for suportado pelo contexto [SWS_CRYPT_50073].

Se ocorrer um erro, aplica-se a semântica de rollback especificada (rollback_semantics) [SWS_CRYPT_50073].

Concorrência e interação

A função está declarada com noexcept=0, assegura segurança contra exceções e foi concebida para ser thread-safe [SWS_CRYPT_50073]. Se o algoritmo exigir o fornecimento externo de um vetor de inicialização, deve ser utilizada, em alternativa, a sobrecarga Start(CryptoTransform, ReadOnlyMemRegion) [SWS_CRYPT_24715]. Após a inicialização bem-sucedida, dados adicionais autenticados podem ser integrados no cálculo da tag de autenticação através de UpdateAuthenticatedData [SWS_CRYPT_20313].

O método UpdateAuthenticatedData da interface ara::crypto::cryp::AuthCipherCtx serve para atualizar passo a passo o cálculo da tag de autenticação com mais um fragmento de dados autenticados adicionais (Additional Authenticated Data) [SWS_CRYPT_20313]. O buffer correspondente é passado como ReadOnlyMemRegion por meio do parâmetro authenticatedData [SWS_CRYPT_20313].

Em relação ao contexto de chamada e à concorrência, a operação está definida como thread-safe e exception safe [SWS_CRYPT_20313]. Para a chamada aplicam-se condições estritas de ordenação:

• A transformação deve ter sido iniciada previamente por meio do método Start(); caso contrário, ara::crypto::CryptoErrc::kProcessingNotStarted é reportado [SWS_CRYPT_20313].
• A função não pode mais ser chamada se UpdateConfidentialData já tiver sido executado; em caso de não cumprimento, é retornado o erro ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_20313].

Como valor de retorno, a função fornece um ara::core::Result<void>, que está vazio em caso de sucesso ou encapsula um código de erro ocorrido [SWS_CRYPT_20313]. Todos os erros apresentam semântica de rollback [SWS_CRYPT_20313]:

• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do buffer de entrada passado é inválido [SWS_CRYPT_20313].
• ara::crypto::CryptoErrc::kUnsupported: O processamento de stream não é suportado pelo contexto atual [SWS_CRYPT_20313].

O método UpdateConfidentialData da classe ara::crypto::cryp::AuthCipherCtx serve para a cifragem ou decifragem passo a passo de dados úteis confidenciais no âmbito de um contexto de cifragem autenticada [SWS_CRYPT_50074]. São passados a ele o buffer de entrada in (tipo ReadOnlyMemRegion) com uma parte do texto em claro ou texto cifrado, bem como o buffer de saída out (tipo ReadWriteMemRegion) [SWS_CRYPT_50074]. Como valor de retorno síncrono, a função fornece um ara::core::Result<std::size_t>, que, em caso de sucesso, contém o número de bytes efetivamente gravados; este pode ser menor que a capacidade de out [SWS_CRYPT_50074].

Relativamente ao fluxo e à concorrência, aplicam-se as seguintes condições:

• Ordem de execução e integridade: Antes do processamento, a operação deve ter sido iniciada via Start() [SWS_CRYPT_50074]. Se o método for utilizado para decifragem, o texto em claro é emitido sem verificação prévia de autenticidade; a aplicação não deve, sob hipótese alguma, utilizar esses dados antes da verificação final por meio de Finish() [SWS_CRYPT_50074]. Dados autenticados adicionais podem ser incluídos em paralelo no cálculo da tag via UpdateAuthenticatedData [SWS_CRYPT_20313].
• Segurança de threads e de exceções: A operação está declarada como thread-safe bem como exception-safe e não lança exceções (noexcept) [SWS_CRYPT_50074].

Se o processamento falhar, aplica-se a semântica de rollback com o retorno de um código de erro correspondente em ara::core::Result [SWS_CRYPT_50074]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: O processamento ainda não foi iniciado via Start() [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kInsufficientCapacity: O buffer de saída out está subdimensionado [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do buffer in é inválido [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kUnsupported: O processamento de fluxo contínuo (stream) não é suportado pelo contexto [SWS_CRYPT_50074].