classe ara::crypto::Formatter

A interface ara::crypto::Formatter permite a conversão e serialização thread-safe de dados criptográficos entre formatos em bruto, DER e PEM [SWS_CRYPT_50197]. Após a definição do formato de destino e o apuramento do tamanho de buffer necessário, o método Convert transfere os dados de origem para o buffer de saída preparado [SWS_CRYPT_50198]. O pré-requisito essencial para uma execução bem-sucedida é uma memória de destino suficientemente dimensionada, bem como a conformidade formal dos dados de entrada com o formato de origem configurado.

mais ›

Contexto

A interface ara::crypto::Formatter define no módulo crypto a interface unificada para a formatação, transformação e serialização de estruturas de dados criptográficos. A sua principal tarefa consiste em converter dados úteis e objetos criptográficos entre representações como dados em bruto puros (kFormatRawValueOnly), codificações ASN.1-DER (kFormatDerEncoded) e formatos textuais PEM (kFormatPemEncoded), tendo em conta um identificador de algoritmo (AlgId) [SWS_CRYPT_50197]. Neste contexto, o formatador atua como elo de ligação entre objetos criptográficos e buffers de memória, lendo dados através de ReadOnlyMemRegion e emitindo-os em ReadWriteMemRegion [SWS_CRYPT_50198].

Ciclo de vida

Dado que ara::crypto::Formatter está declarada como uma interface puramente virtual, disponibiliza o alias de tipo de smart pointer canónico Sptr, definido como std::shared_ptr<Formatter>, para referenciação e gestão do ciclo de vida [SWS_CRYPT_50191]. Na prática, instâncias concretas da interface deverão ser disponibilizadas através de métodos de fábrica de componentes criptográficos de nível superior. Pergunta Q-99e96992d02b9c13 (aberta) Após a criação, um formatador encontra-se inicialmente num estado inicial não configurado antes de ser preparado para transformações através de chamadas de configuração.

No que diz respeito ao ambiente de execução, a interface garante segurança total contra exceções (exception safe) mediante a utilização consistente de noexcept e o tratamento de erros através de tipos de resultado [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Todas as funções-membro estão também especificadas como thread-safe [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Isto permite o acesso paralelo de leitura e transformação de múltiplas threads a uma instância partilhada de formatador, desde que não ocorram reconfigurações concorrentes.

Caminho de utilização

A utilização regular de ara::crypto::Formatter segue uma sequência definida de parametrização, verificação de capacidade e transformação:

1. Configuração do formato: através de SetFormatConfiguration, são definidos de forma vinculativa o formato de entrada esperado (inputFormat), o formato de saída pretendido (outputFormat) e o identificador de algoritmo (algId) dos dados a processar [SWS_CRYPT_50197].
2. Apuramento do tamanho: antes da conversão propriamente dita, a aplicação invoca GetExportSize para apurar o tamanho exato da memória em bytes que o objeto serializado necessita na configuração atual [SWS_CRYPT_50199]. Isto permite a alocação exata da memória de destino.
3. Conversão de dados: por fim, Convert transforma os dados de origem a partir de uma ReadOnlyMemRegion para o buffer de destino ReadWriteMemRegion em conformidade com a configuração efetuada [SWS_CRYPT_50198].

Diagrama de sequência: sequência de conversão típica desde a seleção de formato e apuramento do tamanho do buffer até à transformação propriamente dita. Fontes: [SWS_CRYPT_50197], [SWS_CRYPT_50199], [SWS_CRYPT_50198]

Cenários de erro

Os métodos de ara::crypto::Formatter sinalizam estados de erro deterministicamente através de valores de retorno do tipo ara::core::Result. Para operações com falha, estão definidas semânticas de rollback claras:

• Formatos não suportados: se a implementação subjacente não suportar o par de conversão especificado ou o identificador de algoritmo, SetFormatConfiguration devolve o código de erro ara::crypto::CryptoErrc::kUnsupportedFormat [SWS_CRYPT_50197].
• Dados de entrada inválidos: caso os dados em bruto transmitidos no buffer não correspondam ao formato configurado ou sejam sintaticamente inválidos, Convert falha com ara::crypto::CryptoErrc::kInvalidArgument [SWS_CRYPT_50198].
• Buffer de destino insuficiente: se a ReadWriteMemRegion disponibilizada for demasiado pequena para o resultado serializado, Convert é interrompido com ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50198]. Este problema pode ser evitado de forma direcionada mediante consulta prévia através de GetExportSize [SWS_CRYPT_50199].
• Falta de pré-configuração: embora não estejam listados códigos de erro normalizados para GetExportSize [SWS_CRYPT_50199], é presumivelmente obrigatório estabelecer previamente uma configuração válida através de SetFormatConfiguration para que seja possível realizar uma determinação de tamanho ou conversão consistente. Pergunta Q-e7cf4306bc7cfb49 (aberta)