classe ara::crypto::cryp::VerifierPublicCtx

Utilização e semântica

O método Cancel() aborta uma operação de streaming em andamento que foi previamente iniciada por Start() e ainda não concluída [SWS_CRYPT_50023]. Ele está definido no cabeçalho ara/crypto/cryp/verifier_public_ctx.h como um método puramente virtual do contexto ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]. A chamada ocorre de forma síncrona e sem argumentos. Como valor de retorno, serve um ara::core::Result<void>, que em caso de sucesso está vazio e confirma o cancelamento bem-sucedido da operação [SWS_CRYPT_50023].

Tratamento de erros

Se o processamento de dados ainda não tiver sido iniciado pela chamada do método Start(), a operação de cancelamento falha. Nesse cenário, a função retorna um resultado de erro com o código de erro ara::crypto::CryptoErrc::kProcessingNotStarted garantindo a semântica de rollback [SWS_CRYPT_50023].

Simultaneidade e restrições

A especificação classifica o método como seguro para threads (thread-safe) e seguro contra exceções (exception safe) com a designação noexcept [SWS_CRYPT_50023]. Interpretação: após o cancelamento bem-sucedido, o contexto provavelmente retornará ao estado inicial anterior ao início do processamento, permitindo que um novo processo de streaming seja iniciado. Pergunta Q-d80d09c8a8311bbc (aberta)

Interação no módulo crypt

Este padrão de cancelamento uniforme com assinatura e tratamento de erros idênticos aplica-se de forma consistente a todos os contextos de streaming do módulo crypt:

• MessageAuthnCodeCtx para Message Authentication Codes [SWS_CRYPT_50027],
• SignerPrivateCtx para a geração de assinaturas digitais [SWS_CRYPT_50041],
• SymmetricCipherCtx para criptografia e descriptografia simétricas [SWS_CRYPT_50046],
• HashFunctionCtx para operações de hash criptográfico [SWS_CRYPT_50058],
• DecryptorPrivateCtx para descriptografia assimétrica [SWS_CRYPT_50069],
• AuthCipherCtx para cifragem autenticada [SWS_CRYPT_50077] bem como
• EncryptorPublicCtx para criptografia assimétrica [SWS_CRYPT_50089].

O método Finish em ara::crypto::cryp::VerifierPublicCtx conclui uma verificação de assinatura e retorna o resultado da verificação [SWS_CRYPT_50022]. Ele recebe através do buffer de entrada signature (tipo ReadOnlyMemRegion) a assinatura a verificar, bem como através de signatureFormat (tipo FormatId) o seu formato [SWS_CRYPT_50022]. A chamada ocorre de forma síncrona e está declarada como thread-safe e exception safe de acordo com a especificação [SWS_CRYPT_50022].

Como valor de retorno serve um ara::core::Result<bool> [SWS_CRYPT_50022]: em caso de validação bem-sucedida da assinatura, o resultado contém true; em caso de assinatura com conteúdo inválido, false. Se, por outro lado, ocorrer um erro de processamento, é retornado um código de erro correspondente [SWS_CRYPT_50022]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: a operação não foi iniciada com sucesso previamente (semântica de rollback) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidInputSize: o tamanho do buffer de signature é inválido (semântica de rollback) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kUnsupportedFormat: o formato especificado signatureFormat não é suportado (semântica de rollback) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidArgument: a assinatura não corresponde ao formato especificado (semântica de rollback) [SWS_CRYPT_50022].

No fluxo criptográfico, esta função forma a contraparte da geração de assinatura via ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040], a qual escreve uma assinatura num buffer de saída. Todos os erros reportados possuem semântica de rollback [SWS_CRYPT_50022], de modo que o estado do contexto permanece consistente em caso de falha.

O método SetKey configura uma instância de VerifierPublicCtx para o uso de uma chave pública concreta para a verificação de assinatura ([SWS_CRYPT_24115]). Por meio do parâmetro key, é passado um ponteiro do tipo PublicKey::Sptr. A chamada ocorre sincronicamente e retorna um ara::core::Result<void>, que em caso de sucesso está vazio ou encapsula um código de erro específico.

