classe ara::crypto::cryp::EncryptorPublicCtx

O método Cancel() cancela uma operação de streaming ativa no contexto ara::crypto::cryp::EncryptorPublicCtx, a qual foi previamente iniciada por meio de Start() e ainda não concluída [SWS_CRYPT_50089]. Ele não recebe parâmetros de entrada e retorna um ara::core::Result<void>, que fica vazio em caso de sucesso [SWS_CRYPT_50089]. Como a assinatura fornece imediatamente um Result e não um Future, o cancelamento deve ser executado de forma síncrona. Pergunta Q-cd18e56d693fe1a4 (aberta)

Tratamento de erros e simultaneidade

Se o processamento de dados não foi iniciado previamente por Start(), a operação falha com o código de erro ara::crypto::CryptoErrc::kProcessingNotStarted mantendo a semântica de rollback [SWS_CRYPT_50089]. De acordo com a especificação, a interface está declarada com noexcept, segura contra exceções (exception safe) e classificada como segura para threads (thread-safe) para o acesso concorrente [SWS_CRYPT_50089].

Interação na pilha de criptografia

O comportamento de cancelamento realizado por Cancel() segue um padrão de projeto uniforme para operações de streaming com estado no módulo de criptografia. Interfaces análogas com semântica de erro idêntica existem para:

• operações de assinatura e verificação em SignerPrivateCtx [SWS_CRYPT_50041] e VerifierPublicCtx [SWS_CRYPT_50023],
• cifragens simétricas e autenticadas em SymmetricCipherCtx [SWS_CRYPT_50046] bem como AuthCipherCtx [SWS_CRYPT_50077],
• descriptografia assimétrica em DecryptorPrivateCtx [SWS_CRYPT_50069],
• códigos de autenticação de mensagem em MessageAuthnCodeCtx [SWS_CRYPT_50027] bem como cálculos de hash em HashFunctionCtx [SWS_CRYPT_50058].

O método síncrono Encrypt serve para a encriptação de dados de texto simples numa única chamada ([SWS_CRYPT_50090]). Assume os dados de entrada a partir do buffer in (ReadOnlyMemRegion) e grava o texto cifrado no buffer de saída out (ReadWriteMemRegion) ([SWS_CRYPT_50090]). O valor de retorno ara::core::Result<std::size_t> fornece em caso de sucesso o tamanho dos dados de saída efetivamente gravados, o qual pode ser inferior à capacidade total de out ([SWS_CRYPT_50090]).

No que diz respeito à concorrência, a função está especificada como segura para threads (thread-safe) bem como segura contra exceções (exception safe) ([SWS_CRYPT_50090]).

Na interação com o contexto EncryptorPublicCtx, devem ser respeitados os seguintes limites de buffer antes da chamada:

• O tamanho de entrada tem de situar-se dentro dos limites predefinidos por [SWS_CRYPT_50178] (GetMinimumChunkSize) e [SWS_CRYPT_50091] (GetMaximumChunkSize).
• A capacidade máxima necessária do buffer de saída out pode ser calculada previamente através de GetRequiredOutputBufferSize com o parâmetro isFinal = true ([SWS_CRYPT_50177]).

Todos os casos de erro possuem semântica de rollback ([SWS_CRYPT_50090]). Aos erros definidos de ara::crypto::CryptoErrc pertencem:

• kUninitializedContext: O contexto não foi inicializado através do fornecimento de uma chave ([SWS_CRYPT_50090]).
• kEmptyKeySlot: Um KeySlot configurado está vazio ([SWS_CRYPT_50090]).
• kIncompatibleObject: O tipo de chave não é adequado à transformação ([SWS_CRYPT_50090]).
• kUsageViolation: A utilização da chave não permite encriptação de dados (kAllowDataEncryption) ([SWS_CRYPT_50090]).
• kInsufficientCapacity: O buffer out é demasiado pequeno ([SWS_CRYPT_50090]).
• kInvalidInputSize ou kInvalidArgument: O tamanho de entrada não é processável ou os dados de entrada são inválidos ([SWS_CRYPT_50090]).
• kUnsupported: A encriptação em chamada única (single-call) não é suportada ([SWS_CRYPT_50090]).
• kBusyResource: Um recurso necessário está ocupado ([SWS_CRYPT_50090]).

usar

O método Finish conclui o processo de encriptação assimétrica no contexto de ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50088]. A chamada é efetuada de forma síncrona e está especificada como noexcept, exception-safe bem como thread-safe. Como parâmetros, a função assume através de in (ReadOnlyMemRegion) o fragmento final de texto simples e grava os dados de texto cifrado resultantes no buffer de saída out (ReadWriteMemRegion). O tamanho de buffer necessário para out pode ser determinado previamente através de GetRequiredOutputBufferSize(). O valor de retorno ara::core::Result<std::size_t> fornece em caso de sucesso o número de bytes efetivamente gravados, o qual pode resultar inferior à capacidade total do buffer de saída [SWS_CRYPT_50088].

