API संदर्भ

हस्ताक्षर और AAD

Ed25519 हस्ताक्षर और AEAD अतिरिक्त प्रमाणित डेटा: प्रवेश बिंदु, बाइट प्रारूप, कारण और ठोस उदाहरण।

API हस्ताक्षर

ये प्रविष्टियाँ Ed25519 हस्ताक्षर उपयोग करती हैं। हर हस्ताक्षरित ऐरे की पहली वस्तु उसका SignaturePurpose मान है; यह अलग-अलग कार्रवाइयों के प्रमाण अलग करता है और अलग संचार फ़ील्ड नहीं है।

एन्क्रिप्टेड HTTP /graphql और /guest_graphql अनुरोध तथा WSS /graphql फ़्रेम, Ed25519 हस्ताक्षर के बिना सत्र AEAD टैग उपयोग करते हैं। /graphql के API-टोकन अनुरोध Bearer प्रमाणीकरण उपयोग करते हैं। नीचे की प्रविष्टियाँ बताती हैं कि किस अनुरोध, प्रतिक्रिया या नेस्टेड पेलोड में हस्ताक्षर होता है।

AUTH_SERVER_HELLO · WSS /auth · ServerHello
हस्ताक्षर का कारण
डिवाइस पहचान, क्लाइंट ID और दोनों हैंडशेक संदेश बाँधता है। ब्राउज़र पासवर्ड-रहित अनुमोदन चैनल कुंजी निकालने से पहले हस्ताक्षरित ServerHello जाँचता है।
हस्ताक्षर और सत्यापन पक्ष
डिवाइस ServerHello पर हस्ताक्षर करता है; कनेक्ट होने वाला ब्राउज़र/क्लाइंट डिवाइस की पहचान सार्वजनिक कुंजी से सत्यापन करता है।
हस्ताक्षरित JSON ऐरे
javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
हस्ताक्षर का कारण
अनुरोध एन्क्रिप्शन के साथ भेजने वाले डिवाइस को प्रमाणित करता है। मूल GraphQL अनुरोध और चैनल संदर्भ को बाँधता है ताकि प्रमाण दूसरे चैनल में न ले जाया जा सके। अनुरोध UUIDv7 की समय वैधता अलग जाँची जाती है।
हस्ताक्षर और सत्यापन पक्ष
भेजने वाला पीयर अनुरोध पर हस्ताक्षर करता है; प्राप्तकर्ता पीयर प्रेषक की सहेजी गई पहचान सार्वजनिक कुंजी से सत्यापन करता है।
हस्ताक्षरित JSON ऐरे
javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]

channelId ऐरे का दूसरा मान है: सीधे पीयर अनुरोधों के लिए खाली; अन्यथा ठीक c-cid चैनल ID। हस्ताक्षर की गणना के लिए variables के सभी स्तरों पर ऑब्जेक्ट की कुंजियाँ क्रमबद्ध करें।

PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
हस्ताक्षर का कारण
अनुरोध करने वाले की पहचान, इच्छित प्राप्तकर्ता, डिवाइस विवरण और ECDH सार्वजनिक कुंजी बाँधता है। प्राप्तकर्ता साझा कुंजी निकालने से पहले बदलाव पहचान सकता है; QR स्कैनिंग भी उसी purpose से दिखाए गए आमंत्रण को सत्यापित करती है।
हस्ताक्षर और सत्यापन पक्ष
अनुरोध करने वाला डिवाइस हस्ताक्षर करता है; प्राप्तकर्ता डिवाइस या QR स्कैनर आमंत्रण के signaturePublicKey से सत्यापन करता है। उपयोगकर्ता पुष्टि या विश्वसनीय पहचान से मिलान अभी भी आवश्यक है।
हस्ताक्षरित JSON ऐरे
javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
हस्ताक्षर का कारण
स्वीकार करने वाले डिवाइस की ECDH सार्वजनिक कुंजी और कनेक्शन विवरण को एक requestId से बाँधता है। असंबंधित या बदली गई स्वीकृति लंबित युग्मन पूरा नहीं कर सकती।
हस्ताक्षर और सत्यापन पक्ष
स्वीकार करने वाला डिवाइस हस्ताक्षर करता है; अनुरोध करने वाला डिवाइस अपेक्षित पीयर पहचान सार्वजनिक कुंजी से सत्यापन करता है।
हस्ताक्षरित JSON ऐरे
javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
हस्ताक्षर का कारण
लंबित अनुरोध अस्वीकार करने वाले की पहचान प्रमाणित करता है। केवल requestId और signature भेजे जाते हैं; अस्वीकृति साझा कुंजी स्थापित नहीं करती।
हस्ताक्षर और सत्यापन पक्ष
अस्वीकार करने वाला डिवाइस हस्ताक्षर करता है; अनुरोध करने वाला डिवाइस अपेक्षित पीयर पहचान सार्वजनिक कुंजी से सत्यापन करता है।
हस्ताक्षरित JSON ऐरे
javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
हस्ताक्षर का कारण
स्कैनर की पहचान और स्वीकृति विवरण को ठीक स्कैन किए गए आमंत्रण से बाँधता है। बाहरी Ed25519 हस्ताक्षर स्कैनर प्रमाणित करता है; HMAC प्रतिक्रिया को request.signature से बाँधता है।
हस्ताक्षर और सत्यापन पक्ष
स्कैन करने वाला डिवाइस हस्ताक्षर करता है; QR दिखाने वाला डिवाइस उत्तर में स्कैनर के signaturePublicKey से सत्यापन करता है और स्कैन किए अनुरोध का बंधन जाँचता है।
हस्ताक्षरित JSON ऐरे
javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]

QR स्वीकृति में acceptSignedArrayJSON, PAIRING_ACCEPT ऐरे की संक्षिप्त JSON स्ट्रिंग है जिसमें स्कैनर की पहचान और नाम हैं। स्कैनर उस आंतरिक ऐरे पर सीधे हस्ताक्षर करने के बजाय QR_PAIR_ACCEPT ऐरे पर हस्ताक्षर करता है। HMAC कुंजी request.signature की UTF-8 स्ट्रिंग है, उसके Base64-डिकोड किए बाइट नहीं।

PAIR_CANCEL · POST /nearby · PAIR_CANCEL
हस्ताक्षर का कारण
रद्द करने को प्रमाणित करता है और उसे मूल requestSignature तथा दोनों डिवाइस से बाँधता है, ताकि दूसरे युग्मन प्रयास को रद्द न किया जा सके।
हस्ताक्षर और सत्यापन पक्ष
रद्द करने वाला डिवाइस हस्ताक्षर करता है; प्राप्तकर्ता डिवाइस पहचान सत्यापित करके लंबित अनुरोध से मिलाता है।
हस्ताक्षरित JSON ऐरे
javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
हस्ताक्षर का कारण
कनेक्ट होने वाले पीयर को प्रमाणित करता है और उसके प्रमाण को इस कनेक्शन के पूरे एन्क्रिप्टेड init और ack फ़्रेम से बाँधता है, ताकि दूसरे कनेक्शन में पुनः उपयोग न हो।
हस्ताक्षर और सत्यापन पक्ष
कनेक्ट होने वाला पीयर क्लाइंट प्रमाण पर हस्ताक्षर करता है; स्थिति सर्वर सहेजी गई पीयर पहचान सार्वजनिक कुंजी से सत्यापन करता है।
हस्ताक्षरित JSON ऐरे
javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
हस्ताक्षर का कारण
बाहरी पीयर अनुरोध हस्ताक्षर के अतिरिक्त सिस्टम-संदेश पेलोड में सत्यापन योग्य सदस्यता प्रमाण रखता है। चैनल, संस्करण, कार्रवाई और लक्ष्य बाँधता है; प्राप्तकर्ता स्वामी/सदस्य अनुमतियाँ अलग लागू करते हैं।
हस्ताक्षर और सत्यापन पक्ष
कार्रवाई के अनुसार स्वामी या कार्रवाई करने वाला सदस्य हस्ताक्षर करता है; प्राप्तकर्ता सदस्य संबंधित पहचान और अनुमतियाँ सत्यापित करता है।
हस्ताक्षरित JSON ऐरे
javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
हस्ताक्षर का कारण
घोषित TLS प्रमाणपत्र के SHA-256 फ़िंगरप्रिंट को डिवाइस पहचान से बाँधता है। प्रबंधित पीयर प्रॉक्सी उस प्रमाणपत्र फ़िंगरप्रिंट पर भरोसा करने से पहले यह प्रमाण सत्यापित करती है।
हस्ताक्षर और सत्यापन पक्ष
डिवाइस /init प्रतिक्रिया के tlsCertificateSignature पर हस्ताक्षर करता है; जुड़ने वाली प्रबंधित प्रॉक्सी अपेक्षित डिवाइस पहचान सार्वजनिक कुंजी से सत्यापन करती है।
हस्ताक्षरित JSON ऐरे
javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]

