Mã hóa WebSocket
Đăng ký GraphQL dùng khung nhị phân đã mã hóa.
Trang này trình bày WSS /graphql: khóa phiên xác thực các khung init, ack và thông điệp bằng thẻ XChaCha20-Poly1305. Các khung này không chứa chữ ký Ed25519 hoặc SignaturePurpose. Đăng nhập không mật khẩu ký ServerHello trên WSS /auth; xem phần Xác thực.
wss://<host>:<port>/graphql?cid=706c6169-3b80-8f42-9a61-4e312e54d001Gửi Init
Máy chủ xác minh Init và đọc clientNonce.
Chống phát lại
…/graphql?cid=<clientId>binding = SHA256(fields(initFrame, ackFrame))client → server: seq 1, 2, 3…server → client: seq 1, 2, 3…seq = lastReceived + 1lastReceived ← seqcloseKết nối lại: binding mới, đặt lại bộ đếm
Các tuyến WebSocket khác
key: Token phiên hiện có
wss://<host>:<port>/screen?cid=<clientId>Init · clientNonce
Máy chủ xác minh Init và đọc clientNonce.
Thao tác
1. Kết nối
Gửi Init sau khi socket mở. cid xác định máy khách.
const cid = '706c6169-3b80-8f42-9a61-4e312e54d001' // Your existing session's client ID
const socket = new WebSocket(
'wss://<device-host>:<https-port>/graphql?cid=' + encodeURIComponent(cid)
)
socket.binaryType = 'arraybuffer'
let binding: Uint8Array
let lastSent = 0n
let lastReceived = 0n2. Init máy khách
Gửi trong 10 giây. clientNonce: 32 byte ngẫu nhiên dạng 64 ký tự hex. nonce AEAD: 24 byte ngẫu nhiên cho mỗi khung.
// Run immediately on socket.open.
const init = {
clientNonce: Array.from(randomBytes(32), n => n.toString(16).padStart(2, '0')).join(''),
}
const aad = fields([utf8.encode('WS_INIT'), utf8.encode('/graphql'), utf8.encode(cid)])
const initFrame = seal(key, utf8.encode(JSON.stringify(init)), aad)
socket.send(initFrame) // Retain these exact bytes for Ack.3. Ack máy chủ
Xác minh Ack và tính binding, rồi gửi ngay xác nhận rỗng đã mã hóa tại sequence máy khách 1.
socket.addEventListener('message', event => {
const ackFrame = new Uint8Array(event.data)
if (ackFrame.length < 40) throw new Error('Invalid Ack')
const aad = fields([utf8.encode('WS_ACK'), utf8.encode('/graphql'), utf8.encode(cid), sha256(initFrame)])
const ack: { serverNonce: string } = JSON.parse(decoder.decode(open(key, ackFrame, aad)))
if (!/^[0-9a-f]{64}$/.test(ack.serverNonce)) throw new Error('Invalid serverNonce')
binding = sha256(fields([initFrame, ackFrame]))
lastSent = lastReceived = 0n
const counter = uint64be(1n)
const confirmationAad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('client'), counter])
const encrypted = seal(key, new Uint8Array(), confirmationAad)
lastSent = 1n
socket.send(concatBytes(counter, encrypted))
}, { once: true })4. Gửi thông điệp đã mã hóa
Dùng direction client và nonce mới. Xác nhận rỗng dùng sequence 1; nghiệp vụ bắt đầu tại sequence 2 và tăng nghiêm ngặt.
const message = {
type: 'subscribe', id: 'prefs',
payload: { query: 'subscription { prefsChanged }' },
}
const next = lastSent + 1n
const counter = uint64be(next) // Reject overflow; never wrap.
const aad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('client'), counter])
const encrypted = seal(key, utf8.encode(JSON.stringify(message)), aad)
lastSent = next // Advance only after successful encryption.
socket.send(concatBytes(counter, encrypted))5. Nhận thông điệp đã mã hóa
Yêu cầu lastReceived + 1 (đầu tiên: 1) và direction server. Chỉ tăng sau khi giải mã đã xác thực.
// For each binary message after Ack, in arrival order:
const frame = new Uint8Array(event.data)
if (frame.length < 48) throw new Error('Invalid frame')
const sequence = new DataView(frame.buffer).getBigUint64(0, false)
if (sequence !== lastReceived + 1n) throw new Error('Invalid sequence')
const aad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('server'), frame.subarray(0, 8)])
const plaintext = open(key, frame.subarray(8), aad) // Throws on invalid tag.
lastReceived = sequence // Advance only after authentication.
const message = JSON.parse(decoder.decode(plaintext))6. Loại thông điệp
Các thông điệp JSON của ứng dụng, kể cả ping/pong, được mã hóa. Khung điều khiển Ping/Pong gốc của WebSocket không được bọc trong lớp mã hóa này, nhưng TLS có thể bảo vệ chúng. subscriptionReady báo rằng đăng ký đã sẵn sàng.
const subscribe = {
type: 'subscribe', id: 'prefs',
payload: { query: 'subscription { prefsChanged }' },
}
const ready = {
type: 'next', id: 'prefs',
payload: { data: null, extensions: { subscriptionReady: true } },
}
const event = {
type: 'next', id: 'prefs',
payload: { data: { prefsChanged: true } },
}
const complete = { type: 'complete', id: 'prefs' }
const ping = { type: 'ping', payload: null }
const pong = { type: 'pong', payload: null }
const error = { type: 'error', id: 'prefs', payload: [{ message: '...' }] }7. Giới hạn và lỗi
Đóng khi lỗi xác thực hoặc số thứ tự. Kết nối lại bằng lần bắt tay mới.
Server Init wait: timeout(10 seconds, socket.next()), after upgrade and session-key lookup
Server confirmation: timeout(10 seconds, socket.next()), after Ack send completes
Confirmation: send encrypted empty payload immediately after Ack, client sequence 1
Business messages: client starts at sequence 2; server starts at sequence 1
Init replay: may receive a fresh Ack; old bound frames fail
Replay state: connection counters, no timestamp or global cache
Message sequence: last + 1, independently in each direction
Sequence overflow: u64 max once; next frame fails, never wrap to 0
Frame size: <= 1,048,576 bytes
Timeout/auth failure: close 1008, reason "invalid_subscription"
Reconnect: fresh Init / Ack, new binding, last counters reset to 0; no legacy fallback