curl2code

Руководство по настройке SSL, TLS и прокси в curl

Настройка HTTPS-сертификатов, версий TLS, прокси и пользовательского DNS-разрешения в curl необходима для безопасного взаимодействия с API, CI/CD-пайплайнов и отладки сетевых проблем. Это руководство охватывает все флаги SSL, TLS, прокси и сети — от отключения проверки сертификатов с помощью -k при локальной разработке до настройки взаимного TLS с --cert и маршрутизации трафика через прокси SOCKS5. Каждая опция сопровождается понятным объяснением, соображениями безопасности и готовым примером.

Краткая справка по флагам SSL и Proxy

-kSSL/TLS

Разрешить небезопасные соединения — пропустить всю проверку SSL

--cacertSSL/TLS

Проверить сертификат сервера по конкретному CA-бандлу

--certSSL/TLS

Предоставить клиентский сертификат для взаимной TLS-аутентификации

--keySSL/TLS

Указать файл закрытого ключа для клиентского сертификата

--tlsv1.2SSL/TLS

Использовать TLS версии 1.2 или выше для соединения

--tlsv1.3SSL/TLS

Использовать TLS версии 1.3 или выше для соединения

--ssl-reqdSSL/TLS

Требовать SSL/TLS для соединения (завершиться с ошибкой, если недоступно)

--ciphersSSL/TLS

Указать шифры SSL для соединения

--cert-typeSSL/TLS

Указать тип клиентского сертификата (PEM, DER, ENG, P12)

--pinnedpubkeySSL/TLS

Привязать и проверить открытый ключ сервера (стиль HPKP)

-xПрокси

Направить весь трафик через указанный прокси-сервер

--socks5Прокси

Направить соединение через SOCKS5-прокси

--proxy-userПрокси

Указать имя пользователя:пароль для прокси-сервера

--noproxyПрокси

Список хостов, которые не должны проходить через прокси

--socks5-hostnameПрокси

SOCKS5-прокси с DNS-разрешением через прокси

--proxy-cacertПрокси

CA-сертификат для проверки самого HTTPS-прокси

--resolveСеть

Привязать пару host:port к пользовательскому IP-адресу

--connect-toСеть

Подключиться к другому host:port, отличному от указанного в URL

--local-portСеть

Задать номер или диапазон локального порта для соединения

--interfaceСеть

Привязать соединение к определённому сетевому интерфейсу

--dns-serversСеть

Использовать пользовательские DNS-серверы вместо системных (c-ares)

curl -k: Игнорирование ошибок SSL-сертификатов

Что делает
Флаг -k (или --insecure) отключает всю проверку сертификатов SSL/TLS. curl не будет проверять, подписан ли сертификат сервера доверенным CA, совпадает ли hostname или истёк ли срок действия сертификата.
Когда использовать
Используйте только для локальной разработки с самоподписанными сертификатами или в тестовых средах. Для staging/production используйте --cacert с реальным CA-сертификатом — это и безопаснее, и явнее.
$ curl -k https://localhost:8443/api/health

Никогда не используйте -k в production-скриптах или CI/CD-пайплайнах. Он отключает всю валидацию сертификатов, делая соединение уязвимым для атак «человек посередине» (MITM). Используйте --cacert для доверия конкретному CA.

curl --cacert: Использование пользовательского CA-сертификата

Что делает
Флаг --cacert указывает curl проверять SSL-сертификат сервера по конкретному файлу CA-бандла (Certificate Authority) в формате PEM вместо системного хранилища доверия.
Когда использовать
Используйте, когда сервер использует сертификат, подписанный частным или внутренним CA, которого нет в системном хранилище доверия. Это типично для корпоративных сред, кластеров Kubernetes и Docker-конфигураций с внутренним PKI.
$ curl --cacert /path/to/corporate-ca.pem https://internal-api.example.com/data

curl --cert: Клиентский сертификат (Взаимный TLS)

