classe ara::crypto::cryp::DecryptorPrivateCtx

O método Cancel da classe ara::crypto::cryp::DecryptorPrivateCtx, definido em ara/crypto/cryp/decryptor_private_ctx.h, cancela uma operação de streaming em andamento que foi previamente iniciada por meio de Start() e ainda não concluída [SWS_CRYPT_50069]. A chamada não recebe parâmetros de entrada e fornece como valor de retorno um ara::core::Result<void> [SWS_CRYPT_50069]. Se o cancelamento do processamento de streaming tiver sido bem-sucedido, o objeto conterá um resultado vazio; caso contrário, transportará um erro ocorrido [SWS_CRYPT_50069]. A interface puramente virtual é declarada como noexcept, apresenta total segurança contra exceções e é indicada como thread-safe para acesso concorrente [SWS_CRYPT_50069].

No tratamento de erros e nas condições de fluxo, deve-se observar a ordem exata: se o processamento de dados não tiver sido previamente iniciado pela chamada do método Start(), a operação falha e retorna o código de erro específico ara::crypto::CryptoErrc::kProcessingNotStarted com semântica de rollback [SWS_CRYPT_50069]. O chamador deve, portanto, assegurar que já exista uma operação ativa antes do cancelamento, a fim de evitar esse estado de erro [SWS_CRYPT_50069].

Na interação com toda a arquitetura de módulos de crypt, Cancel segue um padrão de projeto padronizado para procedimentos de streaming com estado. A mesma assinatura, semântica de retorno e tratamento de erros são compartilhados pelos contextos criptográficos correlatos 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::AuthCipherCtx [SWS_CRYPT_50077] bem como ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50089].

O método síncrono Decrypt desencripta dados de texto cifrado num único passo ([SWS_CRYPT_50070]). O buffer de entrada in passa o texto cifrado como ReadOnlyMemRegion, enquanto o buffer de saída out do tipo ReadWriteMemRegion recebe o texto simples ([SWS_CRYPT_50070]). Em caso de desencriptação bem-sucedida, a função fornece através de ara::core::Result<std::size_t> o número efetivo de bytes gravados, o qual pode ser inferior à capacidade total de out ([SWS_CRYPT_50070]).

A interface está especificada como thread-safe bem como exception safe ([SWS_CRYPT_50070]). Antes da chamada, o contexto tem de ter sido inicializado mediante atribuição de uma chave; caso contrário, a função falha com UninitializedContext ou, no caso de um KeySlot vazio, com ara::crypto::CryptoErrc::kEmptyKeySlot ([SWS_CRYPT_50070]). A chave tem de ser compatível com o algoritmo de transformação (caso contrário, kIncompatibleObject) e incluir a permissão kAllowDataDecryption (caso contrário, kUsageViolation) ([SWS_CRYPT_50070]).

Para prevenir transbordamentos de buffer, a capacidade máxima necessária do buffer de saída pode ser consultada previamente com GetRequiredOutputBufferSize indicando isFinal = true ([SWS_CRYPT_50159]). Se a capacidade de out não for suficiente, o método aborta com ara::crypto::CryptoErrc::kInsufficientCapacity ([SWS_CRYPT_50070]). O tamanho do buffer de entrada in também tem de estar no intervalo entre GetMinimumChunkSize ([SWS_CRYPT_50160]) e GetMaximumChunkSize ([SWS_CRYPT_50071]), caso contrário é retornado ara::crypto::CryptoErrc::kInvalidInputSize ([SWS_CRYPT_50070]). Outros erros especificados com semântica de rollback são kUnsupported, kInvalidArgument bem como kBusyResource ([SWS_CRYPT_50070]).

O método Finish conclui um processo de decifragem no contexto de ara::crypto::cryp::DecryptorPrivateCtx de forma síncrona [SWS_CRYPT_50068]. Ele processa através do buffer de entrada in (ReadOnlyMemRegion) o último segmento de criptograma e escreve os dados de texto em claro resultantes no buffer de saída out (ReadWriteMemRegion) [SWS_CRYPT_50068]. O número de bytes realmente escritos é retornado como ara::core::Result<std::size_t> e pode revelar-se menor do que a capacidade total do buffer de destino out [SWS_CRYPT_50068].

