Chữ ký và AAD
Chữ ký Ed25519 và dữ liệu xác thực bổ sung AEAD: điểm vào, định dạng byte, lý do và ví dụ cụ thể.
Chữ ký API
Các mục này dùng chữ ký Ed25519. Phần tử đầu của mỗi mảng được ký là giá trị SignaturePurpose; nó phân tách bằng chứng cho các thao tác khác nhau và không phải trường truyền riêng.
Các yêu cầu HTTP /graphql và /guest_graphql đã mã hóa cùng khung WSS /graphql dùng thẻ AEAD phiên mà không có chữ ký Ed25519. Yêu cầu API-token đến /graphql dùng xác thực Bearer. Các mục dưới nêu rõ yêu cầu, phản hồi hoặc tải trọng lồng nào mang chữ ký.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Lý do ký
- Ràng buộc danh tính thiết bị, ID máy khách và cả hai thông điệp bắt tay. Trình duyệt kiểm tra ServerHello đã ký trước khi dẫn xuất khóa kênh phê duyệt không mật khẩu.
- Ký và xác minh
- Thiết bị ký ServerHello; trình duyệt/máy khách kết nối xác minh bằng khóa công khai danh tính thiết bị.
- Mảng JSON được ký
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Lý do ký
- Xác thực thiết bị gửi bên cạnh mã hóa yêu cầu. Ràng buộc yêu cầu GraphQL gốc và ngữ cảnh kênh để bằng chứng không thể chuyển sang kênh khác. Độ mới UUIDv7 yêu cầu được kiểm tra riêng.
- Ký và xác minh
- Thiết bị ngang hàng gửi ký yêu cầu; bên nhận xác minh bằng khóa công khai danh tính đã lưu của bên gửi.
- Mảng JSON được ký
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId là giá trị thứ hai của mảng: rỗng với yêu cầu ngang hàng trực tiếp; nếu không, phải đúng ID kênh c-cid. Khi tính chữ ký, sắp xếp đệ quy các khóa đối tượng trong variables.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Lý do ký
- Ràng buộc danh tính yêu cầu, bên nhận dự kiến, thông tin thiết bị và khóa công khai ECDH. Bên nhận có thể phát hiện thay đổi trước khi dẫn xuất khóa chung; quét QR xác minh lời mời hiển thị với cùng purpose.
- Ký và xác minh
- Thiết bị yêu cầu ký; thiết bị nhận hoặc máy quét QR xác minh bằng signaturePublicKey của lời mời. Vẫn cần xác nhận người dùng hoặc đối chiếu danh tính tin cậy.
- Mảng JSON được ký
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Lý do ký
- Ràng buộc khóa công khai ECDH và thông tin kết nối của thiết bị chấp nhận với một requestId. Chấp nhận không liên quan hoặc đã sửa không thể hoàn tất ghép đôi đang chờ.
- Ký và xác minh
- Thiết bị chấp nhận ký; thiết bị yêu cầu xác minh bằng khóa công khai danh tính ngang hàng dự kiến.
- Mảng JSON được ký
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Lý do ký
- Xác thực ai đã từ chối yêu cầu đang chờ. Chỉ truyền requestId và signature; từ chối không thiết lập khóa chung.
- Ký và xác minh
- Thiết bị từ chối ký; thiết bị yêu cầu xác minh bằng khóa công khai danh tính ngang hàng dự kiến.
- Mảng JSON được ký
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Lý do ký
- Ràng buộc danh tính thiết bị quét và thông tin chấp nhận với đúng lời mời đã quét. Chữ ký Ed25519 bên ngoài xác thực thiết bị quét; HMAC ràng buộc phản hồi với request.signature.
- Ký và xác minh
- Thiết bị quét ký; thiết bị hiển thị QR xác minh bằng signaturePublicKey của thiết bị quét trong phản hồi và kiểm tra ràng buộc yêu cầu đã quét.
- Mảng JSON được ký
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
Khi chấp nhận QR, acceptSignedArrayJSON là chuỗi JSON thu gọn của mảng PAIRING_ACCEPT, có danh tính và tên thiết bị quét. Thiết bị quét ký mảng QR_PAIR_ACCEPT thay vì ký trực tiếp mảng bên trong. Khóa HMAC là chuỗi request.signature UTF-8, không phải các byte đã giải mã Base64.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Lý do ký
- Xác thực việc hủy và ràng buộc với requestSignature gốc cùng hai thiết bị, ngăn hủy một lần ghép đôi khác.
- Ký và xác minh
- Thiết bị hủy ký; thiết bị nhận xác minh danh tính và đối chiếu yêu cầu đang chờ.
- Mảng JSON được ký
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Lý do ký
- Xác thực thiết bị ngang hàng kết nối và ràng buộc bằng chứng với toàn bộ khung init và ack đã mã hóa của kết nối này, ngăn tái sử dụng giữa các kết nối.
- Ký và xác minh
- Thiết bị ngang hàng kết nối ký bằng chứng máy khách; máy chủ trạng thái xác minh bằng khóa công khai danh tính ngang hàng đã lưu.
- Mảng JSON được ký
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Lý do ký
- Mang bằng chứng thành viên có thể xác minh trong tải trọng thông điệp hệ thống, ngoài chữ ký yêu cầu ngang hàng bên ngoài. Ràng buộc kênh, phiên bản, hành động và đích; bên nhận thực thi quyền chủ sở hữu/thành viên riêng.
- Ký và xác minh
- Chủ sở hữu hoặc thành viên hành động ký tùy thao tác; thành viên nhận xác minh danh tính và quyền tương ứng.
- Mảng JSON được ký
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Lý do ký
- Ràng buộc vân tay SHA-256 chứng chỉ TLS được công bố với danh tính thiết bị. Proxy ngang hàng được quản lý xác minh bằng chứng này trước khi tin vân tay chứng chỉ.
- Ký và xác minh
- Thiết bị ký tlsCertificateSignature trong phản hồi /init; proxy được quản lý kết nối vào xác minh bằng khóa công khai danh tính thiết bị dự kiến.
- Mảng JSON được ký
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose là giá trị trong tiêu đề mục. Tuần tự hóa mảng đã cho thành JSON thu gọn, mã hóa UTF-8 rồi ký bằng khóa danh tính Ed25519 của bên gửi; signature là Base64. Giữ nguyên thứ tự trường, kiểu và chuỗi JSON gốc. Chữ ký xác định bên ký; độ mới và quyền được kiểm tra riêng.
Tham chiếu AAD
AAD được xác thực cùng bản mã, nhưng không được mã hóa hoặc thêm thành trường riêng trong khung. Hai bên dựng lại cùng các byte; mọi sai khác đều làm xác minh thẻ thất bại. Ví dụ dùng lại các khung xác thực và WebSocket giả lập trong tài liệu này.
Dấu hai gạch đứng trong công thức biểu thị phép nối byte. 0x00 là một byte bằng không. fields(x₁, …, xₙ) nối từng uint32be(byteLength(xᵢ)) rồi đến xᵢ. SHA256 trả về 32 byte thô; hex chỉ dùng để hiển thị. JSON.stringify nghĩa là JSON thu gọn với thứ tự trường đã chỉ định. Mỗi chiều WebSocket bắt đầu chuỗi riêng từ 1.
WSS /auth · đăng nhập bằng mật khẩu
AUTH_REQUEST / AUTH_RESPONSERàng buộc thông tin máy khách đã mã hóa và kết quả phê duyệt với danh tính máy khách và máy chủ này; phân biệt chiều yêu cầu và phản hồi.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestKết quả đăng nhập OPAQUE Rust/WASM trả về requestAad và responseAad. Dùng trực tiếp chúng mà không tự dựng ngữ cảnh nội bộ. digest là phần giá trị băm 32 byte, không phải trường yêu cầu bổ sung. LOGIN_PASSWORD được cố định trong thư viện đăng nhập; bên gọi không cung cấp tham số purpose.
Đầu vào cụ thể và các byte AAD
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · đăng nhập không mật khẩu
AUTH_REQUEST / AUTH_RESPONSERàng buộc các thông điệp phê duyệt đã mã hóa với lần bắt tay này, bao gồm cả hai khóa công khai tạm thời và phản hồi máy chủ đã ký.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestThư viện bắt tay quản lý AAD nội bộ. Dùng encryptRequest và decryptResponse mà không tự dựng ngữ cảnh nội bộ. digest là phần giá trị băm 32 byte, không phải trường yêu cầu bổ sung. LOGIN_NO_PASSWORD được cố định trong thư viện đăng nhập; bên gọi không cung cấp tham số purpose.
Đầu vào cụ thể và các byte AAD
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INITRàng buộc việc đăng ký với đường dẫn WebSocket và danh tính máy khách.
fields(WS_INIT, path, cid)path là đường dẫn logic, không có lược đồ, máy chủ hoặc chuỗi truy vấn. cid là ID máy khách gốc trước khi mã hóa URL. Ví dụ dùng /graphql.
Đầu vào cụ thể và các byte AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKRàng buộc xác nhận với đúng khung init đã mã hóa, đường dẫn và danh tính máy khách.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame là toàn bộ dữ liệu nhị phân nonce + ciphertext + tag, không phải JSON init đã giải mã. SHA256(initFrame) được đưa vào dưới dạng 32 byte thô.
Đầu vào cụ thể và các byte AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · khung đã mã hóa
WS_FRAMERàng buộc từng khung với lần bắt tay kết nối, chiều gửi và số thứ tự, ngăn tái sử dụng ở kết nối hoặc chiều khác.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame và ackFrame là các khung nhị phân đã mã hóa hoàn chỉnh. direction là client hoặc server theo bên gửi. sequence được mã hóa bằng tám byte big-endian; ví dụ hiển thị 1 ở cả hai chiều độc lập, kể cả khung xác nhận rỗng.
Đầu vào cụ thể và các byte AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001HTTP · yêu cầu đã mã hóa
HTTP_REQUESTRàng buộc dữ liệu đã mã hóa với phương thức HTTP logic và điểm cuối, ngăn tái sử dụng tại điểm cuối REST khác.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload và /upload_chunk đều dùng HTTP_REQUEST. Tải lên multipart ràng buộc siêu dữ liệu info đã mã hóa. Chuyển tiếp Proxy/BLE/Aware dùng đường dẫn đích logic, không dùng URL proxy.
Phản hồi đã mã hóa xác minh thẻ với AAD rỗng. Bản rõ là 0x00 + SHA256(yêu cầu mã hóa gốc) + JSON phản hồi; máy khách kiểm tra giá trị băm yêu cầu sau khi giải mã.
Đầu vào cụ thể và các byte AAD
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"AAD · hex · 26 B
485454505f524551554553542e504f53542e2f6772617068716cmethod = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"AAD · hex · 32 B
485454505f524551554553542e504f53542e2f67756573745f6772617068716cmethod = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f706565725f6772617068716cmethod = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"AAD · hex · 23 B
485454505f524551554553542e504f53542e2f696e6974method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"AAD · hex · 25 B
485454505f524551554553542e504f53542e2f75706c6f6164method = POST
endpoint = /upload_chunk
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload_chunk"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bURL tài nguyên · /fs, /zip/* và /proxy/*
FS / ZIP_FILESRàng buộc tải trọng URL đã mã hóa với mục đích, phạm vi phiên/chia sẻ và chủ sở hữu.
{purpose}.{mode}.{owner}FS bao gồm xem trước tệp, tải thư mục, tài nguyên proxy và tham chiếu tệp đính kèm; ZIP_FILES dành cho lựa chọn lưu trữ. mode là c cho phiên hoặc s cho chia sẻ; owner là ID máy khách của phiên hoặc ID chia sẻ.
Đầu vào cụ thể và các byte AAD
purpose = FS
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "FS.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 41 B
46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"AAD · hex · 41 B
46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334purpose = ZIP_FILES
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "ZIP_FILES.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 48 B
5a49505f46494c45532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031