Криптография

Модуль stappler_crypto представляет интерфейс для работы с открытыми и закрытыми ключами, интерфейсы JsonWebToken и криптоблоков на основе блочных шифров.

Для большинства функций может быть указана исходная криптографическая библиотека с помощью типа Backend. Если используется API без указания Backend, он определяется автоматически в зависимости от доступных в следующем порядке: OpenSSL, GnuTLS, MbedTLS, встроенные в SDK функции криптографии (Backend::Embedded). Такие функции автоматически определяют библиотеку, способную выполнить задачу.

API криптографии общий, для использования функций ГОСТ-криптографии необходимо либо передать соответствующий открытый или закрытый ключ, либо указать соответствующее значение в перечислении:

• HashFunction::GOST_3411
• SignAlgorithm::[GOST_256, GOST_512]
• KeyType::[GOST3410_2012_256,GOST3410_2012_512]
• BlockCipher::Gost3412_2015_CTR_ACPKM

Проверить поддержку отечественной криптографии можно через присутствие соответствующих флагов BackendFlags::SupportsGost3412_2015 (для блочного шифра) и BackendFlags::SupportsGost3410_2012 (для ЭЦП и хэш-функций) при вызове crypto::listBackends.

Криптографический интерфейс

Интерфейс закрытого ключа (crypto::PrivateKey):

• generate — генерирует новый ключ
• exportPublic — экспортирует открытый ключ
• exportPem — экспортирует ключ в текстовом обменном формате pem
• exportDer — экспортирует ключ в бинарном обменном формате
• sign — подписывает сообщение ключом
• verify — верифицирует подпись сообщения
• isSupported — проверяет, доступен ли формат ключа в используемой криптографической библиотеке

Интерфейс открытого ключа (crypto::PublicKey):

• importOpenSSH — импортирует ключ в формате OpenSSH (поддерживаются только RSA-ключи)
• exportPem — экспортирует ключ в текстовом обменном формате pem
• exportDer — экспортирует ключ в бинарном обменном формате
• verify — верифицирует подпись сообщения

Интерфейс блочных шифров реализует базовое кодирование и декодирование стандартным шифром AES в режиме CBC, либо шифром ГОСТ, а также генерацию ключа AES и ГОСТ на базе закрытого ключа. Интерфейс также подставляет к кодируемым данным метаданные о версии алгоритма и размере блока.

• encryptBlock — кодирует данные
• decryptBlock- декодирует данные
• makeBlockKey — создаёт ключ на базе закрытого ключа

Также, модуль предоставляет унифицированные функции хеширования. Их использование предпочтительнее прямому использованию встроенных криптографических хэшей.

• hash256
• hash512

Пример использования функций реализован в соответствующем тесте libstappler-root/tests/common/src/CryptoTest.cpp.

JsonWebToken

Реализована полная поддержка формата JWT, добавлен вариант использовать для кодирования формат CBOR. Потенциально, возможно использовать другие варианты алгоритма подписи, в том числе, отечественные алгоритмы.

Добавлены режимы подписи SigAlg::GS256 и SigAlg::GS512 (libstappler-core/crypto/SPJsonWebToken.h:46) для использования хэша ГОСТ 34.10-2018.

Основные функции:

• make — создаёт токен на основе основных параметров
• validate — проверяет криптографическую подпись токена с помощью открытого ключа
• validatePayload — проверяет содержимое токена на основе известных параметров и времени жизни
• exportPlain — экспортирует неподписанный токен
• exportSigned — экспортирует подписанный закрытым ключом токен

Доступ к хранимым данным возможен напрямую через поля структуры header и payload.

Криптохранилища

Интерфейс предназначен для использования совместно с JsonWebToken для хранения зашифрованных данных внутри токена.

Токен использует набор ключей (закрытый, открытый, дополнительный секретный хэш системы) и набор дополнительных регенерируемых данных для генерации и регенерации ключа шифрования AES либо ГОСТ 34.11.

При создании токена, новый ключ шифрования генерируется на основе переданных дополнительных данных. При чтении токена должны быть переданы точно такие же дополнительные данные для корректной регенерации ключа.

Объект токена реализован поверх интерфейса блока данных, что позволяет использовать его напрямую как нетипизированный контейнер.

Основные функции:

• parse — разбирает токен из JsonWebToken или его полезной нагрузки, и набора ключей
• create — создаёт новый интерфейс токена на основе набора ключей
• exportToken — экспортирует текущий токен как JsonWebToken c шифроблоком. Использует предоставленный отпечаток системы для генерации ключа
• exportData — экспортирует блок полезной нагрузки с метаданными, необходимыми для регенерации ключа

Криптохранилища при экспорте криптоблока с ключом на основе ГОСТ 34.10-2018 определены так, чтобы одновременно использовать блочный шифр ГОСТ 34.12-2018 (Кузнечик). Для вычисления отпечатка клиента хэш-функция определяется явно, как SHA-2 или ГОСТ 34.11-2018.