PlainApp
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은 0 바이트 하나입니다. 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는 빅 엔디언 8바이트로 인코딩합니다. 예제는 빈 확인 프레임을 포함하여 독립적인 양방향에 각각 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