Настройка сертификата кеша

Выберите вариант TLS для режима кеша#

Нет суффикса _cache- в пароле? Ничего менять не нужно. Обычный режим прокси сохраняет сквозной TLS и не требует установки сертификата или изменений TLS на клиенте для незашифрованного эндпоинта прокси http://. Эндпоинт прокси https:// — единственное исключение: сертификат его хаба выстраивается в цепочку до этого же корневого сертификата, поэтому доверяйте ему для соединения с прокси, как описано в разделе HTTP- и HTTPS-эндпоинт прокси. Одно это доверие никогда не включает режим кеша.

При включённом режиме кеша выберите один из вариантов:

Если пропустить проверку, клиент не сможет аутентифицировать сертификаты целевых сайтов. Никогда не используйте этот вариант для входа в аккаунты, платежей, закрытых API, cookie или конфиденциального трафика.

URL прокси может начинаться с http://, потому что он указывает на эндпоинт HTTP-прокси. Целевой сайт при этом остаётся https://example.com/...; схема эндпоинта прокси и схема целевого сайта — это разные вещи.

Отключение проверки для изолированной автоматизации с публичными данными#

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

curl#

curl --insecure --proxy 'http://hub-us-7.litport.net:PORT' \
  --proxy-user 'USER:PASSWORD_cache-scripts' \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

Python Requests#

import requests

requests.get(
    'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js',
    proxies={'https': 'http://USER:[email protected]:PORT'},
    verify=False,
    timeout=30,
)

Node#

NODE_TLS_REJECT_UNAUTHORIZED=0 node scraper.mjs

Настройте HTTP-прокси в этом изолированном процессе Node. Эта настройка окружения отключает проверку сертификатов для этого процесса; не задавайте её для сервиса общего назначения.

Автоматизация браузера#

import { chromium } from 'playwright'

const browser = await chromium.launch({ proxy: {
  server: 'http://hub-us-7.litport.net:PORT',
  username: 'USER',
  password: 'PASSWORD_cache-scripts',
}})
const context = await browser.newContext({ ignoreHTTPSErrors: true })
await (await context.newPage()).goto('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js')

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

Go#

proxyURL, err := url.Parse("http://USER:[email protected]:PORT")
if err != nil { log.Fatal(err) }
client := &http.Client{Transport: &http.Transport{
  Proxy: http.ProxyURL(proxyURL),
  TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, // public-data-only isolated client
}}
response, err := client.Get("https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js")

Доверять корневому сертификату Litport (рекомендуется)#

Два проверяемых TLS-участка#

В режиме кеша клиентское TLS-соединение завершается на выбранном хабе Litport, чтобы он мог прочитать подходящий ответ и позже отдать локальную копию. Клиент проверяет выпущенный сертификат целевого сайта по корневому сертификату кеша Litport. Отдельно хаб проверяет настоящий сертификат и имя хоста исходного сервера, прежде чем читать его ответ. Оставляйте проверку включённой на обеих границах доверия.

У цели с HTTP нет аутентифицированной идентичности исходного сервера, и она остаётся на обычном пути прокси. Для режима кеша используйте цель с HTTPS.

Опубликованные данные корневого сертификата#

Скачать: https://litport.net/certificates/litport-cache-root.crt

Машиночитаемые данные (необязательно): litport-cache-root.json

Отпечаток — это хеш DER-представления сертификата. Контрольная сумма файла — это хеш байтов скачанного PEM-файла, включая текстовую кодировку и окончания строк, поэтому эти значения SHA-256 различаются.

curl --fail --remote-name https://litport.net/certificates/litport-cache-root.crt
openssl x509 -in litport-cache-root.crt -noout -subject -issuer -dates -fingerprint -sha256
sha256sum litport-cache-root.crt

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

Что разрешает установка корневого сертификата#

Публичный корневой сертификат позволяет вашему клиенту проверять сертификаты целевых сайтов, выпущенные иерархией CA кеша Litport. Тот же корневой сертификат проверяет и сертификат, который хаб предъявляет на своём эндпоинте прокси https://; см. HTTP- и HTTPS-эндпоинт прокси. Закрытый ключ корневого сертификата Litport хранит офлайн; на хабы он не передаётся. Каждый хаб получает собственный промежуточный сертификат и закрытый ключ, поэтому при компрометации одного хаба ключ корневого сертификата не раскрывается.

