Tham chiếu API

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_RESPONSE

Rà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.

text
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

Kế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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
text
direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · đăng nhập không mật khẩu
AUTH_REQUEST / AUTH_RESPONSE

Rà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ý.

text
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

Thư 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

text
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 44 B

415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
text
direction = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 45 B

415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
WSS /graphql, /screen, /image_editor, /status · init
WS_INIT

Ràng buộc việc đăng ký với đường dẫn WebSocket và danh tính máy khách.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001

AAD · hex · 63 B

0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031
WSS /graphql, /screen, /image_editor, /status · ack
WS_ACK

Rà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.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · khung đã mã hóa
WS_FRAME

Rà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.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001
text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001
HTTP · yêu cầu đã mã hóa
HTTP_REQUEST

Rà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.

text
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

text
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"

AAD · hex · 26 B

485454505f524551554553542e504f53542e2f6772617068716c
text
method = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"

AAD · hex · 32 B

485454505f524551554553542e504f53542e2f67756573745f6772617068716c
text
method = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"

AAD · hex · 31 B

485454505f524551554553542e504f53542e2f706565725f6772617068716c
text
method = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"

AAD · hex · 23 B

485454505f524551554553542e504f53542e2f696e6974
text
method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"

AAD · hex · 25 B

485454505f524551554553542e504f53542e2f75706c6f6164
text
method = POST
endpoint = /upload_chunk
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload_chunk"

AAD · hex · 31 B

485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6b
URL tài nguyên · /fs, /zip/* và /proxy/*
FS / ZIP_FILES

Rà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.

text
{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

text
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

46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031
text
purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"

AAD · hex · 41 B

46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334
text
purpose = 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