purpose का अर्थ प्रविष्टि शीर्षक का मान है। दिखाए गए ऐरे को संक्षिप्त JSON में सीरियलाइज़ करें, UTF-8 में एन्कोड करें और प्रेषक की Ed25519 पहचान कुंजी से हस्ताक्षर करें; signature, Base64 है। फ़ील्ड क्रम, प्रकार और मूल JSON स्ट्रिंग अपरिवर्तित रखें। हस्ताक्षर हस्ताक्षरकर्ता की पहचान करता है; समय की वैधता और प्राधिकरण अलग जाँचे जाते हैं।

AAD संदर्भ

AAD का प्रमाणीकरण सिफरटेक्स्ट के साथ होता है, लेकिन उसे एन्क्रिप्ट नहीं किया जाता और न ही अलग फ़्रेम फ़ील्ड के रूप में जोड़ा जाता है। दोनों पक्ष वही बाइट पुनर्निर्मित करते हैं; कोई अंतर होने पर टैग सत्यापन विफल होता है। उदाहरण इस दस्तावेज़ के कृत्रिम प्रमाणीकरण और WebSocket फ़्रेम का पुनः उपयोग करते हैं।

सूत्रों में दोहरी खड़ी रेखा का अर्थ बाइट जोड़ना है। 0x00 एक शून्य बाइट है। fields(x₁, …, xₙ) प्रत्येक uint32be(byteLength(xᵢ)) के बाद xᵢ को जोड़ता है। SHA256 32 मूल बाइट लौटाता है; hex केवल प्रदर्शन के लिए है। JSON.stringify का अर्थ निर्धारित फ़ील्ड क्रम वाला संक्षिप्त JSON है। प्रत्येक WebSocket दिशा अपना क्रम 1 से शुरू करती है।

WSS /auth · पासवर्ड लॉगिन
AUTH_REQUEST / AUTH_RESPONSE

एन्क्रिप्टेड क्लाइंट जानकारी और अनुमोदन परिणाम को इस क्लाइंट तथा सर्वर की पहचान से बाँधता है; अनुरोध और प्रतिक्रिया दिशाओं को अलग रखता है।

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

OPAQUE Rust/WASM लॉगिन परिणाम requestAad और responseAad लौटाता है। आंतरिक संदर्भ बनाए बिना उनका सीधे उपयोग करें। digest 32-बाइट डाइजेस्ट वाला भाग है, कोई अतिरिक्त अनुरोध फ़ील्ड नहीं। LOGIN_PASSWORD लॉगिन लाइब्रेरी में निश्चित है; कॉल करने वाला purpose पैरामीटर नहीं देता।

ठोस इनपुट और 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 · पासवर्ड के बिना लॉगिन
AUTH_REQUEST / AUTH_RESPONSE

एन्क्रिप्टेड अनुमोदन संदेशों को इस हैंडशेक से बाँधता है, जिसमें दोनों अस्थायी सार्वजनिक कुंजियाँ और हस्ताक्षरित सर्वर प्रतिक्रिया शामिल हैं।

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

