classe ara::crypto::cryp::KeyDecapsulatorPrivateCtx

A interface ara::crypto::cryp::KeyDecapsulatorPrivateCtx destina-se ao desencapsulamento assimétrico de dados de chave (Key Encapsulation Mechanism, KEM) para a geração de chaves simétricas de destino [SWS_CRYPT_21412]. Antes do desencapsulamento, o contexto deve ser obrigatoriamente inicializado através de SetKey com uma chave privada ou com um local de armazenamento de chave correspondente [SWS_CRYPT_21413]. Em seguida, o método Decapsulate transforma os dados encapsulados numa nova instância de chave simétrica de forma thread-safe e segura contra exceções [SWS_CRYPT_21412]. Todas as chamadas de interface garantem uma semântica de rollback estrita em caso de erro.

mais ›

Contexto

A classe ara::crypto::cryp::KeyDecapsulatorPrivateCtx constitui a interface normalizada para mecanismos de desencapsulamento de chaves assimétricas (Key Encapsulation Mechanism, KEM) baseados em chaves privadas. Como contexto criptográfico especializado, herda de CryptoContext e destina-se a desencapsular dados de chave encapsulados previamente transmitidos, utilizando uma chave privada assimétrica, e a transformá-los num novo objeto de chave simétrica (SymmetricKey) [SWS_CRYPT_21412].

Pelo menos três componentes participam na operação de desencapsulamento: a aplicação requerente, o próprio contexto de desencapsulamento e as fontes de chave sob a forma de um PrivateKey [SWS_CRYPT_21413] ou de um slot de memória referenciado via KeySlot [SWS_CRYPT_50083]. Após o desencapsulamento bem-sucedido, o contexto disponibiliza o objeto de chave simétrica gerado como smart pointer [SWS_CRYPT_21412].

Diagrama de contexto: integração do contexto de desencapsulamento entre a disponibilização da chave e a geração da chave de destino. Fontes: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Ciclo de vida

O contexto é tipicamente referenciado e partilhado através do alias de tipo KeyDecapsulatorPrivateCtx::Sptr como std::shared_ptr [SWS_CRYPT_21401]. Como a interface define funções de elemento puramente virtuais, a instanciação do objeto concreto realiza-se presumivelmente através de uma fábrica criptográfica de nível superior (interpretação). Pergunta Q-870e12aabbad8472 (aberta) A destruição e a limpeza de recursos estão associadas ao ciclo de vida do smart pointer.

Inicialmente, o contexto encontra-se num estado não inicializado, no qual ainda não foi atribuída nenhuma chave de desencapsulamento. Uma chamada direta de Decapsulate falha neste estado com o erro UninitializedContext [SWS_CRYPT_21412]. Apenas após a chamada bem-sucedida de um dos dois métodos sobrecarregados SetKey é que o contexto transita para o estado operacional [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Caso seja atribuído um KeySlot, a chave privada nele contida é utilizada apenas dinamicamente no momento do desencapsulamento efetivo; alterações no conteúdo do slot afetam, portanto, presumivelmente de imediato futuras chamadas de desencapsulamento (interpretação). Pergunta Q-0b0dfc1fd3ebbc6f (aberta)

No que diz respeito à concorrência e tolerância a falhas, todos os métodos estão especificados como thread-safe (thread-safe) e seguros contra exceções (exception safe) [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Uma vez que o método de transformação Decapsulate está declarado como const, múltiplas threads podem desencadear desencapsulamentos em paralelo sobre o mesmo contexto configurado [SWS_CRYPT_21412].

Caminho de utilização

O fluxo regular para desencapsulamento de uma chave de sessão divide-se em duas fases sucessivas:

1. Configuração da chave de desencapsulamento: a aplicação configura o contexto através de SetKey, passando um PrivateKey::Sptr [SWS_CRYPT_21413] ou depositando um KeySlot::Sptr [SWS_CRYPT_50083]. O resultado é um ara::core::Result<void> cujo status deve ser verificado antes da próxima etapa.
2. Execução do desencapsulamento: a aplicação chama Decapsulate e passa os dados do buffer da chave encapsulada (ReadOnlyMemRegion encapsulatedKey), o identificador de algoritmo da chave de destino (AlgId algId), bem como os seus tipos de uso permitidos (AllowedUsageFlags allowedUsage) [SWS_CRYPT_21412].
3. Processamento do resultado: em caso de transformação bem-sucedida, a função retorna um ara::core::Result<SymmetricKey::Sptr> através do qual a nova chave simétrica pode ser utilizada imediatamente para operações criptográficas subsequentes [SWS_CRYPT_21412].

Diagrama de sequência: fluxo típico de configuração de chave e desencapsulamento de uma chave de destino. Fontes: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Cenários de erro

Todas as operações retornam estados de erro através de ara::core::Result e asseguram uma semântica estrita de rollback (rollback_semantics), fazendo com que o contexto permaneça em um estado válido em caso de falhas [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083].

No âmbito da configuração da chave via SetKey, podem ocorrer os seguintes erros:

• CryptoErrc::kIncompatibleObject: o objeto PrivateKey passado ou o KeySlot é incompatível com o contexto [SWS_CRYPT_21413], [SWS_CRYPT_50083].
• CryptoErrc::kUsageViolation: as flags de permissão da chave privada não contêm o direito para desempacotamento (kAllowKeyUnwrapping) [SWS_CRYPT_21413].
• CryptoErrc::kUnsupported: a implementação do contexto suporta apenas a respectiva outra variante de configuração (por ex., vinculação exclusiva via KeySlot ou exclusivamente via PrivateKey) [SWS_CRYPT_21413], [SWS_CRYPT_50083].

Ao chamar Decapsulate, estão especificadas as seguintes causas de erro:

• UninitializedContext: nenhuma chave foi atribuída previamente ao contexto [SWS_CRYPT_21412].
• CryptoErrc::kInvalidArgument: o formato de dados do buffer passado encapsulatedKey é inválido [SWS_CRYPT_21412].
• CryptoErrc::kUnknownIdentifier: o identificador algId passado não é suportado [SWS_CRYPT_21412].
• CryptoErrc::kIncompatibleArguments: ou as permissões de destino allowedUsage não correspondem a algId ou ao tipo de chave, ou algId é incompatível com os dados KEM em encapsulatedKey [SWS_CRYPT_21412].
• CryptoErrc::kUsageViolation: as regras de uso da chave configurada não permitem desempacotamento (kAllowKeyUnwrapping ausente) [SWS_CRYPT_21412].
• CryptoErrc::kEmptyKeySlot: um KeySlot previamente vinculado via SetKey não contém nenhuma chave no momento da execução [SWS_CRYPT_21412].
• CryptoErrc::kBusyResource: um recurso do sistema necessário para o cálculo criptográfico está temporariamente ocupado [SWS_CRYPT_21412].