classe ara::crypto::cryp::KeyEncapsulatorPublicCtx

O método síncrono Encapsulate encapsula uma chave simétrica fornecida (key) e escreve o resultado no buffer de saída encapsulatedKey [SWS_CRYPT_21813]. Em caso de execução bem-sucedida, retorna através de ara::core::Result<std::size_t> o tamanho em bytes da chave encapsulada [SWS_CRYPT_21813].

Em caso de erro, é retornado um código de erro correspondente com semântica de rollback [SWS_CRYPT_21813]. As causas de erro relevantes são:

• UninitializedContext: O contexto não foi inicializado com um valor de chave pública [SWS_CRYPT_21813].
• ara::crypto::CryptoErrc::kUsageViolation: Falta a flag de uso kAllowKeyWrapping na chave de encapsulamento ou falta kAllowSecuredExport na chave a ser encapsulada [SWS_CRYPT_21813].
• ara::crypto::CryptoErrc::kIncompatibleObject ou CryptoErrc::kInvalidInputSize: O objeto de chave é incompatível ou o tamanho da chave não é suportado pelo contexto [SWS_CRYPT_21813].
• CryptoErrc::kUnsupported: O contexto não suporta o encapsulamento de chaves fornecidas porque ele mesmo as gera durante o encapsulamento [SWS_CRYPT_21813].
• ara::crypto::CryptoErrc::kInsufficientCapacity: O buffer encapsulatedKey está dimensionado pequeno demais [SWS_CRYPT_21813].
• ara::crypto::CryptoErrc::kBusyResource ou ara::crypto::CryptoErrc::kEmptyKeySlot: Um recurso está ocupado ou um KeySlot configurado está vazio [SWS_CRYPT_21813].

A operação é declarada como const, noexcept e especificada como thread-safe e exception safe [SWS_CRYPT_21813].

Na interação com o módulo, esta função difere da sobrecarga alternativa [SWS_CRYPT_50011], que não recebe uma chave existente, mas gera dinamicamente uma nova chave simétrica e a retorna juntamente com o resultado do encapsulamento [SWS_CRYPT_50011].

Utilização e semântica

O método síncrono Encapsulate gera internamente uma nova chave simétrica e a encapsula utilizando o contexto [SWS_CRYPT_50011]. Como parâmetros de entrada, são especificados o algoritmo de destino algId bem como as flags de uso permitidas allowedUsage para a chave gerada [SWS_CRYPT_50011]. O criptograma da chave é gravado no buffer de saída encapsulatedKey [SWS_CRYPT_50011]. Em caso de sucesso, o valor de retorno encapsula um par composto pelo tamanho real em bytes da chave encapsulada e um smart pointer para o objeto de chave gerado (std::pair<std::size_t, SymmetricKey::Sptr>) dentro de um ara::core::Result [SWS_CRYPT_50011].

Tratamento de erros e proteção

Em caso de erro, os valores de retorno possuem predominantemente semântica de rollback [SWS_CRYPT_50011]. As possíveis causas de erro incluem:

• UninitializedContext: o contexto não foi inicializado previamente com uma chave pública [SWS_CRYPT_50011].
• CryptoErrc::kUsageViolation: falta à chave de encapsulamento a flag kAllowKeyWrapping ou falta à chave de destino kAllowSecuredExport [SWS_CRYPT_50011].
• CryptoErrc::kInsufficientCapacity: o buffer de saída encapsulatedKey não oferece capacidade suficiente [SWS_CRYPT_50011].
• CryptoErrc::kUnknownIdentifier ou CryptoErrc::kUnsupported: a algId é desconhecida ou a geração durante o encapsulamento não é suportada [SWS_CRYPT_50011].
• CryptoErrc::kEmptyKeySlot ou CryptoErrc::kBusyResource: um KeySlot configurado está vazio ou um recurso necessário está ocupado [SWS_CRYPT_50011].

Concorrência e interação

A operação é especificada como const, noexcept, thread-safe bem como exception-safe [SWS_CRYPT_50011]. Em comparação com a sobrecarga [SWS_CRYPT_21813], à qual é passada uma chave existente e que retorna apenas o seu tamanho, este método executa a geração e o encapsulamento da chave em uma etapa conjunta [SWS_CRYPT_50011].

usar

O método SetKey configura a instância de ara::crypto::cryp::KeyEncapsulatorPublicCtx de modo que o objeto de chave passado seja utilizado como chave de encapsulamento [SWS_CRYPT_21815]. Como parâmetro serve key do tipo PublicKey::Sptr [SWS_CRYPT_21815]. A chamada ocorre de forma síncrona e fornece como valor de retorno um ara::core::Result<void>, que está vazio em caso de sucesso ou transporta um código de erro [SWS_CRYPT_21815].

Tratamento de erros

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

• ara::crypto::CryptoErrc::kIncompatibleObject: O objeto de chave fornecido é incompatível com o contexto [SWS_CRYPT_21815].
• ara::crypto::CryptoErrc::kUsageViolation: O uso permitido da chave não contém a flag kAllowKeyWrapping [SWS_CRYPT_21815].
• ara::crypto::CryptoErrc::kUnsupported: O contexto suporta exclusivamente a definição de uma chave por meio de um KeySlot [SWS_CRYPT_21815].

Simultaneidade e restrições

A função está especificada como thread-safe e exception safe com garantia noexcept [SWS_CRYPT_21815].

Interação

Por meio da configuração da chave, o contexto é preparado para o encapsulamento de chave, que é executado através do método Encapsulate [SWS_CRYPT_50011]. Se o contexto não suportar a atribuição direta de chave ou se a chave tiver de ser obtida de uma área de armazenamento, a sobrecarga de SetKey com um KeySlot::Sptr está disponível como alternativa [SWS_CRYPT_50012].

O método SetKey da classe ara::crypto::cryp::KeyEncapsulatorPublicCtx configura o contexto de forma que a chave pública armazenada em um slot de chave transmitido (KeySlot) seja utilizada no momento do encapsulamento da chave [SWS_CRYPT_50012].

usar

A chamada ocorre de forma síncrona e está especificada como noexcept, bem como exception safe [SWS_CRYPT_50012]. Como parâmetro, serve keySlot do tipo KeySlot::Sptr, o qual deve conter uma chave pública [SWS_CRYPT_50012]. O valor de retorno é um ara::core::Result<void>, que não contém valor em caso de sucesso [SWS_CRYPT_50012].

Tratamento de erros

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

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

Concorrência e interação

A função está definida como thread-safe [SWS_CRYPT_50012]. Além da atribuição por meio de um slot de chave, existe uma sobrecarga alternativa para a transferência direta de um PublicKey::Sptr [SWS_CRYPT_21815]. A chave configurada é empregada assim que o encapsulamento de chave for executado via Encapsulate [SWS_CRYPT_50011]. Em relação à ordem, SetKey presumivelmente deve ser executado antes da chamada de Encapsulate para que o contexto esteja inicializado. Pergunta Q-769923d4fb9a3d1e (aberta)