classe ara::crypto::cryp::SignerPrivateCtx

O método Cancel() serve para o cancelamento síncrono de uma operação de streaming em andamento e ainda não concluída dentro da classe ara::crypto::cryp::SignerPrivateCtx, a qual foi previamente iniciada por uma chamada de Start() [SWS_CRYPT_50041]. A interface puramente virtual virtual ara::core::Result<void> Cancel() noexcept = 0; está declarada no cabeçalho ara/crypto/cryp/signer_private_ctx.h, não recebe parâmetros de entrada e sinaliza o cancelamento bem-sucedido por meio de um ara::core::Result<void> vazio [SWS_CRYPT_50041]. Para o chamador, o método é especificado como seguro contra exceções (exception safe) e concorrentemente thread-safe [SWS_CRYPT_50041].

Em relação à ordem de chamada e ao tratamento de erros, Cancel() pressupõe obrigatoriamente um processamento ativo: se o processamento de dados não tiver sido iniciado previamente por uma chamada do método Start(), o cancelamento falha e retorna o código de erro ara::crypto::CryptoErrc::kProcessingNotStarted com semântica de rollback definida [SWS_CRYPT_50041]. Interpretação: após uma chamada bem-sucedida de Cancel(), o contexto deve retornar a um estado básico não iniciado, de modo que um novo procedimento de assinatura ou streaming possa ser iniciado. Pergunta Q-348fb3ae43e424c9 (aberta)

O design segue um princípio uniforme para todas as operações de streaming no módulo criptográfico. Assinaturas e semânticas de erro perfeitamente idênticas existem para contextos correlatos como VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] bem como EncryptorPublicCtx [SWS_CRYPT_50089].

usar

O método ara::crypto::cryp::SignerPrivateCtx::Finish conclui a geração de assinatura de forma síncrona e escreve a assinatura calculada diretamente no buffer de saída disponibilizado signature [SWS_CRYPT_50040]. A função aguarda como parâmetros passados a área de memória gravável signature (tipo ReadWriteMemRegion) e o formato pretendido signatureFormat (tipo FormatId) [SWS_CRYPT_50040]. Como valor de retorno, ara::core::Result<size_t> fornece o tamanho real em bytes dos dados de assinatura escritos; esta quantidade de dados pode ser menor do que a capacidade do buffer de destino [SWS_CRYPT_50040].

Tratamento de erros

Para todos os casos de erro ocorridos, está especificada uma semântica de rollback [SWS_CRYPT_50040]. Os seguintes códigos de erro podem ser retornados através do resultado:

