класс ara::crypto::Formatter

Интерфейс ara::crypto::Formatter обеспечивает потокобезопасное преобразование и сериализацию криптографических данных между необработанными форматами, DER и PEM [SWS_CRYPT_50197]. После определения целевого формата и определения требуемого размера буфера метод Convert переносит исходные данные в подготовленный выходной буфер [SWS_CRYPT_50198]. Важным условием успешного выполнения является достаточный размер целевой памяти, а также формальное соответствие входных данных сконфигурированному исходному формату.

больше ›

Контекст

Интерфейс ara::crypto::Formatter определяет в модуле crypto унифицированный интерфейс для форматирования, преобразования и сериализации криптографических структур данных. Его основная задача состоит в том, чтобы конвертировать полезные данные и криптографические объекты между представлениями, такими как чисто необработанные данные (kFormatRawValueOnly), кодировки ASN.1-DER (kFormatDerEncoded), а также текстовые форматы PEM (kFormatPemEncoded) с учетом идентификатора алгоритма (AlgId) [SWS_CRYPT_50197]. При этом Formatter выступает связующим звеном между криптографическими объектами и буферами памяти, считывая данные через ReadOnlyMemRegion и выводя их в ReadWriteMemRegion [SWS_CRYPT_50198].

Жизненный цикл

Поскольку ara::crypto::Formatter объявлен как чисто виртуальный интерфейс, для ссылки на него и управления жизненным циклом он предоставляет канонический псевдоним типа интеллектуального указателя Sptr, определенный как std::shared_ptr<Formatter> [SWS_CRYPT_50191]. Конкретные экземпляры интерфейса на практике, по-видимому, предоставляются через фабричные методы вышестоящих криптографических компонентов. Вопрос Q-99e96992d02b9c13 (открытый) После создания Formatter сначала находится в несконфигурированном исходном состоянии, прежде чем он будет подготовлен к преобразованиям вызовами конфигурации.

Что касается среды выполнения, интерфейс гарантирует полную безопасность исключений (exception safe) за счет последовательного использования noexcept и обработки ошибок через типы Result [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Все функции-члены, кроме того, специфицированы как потокобезопасные (thread-safe) [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Это позволяет осуществлять параллельный доступ на чтение и преобразование из нескольких потоков к общему экземпляру Formatter, пока не происходят конкурирующие реконфигурации.

Путь использования

Штатное использование ara::crypto::Formatter следует фиксированной последовательности параметризации, проверки емкости и преобразования:

1. Конфигурация формата: через SetFormatConfiguration обязательно фиксируются ожидаемый входной формат (inputFormat), желаемый выходной формат (outputFormat), а также идентификатор алгоритма (algId) обрабатываемых данных [SWS_CRYPT_50197].
2. Определение размера: перед фактическим преобразованием приложение вызывает GetExportSize, чтобы определить точный размер памяти в байтах, который требуется сериализованному объекту при текущей конфигурации [SWS_CRYPT_50199]. Это обеспечивает точно выверенное выделение целевой памяти.
3. Преобразование данных: в завершение Convert преобразует исходные данные из ReadOnlyMemRegion в целевой буфер ReadWriteMemRegion в соответствии с выполненной конфигурацией [SWS_CRYPT_50198].

Диаграмма последовательности: типичная последовательность преобразования от выбора формата через определение размера буфера до фактической трансформации. Источники: [SWS_CRYPT_50197], [SWS_CRYPT_50199], [SWS_CRYPT_50198]

Сценарии ошибок

Методы ara::crypto::Formatter детерминированно сигнализируют об ошибочных состояниях через возвращаемые значения типа ara::core::Result. При этом для сбойных операций заложена четкая семантика отката:

• Неподдерживаемые форматы: если базовая реализация не поддерживает указанную пару преобразования или идентификатор алгоритма, SetFormatConfiguration возвращает код ошибки ara::crypto::CryptoErrc::kUnsupportedFormat [SWS_CRYPT_50197].
• Недопустимые входные данные: если переданные в буфере необработанные данные не соответствуют сконфигурированному формату или синтаксически невалидны, Convert завершается сбоем с ara::crypto::CryptoErrc::kInvalidArgument [SWS_CRYPT_50198].
• Недостаточный целевой буфер: если предоставленный ReadWriteMemRegion слишком мал для сериализованного результата, Convert прерывается с ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50198]. Эту проблему можно целенаправленно предотвратить предварительным запросом через GetExportSize [SWS_CRYPT_50199].
• Отсутствие предварительной конфигурации: хотя для GetExportSize не приведены стандартизированные коды ошибок [SWS_CRYPT_50199], для обеспечения согласованного определения размера или преобразования, по-видимому, обязательно должна быть предварительно установлена валидная конфигурация через SetFormatConfiguration. Вопрос Q-e7cf4306bc7cfb49 (открытый)