{
  "index": 339,
  "slug": "editorial-2018-08-practice-tls-ca",
  "title": "PHP cURL: как исправить ошибку проверки TLS без отключения защиты",
  "excerpt": "PHP cURL возвращает ошибку сертификата, хотя адрес открывается в браузере. Разбираем CA bundle, цепочку, SNI и hostname, а затем проверяем исправление тем же запросом.",
  "contentHtml": "<p>PHP cURL возвращает <code>false</code>, а в ошибке, например, написано <code>SSL certificate problem</code>. В браузере тот же адрес открывается. Ошибка часто заканчивается быстрым обходом: разработчик выставляет <code>CURLOPT_SSL_VERIFYPEER</code> в <code>false</code> и получает ответ от API. Это не исправление. Клиент перестаёт проверять, кому он отправляет токен, персональные данные или платёжные параметры. Цена ошибки — не только сбой запроса, но и возможность незаметно установить TLS-соединение с чужим сервером.</p>\n<p>Правильный путь начинается с факта отказа. Нужно выяснить, не читается ли локальный CA bundle — набор доверенных сертификатов, не отсутствует ли промежуточный сертификат, не выбран ли другой виртуальный хост по SNI и подходит ли имя из URL сертификату. Эти причины дают похожие сообщения, но требуют разных владельцев и действий.</p>\n<h2>Что именно проверяет TLS</h2>\n<p>HTTPS-клиент проверяет не просто строку в адресе. Он получает сертификат сервера, строит цепочку до доверенного корня из локального хранилища и сверяет имя хоста с сертификатом. До этого сервер может выбрать сертификат по SNI (Server Name Indication) — имени, которое клиент передаёт в начале TLS-диалога. При включённой проверке ошибка в любом звене останавливает запрос.</p>\n<p>CA bundle отвечает на вопрос «каким центрам сертификации доверяет этот процесс?». Серверная цепочка отвечает на вопрос «прислал ли сервер сертификаты, нужные для построения пути?». Имя хоста (hostname) отвечает на вопрос «выдан ли сертификат именно этому имени?». SNI помогает серверу выбрать нужный виртуальный хост. Нельзя исправить одну проблему настройкой, предназначенной для другой.</p>\n<h2>Сначала фиксирую отказ в PHP</h2>\n<p>Диагностика должна выполняться тем же PHP-процессом и с тем же URL, который использует приложение. Браузер и команда <code>curl</code> в командной строке могут работать с другими версиями TLS-библиотеки, другими хранилищами и другим пользователем ОС. Это полезные контрольные точки, но не доказательство для PHP.</p>\n<pre><code>&lt;?php\n\n$url = 'https://api.partner.example/v1/ping';\n$caFile = '/opt/app/certs/ca-bundle.pem';\n\nif (!is_readable($caFile)) {\n    throw new RuntimeException('CA bundle is not readable: ' . $caFile);\n}\n\n$handle = curl_init($url);\nif ($handle === false) {\n    throw new RuntimeException('Unable to initialize cURL');\n}\n\n$verbose = fopen('php://temp', 'w+');\nif ($verbose === false) {\n    curl_close($handle);\n    throw new RuntimeException('Unable to create cURL trace stream');\n}\n\n$settingsApplied = curl_setopt_array($handle, [\n    CURLOPT_RETURNTRANSFER =&gt; true,\n    CURLOPT_CAINFO =&gt; $caFile,\n    CURLOPT_SSL_VERIFYPEER =&gt; true,\n    CURLOPT_SSL_VERIFYHOST =&gt; 2,\n    CURLOPT_VERBOSE =&gt; true,\n    CURLOPT_STDERR =&gt; $verbose,\n    CURLOPT_CONNECTTIMEOUT =&gt; 5,\n    CURLOPT_TIMEOUT =&gt; 15,\n]);\nif (!$settingsApplied) {\n    curl_close($handle);\n    fclose($verbose);\n    throw new RuntimeException('Unable to configure cURL');\n}\n\n$body = curl_exec($handle);\n$errno = curl_errno($handle);\n$error = curl_error($handle);\nrewind($verbose);\n$trace = stream_get_contents($verbose);\n\ncurl_close($handle);\nfclose($verbose);\n\nif ($body === false) {\n    throw new RuntimeException('cURL error ' . $errno . ': ' . $error);\n}\n\necho $body;</code></pre>\n<p>Вызовы <code>curl_errno()</code> и <code>curl_error()</code> стоят до <code>curl_close()</code>. Номер и текст нужно сохранять вместе с именем хоста, временем, версией PHP cURL и идентификатором запроса. Verbose-трасса подходит для закрытого стенда. В рабочий лог её можно писать только после удаления токенов, заголовков авторизации и тела запроса.</p>\n<p>Путь к CA bundle должен приходить из конфигурации окружения. Не принимайте его из HTTP-параметра. Файл должен быть доступен пользователю PHP-FPM или Apache и не должен находиться в каталоге, который раздаёт веб-сервер.</p>\n<h2>Разделяю симптом, причину, проверку и действие</h2>\n<div class=\"table-scroll\"><table><caption>Типовые ветки диагностики ошибки TLS</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>Ошибка о невозможности проверить peer, часто код 60</td><td>Нет доверенного корня, неполная цепочка или неверное имя</td><td>Снять сертификаты с SNI, проверить путь через тот же CA bundle и сверить имя хоста</td><td>Исправить bundle, серверную цепочку или адрес; оставить проверки включёнными</td></tr><tr><td>Ошибка чтения CA-файла, часто код 77</td><td>Файл отсутствует, путь относительный или пользователь процесса не имеет доступа</td><td><code>is_readable()</code>, абсолютный путь и права каждого каталога</td><td>Исправить доставку файла и права процесса PHP</td></tr><tr><td>CLI проходит, PHP отказывает</td><td>Разные libcurl, TLS-библиотеки, хранилища CA или пользователь ОС</td><td><code>curl_version()</code> в PHP, <code>curl -V</code> в командной строке, явный <code>--cacert</code></td><td>Сравнить окружения и задать CA bundle именно PHP</td></tr><tr><td>Браузер проходит, PHP отказывает</td><td>Браузер использует системное или собственное хранилище</td><td>Повторить запрос из PHP с явным <code>CURLOPT_CAINFO</code></td><td>Не считать браузер контрольным результатом; исправить PHP-окружение</td></tr><tr><td>Сертификаты меняются при запуске с разным именем</td><td>Разные виртуальные хосты и SNI</td><td><code>openssl s_client</code> с именем хоста из URL и без подмены на IP</td><td>Исправить URL, DNS или конфигурацию TLS на сервере</td></tr></tbody></table></div>\n<h2>Сравниваю версии и хранилища</h2>\n<p>Сначала смотрю, чем собран PHP-модуль. Это отделяет ошибку приложения от различий окружения.</p>\n<pre><code>$version = curl_version();\n\nprintf('libcurl: %s\\n', $version['version']);\nprintf('TLS library: %s\\n', $version['ssl_version']);\nprintf('curl.cainfo: %s\\n', ini_get('curl.cainfo') ?: '(not set)');</code></pre>\n<p>Затем выполняю учебную CLI-команду с тестовым адресом и явным файлом. Адрес <code>api.partner.example</code> не является производственным сервером. В реальной проверке его заменяют точным именем хоста из конфигурации приложения.</p>\n<pre><code>curl -v \\\n  --cacert /opt/app/certs/ca-bundle.pem \\\n  https://api.partner.example/v1/ping</code></pre>\n<p>Если CLI проходит, а PHP нет, сравниваю не только файл. Проверяю пользователя процесса, права на каталог, значение <code>curl.cainfo</code>, версию <code>curl_version()</code> и наличие прокси. Если оба клиента отказывают, перехожу к серверной цепочке и имени. Повторный запуск с отключённой проверкой не добавляет диагностического факта.</p>\n<h2>Проверяю серверную цепочку и SNI</h2>\n<p>Для виртуального хоста передаю серверу имя из URL. Команда ниже — учебный пример для закрытого стенда. Она показывает сертификаты, которые сервер прислал в ответ. Она не заменяет проверку цепочки.</p>\n<pre><code>openssl s_client \\\n  -connect api.partner.example:443 \\\n  -servername api.partner.example \\\n  -showcerts \\\n  &lt;/dev/null</code></pre>\n<p>Из вывода выписываю конечный сертификат и каждый промежуточный сертификат (intermediate). Корневой сертификат обычно хранится у клиента и не обязан приходить от сервера. Если сервер не прислал нужный промежуточный сертификат, исправление принадлежит владельцу HTTPS-сервера. Не добавляю промежуточный сертификат в хранилище доверия как постоянный обход: это смешивает две разные роли.</p>\n<p>Серверный список можно проверить отдельно. В примере <code>leaf.pem</code> содержит конечный сертификат, <code>intermediate.pem</code> — промежуточный сертификат, а <code>ca-bundle.pem</code> — доверенные корни. Имена файлов условны.</p>\n<pre><code>openssl verify \\\n  -purpose sslserver \\\n  -CAfile ./ca-bundle.pem \\\n  -untrusted ./intermediate.pem \\\n  ./leaf.pem</code></pre>\n<p>Успешная команда подтверждает построение цепочки для выбранного набора доверия. Она не подтверждает, что сертификат подходит имени хоста. Это условие проверяю отдельно тем же URL из PHP. IP-адрес не заменяет имя: сертификат должен содержать этот IP как IP-адрес, а не только DNS-имя.</p>\n<h2>Исправляю только подтверждённую ветку</h2>\n<p>Для одного вызова указываю абсолютный путь через <code>CURLOPT_CAINFO</code>. Для всего PHP-окружения можно задать абсолютный путь в <code>curl.cainfo</code>. После изменения конфигурации перезапускаю тот процесс PHP, который реально выполняет запрос. Изменение CLI-конфигурации не меняет настройки PHP-FPM автоматически.</p>\n<pre><code>; php.ini. Пример, не универсальное имя каталога.\ncurl.cainfo='/opt/app/certs/ca-bundle.pem'</code></pre>\n<p>Bundle беру из управляемого источника: пакета операционной системы, согласованного хранилища проекта или официального канала поставщика. Если API использует частный CA, добавляю доверенный корень по процедуре владельца сервиса. Не копирую leaf-сертификат из браузера и не собираю хранилище из случайных файлов. Leaf может быть перевыпущен, а доверие должно принадлежать контролируемому CA.</p>\n<figure><img src='/assets/editorial/2018/tls-ca-diagnostic-2018.svg' alt='Схема диагностики ошибки TLS в PHP cURL: ошибка, версия клиента, CA bundle, серверная цепочка с SNI, исправление и повторная проверка' /><figcaption>Сначала фиксируем отказ и отделяем окружение от сервера. Только после этого меняем CA bundle или исправляем цепочку.</figcaption></figure>\n<h2>Порядок действий</h2>\n<ol><li>Повторить тот же запрос в PHP на закрытом стенде и сохранить код, текст ошибки, имя хоста, версии и безопасную трассу.</li><li>Проверить абсолютный путь к CA bundle, чтение файла пользователем PHP и значение <code>curl.cainfo</code>.</li><li>Сравнить PHP cURL с CLI через <code>curl_version()</code>, <code>curl -V</code> и явный <code>--cacert</code>.</li><li>Получить серверный список сертификатов через <code>openssl s_client</code> с <code>-servername</code> из URL.</li><li>Разделить сертификаты в формате PEM (блоки <code>BEGIN CERTIFICATE</code>/<code>END CERTIFICATE</code>) и проверить цепочку через <code>openssl verify</code>, не смешивая <code>-CAfile</code> и <code>-untrusted</code>.</li><li>Проверить имя хоста в URL и Subject Alternative Name (SAN) сертификата. Не подставлять IP как диагностический shortcut.</li><li>Исправить только подтверждённую причину: путь или права, клиентский bundle, серверную цепочку, DNS или сертификат.</li><li>Перезапустить нужный PHP-процесс и повторить исходный запрос при <code>CURLOPT_SSL_VERIFYPEER =&gt; true</code> и <code>CURLOPT_SSL_VERIFYHOST =&gt; 2</code>.</li></ol>\n<h2>Ограничения и отрицательный путь</h2>\n<p>CA bundle не исправит неверную дату на машине, отозванный сертификат, несовместимую политику TLS или неправильное имя хоста. Если корень неизвестен и его нельзя добавить через управляемый процесс, запрос должен оставаться отклонённым. Это честный результат, а не повод включать <code>CURLOPT_SSL_VERIFYPEER =&gt; false</code>.</p>\n<p>Проверка сертификата не превращает API в надёжный сервис. После TLS остаются ошибки DNS, прокси, HTTP, авторизации и формата ответа. Здесь рассматривается только граница установления доверенного TLS-соединения. Учебные команды и адреса из статьи не доказывают доступность какого-либо production-сервиса.</p>\n<h2>Проверяемый критерий готовности</h2>\n<p>Исправление готово, если исходный PHP-код устанавливает соединение с тем же именем хоста, строит цепочку через согласованный CA bundle и проходит проверку имени при включённых проверках сертификата и имени хоста. Путь к bundle доступен следующему разработчику, а проверка воспроизводится тем же пользователем и тем же PHP-процессом. Если запрос всё ещё падает, результатом должны быть конкретные факты: код и текст ошибки, версия клиента, серверный список с SNI, проверка цепочки и проверенное имя. Тогда следующий шаг адресует причину, а не скрывает её.</p>\n<h2>Проверяемые источники</h2><ul><li><a href='https://curl.se/docs/sslcerts.html' target='_blank' rel='noopener noreferrer'>curl: SSL Certificate Verification</a> — модель проверки, хранилище CA, явный CA-файл и предупреждение об отключении проверки.</li><li><a href='https://curl.se/libcurl/c/libcurl-errors.html' target='_blank' rel='noopener noreferrer'>libcurl: Error Codes</a> — коды 60 для ошибки проверки сертификата и 77 для ошибки чтения CA-файла.</li><li><a href='https://www.php.net/manual/en/curl.constants.php' target='_blank' rel='noopener noreferrer'>PHP manual: cURL constants</a> — <code>CURLOPT_CAINFO</code>, <code>CURLOPT_SSL_VERIFYPEER</code> и <code>CURLOPT_SSL_VERIFYHOST</code>.</li><li><a href='https://docs.openssl.org/master/man1/openssl-s_client/' target='_blank' rel='noopener noreferrer'>OpenSSL: s_client</a> — параметры <code>-servername</code>, <code>-showcerts</code> и настройки проверки.</li></ul>"
}