В соединении с включённым кешем выбранный хаб может читать HTTPS-запрос и ответ. Установка корневого сертификата на уровне системы также заставляет каждое приложение, использующее это системное хранилище, принимать сертификаты, выпущенные иерархией кеша Litport. Ограничивайте доверие клиентом кеша или его выделенным контейнером, используйте режим кеша только для публичных статических данных и удаляйте корневой сертификат, когда нагрузке он больше не нужен. Без корректного суффикса _cache- Litport оставляет HTTPS-туннель непрозрачным, даже если корневой сертификат остаётся установленным.

Настройка клиента#

Предпочитайте доверие на уровне процесса, профиля или выделенного контейнера. Системное доверие широко: все приложения, использующие это хранилище, могут доверять сертификатам, выпущенным этим корневым сертификатом. Замените USER, PASSWORD и PORT; закодируйте зарезервированные символы URL в процентной кодировке и никогда не коммитьте секреты прокси.

curl --proxy 'http://hub-us-7.litport.net:PORT' \
  --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

import requests

requests.get(
    "https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js",
    proxies={"https": "http://USER:[email protected]:PORT"},
    verify="litport-cache-root.crt",
    timeout=30,
)

NODE_EXTRA_CA_CERTS=./litport-cache-root.crt node scraper.js

// Configure the Litport HTTP proxy in your Node client.
// Keep rejectUnauthorized at its default true.

// Trust litport-cache-root.crt in the isolated browser/profile
// trust store actually used by the automation browser.
// Keep ignoreHTTPSErrors: false.
// Do not use --ignore-certificate-errors.

pool, _ := x509.SystemCertPool()
pem, _ := os.ReadFile("litport-cache-root.crt")
pool.AppendCertsFromPEM(pem)
transport := &http.Transport{
    Proxy: http.ProxyURL(proxyURL),
    TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
}

keytool -importcert -alias litport-cache \
  -file litport-cache-root.crt \
  -keystore ./litport-cache-truststore.p12 \
  -storetype PKCS12

java -Djavax.net.ssl.trustStore=./litport-cache-truststore.p12 App

<network-security-config>
  <base-config>
    <trust-anchors><certificates src="system" /></trust-anchors>
  </base-config>
  <debug-overrides>
    <trust-anchors>
      <certificates src="@raw/litport_cache_root" />
    </trust-anchors>
  </debug-overrides>
</network-security-config>

1. Установите корневой профиль Litport.
2. Откройте Настройки → Основные → Об этом устройстве → Доверие сертификатам.
3. Включите полное доверие для корневого сертификата Litport.
4. Удалите профиль, когда проверка режима кеша закончена.

curl#

--cacert заменяет для этого запроса набор CA curl по умолчанию. Если целевому сайту нужен другой приватный CA, объедините необходимые корневые сертификаты в отдельном наборе.

curl --proxy 'http://hub-us-7.litport.net:PORT' --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt --verbose \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

Python Requests, httpx и aiohttp#

Файл verify в Requests заменяет набор по умолчанию. Для httpx и aiohttp сначала создайте контекст по умолчанию, затем вызовите load_verify_locations(), чтобы добавить этот корневой сертификат к системным.

import asyncio, ssl
import aiohttp, httpx, requests
proxy = 'http://USER:[email protected]:PORT'
url = 'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'
requests.get(url, proxies={'https': proxy}, verify='litport-cache-root.crt', timeout=30)
context = ssl.create_default_context()
context.load_verify_locations(cafile='litport-cache-root.crt')
httpx.get(url, proxy=proxy, verify=context, timeout=30)
async def fetch():
    async with aiohttp.ClientSession(connector=aiohttp.TCPConnector(ssl=context)) as session:
        async with session.get(url, proxy=proxy) as response: return await response.read()
asyncio.run(fetch())

HTTPS-клиенты Node#

NODE_EXTRA_CA_CERTS добавляет корневые сертификаты в Node. Трафик направляет настоящий агент HTTPS-прокси; оставьте rejectUnauthorized со значением по умолчанию true.

