classe ara::crypto::Serializable

A interface ara::crypto::Serializable define o padrão uniforme para exportação pública de objetos criptográficos em sequências de bytes específicas de formato. As aplicações determinam previamente por meio de GetExportSize() o tamanho de buffer necessário e, em seguida, executam a serialização real por meio de ExportPublicly() em um buffer disponibilizado [SWS_CRYPT_10711]. Todas as operações são seguras contra exceções, bem como thread-safe, sendo que a exportação de chaves pressupõe obrigatoriamente a permissão kAllowPlaintextExport e os erros estão sempre sujeitos a uma semântica de rollback [SWS_CRYPT_50006].

mais ›

Contexto

A interface ara::crypto::Serializable define o contrato abstrato para objetos criptográficos no módulo crypto que podem ser convertidos em uma representação padronizada de bytes. Como interface pura, ela encapsula a capacidade de serializar um objeto em um formato de saída especificado por um identificador de formato (FormatId) [SWS_CRYPT_10711]. Entre os parceiros típicos de interação estão componentes de aplicação ou de plataforma que precisam armazenar persistentemente artefatos criptográficos, como chaves ou certificados, transmiti-los por canais de comunicação ou trocá-los em texto simples. A interface assegura que a exportação ocorra de maneira controlada e considerando formatos, bem como restrições de segurança.

Ciclo de vida

Como ara::crypto::Serializable representa uma interface puramente virtual com métodos puramente virtuais, a classe não possui lógica própria de instanciação. O tempo de vida e a criação dependem inteiramente das classes criptográficas concretas derivadas que implementam a interface. Ambos os métodos especificados da interface, GetExportSize() [SWS_CRYPT_50006] e ExportPublicly() [SWS_CRYPT_10711], são declarados como const e não alteram o estado interno do objeto durante a serialização. Conforme a especificação, as operações são projetadas para serem seguras contra exceções (exception safe) e seguras para concorrência (thread-safe) [SWS_CRYPT_10711], [SWS_CRYPT_50006], de modo que acessos paralelos de leitura à mesma instância de objeto são permitidos.

Caminho de utilização

O fluxo regular de uma exportação divide-se em uma sequência de duas etapas composta por determinação do tamanho e a serialização real. Para evitar estouros de buffer ou alocações com falha, o chamador consulta previamente, por meio do método GetExportSize(), o tamanho de buffer exatamente necessário em bytes para o formato de destino desejado [SWS_CRYPT_50006]. Após o retorno bem-sucedido, o chamador disponibiliza uma área de memória gravável do tipo ReadWriteMemRegion. Presumivelmente, na maioria das implementações, essa área de memória é alocada dinamicamente com base na contagem de bytes apurada ou disponibilizada a partir de um pool de memória reservado previamente. Pergunta Q-0c04ba0a352f0a37 (aberta)

Na etapa seguinte, a aplicação chama ExportPublicly() e passa tanto o buffer disponibilizado quanto o FormatId [SWS_CRYPT_10711] previamente selecionado. O objeto serializa seus dados úteis na área de memória passada e, em caso de sucesso, retorna a quantidade de bytes efetivamente gravada dentro do tipo de retorno ara::core::Result<std::size_t> [SWS_CRYPT_10711].

Diagrama de sequência: ordem típica de chamadas para serialização de um objeto por meio de consulta de tamanho e exportação subsequente. Fontes: [SWS_CRYPT_50006], [SWS_CRYPT_10711]

Cenários de erro

As operações da interface sinalizam estados de erro por meio do tipo de retorno ara::core::Result, sendo que todos os erros especificados garantem uma estrita semântica de rollback (rollback_semantics) [SWS_CRYPT_10711], [SWS_CRYPT_50006]. Se uma chamada falhar, o sistema como um todo permanece em um estado consistente. Estão definidos os seguintes casos de erro:

• ara::crypto::CryptoErrc::kUnsupportedFormat: é retornado tanto por GetExportSize() [SWS_CRYPT_50006] quanto por ExportPublicly() [SWS_CRYPT_10711] se o FormatId indicado não for suportado para o tipo concreto de objeto.
• ara::crypto::CryptoErrc::kInsufficientCapacity: ocorre em ExportPublicly() se a capacidade do buffer ReadWriteMemRegion passado não for suficiente para os dados serializados [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported: é reportado por ExportPublicly() caso a exportação para o objeto específico não seja suportada em princípio [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation: ocorre em ExportPublicly() se o objeto for uma chave cujas regras de uso não permitam uma exportação em texto simples (o uso permitido não inclui kAllowPlaintextExport) [SWS_CRYPT_10711].