classe ara::crypto::cryp::KeyAgreementPrivateCtx

A interface ara::crypto::cryp::KeyAgreementPrivateCtx serve para a execução de processos de acordo de chaves criptográficas com base numa chave privada local e na chave pública de uma contraparte [SWS_CRYPT_21312]. Após a atribuição da própria chave e de parâmetros opcionais, o método AgreeKey calcula um segredo partilhado e retorna-o como um objeto de chave simétrica. Uma condição de contorno central é a inicialização completa antes da execução, dado que a ausência de parâmetros ou a falta de autorizações para kAllowKeyAgreement levam ao cancelamento com os respetivos códigos de erro [SWS_CRYPT_21312]. Todas as operações são concebidas como thread-safe.

mais ›

Contexto

A interface ara::crypto::cryp::KeyAgreementPrivateCtx serve no módulo crypto da Adaptive Platform para a execução de processos assimétricos de acordo de chaves (Key Agreement). A sua responsabilidade central reside no cálculo de uma chave simétrica partilhada a partir de uma chave privada local e da chave pública de um parceiro de comunicação [SWS_CRYPT_21312]. Como contexto de criptografia especializado, a classe interage com múltiplas abstrações de chaves e de armazenamento: a chave privada própria pode ser vinculada diretamente como objeto PrivateKey [SWS_CRYPT_21313] ou referenciada através de um KeySlot [SWS_CRYPT_50053]. A contraparte contribui com a sua chave pública sob a forma de um PublicKey, enquanto o resultado é disponibilizado como um objeto SymmetricKey independente [SWS_CRYPT_21312]. Complementarmente, parâmetros de configuração específicos do algoritmo podem ser passados como área de memória ou número inteiro [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Diagrama de contexto: interação de KeyAgreementPrivateCtx com chaves, slots de chaves e objeto de resultado. Fontes: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50053].

Ciclo de vida

O ciclo de vida e as relações de posse de KeyAgreementPrivateCtx baseiam-se em ponteiros partilhados (shared pointers); a especificação disponibiliza para tal o alias de tipo KeyAgreementPrivateCtx::Sptr [SWS_CRYPT_21301]. Interpretação: a instanciação deverá ocorrer através de uma factory de nível superior de um CryptoProvider, dado que a classe representa uma interface puramente virtual sem especificação de construtor. Pergunta Q-22dca518675fba51 (aberta) Após a criação, a instância encontra-se num estado básico não operacional. O contexto apenas é inicializado mediante a configuração de uma chave privada através de SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053] e a atribuição de todos os parâmetros necessários para o esquema selecionado [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Se um cálculo de chave for iniciado antes da conclusão destas etapas de configuração, a chamada falhará [SWS_CRYPT_21312]. Em relação à concorrência, todas as funções-membro são especificadas como thread-safe (thread-safe) e exception-safe (exception safe) [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Como a função de execução AgreeKey está declarada como const [SWS_CRYPT_21312], o mesmo contexto inicializado pode ser usado em paralelo para acordos com diferentes contrapartes.

Caminho de utilização

O uso prático divide-se em uma sequência estruturada de configuração e cálculo:

• Atribuição de chave: primeiramente, a aplicação vincula sua própria chave privada ao contexto. Isso ocorre por meio de SetKey(PrivateKey::Sptr) [SWS_CRYPT_21313] para um objeto de chave carregado ou por meio de SetKey(KeySlot::Sptr) [SWS_CRYPT_50053] para um slot de chave cujo conteúdo só é avaliado no momento do acordo.
• Definição de parâmetros: caso o algoritmo de destino exija dados de inicialização adicionais, estes são passados via SetParameter como buffer ReadOnlyMemRegion [SWS_CRYPT_50051] ou como inteiro de 64 bits std::uint64_t [SWS_CRYPT_50052].
• Acordo de chave: com AgreeKey, o algoritmo criptográfico é executado [SWS_CRYPT_21312]. O componente chamador passa a chave pública da contraparte (otherSideKey), o identificador do algoritmo de destino desejado (targetAlgId) e as flags de uso permitidas (allowedUsage).
• Obtenção do resultado: após a conclusão bem-sucedida, AgreeKey fornece um objeto SymmetricKey contendo o segredo compartilhado calculado [SWS_CRYPT_21312].

Diagrama de sequência: fluxo típico de acordo de chaves, desde a atribuição da chave até a geração da chave simétrica. Fontes: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051].

Cenários de erro

Métodos de KeyAgreementPrivateCtx retornam erros por meio de ara::core::Result e asseguram semântica de rollback [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Cenários de erro típicos incluem:

• CryptoErrc::kUninitializedContext: ocorre em AgreeKey caso nenhuma chave tenha sido definida previamente ou parâmetros obrigatórios estejam ausentes [SWS_CRYPT_21312].
• CryptoErrc::kIncompatibleObject: é reportado quando um PrivateKey ou KeySlot fornecido não corresponde ao tipo do contexto [SWS_CRYPT_21313], [SWS_CRYPT_50053], ou quando a chave da contraparte otherSideKey é incompatível [SWS_CRYPT_21312].
• CryptoErrc::kUsageViolation: sinaliza que a permissão kAllowKeyAgreement não foi concedida para a chave privada ou para a chave da contraparte [SWS_CRYPT_21312], [SWS_CRYPT_21313].
• CryptoErrc::kUnsupported: indica que a implementação do contexto suporta exclusivamente a respectiva outra variante de SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053], ou que um nome de parâmetro solicitado não é suportado [SWS_CRYPT_50051], [SWS_CRYPT_50052].
• CryptoErrc::kInvalidArgument: surge em caso de valores inválidos em SetParameter [SWS_CRYPT_50051], [SWS_CRYPT_50052] ou flags de allowedUsage inadmissíveis para a chave de destino [SWS_CRYPT_21312].
• CryptoErrc::kUnknownIdentifier: é acionado caso o identificador targetAlgId para o algoritmo de destino seja desconhecido [SWS_CRYPT_21312].
• CryptoErrc::kEmptyKeySlot e CryptoErrc::kBusyResource: são retornados por AgreeKey quando o KeySlot configurado não contém nenhuma chave no momento da execução ou quando um recurso necessário está ocupado [SWS_CRYPT_21312].