npm install https-proxy-agent
NODE_EXTRA_CA_CERTS=./litport-cache-root.crt node scraper.mjs

import https from 'node:https'
import { HttpsProxyAgent } from 'https-proxy-agent'
const agent = new HttpsProxyAgent('http://USER:[email protected]:PORT')
https.get('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js', { agent }, response => response.resume())

Эта настройка не затрагивает трафик Chromium, Playwright и Puppeteer.

Автоматизация браузера#

Установите корневой сертификат в хранилище ОС или NSS изолированного профиля браузера. Оставьте ignoreHTTPSErrors: false и не используйте --ignore-certificate-errors.

import { chromium } from 'playwright'
const browser = await chromium.launch({ proxy: {
  server: 'http://hub-us-7.litport.net:PORT', username: 'USER', password: 'PASSWORD_cache-scripts',
}})
const context = await browser.newContext({ ignoreHTTPSErrors: false })
await (await context.newPage()).goto('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js')

Go#

pool, err := x509.SystemCertPool()
if err != nil || pool == nil { pool = x509.NewCertPool() }
pem, err := os.ReadFile("litport-cache-root.crt")
if err != nil || !pool.AppendCertsFromPEM(pem) { log.Fatal("could not add Litport root") }
proxyURL, err := url.Parse("http://USER:[email protected]:PORT")
if err != nil { log.Fatal(err) }
client := &http.Client{Transport: &http.Transport{
  Proxy: http.ProxyURL(proxyURL),
  TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
}}
response, err := client.Get("https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js")

SystemCertPool вместе с AppendCertsFromPEM сохраняет системные корневые сертификаты и добавляет к ним этот.

Java#

Выделенный truststore действует на уровне процесса, но заменяет набор Java по умолчанию. Импортируйте другие необходимые корневые сертификаты в это выделенное хранилище.

keytool -importcert -noprompt -alias litport-cache -file litport-cache-root.crt \
  -keystore ./litport-cache-truststore.p12 -storetype PKCS12 -storepass changeit
java -Djavax.net.ssl.trustStore=./litport-cache-truststore.p12 \
  -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=changeit App

Установка и удаление в общих хранилищах доверенных сертификатов#

Используйте их только тогда, когда доверие на уровне процесса или профиля недоступно; они действуют и на другие приложения.

Debian и Ubuntu#

sudo install -m 0644 litport-cache-root.crt /usr/local/share/ca-certificates/litport-cache-root.crt
sudo update-ca-certificates
# Remove: sudo rm /usr/local/share/ca-certificates/litport-cache-root.crt && sudo update-ca-certificates

RHEL и Fedora#

sudo install -m 0644 litport-cache-root.crt /etc/pki/ca-trust/source/anchors/litport-cache-root.crt
sudo update-ca-trust extract
# Remove: sudo rm /etc/pki/ca-trust/source/anchors/litport-cache-root.crt && sudo update-ca-trust extract

macOS#

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain litport-cache-root.crt
# Remove: sudo security delete-certificate -c 'Litport cache root CA' /Library/Keychains/System.keychain

Windows#

Выполните в PowerShell с правами администратора:

certutil -addstore -f Root .\litport-cache-root.crt
# Remove: certutil -delstore Root "Litport cache root CA"

Firefox и NSS#

Задайте в FIREFOX_PROFILE каталог профиля с cert9.db; в Debian/Ubuntu сначала установите libnss3-tools.

certutil -A -n 'Litport cache root' -t 'C,,' -i litport-cache-root.crt -d "sql:$FIREFOX_PROFILE"
# Remove: certutil -D -n 'Litport cache root' -d "sql:$FIREFOX_PROFILE"

Контейнеры и Kubernetes#

Используйте выделенный образ нагрузки или монтирование только для чтения во время выполнения вместо доверия на уровне хоста. Для Node:

COPY litport-cache-root.crt /opt/litport/litport-cache-root.crt
ENV NODE_EXTRA_CA_CERTS=/opt/litport/litport-cache-root.crt