Tratamento de erros e simultaneidade

Todos os casos de erro possuem semântica de rollback, de modo que o estado do contexto permanece consistente em caso de falha [SWS_CRYPT_50088]. O método reporta os seguintes códigos de erro específicos de ara::crypto::CryptoErrc:

• kProcessingNotStarted: O processamento de dados não foi previamente iniciado através da chamada de Start().
• kInsufficientCapacity: O buffer de saída out fornecido é demasiado pequeno.
• kInvalidInputSize: O tamanho de buffer de in não pode ser processado pelo contexto.
• kInvalidArgument: Os dados de entrada passados contêm valores inválidos.
• kUnsupported: O processamento de stream não é suportado pelo contexto concreto.

Interação

A finalização conclui o fluxo de processamento criptográfico [SWS_CRYPT_50088]. Como contraparte complementar para a desencriptação funciona DecryptorPrivateCtx::Finish [SWS_CRYPT_50068], enquanto na área da cifragem simétrica SymmetricCipherCtx::Finish [SWS_CRYPT_50045] disponibiliza um padrão de fluxo comparável.

Utilização e contexto de chamada

O método puramente virtual SetKey da interface ara::crypto::cryp::EncryptorPublicCtx (ficheiro de cabeçalho ara/crypto/cryp/encryptor_public_ctx.h) serve para a atribuição de uma chave para operações de cifragem assimétricas [SWS_CRYPT_50086]. Como parâmetro, é passado um smart pointer keySlot do tipo KeySlot::Sptr, que tem de conter um PublicKey [SWS_CRYPT_50086]. A chamada ocorre de forma síncrona e sinaliza o sucesso através de um ara::core::Result<void> vazio. Essencial para a semântica é o facto de a chave armazenada no slot só ser utilizada no momento em que a encriptação é iniciada [SWS_CRYPT_50086]. (Interpretação: Como a resolução da chave só ocorre com o início efetivo da encriptação, atualizações do conteúdo do slot antes desse momento de início deverão ainda produzir efeitos.) Pergunta Q-25c5d462aafde8a1 (aberta)

Tratamento de erros

Se a configuração falhar, é retornado um código de erro com semântica de rollback no objeto Result [SWS_CRYPT_50086]:

• ara::crypto::CryptoErrc::kIncompatibleObject: É reportado se o keySlot fornecido for incompatível com este contexto [SWS_CRYPT_50086].
• ara::crypto::CryptoErrc::kUnsupported: Ocorre quando a implementação concreta do contexto suporta exclusivamente a definição direta de um PublicKey e não permite vinculação de chave através de um KeySlot [SWS_CRYPT_50086].

Concorrência e interação

A operação está declarada como noexcept, segura contra exceções (exception safe) e especificada como segura para threads (thread-safe) para utilização concorrente [SWS_CRYPT_50086].

O conceito de referenciação indireta de chaves via KeySlot encontra-se de forma comparável também noutros contextos assimétricos, tais como VerifierPublicCtx::SetKey [SWS_CRYPT_50018] e KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_50012]. Ele distingue-se de métodos que aceitam objetos de chave diretamente, como por exemplo em [SWS_CRYPT_24115] ou [SWS_CRYPT_21815].

usar

O método virtual SetKey da classe ara::crypto::cryp::EncryptorPublicCtx configura o contexto para o uso de uma chave pública fornecida [SWS_CRYPT_50175].\nPor meio do parâmetro key (do tipo PublicKey::Sptr), é passado o objeto de chave a ser utilizado para a criptografia [SWS_CRYPT_50175].\nA execução ocorre de forma síncrona e retorna um ara::core::Result<void> que, em caso de sucesso, não contém nenhum valor [SWS_CRYPT_50175].

Tratamento de erros

Se ocorrer um erro durante a configuração, um código de erro correspondente com semântica de rollback definida é reportado [SWS_CRYPT_50175]:

• ara::crypto::CryptoErrc::kUsageViolation: O uso permitido da chave não autoriza a criptografia de dados (kAllowDataEncryption) [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kIncompatibleObject: O objeto de chave passado é incompatível com este contexto de criptografia [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kUnsupported: A implementação concreta do contexto suporta exclusivamente a vinculação por meio de um KeySlot [SWS_CRYPT_50175].

Simultaneidade e restrições

A interface é definida como noexcept e especifica um comportamento que é tanto thread-safe quanto exception safe [SWS_CRYPT_50175].\nGraças à semântica de rollback, o contexto permanece em seu estado anterior em caso de erro.\nInterpretação: Uma chamada bem-sucedida deve ser um pré-requisito obrigatório para operações de criptografia subsequentes, já que o contexto não pode executar nenhuma operação sem uma chave atribuída. Pergunta Q-ab4779cac18793fa (aberta)

Interação

Este procedimento segue o padrão de todo o módulo para contextos assimétricos, como também é utilizado em VerifierPublicCtx::SetKey [SWS_CRYPT_24115] e KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_21815] para vinculação de chaves.\nAlternativamente, interfaces relacionadas preveem variantes de KeySlot para a configuração, como em VerifierPublicCtx [SWS_CRYPT_50018] ou KeyEncapsulatorPublicCtx [SWS_CRYPT_50012].

Utilização e semântica

O método puramente virtual Start da classe ara::crypto::cryp::EncryptorPublicCtx serve para a inicialização do contexto para uma nova encriptação [SWS_CRYPT_50087]. Não recebe parâmetros de passagem e é executado de forma síncrona. Como valor de retorno, a função fornece um ara::core::Result<void>, que ou confirma a inicialização bem-sucedida ou transporta um código de erro ocorrido [SWS_CRYPT_50087].

Tratamento de erros e comportamento de rollback

Se as pré-condições necessárias para o processo de encriptação não forem satisfeitas, a chamada falha. A especificação assegura uma semântica de rollback para casos de erro e define as seguintes causas de erro [SWS_CRYPT_50087]:

• UninitializedContext: Nenhuma chave foi previamente atribuída ao contexto.
• ara::crypto::CryptoErrc::kEmptyKeySlot: Um KeySlot configurado está atualmente desocupado.
• ara::crypto::CryptoErrc::kUsageViolation: As permissões da chave não contêm a flag de utilização kAllowDataEncryption.
• ara::crypto::CryptoErrc::kIncompatibleObject: O tipo de chave atribuído é incompatível com a transformação requerida.
• ara::crypto::CryptoErrc::kBusyResource: Um recurso necessário para a inicialização está ocupado.
• ara::crypto::CryptoErrc::kUnsupported: O processamento de stream não é suportado pelo contexto concreto.

Concorrência e interação

O método está especificado como thread-safe e exception safe [SWS_CRYPT_50087]. O fornecimento de uma chave adequada no contexto é um pré-requisito obrigatório para o sucesso. Conceptualmente, a função integra-se em ciclos de vida padronizados de contextos criptográficos, nos quais as operações são preparadas através de chamadas sem parâmetros – comparável a verificações de assinatura [SWS_CRYPT_50019], gerações de assinatura [SWS_CRYPT_50037] ou cálculos de MAC [SWS_CRYPT_22111]. A chamada deverá representar o ponto de partida obrigatório antes da realização efetiva de uma encriptação de stream. Pergunta Q-db262c3914e6b4cf (aberta)

usar

O método síncrono Update da classe ara::crypto::cryp::EncryptorPublicCtx serve para a criptografia progressiva de blocos de dados de um texto simples [SWS_CRYPT_50176]. Por meio do parâmetro in (ReadOnlyMemRegion), é passada uma parte do texto simples, enquanto os dados criptografados são gravados no buffer de saída out (ReadWriteMemRegion) [SWS_CRYPT_50176]. Como valor de retorno, a função fornece via ara::core::Result<std::size_t> a quantidade real de bytes gravados, que pode ser menor do que a capacidade disponibilizada de out [SWS_CRYPT_50176].

Sequência e interação

Antes da primeira chamada de Update, o processamento de dados deve obrigatoriamente ter sido iniciado por Start() [SWS_CRYPT_50176]. O tamanho de entrada máximo permitido para chamadas individuais pode ser consultado por meio do método GetMaximumChunkSize() [SWS_CRYPT_50091]. Além disso, o tamanho mínimo necessário para out pode ser calculado via GetRequiredOutputBufferSize() [SWS_CRYPT_50176].

Tratamento de erros e simultaneidade

Se ocorrer um erro durante a execução, este é reportado com semântica de rollback [SWS_CRYPT_50176]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: O processamento de dados não foi iniciado anteriormente com Start() [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInsufficientCapacity: A capacidade do buffer out não é suficiente para o resultado [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho do buffer de in é inválido [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kUnsupported: O processamento de stream não é suportado pelo contexto atual [SWS_CRYPT_50176].

O método é declarado como seguro contra exceções e seguro para threads [SWS_CRYPT_50176]. Não obstante, a chamada paralela de múltiplas operações no mesmo objeto de contexto provavelmente deve exigir uma sincronização externa para assegurar uma ordem determinística dos fragmentos de dados criptografados. Pergunta Q-b22ffe505b583b25 (aberta)