Antes da chamada, o processamento de dados tem de ter sido obrigatoriamente iniciado com Start(); caso contrário, é reportado o erro CryptoErrc::kProcessingNotStarted [SWS_CRYPT_50068]. O tamanho de bloco máximo permitido para in pode ser determinado através de GetMaximumChunkSize() [SWS_CRYPT_50071]; em caso de comprimento de entrada inadequado, a chamada falha com CryptoErrc::kInvalidInputSize [SWS_CRYPT_50068]. Se out for demasiado pequeno, resulta CryptoErrc::kInsufficientCapacity, podendo o tamanho de buffer necessário ser consultado mediante GetRequiredOutputBufferSize() [SWS_CRYPT_50068]. Outros erros possíveis são CryptoErrc::kInvalidArgument em caso de dados de criptograma inválidos, bem como CryptoErrc::kUnsupported caso o processamento de stream não seja suportado no contexto [SWS_CRYPT_50068].

A operação está especificada como thread-safe e exception safe [SWS_CRYPT_50068]. Graças à semântica de rollback indicada, o estado de processamento deve permanecer inalterado em caso de erros de buffer, de modo que uma repetição deve ser possível após o aumento do buffer. Pergunta Q-e2562509449aa32c (aberta)

usar

O método SetKey configura uma instância de ara::crypto::cryp::DecryptorPrivateCtx para o uso de uma chave armazenada em um KeySlot transmitido [SWS_CRYPT_50066]. Como parâmetro, é transmitido um KeySlot::Sptr, que deve conter um PrivateKey [SWS_CRYPT_50066]. A própria chave só é consultada no momento em que a operação de descriptografia é iniciada [SWS_CRYPT_50066]. A função opera de forma síncrona e reporta o resultado através de ara::core::Result<void> [SWS_CRYPT_50066].

Tratamento de erros

Em caso de erro, um código de erro correspondente é retornado em ara::core::Result, aplicando-se uma semântica de rollback [SWS_CRYPT_50066]:

• ara::crypto::CryptoErrc::kIncompatibleObject: O KeySlot fornecido não é compatível com o contexto [SWS_CRYPT_50066].
• ara::crypto::CryptoErrc::kUnsupported: O contexto suporta apenas a definição direta de um PrivateKey e não KeySlots [SWS_CRYPT_50066].

Concorrência e interação

A interface está declarada como segura para threads (thread-safe) e segura contra exceções (exception safe) [SWS_CRYPT_50066]. Como a avaliação da chave só ocorre no início da desencriptação, uma atualização do conteúdo do slot antes desse momento de início deverá ter efeito. Pergunta Q-ec258ea8b5a1d1c2 (aberta) Enquanto outros contextos criptográficos aceitam chaves parcialmente de forma direta como instância (por exemplo SignerPrivateCtx [SWS_CRYPT_23515]), este método segue o padrão de vinculação tardia via slots de chave, tal como também é utilizado, entre outros, em VerifierPublicCtx [SWS_CRYPT_50018] e KeyDerivationFunctionCtx [SWS_CRYPT_50010].

usar

O método SetKey configura uma instância de ara::crypto::cryp::DecryptorPrivateCtx para o uso de uma chave privada concreta para decodificação de dados [SWS_CRYPT_50157]. Como parâmetro, é passada uma instância via PrivateKey::Sptr key. O valor de retorno é ara::core::Result<void>, confirmando a atribuição bem-sucedida ou retornando um erro. A chamada deve ser executada de forma síncrona (interpretação: a interface bloqueia até a aceitação da chave e não retorna um objeto Future assíncrono). Pergunta Q-b8e9b5cb4174e2b2 (aberta)

Tratamento de erros

Em caso de erro, a implementação assegura uma semântica de rollback, de modo que o estado do contexto permaneça inalterado em caso de falha [SWS_CRYPT_50157]. Os seguintes códigos de erro podem ocorrer:

