API রেফারেন্স

স্বাক্ষর ও AAD

Ed25519 স্বাক্ষর ও AEAD-এর অতিরিক্ত প্রমাণীকৃত তথ্য: প্রবেশবিন্দু, বাইট বিন্যাস, কারণ ও নির্দিষ্ট উদাহরণ।

API স্বাক্ষর

এই এন্ট্রিগুলি Ed25519 স্বাক্ষর ব্যবহার করে। প্রতিটি স্বাক্ষরিত অ্যারের প্রথম উপাদান তার SignaturePurpose; এটি বিভিন্ন কাজের প্রমাণ আলাদা করে, পৃথক পরিবাহিত ক্ষেত্র নয়।

এনক্রিপ্ট করা HTTP /graphql ও /guest_graphql অনুরোধ এবং WSS /graphql ফ্রেম Ed25519 স্বাক্ষর ছাড়া সেশন AEAD ট্যাগ ব্যবহার করে। /graphql-এর API-token অনুরোধে 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 কী হলো UTF-8 request.signature স্ট্রিং, 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 আটটি big-endian বাইটে এনকোড হয়; উদাহরণে খালি নিশ্চিতকরণ ফ্রেমসহ উভয় স্বতন্ত্র দিকে 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 ব্যবহার করে। Multipart আপলোড এনক্রিপ্ট করা info মেটাডেটা বাঁধে। Proxy/BLE/Aware ফরওয়ার্ডিং প্রক্সি URL নয়, যৌক্তিক গন্তব্য পথ ব্যবহার করে।

এনক্রিপ্ট করা উত্তর খালি AAD দিয়ে ট্যাগ যাচাই করে। তার প্লেইনটেক্সট হলো 0x00 + SHA256(মূল এনক্রিপ্ট করা অনুরোধ) + উত্তরের 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