De acordo com a especificação, a operação é concebida como thread-safe e segura contra exceções (exception safe) ([SWS_CRYPT_24115]). Se ocorrer um erro durante a vinculação da chave, uma semântica de rollback entra em ação para todos os casos de erro, de modo que o contexto permaneça em um estado consistente:

• CryptoErrc::kIncompatibleObject: A chave transmitida é incompatível com o contexto de verificação de assinatura ([SWS_CRYPT_24115]).
• CryptoErrc::kUsageViolation: As permissões da chave não permitem a verificação de assinatura (ausência do sinalizador de uso para verificação de assinatura) ([SWS_CRYPT_24115]).
• ara::crypto::CryptoErrc::kUnsupported: A implementação do contexto suporta exclusivamente a vinculação de uma chave por meio de um KeySlot ([SWS_CRYPT_24115]).

No fluxo de trabalho criptográfico, SetKey constitui a contraparte pública de SignerPrivateCtx::SetKey ([SWS_CRYPT_23515]). Se um contexto não permitir a transferência direta de chave via PublicKey::Sptr ou se as chaves forem gerenciadas em slots protegidos, a sobrecarga por meio de KeySlot::Sptr está disponível como alternativa ([SWS_CRYPT_50018]).

usar

O método SetKey da classe ara::crypto::cryp::VerifierPublicCtx configura o contexto de verificação para o uso de uma chave armazenada em um KeySlot passado [SWS_CRYPT_50018]. A chave é utilizada no momento em que a verificação de assinatura é iniciada [SWS_CRYPT_50018].

Como parâmetro, atua um ponteiro inteligente keySlot do tipo KeySlot::Sptr, o qual contém uma chave pública [SWS_CRYPT_50018]. A função opera de forma síncrona e retorna um ara::core::Result<void> para indicar uma conclusão bem-sucedida ou erro [SWS_CRYPT_50018].

Tratamento de erros e semântica

A operação está especificada como noexcept e exception safe [SWS_CRYPT_50018]. Se ocorrer um erro, aplica-se uma semântica de rollback [SWS_CRYPT_50018]:

• ara::crypto::CryptoErrc::kIncompatibleObject: o KeySlot fornecido é incompatível com este contexto [SWS_CRYPT_50018].
• ara::crypto::CryptoErrc::kUnsupported: o contexto suporta exclusivamente a definição direta de um PublicKey [SWS_CRYPT_50018].

Concorrência e interação

O método está especificado como thread-safe [SWS_CRYPT_50018]. Como alternativa ao KeySlot, VerifierPublicCtx oferece uma sobrecarga para definir um PublicKey diretamente [SWS_CRYPT_24115]. Uma configuração de chave correspondente por meio de um KeySlot existe de forma análoga também em outros contextos como SignerPrivateCtx [SWS_CRYPT_50036] ou MessageAuthnCodeCtx [SWS_CRYPT_50026].

usar

O método síncrono Start() da interface ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_50019]) inicializa o contexto para uma nova verificação de assinatura criptográfica na operação de streaming. A função não recebe parâmetros de entrada, é declarada como noexcept e retorna um ara::core::Result<void>, que fica vazio em caso de sucesso.

Tratamento de erros e rollback

Se ocorrer um erro durante a execução, aplica-se a semântica de rollback ([SWS_CRYPT_50019]), fazendo com que o contexto permaneça em um estado consistente. As possíveis causas de erro são:

• UninitializedContext: nenhuma chave criptográfica foi atribuída previamente ao contexto.
• ara::crypto::CryptoErrc::kUsageViolation: a chave atribuída não está liberada para a verificação de assinatura (kAllowSig Verification).
• ara::crypto::CryptoErrc::kEmptyKeySlot: um KeySlot configurado para a verificação está atualmente vazio.
• ara::crypto::CryptoErrc::kUnsupported: o contexto não suporta streaming ou o procedimento pressupõe obrigatoriamente um valor de contexto.
• ara::crypto::CryptoErrc::kBusyResource: um recurso necessário para a operação está ocupado no momento.