• ara::crypto::CryptoErrc::kIncompatibleObject: O objeto de chave passado não é compatível com este contexto [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUsageViolation: O uso permitido da chave não abrange a decodificação de dados (kAllowData Decryption) [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUnsupported: O contexto não suporta a definição direta de um objeto de chave quando este for projetado exclusivamente para ocupação por meio de um KeySlot [SWS_CRYPT_50157].

Simultaneidade e restrições

A interface é especificada explicitamente como thread-safe e exception safe [SWS_CRYPT_50157]. Ela garante a execução segura em ambientes concorrentes e não lança exceções C++ (noexcept=0).

Interação

O procedimento para atribuição de chaves via SetKey é aplicado uniformemente em diferentes contextos criptográficos na Adaptive Platform: enquanto contextos assimétricos relacionados, como KeyAgreementPrivateCtx [SWS_CRYPT_21313], KeyDecapsulatorPrivateCtx [SWS_CRYPT_21413] e SignerPrivateCtx [SWS_CRYPT_23515], também utilizam PrivateKey::Sptr, existem variantes alternativas com KeySlot::Sptr em outros contextos, como KeyDerivationFunctionCtx [SWS_CRYPT_50010] ou VerifierPublicCtx [SWS_CRYPT_50018].

A função-membro Start da classe ara::crypto::cryp::DecryptorPrivateCtx ([SWS_CRYPT_50067]) inicializa o contexto de forma síncrona para uma nova desencriptação. A chamada não recebe parâmetros, não lança exceções (noexcept) e retorna um ara::core::Result<void>, que em caso de sucesso está vazio ([SWS_CRYPT_50067]). Para acessos concorrentes, o método está especificado como thread-safe ([SWS_CRYPT_50067]).

Antes da execução, tem de estar armazenada uma chave compatível, uma vez que o Start verifica o seu estado e permissões ([SWS_CRYPT_50067]). Se a operação falhar, aplica-se uma semântica de rollback ([SWS_CRYPT_50067]). Os códigos de erro relevantes são:

• ara::crypto::CryptoErrc::kUninitializedContext: Ainda não foi atribuída nenhuma chave ao contexto ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está atualmente vazio ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUsageViolation: As permissões da chave não permitem a desencriptação de dados ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kIncompatibleObject: O tipo de chave é incompatível com a transformação ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kBusyResource: Um recurso necessário está ocupado ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUnsupported: O processamento de stream não é suportado pelo contexto ([SWS_CRYPT_50067]).

No sistema global, o método corresponde ao ciclo de vida padronizado de contextos criptográficos adaptativos, tal como é utilizado de forma comparável na verificação de assinaturas ([SWS_CRYPT_50019]), na geração de assinaturas ([SWS_CRYPT_50037]) ou no cálculo de MAC ([SWS_CRYPT_22111]). Interpretação: Uma chamada a Start deverá ser obrigatoriamente necessária antes de passos de processamento adicionais, a fim de colocar o desencriptador num estado inicial definido. Pergunta Q-7d5a95305eb4626a (aberta)

usar

O método Update serve para decodificar um buffer de dados no contexto de ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50158]. A chamada síncrona recebe um segmento parcial de texto cifrado no parâmetro in (ReadOnlyMemRegion) e escreve os dados decodificados no buffer out (ReadWriteMemRegion) [SWS_CRYPT_50158]. Como resultado, é retornado um ara::core::Result<std::size_t> contendo a quantidade real de bytes gravados; esse valor pode ser menor do que a capacidade total de out [SWS_CRYPT_50158].

Interação e dimensionamento de buffer

Antes da execução de Update, o processamento de dados deve obrigatoriamente ter sido iniciado pela chamada de Start() [SWS_CRYPT_50158]. O tamanho mínimo necessário para out pode ser consultado via GetRequiredOutputBufferSize() [SWS_CRYPT_50158]. Além disso, o tamanho máximo de entrada processável para chamadas individuais de Update pode ser determinado via GetMaximumChunkSize() [SWS_CRYPT_50071].

Tratamento de erros e simultaneidade

A interface é especificada como segura para threads e segura para exceções [SWS_CRYPT_50158]. Todos os casos de erro possuem semântica de rollback e retornam códigos de erro específicos em ara::core::Result [SWS_CRYPT_50158]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: O processamento não foi iniciado anteriormente por meio de Start() [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInsufficientCapacity: O buffer de saída out é dimensionado pequeno demais [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do buffer de entrada passado é inválido [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kUnsupported: O processamento de stream não é suportado pelo contexto [SWS_CRYPT_50158].