# Шифрование и 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 своей цепочки сертификатов.

К прежнему [подключению](/learn/security/authentication-basics.md) добавляется --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](/reference/config/tls/.md). Здесь cert\_file, key\_file, ca\_file, timeout.

Сервер объявляет соседей через client\_advertise для переподключений. Если объявлен IP, клиент должен трактовать его как обновление адреса DNS и при соединении с новым IP проверять исходное DNS-имя. Это правило именно для IP в обнаруженном списке.

## Взаимный TLS и личность сертификата

**MTLS** также доказывает серверу личность клиента его сертификатом.

Сертификат обязан строить цепочку к серверному ca\_file; это ещё не определяет пользователя.

[`verify_and_map: true`](/reference/config/tls/verify_and_map.md) проверяет и отображает: сначала email SAN, затем DNS, URI, затем subject DN RFC 2253. SAN используется при совпадении с пользователем, иначе возможен DN даже при наличии SAN.

Сертификат заменяет пароль и creds. DN сравнивается по правилам имён, а не простыми строками: пробелы и порядок атрибутов не мешают.

В ORDERS пользователь остаётся в своей [учётной записи](/learn/security/accounts-and-multitenancy.md) и получает прежние [права orders.>](/learn/security/authorization.md). Имя заменяется на 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 до секретов.

**Движение сообщений — Обычное рукопожатие и TLS-first (анимация):** Две временные шкалы соединения. При обычном рукопожатии INFO сервера с версией и URL подключения передаётся открыто, затем связь переходит на TLS до передачи учётных данных. При handshake\_first TLS выполняется до любого байта протокола, поэтому INFO приходит уже зашифрованным, как у HTTPS-сервера. Учётные данные зашифрованы в обоих режимах; TLS-first устраняет именно открытую строку INFO первого варианта.

* клиент → NATS (обычный режим)
* NATS (обычный режим) → клиент
* клиент (--tlsfirst) → NATS (handshake\_first)
* NATS (handshake\_first) → клиент (--tlsfirst)

На верхней дорожке 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](/reference/config/jetstream/encryption_key.md).

## Типичные ошибки

Ловушки канала и диска:

**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`. Обратное направление иногда сохраняет работающий кластер, поэтому ищите журнал, не только отсутствие маршрута. См. [Кластеризацию](/learn/clustering/.md), [Листы](/learn/topologies/leaf-nodes.md), [TLS](/reference/config/tls/.md).

**Замена файлов требует reload.** cert\_file/key\_file/ca\_file читаются при запуске или SIGHUP, не при каждой установке связи. Существующие соединения сохраняют сессию, новые используют замену. Следите за сроком и применяйте `nats-server --signal reload=<pid>`; см. [Защиту системы](/learn/deployment/hardening.md).

**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; см. [Кластеризацию](/learn/clustering/.md) и [Листы](/learn/topologies/leaf-nodes.md).

## Что дальше

Последняя страница собирает модель и контрольный список.

Перейдите к [итогам](/learn/security/where-next.md).

## См. также

* [TLS](/reference/config/tls/.md) — шифры, кривые, pinning, OCSP.
* [encryption\_key](/reference/config/jetstream/encryption_key.md) — шифрование диска.
* [Основы безопасности](/concepts/security.md).
* [Защита системы](/learn/deployment/hardening.md) — ротация и наблюдение.
