Шифрование и TLS
Освоены список пользователей, цепочка ACME и auth callout, но все пока передают данные по открытому каналу. Учётные данные и JSON заказов читаемы наблюдателю соединения.
Добавим TLS, сертификат клиента как личность order-svc, TLS до первого байта протокола и шифрование JetStream на диске.
TLS каждого типа соединения
Есть клиентские, кластерные, листовые и шлюзовые соединения.
У каждого своя конфигурация. Верхний tls защищает только клиентов.
Мониторинг, WebSocket, MQTT, leafnodes, cluster и gateway имеют собственные вложенные tls. Клиентский TLS не шифрует маршруты автоматически.
Это позволяет разным моделям угроз иметь отдельные параметры. Здесь защищаем order-svc — сервер.
Серверный TLS
Нужны сертификат cert_file, закрытый ключ key_file и сертификат CA ca_file, которому доверяются сертификаты участников.
Для обучения создайте временный CA и серверный сертификат openssl:
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-keyout ca-key.pem -out ca.pem -subj "/CN=Acme Test CA" -days 30
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-keyout server-key.pem -out server.csr -subj "/CN=nats.acme.internal"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem \
-CAcreateserial -out server-cert.pem -days 30 \
-extfile <(printf "subjectAltName=DNS:nats.acme.internal,IP:127.0.0.1")
SAN включает DNS и loopback. Скопируйте три PEM в /etc/nats/certs/. Для эксплуатации используйте организационную PKI или публичный CA.
Добавьте tls:
# nats.conf — client connections now require TLS
listen: "0.0.0.0:4222"
tls {
cert_file: "/etc/nats/certs/server-cert.pem"
key_file: "/etc/nats/certs/server-key.pem"
ca_file: "/etc/nats/certs/ca.pem"
timeout: 2
}
Timeout — секунды установления TLS, стандарт 2. Короткий не даст медленным клиентам закончить, длинный удерживает зависшие подключения.
Проверьте nats-server -t -c nats.conf, затем запустите:
nats-server -c nats.conf
Журнал: TLS required for client connections. Открытый клиент отвергается до аутентификации.
Доверие CA на клиенте
До отправки секретов клиент проверяет сервер по доверенному CA своей цепочки сертификатов.
К прежнему подключению добавляется --tlsca; библиотеки принимают тот же PEM.
- CLI
#!/bin/sh
# Connect and publish as order-svc over TLS.
# The client trusts the CA that signed the server certificate (--tlsca),
# verifies the server's identity, then publishes the canonical order JSON
# over the now-encrypted connection.
nats pub orders.shipped \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server tls://nats.acme.internal:4222 \
--tlsca /etc/nats/certs/ca.pem
# Expected output:
# 14:22:18 Published 91 bytes to "orders.shipped"
14:22:18 Published 91 bytes to "orders.shipped"
91 байт теперь зашифрован в пути. Сам сервер является конечной точкой TLS и видит открытые данные; дальнейшая пересылка зависит от защиты следующих соединений.
Имя подключения должно совпадать с сертификатом. Только nats.acme.internal не покрывает прямой 127.0.0.1. Но подключение по имени, разрешившемуся в loopback, корректно, если DNS это допускает.
Шифры, кривые и закрепление — в TLS. Здесь cert_file, key_file, ca_file, timeout.
Сервер объявляет соседей через client_advertise для переподключений. Если объявлен IP, клиент должен трактовать его как обновление адреса DNS и при соединении с новым IP проверять исходное DNS-имя. Это правило именно для IP в обнаруженном списке.
Взаимный TLS и личность сертификата
MTLS также доказывает серверу личность клиента его сертификатом.
Сертификат обязан строить цепочку к серверному ca_file; это ещё не определяет пользователя.
verify_and_map: true проверяет и отображает: сначала email SAN, затем DNS, URI, затем subject DN RFC 2253. SAN используется при совпадении с пользователем, иначе возможен DN даже при наличии SAN.
Сертификат заменяет пароль и creds. DN сравнивается по правилам имён, а не простыми строками: пробелы и порядок атрибутов не мешают.
В ORDERS пользователь остаётся в своей учётной записи и получает прежние права orders.>. Имя заменяется на DN. ANALYTICS и остальная конфигурация прежние:
# nats.conf — the client certificate is the user
listen: "0.0.0.0:4222"
tls {
cert_file: "/etc/nats/certs/server-cert.pem"
key_file: "/etc/nats/certs/server-key.pem"
ca_file: "/etc/nats/certs/ca.pem"
verify_and_map: true
}
accounts {
ORDERS {
jetstream: enabled
users: [
{
user: "CN=order-svc,O=Acme"
permissions: {
publish: { allow: ["orders.>"] }
subscribe: { allow: ["_INBOX.>"] }
}
}
]
}
}
Выпустите сертификат тем же CA. Атрибуты openssl дают RFC 2253 CN=order-svc,O=Acme, как user:
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-keyout order-svc-key.pem -out order-svc.csr -subj "/O=Acme/CN=order-svc"
openssl x509 -req -in order-svc.csr -CA ca.pem -CAkey ca-key.pem \
-CAcreateserial -out order-svc-cert.pem -days 30
Клиент использует --tlscert и --tlskey вместо пароля:
- CLI
#!/bin/sh
# Connect and publish as order-svc over mutual TLS.
# The client still trusts the CA (--tlsca), but now also presents its own
# certificate (--tlscert) and private key (--tlskey). With verify_and_map
# on the server, the certificate's subject CN=order-svc,O=Acme IS the
# NATS user — no password, no creds file.
nats pub orders.shipped \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server tls://nats.acme.internal:4222 \
--tlsca /etc/nats/certs/ca.pem \
--tlscert /etc/nats/certs/order-svc-cert.pem \
--tlskey /etc/nats/certs/order-svc-key.pem
# Expected output:
# 14:23:05 Published 91 bytes to "orders.shipped"
14:23:05 Published 91 bytes to "orders.shipped"
Сервер связывает CN=order-svc,O=Acme с пользователем ORDERS и применяет права.
Правила DN сложнее равенства строк; сервер понимает в том числе множества атрибутов.
Verify_and_map включает verify, оба не нужны. Обычный verify используйте, если личность сертификата уже отображает внешняя система.
TLS-first
Обычно первым идёт открытый INFO с версией и URL, затем TLS до секретов.
На верхней дорожке INFO открыт, на нижней первый байт принадлежит TLS.
Handshake_first выполняет TLS до протокола, как HTTPS:
tls {
cert_file: "/etc/nats/certs/server-cert.pem"
key_file: "/etc/nats/certs/server-key.pem"
ca_file: "/etc/nats/certs/ca.pem"
handshake_first: true
}
Сервер предупреждает при запуске:
[WRN] Clients that are not using "TLS Handshake First" option will fail to connect
Ожидающий INFO клиент получит nats: error: read tcp ...: i/o timeout. В CLI нужен --tlsfirst, также у context save; библиотеки имеют аналог.
Для перехода auto/auto_fallback ждут TLS 50 мс, затем отправляют INFO. Строка 300ms задаёт другой период.
OpenSSL s_client на обычном NATS-порту получает wrong version number из-за INFO, не поломки TLS. При handshake_first работает как с обычной TLS-точкой.
Для GnuTLS CLI:
gnutls-cli --starttls --port 4222 server.host.name
После INFO нажмите Control-D для начала TLS.
Шифрование хранения
TLS не защищает диск. Шифрование хранения — отдельная общесерверная AEAD-защита данных и метаданных JetStream, не по записям. Оно независимо от транспортного TLS.
Шифрование блоков может выполнять контроллер диска без нагрузки CPU сервера. Оцените, требуется ли именно серверное шифрование.
Задайте key в jetstream через переменную окружения, не секретом в файле:
jetstream {
store_dir: "/data/jetstream"
key: $JS_KEY
}
JS_KEY="s3cr3t-master-key" nats-server -c nats.conf
Стандарт — ChaCha20-Poly1305, cipher: aes выбирает AES-GCM:
[INF] Encryption: ChaCha20-Poly1305
Для ротации перезапустите с новым key и старым prev_key. Сервер перепакует ключи потоков; затем запускайте только с новым. Prev_key нужен один переходный рестарт. TPM и прочее — в encryption_key.
Типичные ошибки
Ловушки канала и диска:
TLS без verify не проверяет клиента. Сервер доказывает себя, но не требует клиентский сертификат. Включите verify или verify_and_map и проверьте вход без сертификата:
- CLI
#!/bin/sh
# Prove that mTLS actually rejects a client with no certificate.
# Run this against a server that has verify: true (or verify_and_map: true).
#
# This connection trusts the CA so the link encrypts, but it sends NO
# client certificate. If the server enforces mTLS, the handshake fails.
# If it succeeds, the server is NOT checking client certs (verify is off)
# and your "mTLS" is encryption-only.
nats pub orders.shipped \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server tls://nats.acme.internal:4222 \
--tlsca /etc/nats/certs/ca.pem
# Expected against a verify-enabled server (no --tlscert / --tlskey given):
# nats: error: remote error: tls: certificate required
# The server log shows:
# [ERR] ... TLS handshake error: tls: client didn't provide a certificate
nats: error: remote error: tls: certificate required
Правильный результат — отказ и [ERR] ... TLS handshake error: tls: client didn't provide a certificate. Успех означает отсутствие проверки.
Verify_and_map требует существующую личность. CN=order-svc,O=Acme эквивалентен вариантам с пробелами и порядком, но неверное значение даёт nats: error: nats: Authorization Violation и authentication error. Читайте DN через openssl x509 -noout -subject, не набирайте вручную.
Кластеру и шлюзу нужны serverAuth и clientAuth. Одна сторона и принимает, и подключается; TLS всегда взаимный. Сертификат только serverAuth вызывает на соседе TLS route handshake error: ... certificate specifies an incompatible key usage. Обратное направление иногда сохраняет работающий кластер, поэтому ищите журнал, не только отсутствие маршрута. См. Кластеризацию, Листы, TLS.
Замена файлов требует reload. cert_file/key_file/ca_file читаются при запуске или SIGHUP, не при каждой установке связи. Существующие соединения сохраняют сессию, новые используют замену. Следите за сроком и применяйте nats-server --signal reload=<pid>; см. Защиту системы.
Handshake_first true закрывает старых клиентов. Сначала используйте 300ms для совместимости, затем true после перехода всех на tlsfirst.
Неверный дисковый ключ скрывает потоки, не уничтожает. Error decrypting our stream metafile: unable to recover keys исправляется рестартом с верным. После ротации удалите prev_key, не держите старый секрет активным.
Что уже готово
Order-svc использует TLS, при желании до INFO. Verify_and_map связывает сертификат с прежними правами ORDERS без пароля/creds. JetStream шифруется ключом вне конфигурации.
Кластер, листы и шлюзы всё ещё требуют собственных tls; см. Кластеризацию и Листы.
Что дальше
Последняя страница собирает модель и контрольный список.
Перейдите к итогам.
См. также
- TLS — шифры, кривые, pinning, OCSP.
- encryption_key — шифрование диска.
- Основы безопасности.
- Защита системы — ротация и наблюдение.