• ara::crypto::CryptoErrc::kProcessingNotStarted: a geração de assinatura não foi iniciada com sucesso previamente [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity: a capacidade do buffer de saída signature passado é demasiado pequena [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat: o valor de signatureFormat é desconhecido ou não é suportado [SWS_CRYPT_50040].

Simultaneidade e restrições

O método está especificado como thread-safe e exception safe e não pode lançar exceções (noexcept) [SWS_CRYPT_50040]. Uma chamada válida pressupõe obrigatoriamente que o processo de geração no contexto tenha sido iniciado com sucesso previamente [SWS_CRYPT_50040].

Interação

A contraparte funcional direta para a verificação da assinatura gerada é constituída pelo método ara::crypto::cryp::VerifierPublicCtx::Finish [SWS_CRYPT_50022]. Em comparação com contextos para cálculos de hash ou MAC, nos quais Finish() apenas finaliza o cálculo e o resultado intermédio ou final é obtido separadamente [SWS_CRYPT_21115] [SWS_CRYPT_21116], SignerPrivateCtx::Finish escreve a assinatura diretamente no buffer [SWS_CRYPT_50040].

usar

O método virtual SetKey da classe ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") configura o contexto de assinatura para a utilização de uma chave privada fornecida [SWS_CRYPT_23515]. É passado como parâmetro key do tipo PrivateKey::Sptr como objeto de chave de origem [SWS_CRYPT_23515]. O método é executado de forma síncrona e retorna um ara::core::Result<void>, o qual está vazio em caso de sucesso ou transporta o código de erro ocorrido em caso de erro [SWS_CRYPT_23515].

Tratamento de erros

Se ocorrer um erro durante a configuração, aplica-se uma semântica de reversão (rollback) [SWS_CRYPT_23515]. Estão especificados os seguintes códigos de erro:

• ara::crypto::CryptoErrc::kIncompatibleObject: o objeto de chave fornecido é incompatível com o contexto atual [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation: a utilização permitida da chave não inclui a geração de assinatura (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported: o contexto específico suporta exclusivamente a definição através de um KeySlot [SWS_CRYPT_23515].

Simultaneidade e restrições

A interface está declarada como noexcept e, de acordo com a especificação, está classificada tanto como segura contra exceções («exception safe») quanto como segura para threads («thread-safe») [SWS_CRYPT_23515].

Interação

Em SignerPrivateCtx existe alternativamente a sobrecarga SetKey(KeySlot::Sptr), a qual configura o contexto de modo a que a chave armazenada num KeySlot só seja utilizada no momento do início do cálculo da assinatura [SWS_CRYPT_50036]. Para a verificação de assinaturas, serve no lado da verificação a contrapartida funcional SetKey com PublicKey::Sptr dentro de ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_24115].

usar

O método SetKey configura o contexto de assinatura [SWS_CRYPT_50036] para o uso de uma chave que se encontra no KeySlot::Sptr fornecido. A chave só é utilizada no momento em que o cálculo de assinatura propriamente dito é iniciado [SWS_CRYPT_50036]. A chamada ocorre de forma síncrona, é declarada como noexcept e retorna um ara::core::Result<void> [SWS_CRYPT_50036].

Tratamento de erros

Se a configuração falhar, um erro será transmitido no objeto de retorno, aplicando-se a semântica de rollback [SWS_CRYPT_50036]:

• ara::crypto::CryptoErrc::kIncompatibleObject: ocorre quando o keySlot fornecido não é compatível com este contexto de assinatura [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported: é reportado caso o contexto suporte exclusivamente a definição direta de um PrivateKey [SWS_CRYPT_50036].

Concorrência e interação

A interface pertence à classe ara::crypto::cryp::SignerPrivateCtx e é especificada como thread-safe bem como exception-safe [SWS_CRYPT_50036]. Além desta variante baseada em slot, SignerPrivateCtx também fornece uma sobrecarga que recebe diretamente um objeto PrivateKey::Sptr [SWS_CRYPT_23515]. Vinculações a slots análogas existem para outros contextos criptográficos, como para a verificação de assinatura com KeySlot em VerifierPublicCtx [SWS_CRYPT_50018] ou para a derivação de chaves em KeyDerivationFunctionCtx [SWS_CRYPT_50010].

O método Sign assina uma mensagem sincronicamente em uma única etapa, conforme [SWS_CRYPT_23512]. Ele recebe a mensagem de entrada a ser assinada (message), o buffer de destino (signature), o formato de assinatura pretendido (signatureFormat) e, opcionalmente, um valor de contexto (context). Em caso de sucesso, a função retorna via ara::core::Result<std::size_t> o tamanho real em bytes da assinatura gerada, que pode ser menor que a capacidade do buffer de destino [SWS_CRYPT_23512].

Em termos de concorrência e segurança de exceções, o método é declarado como noexcept, é considerado exception safe e está explicitamente especificado como thread-safe [SWS_CRYPT_23512].

Antes da chamada, o contexto precisa estar devidamente inicializado com um valor de chave; caso contrário, UninitializedContext é reportado [SWS_CRYPT_23512]. Quanto ao comprimento de entrada, Sign atua em conjunto com [SWS_CRYPT_50042]: via GetMaximumChunkSize é possível determinar o tamanho máximo de buffer suportado para o processamento em etapa única, a fim de prevenir erros como ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_23512] [SWS_CRYPT_50042].

O tratamento de erros prevê semânticas de rollback para códigos de erro específicos [SWS_CRYPT_23512]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: o buffer de saída signature é pequeno demais.
• ara::crypto::CryptoErrc::kUnsupported: o processamento em etapa única não é suportado ou a especificação de contexto context não atende aos requisitos.
• ara::crypto::CryptoErrc::kUnsupportedFormat: o FormatId especificado é desconhecido ou não suportado.
• ara::crypto::CryptoErrc::kUsageViolation: o uso permitido da chave não inclui kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot ou ara::crypto::CryptoErrc::kBusyResource: o KeySlot configurado está vazio ou um recurso necessário está ocupado.

O método sem parâmetros Start inicializa um contexto da classe ara::crypto::cryp::SignerPrivateCtx para uma nova geração de assinatura [SWS_CRYPT_50037]. A chamada ocorre de forma síncrona, é declarada como noexcept e retorna um ara::core::Result<void> vazio em caso de inicialização bem-sucedida ou um código de erro em caso de falha [SWS_CRYPT_50037].

Em caso de falha, a operação suporta semântica de rollback [SWS_CRYPT_50037]. Entre as causas de erro definidas de ara::crypto::CryptoErrc incluem-se:

• kUninitializedContext: o contexto não foi inicializado previamente mediante o fornecimento de uma chave [SWS_CRYPT_50037].
• kEmptyKeySlot: um slot de chave configurado está atualmente vazio [SWS_CRYPT_50037].
• kUsageViolation: as permissões da chave atribuída não incluem kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource: um recurso necessário para a operação está ocupado [SWS_CRYPT_50037].
• kUnsupported: o contexto não suporta streaming ou o algoritmo de assinatura requer obrigatoriamente a especificação de um valor de contexto [SWS_CRYPT_50037].

De acordo com a especificação, a função é thread-safe bem como exception safe [SWS_CRYPT_50037]. Se o algoritmo exigir um valor de contexto específico, deve-se utilizar alternativamente a variante sobrecarregada Start(ReadOnlyMemRegion context) [SWS_CRYPT_50038]. Após a chamada bem-sucedida de Start, as partes da mensagem a serem assinadas podem ser processadas continuamente via Update [SWS_CRYPT_50039].

O método Start serve para a inicialização síncrona do contexto ara::crypto::cryp::SignerPrivateCtx para uma nova geração de assinatura mediante a disponibilização de um valor de contexto ([SWS_CRYPT_50038]). Ele recebe o parâmetro context do tipo ReadOnlyMemRegion e retorna um ara::core::Result<void>. A função está especificada como noexcept=0, exception-safe, bem como declarada como thread-safe ([SWS_CRYPT_50038]).

Em caso de erro, o estado do contexto permanece inalterado através de uma semântica de rollback ([SWS_CRYPT_50038]). As causas de erro especificadas são:

• UninitializedContext: se o contexto não tiver sido inicializado previamente pela disponibilização de uma chave.
• ara::crypto::CryptoErrc::kUnsupported: caso o contexto não suporte streaming ou o algoritmo não permita um valor de contexto.
• ara::crypto::CryptoErrc::kInvalidInputSize: se o tamanho do buffer do valor de contexto passado for inválido.
• ara::crypto::CryptoErrc::kEmptyKeySlot: se um slot de chave configurado estiver atualmente vazio.
• ara::crypto::CryptoErrc::kUsageViolation: caso a utilização permitida da chave não inclua a geração de assinatura (kAllowSig Generation).
• ara::crypto::CryptoErrc::kBusyResource: caso um recurso necessário esteja ocupado.

No fluxo de processamento típico, os dados a assinar presumivelmente deverão ser passados sucessivamente via Update ([SWS_CRYPT_50039]) após o início bem-sucedido. Pergunta Q-7b821391730c9d38 (aberta) Caso o procedimento criptográfico não exija um valor de contexto, está disponível alternativamente a sobrecarga sem parâmetros Start() ([SWS_CRYPT_50037]).

O método Update serve em [SWS_CRYPT_50039] para expandir continuamente o estado interno de um cálculo de assinatura com mais uma seção da mensagem. A chamada ocorre de forma síncrona e processa a região de memória data fornecida do tipo ReadOnlyMemRegion. Como resultado, a função retorna um ara::core::Result<void>, que não contém valor em caso de processamento bem-sucedido ou, caso contrário, encapsula um código de erro [SWS_CRYPT_50039].

Em caso de erro, os valores de retorno possuem semântica de rollback [SWS_CRYPT_50039]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: ocorre quando o cálculo da assinatura não foi iniciado previamente pela chamada do método Start() [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize: é reportado caso o tamanho dos dados de entrada fornecidos não seja suportado pelo contexto [SWS_CRYPT_50039].

Em relação à concorrência e segurança, o método é declarado como thread-safe bem como exception safe [SWS_CRYPT_50039]. Na interação com o contexto de assinatura, o cálculo pressupõe obrigatoriamente que o fluxo tenha sido iniciado com Start(). O tamanho máximo permitido de buffer para chamadas individuais pode ser consultado via GetMaximumChunkSize() [SWS_CRYPT_50042]; este limite presumivelmente representa o teto cuja ultrapassagem leva a kInvalidInputSize. Pergunta Q-cf204a853a730365 (aberta)