Обновление системного хранилища дистрибутива делает сертификат доверенным для каждого процесса в контейнере. Для Kubernetes создайте ConfigMap из скачанного публичного PEM-файла, затем монтируйте его только в ту нагрузку, которой нужен режим кеша:

kubectl create configmap litport-cache-root --from-file=litport-cache-root.crt

# Pod template fragment
spec:
  containers:
    - name: client
      env:
        - name: NODE_EXTRA_CA_CERTS
          value: /var/run/litport-ca/litport-cache-root.crt
      volumeMounts:
        - { name: litport-cache-root, mountPath: /var/run/litport-ca, readOnly: true }
  volumes:
    - name: litport-cache-root
      configMap: { name: litport-cache-root }

Android#

Приложения Android 7.0+ обычно не доверяют CA, добавленным пользователем. Встроенный в приложение CA даёт узкое доверие: включите этот PEM-файл в отладочную сборку и доверяйте только ему. src="user" доверяет каждому CA, установленному пользователем, и это шире, чем следует допускать большинству приложений в продакшене. Android описывает эти источники доверия и отладочные переопределения в документе Конфигурация сетевой безопасности.

<!-- AndroidManifest.xml -->
<application android:networkSecurityConfig="@xml/network_security_config" />

Релизная сборка сохраняет обычные системные корневые сертификаты:

<!-- src/main/res/xml/network_security_config.xml -->
<network-security-config><base-config><trust-anchors><certificates src="system" /></trust-anchors></base-config></network-security-config>

Отладочная сборка добавляет встроенный корневой сертификат Litport:

<!-- src/debug/res/xml/network_security_config.xml -->
<network-security-config>
  <base-config><trust-anchors><certificates src="system" /></trust-anchors></base-config>
  <debug-overrides><trust-anchors><certificates src="@raw/litport_cache_root" /></trust-anchors></debug-overrides>
</network-security-config>

Поместите PEM-файл в src/debug/res/raw/litport_cache_root.pem. Стороннее приложение, политику доверия которого нельзя изменить, несовместимо с режимом кеша с проверкой сертификата; уберите суффикс _cache-.

iPhone и iPad#

Установите скачанный профиль корневого сертификата, затем завершите установку в Настройки → Основные → VPN и управление устройством. В Настройки → Основные → Об этом устройстве → Доверие сертификатов включите полное доверие для корневого сертификата Litport. Удалите его через VPN и управление устройством → профиль → Удалить профиль. Управляемые устройства должны устанавливать и удалять ту же конфигурацию через MDM. Приложение с собственной политикой или закреплением сертификата всё равно может отклонить соединение. Apple описывает отдельный шаг полного доверия в статье Доверие вручную установленным профилям сертификатов.

Проверка конфигурации#

1. Выполните контрольный запрос без суффикса: для него не нужен корневой сертификат, и он работает как обычный запрос через прокси.
2. Выполните тот же HTTPS-запрос с корректным паролем с включённым кешем и включённой проверкой сертификата.
3. Повторите тот же запрос на тот же хаб. Проверьте статистику кеша: сначала должен быть промах, затем попадание; не рассчитывайте на собственные заголовки кеша.
4. Добавьте --verbose к проверяемому запросу curl и убедитесь, что проверка сертификата проходит успешно, а показанный издатель относится к иерархии кеша Litport.
5. При смене хаба возможен промах, потому что записи локальны для хаба; новый корневой сертификат для этого не нужен.

curl --proxy 'http://hub-us-7.litport.net:PORT' --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt --verbose --output /dev/null \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

Типичные проблемы с сертификатом#

Ротация и безопасность данных для подключения#

При ротации сверьте опубликованные отпечаток и контрольную сумму файла нового PEM, доверяйте обоим корневым сертификатам на заявленный период перекрытия, проверьте режим кеша, а затем после перекрытия удалите старый корневой сертификат из каждого выделенного набора, профиля браузера, образа и конфигурации управляемых устройств. Используйте URL прокси в кавычках и --proxy-user, где это возможно; используйте хранилище секретов или передаваемую переменную окружения, кодируйте зарезервированные символы URL в процентной кодировке и никогда не коммитьте секреты прокси или историю команд, содержащую пароли.

Вернитесь к быстрому старту кеша или параметрам и устранению неполадок.