Skip to content

ADR-0003. Mã hoá payload ECDH + AES-256-GCM bắt buộc trên /stream

TrườngGiá trị
StatusAccepted
Date2026-03-28
DecidersPhat Nguyen
Supersedes-

Bối cảnh

  • TLS kết thúc tại Traefik; sau đó, lưu lượng đi qua mạng nội bộ và một bus Redis dùng chung.
  • Payload WebSocket mang dữ liệu order/payment không nên bị đọc được ở bus hay bởi các kết nối khác cùng dùng chung hạ tầng.
  • Chúng ta muốn cô lập khoá theo từng kết nối và đạt forward secrecy mà không cần một service quản lý khoá riêng.

Quyết định

Chúng ta sẽ yêu cầu mã hoá payload đầu-cuối cho mọi kết nối /stream (requireEncryption: true):

  • Trong quá trình handshake, client gửi clientPublicKey; server sinh một cặp khoá ECDH P-256 tạm thời, dẫn xuất một khoá AES-256 qua HKDF-SHA-256, và lưu vào map _clientAesKeys trong bộ nhớ, đánh chỉ mục theo client id.
  • Server trả { serverPublicKey, salt } bên trong sự kiện connected để client dẫn xuất ra cùng một khoá.
  • Mọi message sau đó đều là AES-256-GCM { iv, ct }. Chỉ connectederror được gửi dưới dạng plaintext.
  • Khoá bị xoá khi ngắt kết nối và mất khi khởi động lại (client kết nối lại để dẫn xuất khoá mới).

Hệ quả

ƯuNhược
Payload không đọc được trên đường truyền, ở bus, và với các kết nối khácKhông lưu - khởi động lại buộc mọi client phải kết nối lại
Forward secrecy (khoá tạm thời cho mỗi kết nối)clientPublicKey là bắt buộc - client không hỗ trợ ECDH sẽ bị từ chối
Không cần KMS bên ngoàiMap khoá trong bộ nhớ chỉ giới hạn trong một process; phải dựa vào sticky socket + Redis để mở rộng

Phương án đã cân nhắc

Phương ánƯuNhượcVì sao loại
Chỉ TLS (không mã hoá payload)Đơn giản nhấtPlaintext sau Traefik + trên bus RedisKhông đủ an toàn cho dữ liệu payment
Khoá AES tĩnh dùng chungKhông cần handshakeKhông có forward secrecy; chỉ một lần rò rỉ là lộ tất cảPhạm vi ảnh hưởng quá lớn, không chấp nhận được
mTLS theo từng clientĐịnh danh mạnhQuản lý vòng đời cert nặng nề trên client POS/TauriBất khả thi về vận hành cho cả đội client

Tham chiếu

Proprietary and Confidential. Unauthorized copying, distribution, or use of this software is strictly prohibited.