API Referansı

İ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.

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

OPAQUE 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ı

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /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.

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

El 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ı

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

Kaydı WebSocket yoluna ve istemci kimliğine bağlar.

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

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

AAD · hex · 63 B

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

Onayı tam olarak şifrelenmiş init çerçevesine, yola ve istemci kimliğine bağlar.

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

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

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · şifreli çerçeveler
WS_FRAME

Her ç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.

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

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 · ş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.

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

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
Kaynak 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.

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

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