Что делает
Флаг --cert предоставляет клиентский сертификат для взаимного TLS (mTLS). При mTLS и сервер, и клиент предъявляют сертификаты для взаимной проверки идентичности. Файл сертификата должен быть в формате PEM или PKCS#12.
Когда использовать
Необходим, когда сервер требует аутентификацию по клиентскому сертификату — типично для банковских API, государственных сервисов, IoT-устройств и архитектур нулевого доверия. Всегда используйте вместе с --key, если ключ не встроен в файл сертификата.
$ curl --cert client.pem --key client-key.pem https://mtls-api.example.com/secure

curl --key: Закрытый ключ клиентского сертификата

Что делает
Флаг --key указывает файл закрытого ключа, который соответствует клиентскому сертификату из --cert. Ключ должен соответствовать сертификату. Если ключ защищён паролем, curl запросит парольную фразу (или используйте --pass).
Когда использовать
Всегда используйте вместе с --cert. Если закрытый ключ уже встроен в файл сертификата (типично для PKCS#12 / .p12-файлов), --key можно опустить.
$ curl --cert client.pem --key client-key.pem --cacert server-ca.pem https://api.example.com/secure

curl --tlsv1.2: Принудительно TLS 1.2 как минимум

Что делает
Флаг --tlsv1.2 заставляет curl использовать TLS 1.2 как минимально допустимую версию для SSL/TLS-рукопожатия. Старые протоколы (TLS 1.0, 1.1, SSLv3) отклоняются.
Когда использовать
Используйте для обеспечения минимального стандарта безопасности. TLS 1.2 требуется для соответствия PCI-DSS и поддерживается всеми современными серверами. Большинство современных сборок curl уже по умолчанию используют TLS 1.2+, но этот флаг делает это явным.
$ curl --tlsv1.2 -v https://secure.example.com/api 2>&1 | grep 'SSL connection'

curl --tlsv1.3: Принудительно TLS 1.3 как минимум

Что делает
Флаг --tlsv1.3 заставляет curl использовать TLS 1.3 — самую быструю и безопасную версию TLS. TLS 1.3 устраняет дополнительный round-trip при рукопожатии (поддержка 0-RTT) и убирает все устаревшие наборы шифров.
Когда использовать
Используйте, когда вы знаете, что сервер поддерживает TLS 1.3, и хотите наилучшую производительность и безопасность. Примечание: TLS 1.3 требует OpenSSL 1.1.1+ или совместимую TLS-библиотеку. Не все серверы пока поддерживают его.
$ curl --tlsv1.3 https://modern-api.example.com/data

Дополнительные опции SSL/TLS

--ssl-reqd

Требовать SSL/TLS для соединения (завершиться с ошибкой, если недоступно)

--ciphers

Указать шифры SSL для соединения

--cert-type

Указать тип клиентского сертификата (PEM, DER, ENG, P12)

--pinnedpubkey

Привязать и проверить открытый ключ сервера (стиль HPKP)

curl -x: Использование HTTP/HTTPS-прокси

Что делает
Флаг -x (или --proxy) направляет весь трафик curl через указанный прокси-сервер. Формат: [protocol://]host[:port]. Поддерживаемые протоколы прокси: HTTP, HTTPS, SOCKS4, SOCKS5.
Когда использовать
Используйте для корпоративных прокси-серверов, отладки с помощью Fiddler, Charles или mitmproxy, тестирования географических ограничений или когда прямой доступ в интернет недоступен. Также можно задать переменные окружения http_proxy / https_proxy.
$ curl -x http://proxy.example.com:8080 https://api.example.com/data

curl --socks5: Использование SOCKS5-прокси

Что делает
Флаг --socks5 указывает curl использовать SOCKS5-прокси для TCP-соединения. В отличие от HTTP-прокси, SOCKS5 работает на уровне TCP и может обрабатывать любой протокол — не только HTTP. DNS-разрешение выполняется локально по умолчанию; используйте --socks5-hostname для разрешения DNS через прокси.
Когда использовать
Используйте для SSH-туннелей (ssh -D), доступа к сети Tor или когда прокси должен обрабатывать не-HTTP протоколы. SOCKS5 поддерживает UDP и опционально может обрабатывать DNS, что делает его более гибким, чем HTTP-прокси.
$ curl --socks5 localhost:1080 https://api.example.com/data

curl --proxy-user: Аутентификация на прокси

Что делает
Флаг --proxy-user (или -U) отправляет учётные данные для аутентификации на прокси-сервер. Формат: user:password. Это отдельно от аутентификации на сервере (-u).
Когда использовать
Необходим, когда прокси-сервер требует аутентификацию — типично для корпоративных и enterprise-сетей. Учётные данные отправляются на прокси, а не на целевой сервер.
$ curl -x http://proxy.corp.com:3128 -U user:pass https://external-api.com/data

curl --noproxy: Обход прокси для определённых хостов

Что делает
Флаг --noproxy указывает список хостов, доменов или IP-адресов через запятую, которые должны обходить прокси и подключаться напрямую. Поддерживает шаблоны: *.example.com соответствует всем поддоменам.
Когда использовать
Используйте для исключения localhost, внутренних сервисов или определённых доменов из проксирования. Это важно, когда прокси задан глобально через переменные окружения, но некоторые хосты (например, локальные сервисы) нуждаются в прямом доступе. Используйте * для обхода прокси для всех хостов.
$ curl -x http://proxy:8080 --noproxy "localhost,127.0.0.1,*.internal.com" https://localhost:3000/api

Дополнительные опции прокси

--socks5-hostname

SOCKS5-прокси с DNS-разрешением через прокси

--proxy-cacert

CA-сертификат для проверки самого HTTPS-прокси

curl --resolve: Пользовательское DNS-разрешение

Что делает
Флаг --resolve предоставляет пользовательский IP-адрес для конкретной пары host:port, полностью обходя DNS-запрос. Формат: host:port:address. Можно указать несколько записей --resolve.
Когда использовать
Незаменим для тестирования до распространения DNS, проверки конкретного бэкенда за балансировщиком нагрузки или локальной разработки, где нужно реальное имя хоста для валидации SSL-сертификата. В отличие от редактирования /etc/hosts, это работает для конкретного запроса и порта.
$ curl --resolve api.example.com:443:127.0.0.1 https://api.example.com/health

curl --connect-to: Перенаправление соединения на другой хост

Что делает
Флаг --connect-to перенаправляет TCP-соединение на другую пару host:port, сохраняя оригинальный URL для HTTP-запроса (включая заголовок Host и SNI). Формат: HOST1:PORT1:HOST2:PORT2.
Когда использовать
Используйте для тестирования конкретного бэкенд-сервера за балансировщиком нагрузки без изменения DNS или /etc/hosts. В отличие от --resolve, здесь host:port отображается на host:port (а не на IP), что полезно, когда у цели тоже есть hostname.
$ curl --connect-to api.example.com:443:backend1.internal:8443 https://api.example.com/health

Дополнительные сетевые опции

--local-port

Задать номер или диапазон локального порта для соединения

--interface

Привязать соединение к определённому сетевому интерфейсу

--dns-servers

Использовать пользовательские DNS-серверы вместо системных (c-ares)

Практические сценарии SSL и Proxy

Эти примеры комбинируют несколько флагов для решения типичных задач безопасности и работы с сетью в средах разработки, CI/CD и production.

Тестирование HTTPS на localhost

При локальной разработке с самоподписанным сертификатом комбинируйте --resolve с --cacert (или -k для быстрого тестирования). Это позволяет использовать реальное имя хоста для корректного SSL/SNI без изменения файла hosts.

$ curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/api/status

Взаимный TLS (аутентификация по клиентскому сертификату)

Некоторые API требуют, чтобы и сервер, и клиент предъявляли сертификаты. Укажите --cert, --key и --cacert для установки полностью верифицированного двустороннего TLS-соединения.

$ curl --cert client.pem --key client-key.pem --cacert server-ca.pem https://mtls-api.example.com/data

Корпоративный прокси с аутентификацией

В корпоративных сетях с обязательными прокси-серверами комбинируйте -x с -U для учётных данных прокси. Добавьте --noproxy для исключения внутренних сервисов из проксирования.

$ curl -x http://proxy.corp.com:3128 -U user:pass --noproxy "*.internal.corp" https://external-api.com/data

Docker-контейнер с внутренним CA

Когда сервисы в Docker используют сертификаты от внутреннего CA, примонтируйте CA-сертификат в контейнер и укажите его через --cacert. Это безопаснее, чем -k, потому что всё равно валидирует цепочку сертификатов.

$ curl --cacert /etc/ssl/certs/internal-ca.crt https://service.docker.internal:8443/health

SOCKS5-прокси через SSH-туннель

Создайте SOCKS5-прокси с помощью ssh -D и направьте трафик curl через него с помощью --socks5. Это полезно для доступа к внутренним сервисам через бастион-хост.

$ curl --socks5 localhost:1080 https://internal-api.example.com/status

Часто задаваемые вопросы по SSL и Proxy в curl

Как отключить проверку SSL-сертификатов в curl?

Используйте curl -k URL или curl --insecure URL. Это отключает все проверки сертификатов — срок действия, несоответствие hostname, недоверенный CA. Используйте только для локальной разработки. В production используйте --cacert с реальным CA-сертификатом.

Как заставить curl доверять самоподписанному сертификату?

Используйте curl --cacert /path/to/ca.pem URL, чтобы указать CA-сертификат, которым подписан ваш самоподписанный сертификат. Это безопаснее, чем -k, потому что всё равно валидирует цепочку сертификатов — доверяя только вашему конкретному CA.

Как проверить, какую версию TLS использует curl?

Выполните curl -v URL и найдите строку * SSL connection using TLSv1.x / CipherSuite в подробном выводе. Чтобы принудительно использовать определённую версию, укажите --tlsv1.2 или --tlsv1.3.

Что такое взаимный TLS (mTLS) и как его использовать с curl?

Взаимный TLS требует, чтобы и сервер, и клиент предъявили сертификаты. Используйте: curl --cert client.pem --key client-key.pem --cacert server-ca.pem URL. Пара --cert/--key аутентифицирует клиента; --cacert проверяет сервер.

Как использовать curl через HTTP-прокси?

Используйте curl -x http://proxy:port URL. Для HTTPS-прокси: curl -x https://proxy:port URL. Или задайте переменные окружения http_proxy и https_proxy — curl подхватит их автоматически.

Как использовать curl с SOCKS5-прокси?

Используйте curl --socks5 host:port URL для локального DNS-разрешения или curl --socks5-hostname host:port URL для разрешения DNS через прокси (важно для приватности/Tor). Пример с SSH-туннелем: ssh -D 1080 user@bastion, затем curl --socks5 localhost:1080 URL.

Как аутентифицироваться на прокси-сервере в curl?

Используйте curl -x http://proxy:port -U user:password URL. Флаг -U (или --proxy-user) отправляет учётные данные на прокси. Это отдельно от -u, который аутентифицируется на целевом сервере.

Как исключить определённые хосты из прокси в curl?

Используйте --noproxy "localhost,127.0.0.1,*.internal.com" или задайте переменную окружения NO_PROXY. Поддерживает шаблоны (*.example.com). Используйте --noproxy "*", чтобы полностью обойти прокси для одного запроса.

Как протестировать HTTPS на localhost с помощью curl?

Для быстрого тестирования: curl -k https://localhost:8443/. Для корректной валидации: curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/. Подход с --resolve позволяет hostname сертификата совпадать правильно.

Как переопределить DNS-разрешение для конкретного хоста в curl?

Используйте curl --resolve host:port:IP URL. Пример: curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/. Это обходит DNS только для этой пары host:port — без редактирования /etc/hosts.

Как исправить ошибку 'SSL certificate problem: certificate has expired' в curl?

Срок действия сертификата сервера истёк. Решения: (1) Обновить сертификат на сервере, (2) Обновить CA-бандл: curl --cacert /path/to/updated-ca.pem URL, (3) Только для тестирования: curl -k URL. Проверить срок: curl -v URL 2>&1 | grep expire.

Безопасно ли использовать curl --insecure (-k) в production?

Нет. Флаг -k отключает всю валидацию сертификатов — срок действия, hostname и цепочку доверия. Это делает соединение уязвимым для атак «человек посередине». Всегда используйте --cacert с конкретным CA-сертификатом в production и CI/CD-пайплайнах.