API OpenSSL: основные структуры и подводные камни

EVP (Envelope) API — это высокоуровневый интерфейс OpenSSL для криптографических операций и правильный интерфейс для использования в программном коде приложений. Он скрывает детали, специфичные для алгоритмов, за единообразным интерфейсом, автоматически поддерживает аппаратное ускорение через ENGINE и модули-провайдеры, а также корректно обрабатывает дополнение и детали режимов. Низкоуровневые программные интерфейсы OpenSSL, специфичные для отдельных алгоритмов, в современных версиях устарели, поэтому их следует избегать.

Для симметричного шифрования в OpenSSL используется объект контекста EVP_CIPHER_CTX. Последовательность операций такова: EVP_CIPHER_CTX_new выделяет контекст, EVP_EncryptInit_ex инициализирует его шифром и ключом, EVP_EncryptUpdate многократно обрабатывает данные, EVP_EncryptFinal_ex дописывает последний блок и получает оставшиеся выходные данные, а EVP_CIPHER_CTX_free освобождает память. Пропуск EncryptFinal_ex — распространенная ошибка, приводящая к усеченному результату.

Вычисление дайджеста сообщения с помощью EVP_MD_CTX выполняется аналогично: EVP_MD_CTX_new, EVP_DigestInit_ex с указанием алгоритма (EVP_sha256(), EVP_sha3_256() и т. д.), EVP_DigestUpdate для обработки фрагментов данных и EVP_DigestFinal_ex для получения хеша. Для операций HMAC используется отдельный HMAC_CTX или более новый интерфейс EVP_MAC. Абстракция EVP позволяет заменить алгоритм хеширования, изменив всего один вызов функции.

EVP_PKEY — это унифицированный объект асимметричного ключа в OpenSSL, поддерживающий RSA, ECDSA, Ed25519, DH и другие алгоритмы через единый интерфейс. Ключи создаются из файлов PEM или DER с помощью PEM_read_PrivateKey и PEM_read_PUBKEY либо генерируются с помощью EVP_PKEY_keygen. EVP_PKEY_sign и EVP_PKEY_verify выполняют подписание и проверку для ключей любого типа с помощью одинаковых вызовов функций.

BIO (базовый ввод-вывод) — это уровень абстракции ввода-вывода OpenSSL, позволяющий читать и записывать данные, защищенные TLS, или необработанные данные через цепочку объектов BIO. Цепочка BIO может выглядеть так: BIO_new_ssl (уровень TLS), соединенный с BIO_new_connect (TCP-соединение). Запись в SSL BIO автоматически шифрует и отправляет данные, а чтение расшифровывает полученные данные. Объекты BIO поддерживают файлы, сокеты, буферы памяти и фильтры (base64, буферизацию).

Для TLS-соединений в OpenSSL используются два объекта: SSL_CTX (контекст) хранит общую конфигурацию — сертификат, закрытый ключ, набор сертификатов CA, ограничения на версии протокола и список шифров. SSL представляет отдельное соединение, созданное на основе контекста. Создайте один SSL_CTX для приложения, а затем создавайте на его основе объекты SSL для каждого соединения. SSL_read и SSL_write передают открытый текст; OpenSSL самостоятельно обрабатывает все фрагментирование TLS и шифрование.

Самая опасная ошибка при работе с OpenSSL — игнорирование возвращаемых значений. EVP_EncryptFinal_ex, SSL_read и SSL_write возвращают отрицательные значения или ноль, чтобы указать на ошибки. Вызов SSL_read в цикле без проверки SSL_get_error может привести к бесконечному циклу или пропуску ошибок. Необходимо проверять возвращаемое значение каждой функции OpenSSL, которая может завершиться неудачно: ошибки часто указывают на условия, важные для безопасности, например сбои рукопожатия или проверки сертификата.

SSL_read и SSL_write могут возвращать SSL_ERROR_WANT_READ или SSL_ERROR_WANT_WRITE. Это означает, что операцию следует повторить после ожидания завершения ввода-вывода. Это не настоящие ошибки, а уведомления о состоянии неблокирующего ввода-вывода. Код, который не вызывает SSL_get_error и неправильно выбирает ветвь при ожидании чтения или записи, будет либо активно зацикливаться, либо ошибочно считать эти условия ошибками. Всегда используйте SSL_get_error для интерпретации отрицательных возвращаемых значений операций ввода-вывода TLS.

OpenSSL содержит множество устаревших низкоуровневых функций, которые не следует использовать в новом коде: прямые вызовы DES_encrypt1, непосредственное использование функций хеширования SHA1 или MD5 без уровня EVP, RSA_private_encrypt вместо EVP_PKEY_sign и AES_encrypt (AES ECB без аутентификации). Эти программные интерфейсы обходят проверки безопасности, используют устаревшие алгоритмы или просто менее безопасны, чем соответствующие аналоги EVP. Предупреждения компилятора часто указывают на использование устаревших программных интерфейсов.

OpenSSL использует явное управление памятью: каждый выделенный объект необходимо явно освобождать. Распространенные утечки памяти возникают, если забыть вызвать EVP_CIPHER_CTX_free после шифрования, не вызвать SSL_free после закрытия соединения или не вызвать X509_free после проверки сертификата. В долго работающих серверах такие утечки приводят к постепенному исчерпанию памяти. Используйте такие инструменты, как valgrind или AddressSanitizer, чтобы обнаруживать утечки памяти OpenSSL во время разработки.

В OpenSSL 3.0 появилась модель провайдеров, заменившая прежний программный интерфейс ENGINE для аппаратного ускорения. Провайдеры — это загружаемые модули, реализующие криптографические алгоритмы: провайдер по умолчанию (программная реализация), устаревший провайдер (старые алгоритмы), провайдер FIPS (прошедший проверку FIPS 140-2) и сторонние провайдеры для HSM. Провайдер FIPS обеспечивает работу в соответствии с требованиями, ограничивая доступные алгоритмы одобренными FIPS 140-2, без изменения программного кода приложения.

Почему предпочтительно использовать EVP API OpenSSL, а не низкоуровневые программные интерфейсы, специфичные для алгоритмов?

Повторение материала по API OpenSSL: всегда используйте высокоуровневый API EVP; для симметричных операций — EVP_CIPHER_CTX, для хеширования — EVP_MD_CTX, для асимметричных ключей — EVP_PKEY; используйте цепочки BIO для абстракции ввода-вывода, SSL_CTX и SSL для TLS-соединений; всегда проверяйте возвращаемые значения и вызывайте SSL_get_error; освобождайте все выделенные объекты, чтобы предотвращать утечки; избегайте устаревших низкоуровневых функций; используйте провайдеры OpenSSL 3.0 для соответствия требованиям FIPS или аппаратного ускорения.