हैंडशेक लाइब्रेरी AAD को आंतरिक रूप से संभालती है। आंतरिक संदर्भ बनाए बिना encryptRequest और decryptResponse का उपयोग करें। digest 32-बाइट डाइजेस्ट वाला भाग है, कोई अतिरिक्त अनुरोध फ़ील्ड नहीं। LOGIN_NO_PASSWORD लॉगिन लाइब्रेरी में निश्चित है; कॉल करने वाला purpose पैरामीटर नहीं देता।

ठोस इनपुट और 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

पंजीकरण को WebSocket पथ और क्लाइंट पहचान से बाँधता है।

text
fields(WS_INIT, path, cid)

path तार्किक पथ है जिसमें स्कीम, होस्ट या क्वेरी नहीं होती। cid URL एन्कोडिंग से पहले का मूल क्लाइंट ID है। उदाहरण /graphql का उपयोग करता है।

ठोस इनपुट और AAD बाइट

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

AAD · hex · 63 B

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

पावती को ठीक उसी एन्क्रिप्टेड init फ़्रेम, पथ और क्लाइंट पहचान से बाँधता है।

text
fields(WS_ACK, path, cid, SHA256(initFrame))

initFrame पूरा बाइनरी nonce + ciphertext + tag है, डिकोड किया गया init JSON नहीं। SHA256(initFrame) को 32 मूल बाइट के रूप में शामिल किया जाता है।

ठोस इनपुट और 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 · एन्क्रिप्टेड फ़्रेम
WS_FRAME

हर फ़्रेम को उसके कनेक्शन हैंडशेक, भेजने की दिशा और क्रम से बाँधता है, ताकि दूसरे कनेक्शन या दिशा में पुनः उपयोग न हो।

text
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))

initFrame और ackFrame पूरे एन्क्रिप्टेड बाइनरी फ़्रेम हैं। भेजने वाले के अनुसार direction, client या server होता है। sequence आठ बिग-एंडियन बाइट में एन्कोड होता है; उदाहरण खाली पुष्टि फ़्रेम सहित दोनों स्वतंत्र दिशाओं में 1 दिखाता है।

ठोस इनपुट और 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 · एन्क्रिप्टेड अनुरोध
HTTP_REQUEST

एन्क्रिप्टेड डेटा को उसकी तार्किक HTTP विधि और एंडपॉइंट से बाँधता है, ताकि किसी दूसरे REST एंडपॉइंट पर पुनः उपयोग न हो।

text
HTTP_REQUEST.{method}.{endpoint}

POST /graphql, /guest_graphql, /peer_graphql, /init, /upload और /upload_chunk सभी HTTP_REQUEST का उपयोग करते हैं। मल्टीपार्ट अपलोड एन्क्रिप्टेड info मेटाडेटा को बाँधते हैं। Proxy/BLE/Aware अग्रेषण प्रॉक्सी URL के बजाय तार्किक गंतव्य पथ का उपयोग करता है।

एन्क्रिप्टेड प्रतिक्रियाएँ खाली AAD से टैग सत्यापित करती हैं। उनका प्लेनटेक्स्ट 0x00 + SHA256(original encrypted request) + response JSON है; क्लाइंट डिक्रिप्शन के बाद अनुरोध डाइजेस्ट जाँचते हैं।

ठोस इनपुट और 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 · /fs, /zip/* और /proxy/*
FS / ZIP_FILES

एन्क्रिप्टेड URL पेलोड को उसके उद्देश्य, सत्र/साझा दायरे और स्वामी से बाँधता है।

text
{purpose}.{mode}.{owner}

FS फ़ाइल पूर्वावलोकन, डायरेक्टरी डाउनलोड, प्रॉक्सी संसाधन और अनुलग्नक संदर्भों के लिए है; ZIP_FILES संग्रह हेतु चयन के लिए है। सत्र के लिए mode, c और साझा के लिए s है; owner सत्र का क्लाइंट ID या साझा ID है।

ठोस इनपुट और 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