Concorrência e interação

Embora a especificação aponte o método como seguro para threads ([SWS_CRYPT_50019]), uma chamada paralela na mesma instância de contexto durante uma verificação em andamento provavelmente reiniciaria a operação existente ou falharia devido a recursos ocupados. Pergunta Q-af5e08ff9d905a29 (aberta)

Após a inicialização bem-sucedida, as partes da mensagem são passadas sequencialmente via Update() ([SWS_CRYPT_50021]). Uma operação de streaming em andamento pode ser cancelada prematuramente com Cancel() ([SWS_CRYPT_50023]), se necessário. Se o algoritmo exigir obrigatoriamente um valor de contexto, a função sobrecarregada Start(ReadOnlyMemRegion context) ([SWS_CRYPT_50020]) deverá ser chamada em seu lugar.

usar

A função Start inicializa, de acordo com [SWS_CRYPT_50020], um contexto de verificação da classe ara::crypto::cryp::VerifierPublicCtx para uma nova verificação de assinatura. Como parâmetro de entrada, ela recebe context do tipo ReadOnlyMemRegion, que disponibiliza um valor de contexto específico da aplicação. Como alternativa sem dados de contexto, existe a sobrecarga [SWS_CRYPT_50019]. O valor de retorno é ara::core::Result<void>; Interpretação: Como não estão definidos nem callbacks nem objetos futuros, a chamada deve ser processada de forma puramente síncrona. Pergunta Q-4e10cdb1a4343a3a (aberta)

Tratamento de erros

Em caso de erro, a função fornece um ara::core::Result com um código de erro adequado de ara::crypto::CryptoErrc, estando especificada uma semântica de rollback [SWS_CRYPT_50020]:

• kUninitializedContext: O contexto ainda não foi inicializado através da atribuição de uma chave.
• kEmptyKeySlot: Um KeySlot configurado está atualmente vazio.
• kUsageViolation: O uso permitido da chave atribuída não inclui kAllowSigVerification.
• kInvalidInputSize: O tamanho do buffer do valor de contexto passado é inválido para o algoritmo.
• kUnsupported: O contexto não suporta streaming ou o algoritmo não suporta a definição de um valor de contexto.
• kBusyResource: Um recurso necessário está ocupado.

Simultaneidade e restrições

De acordo com [SWS_CRYPT_50020], o método é classificado como thread-safe, bem como exception-safe. Ele não lança exceções (noexcept).

Interação

Após a execução bem-sucedida de Start, a mensagem de entrada pode ser transmitida passo a passo através de chamadas repetidas de Update [SWS_CRYPT_50021]. Um processo de streaming em andamento, iniciado por Start, pode ser cancelado prematuramente via Cancel, se necessário [SWS_CRYPT_50023].

usar

O método Update() serve para atualizar passo a passo o contexto de verificação de assinatura com uma parte adicional da mensagem de entrada [SWS_CRYPT_50021]. Como parâmetro, é passada uma área de memória data do tipo ReadOnlyMemRegion. A função retorna um ara::core::Result<void>; Interpretação: Devido a este tipo de retorno, o processamento deve ocorrer de forma síncrona. Pergunta Q-f98391030b3b4684 (aberta)

Tratamento de erros

Em caso de erro, é retornado um código de erro correspondente com semântica de rollback [SWS_CRYPT_50021]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: A verificação de assinatura não foi iniciada previamente através da chamada do método Start() [SWS_CRYPT_50021].
• ara::crypto::CryptoErrc::kInvalidInputSize: O tamanho dos dados fornecidos em data não é suportado [SWS_CRYPT_50021].

Concorrência e interação

A operação está classificada na especificação como thread-safe e exception safe [SWS_CRYPT_50021]. Antes da chamada, a inicialização via Start() deve obrigatoriamente ter ocorrido [SWS_CRYPT_50021]. Para evitar que ocorra kInvalidInputSize, o tamanho máximo de buffer permitido para chamadas individuais pode ser consultado através do método GetMaximumChunkSize() do mesmo contexto [SWS_CRYPT_50025]. A contrapartida complementar à geração de assinatura mensagem a mensagem é representada por Update() em SignerPrivateCtx [SWS_CRYPT_50039].

