класс ara::crypto::Serializable

Интерфейс ara::crypto::Serializable определяет единый стандарт для открытого экспорта криптографических объектов в байтовые последовательности специфического формата. Приложения предварительно определяют требуемый размер буфера с помощью GetExportSize() и затем выполняют фактическую сериализацию через ExportPublicly() в предоставленный буфер [SWS_CRYPT_10711]. Все операции являются безопасными относительно исключений, а также потокобезопасными, причем экспорт ключей обязательно требует полномочия kAllowPlaintextExport, а ошибки всегда подчиняются семантике отката [SWS_CRYPT_50006].

больше ›

Контекст

Интерфейс ara::crypto::Serializable определяет абстрактный контракт для криптографических объектов в модуле crypto, которые могут быть преобразованы в стандартизированное байтовое представление. Являясь чистым интерфейсом, он инкапсулирует возможность сериализации объекта в формат вывода, заданный идентификатором формата (FormatId) [SWS_CRYPT_10711]. К типичным партнерам по взаимодействию относятся компоненты приложений или платформы, которым требуется постоянно сохранять криптографические артефакты, такие как ключи или сертификаты, передавать их по каналам связи или обмениваться ими в открытом виде. Интерфейс гарантирует, что экспорт выполняется контролируемо и с учетом форматов, а также ограничений безопасности.

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

Поскольку ara::crypto::Serializable представляет собой чисто виртуальный интерфейс с чисто виртуальными методами, класс не содержит собственной логики создания экземпляров. Время жизни и создание полностью зависят от производных конкретных криптографических классов, реализующих интерфейс. Оба специфицированных метода интерфейса, GetExportSize() [SWS_CRYPT_50006] и ExportPublicly() [SWS_CRYPT_10711], объявлены как const и не изменяют внутреннее состояние объекта при сериализации. Согласно спецификации, операции спроектированы как безопасные относительно исключений (exception safe) и потокобезопасные (thread-safe) [SWS_CRYPT_10711], [SWS_CRYPT_50006], благодаря чему параллельный доступ на чтение к одному и тому же экземпляру объекта является допустимым.

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

Регулярный процесс экспорта делится на двухэтапную последовательность из определения размера и фактической сериализации. Чтобы избежать переполнения буфера или неудачных выделений памяти, вызывающая сторона предварительно запрашивает через метод GetExportSize() точно требуемый размер буфера в байтах для нужного целевого формата [SWS_CRYPT_50006]. После успешного ответа вызывающая сторона предоставляет доступную для записи область памяти типа ReadWriteMemRegion. Предположительно, в большинстве реализаций эта область памяти выделяется динамически на основе определенного количества байтов или предоставляется из предварительно зарезервированного пула памяти. Вопрос Q-0c04ba0a352f0a37 (открытый)

На последующем шаге приложение вызывает ExportPublicly() и передает как предоставленный буфер, так и ранее выбранный FormatId [SWS_CRYPT_10711]. Объект сериализует свои полезные данные в переданную область памяти и в случае успеха возвращает фактически записанное количество байтов внутри типа возвращаемого значения ara::core::Result<std::size_t> [SWS_CRYPT_10711].

Диаграмма последовательности: типичная последовательность вызовов для сериализации объекта через запрос размера и последующий экспорт. Источники: [SWS_CRYPT_50006], [SWS_CRYPT_10711]

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

Операции интерфейса сигнализируют о состояниях ошибок через тип возвращаемого значения ara::core::Result, при этом все специфицированные ошибки гарантируют строгую семантику отката (rollback_semantics) [SWS_CRYPT_10711], [SWS_CRYPT_50006]. В случае сбоя вызова вся система остается в согласованном состоянии. Определены следующие случаи ошибок:

• ara::crypto::CryptoErrc::kUnsupportedFormat: возвращается как методом GetExportSize() [SWS_CRYPT_50006], так и ExportPublicly() [SWS_CRYPT_10711], если указанный FormatId не поддерживается для конкретного типа объекта.
• ara::crypto::CryptoErrc::kInsufficientCapacity: возникает в ExportPublicly(), если емкости переданного буфера ReadWriteMemRegion недостаточно для сериализованных данных [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported: сообщается методом ExportPublicly(), если экспорт для данного конкретного объекта принципиально не поддерживается [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation: возникает при ExportPublicly(), если объект представляет собой ключ, правила использования которого не разрешают экспорт в открытом виде (разрешенное использование не включает kAllowPlaintextExport) [SWS_CRYPT_10711].