서명과 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은 0 바이트 하나입니다. fields(x₁, …, xₙ)는 각 uint32be(byteLength(xᵢ)) 뒤에 xᵢ를 붙여 연결합니다. SHA256은 원시 32바이트를 반환하며 hex는 표시 전용입니다. JSON.stringify는 지정된 필드 순서의 압축 JSON을 뜻합니다. WebSocket의 각 방향은 별도로 시퀀스 1에서 시작합니다.
WSS /auth · 비밀번호 로그인
AUTH_REQUEST / AUTH_RESPONSE암호화된 클라이언트 정보와 승인 결과를 이 클라이언트 및 서버 신원에 결합하고 요청과 응답 방향을 구분합니다.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestOPAQUE Rust/WASM 로그인 결과는 requestAad와 responseAad를 반환합니다. 내부 컨텍스트를 구성하지 말고 그대로 사용하세요. digest는 32바이트 다이제스트 부분이며 추가 요청 필드가 아닙니다. LOGIN_PASSWORD는 로그인 라이브러리 내부에 고정되어 있으며 호출자가 purpose 매개변수를 제공하지 않습니다.
구체적인 입력과 AAD 바이트
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · 비밀번호 없는 로그인
AUTH_REQUEST / AUTH_RESPONSE암호화된 승인 메시지를 양측 임시 공개 키와 서명된 서버 응답이 포함된 이 핸드셰이크에 결합합니다.
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 바이트
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INIT등록을 WebSocket 경로 및 클라이언트 신원에 결합합니다.
fields(WS_INIT, path, cid)path는 스킴, 호스트, 쿼리가 없는 논리 경로입니다. cid는 URL 인코딩 전의 원래 클라이언트 ID입니다. 예제에서는 /graphql을 사용합니다.
구체적인 입력과 AAD 바이트
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACK확인 응답을 정확히 해당하는 암호화된 init 프레임, 경로, 클라이언트 신원에 결합합니다.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame은 nonce + ciphertext + tag로 구성된 전체 바이너리이며 디코딩된 init JSON이 아닙니다. SHA256(initFrame)은 원시 32바이트로 포함됩니다.
구체적인 입력과 AAD 바이트
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · 암호화 프레임
WS_FRAME각 프레임을 해당 연결의 핸드셰이크, 전송 방향, 시퀀스에 결합하여 다른 연결이나 방향에서 재사용하지 못하게 합니다.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame과 ackFrame은 완전한 암호화 바이너리 프레임입니다. direction은 발신자에 따라 client 또는 server입니다. sequence는 빅 엔디언 8바이트로 인코딩합니다. 예제는 빈 확인 프레임을 포함하여 독립적인 양방향에 각각 1을 표시합니다.
구체적인 입력과 AAD 바이트
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 · 암호화 요청
HTTP_REQUEST암호화된 데이터를 논리 HTTP 메서드와 엔드포인트에 결합하여 다른 REST 엔드포인트에서 재사용하지 못하게 합니다.
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 바이트
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
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6b리소스 URL · /fs, /zip/*, /proxy/*
FS / ZIP_FILES암호화된 URL 페이로드를 용도, 세션/공유 범위, 소유자에 결합합니다.
{purpose}.{mode}.{owner}FS는 파일 미리 보기, 디렉터리 다운로드, 프록시 리소스, 첨부 참조에 적용되고 ZIP_FILES는 압축할 선택 항목에 적용됩니다. mode는 세션일 때 c, 공유일 때 s이며 owner는 세션 클라이언트 ID 또는 공유 ID입니다.
구체적인 입력과 AAD 바이트
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