usar

O método Verify do contexto ara::crypto::cryp::VerifierPublicCtx serve para verificar a assinatura de uma mensagem disponibilizada em uma única chamada [SWS_CRYPT_24112]. São passados como parâmetros o buffer de mensagem message, a assinatura signature e o formato signatureFormat [SWS_CRYPT_24112]. Em caso de verificação bem-sucedida, o valor de retorno ara::core::Result<bool> contém true, em caso de não correspondência false ou um código de erro [SWS_CRYPT_24112]. Interpretação: devido ao tipo de resultado síncrono, o processo de verificação presumivelmente é executado de forma bloqueante na thread chamadora. Pergunta Q-671054c6e2b581c6 (aberta)

Tratamento de erros e simultaneidade

A função é especificada como exception safe e thread-safe [SWS_CRYPT_24112]. Em caso de erro, aplica-se uma semântica de rollback para os códigos de erro [SWS_CRYPT_24112]. As possíveis causas de erro abrangem:

• UninitializedContext, se o contexto não foi inicializado com uma chave [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kEmptyKeySlot em caso de slot de chave vazio ou kUsageViolation, se faltar à chave a permissão kAllowSig Verification [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kInvalidInputSize em caso de tamanho de buffer inválido [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kUnsupportedFormat ou kInvalidArgument em caso de formato de assinatura incorreto ou incompatível [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kBusyResource, se os recursos necessários estiverem ocupados [SWS_CRYPT_24112].

Interação

O tamanho máximo do buffer para chamadas únicas pode ser consultado via GetMaximumChunkSize() [SWS_CRYPT_50025]. Se o algoritmo exigir obrigatoriamente um valor de contexto, ara::crypto::CryptoErrc::kUnsupported é retornado [SWS_CRYPT_24112]; neste caso, deve-se selecionar a sobrecarga com o parâmetro adicional context [SWS_CRYPT_50024]. Para verificações de Message Authentication Codes, existe de forma distinta ara::crypto::cryp::MessageAuthnCodeCtx::Verify [SWS_CRYPT_50031].

O método síncrono Verify verifica a assinatura digital de uma mensagem fornecida, considerando um valor de contexto definido pelo usuário em uma única chamada ([SWS_CRYPT_50024]). Como parâmetros de entrada, o método espera os buffers message, context e signature, cada um como ReadOnlyMemRegion, bem como o formato da assinatura através de signatureFormat ([SWS_CRYPT_50024]). O valor de retorno é um ara::core::Result<bool>: contém true em caso de verificação bem-sucedida, false em caso de assinatura incorreta ou um código de erro correspondente ([SWS_CRYPT_50024]).

Em caso de erro, aplica-se uma semântica de rollback ([SWS_CRYPT_50024]). Os códigos de erro específicos incluem, entre outros:

• UninitializedContext, se o contexto de verificação ainda não tiver sido inicializado com um valor de chave ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kInvalidInputSize no caso de tamanho de buffer inadmissível ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupported, se o algoritmo de assinatura selecionado não suportar a especificação de um valor de contexto ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupportedFormat ou ara::crypto::CryptoErrc::kInvalidArgument, se o formato de assinatura especificado não for suportado ou se a assinatura não corresponder ao formato ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUsageViolation, se o uso permitido da chave não incluir kAllowSigVerification, bem como ara::crypto::CryptoErrc::kEmptyKeySlot e ara::crypto::CryptoErrc::kBusyResource ([SWS_CRYPT_50024]).

O método é declarado como const noexcept, é considerado seguro contra exceções e está especificado como thread-safe ([SWS_CRYPT_50024]). Na interação com o contexto, o tamanho máximo do buffer para chamadas individuais pode ser determinado através de GetMaximumChunkSize ([SWS_CRYPT_50025]). Para verificações sem contexto, está disponível a sobrecarga alternativa de Verify ([SWS_CRYPT_24112]).