İmzalar ve AAD
Ed25519 imzaları ve AEAD ek doğrulanmış verileri: giriş noktaları, bayt biçimleri, gerekçeler ve somut örnekler.
API imzaları
Bu girdiler Ed25519 imzaları kullanır. Her imzalı dizinin ilk öğesi SignaturePurpose değeridir; farklı işlemlerin kanıtlarını ayırır ve ayrı bir aktarım alanı değildir.
Şifreli HTTP /graphql ve /guest_graphql istekleri ile WSS /graphql çerçeveleri Ed25519 imzası olmadan oturum AEAD etiketleri kullanır. /graphql API-token istekleri Bearer kimlik doğrulaması kullanır. Aşağıdaki girdiler hangi istek, yanıt veya iç içe yükün imza taşıdığını belirtir.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Neden imzalanır
- Cihaz kimliğini, istemci kimliğini ve iki el sıkışma iletisini bağlar. Tarayıcı parolasız onay kanalı anahtarını türetmeden önce imzalı ServerHello'yu denetler.
- İmzalama ve doğrulama
- Cihaz ServerHello'yu imzalar; bağlanan tarayıcı/istemci cihaz kimliğinin açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Neden imzalanır
- İsteği şifrelemeye ek olarak gönderen cihazı doğrular. Kanıtın başka kanala taşınamaması için özgün GraphQL isteğini ve kanal bağlamını bağlar. İstek UUIDv7 güncelliği ayrıca denetlenir.
- İmzalama ve doğrulama
- Gönderen eş isteği imzalar; alıcı eş gönderenin kaydedilmiş kimlik açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId dizinin ikinci değeridir: doğrudan eş isteklerinde boş, diğerlerinde tam olarak c-cid kanal kimliğidir. İmzayı hesaplarken variables içindeki nesne anahtarlarını özyinelemeli olarak sıralayın.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Neden imzalanır
- İsteyen kimliği, hedef alıcıyı, cihaz ayrıntılarını ve ECDH açık anahtarını bağlar. Alıcı ortak anahtar türetmeden önce değişiklikleri saptayabilir; QR taraması gösterilen daveti aynı purpose ile doğrular.
- İmzalama ve doğrulama
- İsteyen cihaz imzalar; alıcı cihaz veya QR tarayıcı davetin signaturePublicKey değeriyle doğrular. Kullanıcı onayı veya güvenilen kimlik eşleşmesi yine gereklidir.
- İmzalı JSON dizisi
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Neden imzalanır
- Kabul eden cihazın ECDH açık anahtarını ve bağlantı ayrıntılarını tek requestId'ye bağlar. İlgisiz veya değiştirilmiş kabul bekleyen eşleştirmeyi tamamlayamaz.
- İmzalama ve doğrulama
- Kabul eden cihaz imzalar; isteyen cihaz beklenen eş kimliği açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Neden imzalanır
- Bekleyen isteği kimin reddettiğini doğrular. Yalnızca requestId ve signature aktarılır; ret ortak anahtar kurmaz.
- İmzalama ve doğrulama
- Reddeden cihaz imzalar; isteyen cihaz beklenen eş kimliği açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Neden imzalanır
- Tarayan kimliğini ve kabul ayrıntılarını tam olarak taranan davete bağlar. Dış Ed25519 imzası tarayanı doğrular; HMAC yanıtı request.signature değerine bağlar.
- İmzalama ve doğrulama
- Tarayan cihaz imzalar; QR gösteren cihaz yanıttaki tarayan signaturePublicKey değeriyle doğrular ve taranan istek bağını denetler.
- İmzalı JSON dizisi
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
QR kabulünde acceptSignedArrayJSON, tarayanın kimliğini ve adını içeren PAIRING_ACCEPT dizisinin sıkıştırılmış JSON dizesidir. Tarayan, iç diziyi doğrudan imzalamak yerine QR_PAIR_ACCEPT dizisini imzalar. HMAC anahtarı Base64 çözülmüş baytlar değil, UTF-8 request.signature dizesidir.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Neden imzalanır
- İptali doğrular ve özgün requestSignature ile iki cihaza bağlayarak farklı eşleştirme denemesinin iptalini önler.
- İmzalama ve doğrulama
- İptal eden cihaz imzalar; alıcı cihaz kimliği doğrular ve bekleyen istekle eşleştirir.
- İmzalı JSON dizisi
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Neden imzalanır
- Bağlanan eşi doğrular ve kanıtını bu bağlantının tam şifreli init ve ack çerçevelerine bağlayarak bağlantılar arası yeniden kullanımı önler.
- İmzalama ve doğrulama
- Bağlanan eş istemci kanıtını imzalar; durum sunucusu kaydedilmiş eş kimliği açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Neden imzalanır
- Dış eş isteği imzasına ek olarak sistem iletisi yükünde doğrulanabilir üyelik kanıtı taşır. Kanalı, sürümü, eylemi ve hedefi bağlar; alıcılar sahip/üye izinlerini ayrıca uygular.
- İmzalama ve doğrulama
- Eyleme göre sahip veya işlemi yapan üye imzalar; alıcı üye ilgili kimliği ve izinleri doğrular.
- İmzalı JSON dizisi
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Neden imzalanır
- Duyurulan TLS sertifikası SHA-256 parmak izini cihaz kimliğine bağlar. Yönetilen eş proxy'si sertifika parmak izine güvenmeden önce bu kanıtı doğrular.
- İmzalama ve doğrulama
- Cihaz /init yanıtındaki tlsCertificateSignature değerini imzalar; bağlanan yönetilen proxy beklenen cihaz kimliği açık anahtarıyla doğrular.
- İmzalı JSON dizisi
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose girdi başlığındaki değerdir. Gösterilen diziyi sıkıştırılmış JSON olarak serileştirin, UTF-8 kodlayın, sonra gönderenin Ed25519 kimlik anahtarıyla imzalayın; signature Base64'tür. Alan sırasını, türleri ve özgün JSON dizelerini değiştirmeyin. İmza imzalayanı tanımlar; güncellik ve yetki ayrıca denetlenir.
AAD başvurusu
AAD, şifreli metinle birlikte doğrulanır; ancak şifrelenmez veya ayrı bir çerçeve alanı olarak eklenmez. İki taraf aynı baytları yeniden oluşturur; her uyuşmazlık etiket doğrulamasını başarısız kılar. Örnekler bu belgelerdeki sentetik kimlik doğrulama ve WebSocket çerçevelerini yeniden kullanır.
Formüllerdeki çift dikey çizgi bayt birleştirmeyi belirtir. 0x00 tek bir sıfır bayttır. fields(x₁, …, xₙ), her uint32be(byteLength(xᵢ)) değerini ardından xᵢ ile birleştirir. SHA256 32 ham bayt döndürür; hex yalnızca gösterim içindir. JSON.stringify, belirtilen alan sıralı sıkıştırılmış JSON anlamına gelir. Her WebSocket yönü kendi sırasını 1'den başlatır.
WSS /auth · parolalı oturum açma
AUTH_REQUEST / AUTH_RESPONSEŞifreli istemci bilgilerini ve onay sonucunu bu istemci ve sunucu kimliğine bağlar; istek ve yanıt yönlerini ayırır.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestOPAQUE Rust/WASM oturum açma sonucu requestAad ve responseAad döndürür. İç bağlamı oluşturmadan bunları doğrudan kullanın. digest, ek istek alanı değil, 32 baytlık özet kısmıdır. LOGIN_PASSWORD oturum açma kitaplığında sabittir; çağıranlar purpose parametresi sağlamaz.
Somut girdiler ve AAD baytları
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · parolasız oturum açma
AUTH_REQUEST / AUTH_RESPONSEŞifreli onay iletilerini iki geçici açık anahtar ve imzalı sunucu yanıtı dahil bu el sıkışmaya bağlar.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestEl sıkışma kitaplığı AAD'yi içeride yönetir. İç bağlamı oluşturmadan encryptRequest ve decryptResponse kullanın. digest, ek istek alanı değil, 32 baytlık özet kısmıdır. LOGIN_NO_PASSWORD oturum açma kitaplığında sabittir; çağıranlar purpose parametresi sağlamaz.
Somut girdiler ve AAD baytları
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INITKaydı WebSocket yoluna ve istemci kimliğine bağlar.
fields(WS_INIT, path, cid)path; şema, ana makine veya sorgu içermeyen mantıksal yoldur. cid, URL kodlamasından önceki özgün istemci kimliğidir. Örnek /graphql kullanır.
Somut girdiler ve AAD baytları
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKOnayı tam olarak şifrelenmiş init çerçevesine, yola ve istemci kimliğine bağlar.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame, çözülmüş init JSON'u değil, tam ikili nonce + ciphertext + tag dizisidir. SHA256(initFrame) 32 ham bayt olarak dahil edilir.
Somut girdiler ve AAD baytları
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · şifreli çerçeveler
WS_FRAMEHer çerçeveyi bağlantısının el sıkışmasına, gönderim yönüne ve sırasına bağlayarak başka bağlantı veya yönde yeniden kullanılmasını önler.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame ve ackFrame tam şifreli ikili çerçevelerdir. direction gönderene göre client veya server olur. sequence sekiz big-endian bayt olarak kodlanır; örnek, boş onay çerçevesi dahil iki bağımsız yönde de 1 gösterir.
Somut girdiler ve AAD baytları
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 · şifreli istekler
HTTP_REQUESTŞifreli verileri mantıksal HTTP yöntemine ve uç noktasına bağlayarak başka REST uç noktasında yeniden kullanımı önler.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload ve /upload_chunk tümü HTTP_REQUEST kullanır. Çok parçalı yüklemeler şifreli info meta verisini bağlar. Proxy/BLE/Aware iletimi proxy URL'si yerine mantıksal hedef yolu kullanır.
Şifreli yanıtlar etiketi boş AAD ile doğrular. Düz metinleri 0x00 + SHA256(özgün şifreli istek) + yanıt JSON'udur; istemciler şifreyi çözdükten sonra istek özetini denetler.
Somut girdiler ve AAD baytları
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
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bKaynak URL'leri · /fs, /zip/* ve /proxy/*
FS / ZIP_FILESŞifreli URL yüklerini amaçlarına, oturum/paylaşım kapsamına ve sahibine bağlar.
{purpose}.{mode}.{owner}FS dosya önizlemelerini, dizin indirmelerini, proxy kaynaklarını ve ek referanslarını kapsar; ZIP_FILES arşiv seçimlerini kapsar. mode oturum için c, paylaşım için s olur; owner oturum istemci kimliği veya paylaşım kimliğidir.
Somut girdiler ve AAD baytları
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