문제 해결

이 페이지는 X Chat 암호화와 Chat XDK에 특화된 문제—키, 안전한 키 백업, 복호화/검증, 그리고 암호화된 전송 페이로드 구축—를 다룹니다. 웹훅, OAuth, HTTP 상태 코드 및 속도 제한은 일반 X API 및 인증 문서를 사용하세요.

키 및 안전한 키 백업

잠금 해제 실패 (잘못된 패스코드)

패스코드가 setup에서 사용한 것과 일치하는지 확인하세요
시도 사이에 기다리세요; realm은 잘못된 추측에 대해 속도 제한을 두고 너무 많은 실패 후에는 복구를 잠글 수 있습니다

try:
    chat.unlock(passcode)
except ValueError as e:
    print(e)  # may mention InvalidPin or guesses remaining

try {
  await chat.unlock(passcode);
} catch (e) {
  console.error((e as Error).message);
}

chat.unlock(passcode_bytes).await?;

if err := chat.Unlock(passcode, juiceboxConfigJSON); err != nil {
    log.Println(err)
}

try { chat.Unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { Console.WriteLine(e.Message); }

try { chat.unlock(passcode, juiceboxConfigJson); }
catch (Exception e) { System.out.println(e.getMessage()); }

키 또는 신원이 설정되지 않아 암호화 또는 복호화 실패

먼저 개인 키를 로드한 다음 세션 신원—당신의 사용자 ID와 X의 레코드에 있는 public_key_version—을 설정하세요. encrypt_* 및 prepare_* 메서드는 이를 사용해 서명합니다; 세션 신원 없이 (그리고 호출별 명시적 오버라이드도 없이) 이들을 호출하는 것은 오류입니다.

chat.unlock(passcode)  # or: chat.import_keys(blob)
chat.set_identity(my_user_id, signing_key_version)

await chat.unlock(passcode);
chat.setIdentity(myUserId, signingKeyVersion);

chat.import_keys(&blob)?;
chat.set_identity(&my_user_id, &signing_key_version);

blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
_ = chat.ImportKeys(blob)
_ = chat.SetIdentity(myUserID, signingKeyVersion)

chat.ImportKeys(blobBytes);
chat.SetIdentity(myUserId, signingKeyVersion);

chat.importKeys(blobBytes);
chat.setIdentity(myUserId, signingKeyVersion);

로컬 공개 키가 계정에 등록된 키와 절대 일치하지 않음

클라이언트는 종종 “이 기기에 있는 키가 이 계정에 등록된 키 중 하나입니까?” 라는 질문에 답해야 합니다 — 복원이나 임포트 후에 올바른 public_key_version을 채택하기 위해, 또는 온보딩이 이미 완료되었는지 결정하기 위해서입니다. Chat XDK의 get_public_keys 출력을 API의 public_key 필드와 문자열로 비교하면 같은 키에 대해서도 항상 실패합니다. 두 값이 서로 다른 인코딩을 사용하기 때문입니다:

API는 등록에서 업로드한 대로 키를 저장하고 반환합니다: DER (SPKI) 인코딩 — 고정된 알고리즘 식별자 접두사 뒤의 원시 키
Chat XDK의 get_public_keys는 그 접두사 없이 원시 키만 반환합니다

같은 키, 두 가지 표기입니다. 비교하려면 양쪽을 base64로 디코딩하고 API 바이트가 SDK 바이트로 끝나는지 확인하세요 (양쪽이 언젠가 같은 인코딩을 가지는 경우를 대비해 동일한 바이트도 일치로 간주합니다):

import base64

def same_key(local_b64: str, server_b64: str) -> bool:
    local = base64.b64decode(local_b64)    # chat.get_public_keys()["identity"]
    server = base64.b64decode(server_b64)  # API row's "public_key"
    return local == server or (len(server) > len(local) and server.endswith(local))

const sameKey = (localB64: string, serverB64: string): boolean => {
  const local = Buffer.from(localB64, 'base64');   // chat.getPublicKeys().identity
  const server = Buffer.from(serverB64, 'base64'); // API row's public_key
  return local.equals(server) ||
    (server.length > local.length && server.subarray(server.length - local.length).equals(local));
};

fn same_key(local: &[u8], server: &[u8]) -> bool {
    local == server || (server.len() > local.len() && server.ends_with(local))
}

func sameKey(local, server []byte) bool {
    return bytes.Equal(local, server) ||
        (len(server) > len(local) && bytes.HasSuffix(server, local))
}

static bool SameKey(byte[] local, byte[] server) =>
    local.SequenceEqual(server) ||
    (server.Length > local.Length &&
     server.AsSpan(server.Length - local.Length).SequenceEqual(local));

static boolean sameKey(byte[] local, byte[] server) {
    if (Arrays.equals(local, server)) return true;
    if (server.length <= local.length) return false;
    byte[] tail = Arrays.copyOfRange(server, server.length - local.length, server.length);
    return Arrays.equals(tail, local);
}

일치하면 해당 행의 public_key_version을 set_identity에 채택하세요. 버전을 비교할 때(예: 최신 키를 선택하기 위해)는 숫자로 비교하세요 — 버전은 문자열 길이가 다양한 밀리초 타임스탬프이므로 사전식 비교는 잘못된 것을 선택합니다.

메시지에 대한 대화 키 누락

Message encrypted with key version '…' but no matching key found와 같은 오류는 해당 메시지의 conversation_key_version에 대한 원시 키가 없다는 뜻입니다.

extract_conversation_keys로 conversation_key_change_event(실시간 이벤트) 또는 meta.conversation_key_events(이력)의 키 자료를 복호화하거나, 또는 decrypt_events에 그 blob을 포함하세요—set_cache_keys(true)가 활성화된 상태에서는 decrypt_events가 각 대화의 최신 검증된 키도 유지하므로 이후의 decrypt_event 및 encrypt_* 호출에서는 이를 생략할 수 있습니다
해당 버전에 대해 대화 키가 추가되었고 여전히 참가자인지 확인하세요 (시작하기 참조)

상대방에게 공개 키가 없음

아직 온보딩을 마치지 않았을 수 있습니다. 그들이 등록한 후, API 참조 → Encryption keys에서 public_key, signing_public_key, identity_public_key_signature, public_key_version을 로드하세요.

복호화 및 서명

복호화 실패

오래되었거나 잘못된 원시 대화 키, 또는 잘못된 키 버전
불완전한 encoded_event 문자열
이벤트 유형이 복호화 가능한 콘텐츠로 처리할 수 있는 암호화된 메시지가 아님

서명 검증 실패

검증은 기본적으로 실패-폐쇄입니다(reject_unverified = true): SDK는 이미 검증되지 않은 서명 이벤트를 거부하므로, 여기서 실패가 발생한다면 검사를 켜야 한다는 뜻이 아니라 검증 입력이 잘못되었다는 뜻입니다. 일반적인 원인:

발신자에 대한 서명 키 항목이 누락되었거나 불완전함 (Chat XDK가 요구하는 모든 필드—Chat XDK 참조)
호출에서 서명 키가 전달되지 않았고 set_signing_keys로 저장된 것도 없음
발신자가 버전을 교체함—공개 키를 다시 가져오세요
허용된 최소값보다 낮은 키 버전은 절대 검증되지 않습니다
그룹 키 변경 이벤트에서 서명자가 이미 그룹을 떠났다면 그들의 키가 더 이상 제공되지 않습니다 — 떠난 멤버로 인한 키 변경 참조

set_reject_unverified 세터는 이 기본값을 비활성화(false, 권장하지 않음)하기 위해 존재합니다. 이전에 비활성화했다면 실패-폐쇄 기본값으로 복원하세요:

chat.set_reject_unverified(True)

chat.setRejectUnverified(true);

chat.set_reject_unverified(true);

chat.SetRejectUnverified(true)

chat.SetRejectUnverified(true);

chat.setRejectUnverified(true);

답장에 `reply_preview_validation: "Invalid"`가 포함됨

복호화된 답장은 reply_preview_validation("Valid" / "Invalid"; JavaScript는 'valid' / 'invalid')을 포함할 수 있습니다. Invalid는 메시지 내부의 인용된 미리보기가 임베드된 서명 원본 이벤트와 일치하지 않는다는 뜻입니다—인용을 신뢰할 수 없는 것으로 취급하고 인용 내용은 검증된 원본에서만 렌더링하세요. 메시지 자체는 별도로 검증되며 여전히 진본입니다; 미리보기가 유효하지 않다고 해서 예외가 발생하지는 않습니다.

오래된 이벤트가 영구적으로 검증에 실패함

오래된 이벤트에서 signature missing or no matching signing key나 ECDSA 불일치 같은 오류는 영구적입니다. 서명은 불변이며 이벤트 자체에서 서명된 페이로드를 재구축하여 검증되므로, 다른 바이트로 서명된 (또는 서명되지 않은) 이벤트는 이후 로드 시마다 실패합니다—재시도, 키 갱신, 또는 API 호출로도 치유할 수 없습니다. 이러한 이벤트를 재시도 가능한 오류가 아닌 툼스톤으로 취급하세요. 대화 키를 교체하면 그 시점 이후부터 깨끗하고 검증 가능한 이력이 시작됩니다; 새 메시지는 영향을 받지 않습니다.

전송 페이로드 구축

이러한 실수들은 X Chat 암호화에 특화된 것입니다 (일반 HTTP 오류가 아님):

이슈	해결
잘못된 키 바이트	API의 암호화된 키 문자열이 아니라 원시 대화 키 바이트를 Chat XDK에 전달하세요
잘못된 JSON 필드 이름	`encrypted_content` → `encoded_message_create_event` 및 `encoded_event_signature` → `encoded_message_event_signature`로 매핑하세요
잘못된 메시지 ID	반환된 페이로드의 `message_id`를 그대로 전송하세요—SDK가 이를 생성해 서명된 이벤트에 포함하므로, 다른 값을 쓰면 실패합니다. 재시도 시에는 동일한 암호화된 페이로드를 재사용하여 ID가 두 번 생성되지 않도록 하세요
버전 불일치	`conversation_key_version`을 사용하는 키에 맞추고; `set_identity`에 전달하는 서명 키 버전을 공개 키 레코드와 일치시키세요
경로 ID 형식	URL 경로에는 여전히 하이픈으로 연결된 대화 ID가 필요합니다(`:` → `-`), 하지만 서명 시 SDK는 어떤 형태든 허용합니다: `A:B`, `A-B`(둘 중 어떤 순서든), 또는 단순한 수신자 사용자 ID—모두 동일한 서명된 바이트로 정규화됩니다

상태 변경 호출에서 API가 400을 반환함

모든 상태 변경 채팅 호출—대화 키 추가 또는 교체, 그룹 생성, 멤버 추가—에는 API 경계에서 검증되는 요청 본문의 **action_signatures**가 필요합니다. 누락되거나 잘못된 형식의 항목(각각 message_id, encoded_message_event_detail, 그리고 signature, public_key_version, signature_version이 있는 message_event_signature가 필요함)은 즉시 HTTP 400 problem-details 응답을 반환합니다. SDK prepare 메서드(prepare_conversation_key_change, prepare_group_create, prepare_group_members_change)를 사용하고 반환된 모든 서명을 보내세요—그룹 생성과 멤버 추가는 두 개를 반환합니다.

미디어 암호화 및 복호화

첨부 파일을 참조하는 메시지와 동일한 대화 키(및 버전)를 사용하세요
decrypt_stream을 실행하기 전까지 다운로드 응답을 암호문으로 취급하세요
MIME 유형은 복호화 후에 추론하세요; 다운로드 Content-Type은 종종 실제 이미지 유형이 아닙니다

세부 사항: 미디어.

안전한 디버깅

암호화 실패를 조사할 때:

대화 ID, 이벤트 ID, 키 버전만 로그에 남기세요
평문, 패스코드, 개인 키, 또는 전체 키 blob을 로그에 남기지 마세요
set_identity에 전달한 서명 키 버전이 공개 키 레코드의 public_key_version과 일치하는지 확인하세요
불완전한 이력의 경우, 복호화하기 전에 키 변경 메타데이터를 건너뛰지 않도록 모든 이벤트 페이지를 페이지 처리하세요

Getting Started

Products

Fundamentals

Partners & Customers

Resources

키 및 안전한 키 백업

잠금 해제 실패 (잘못된 패스코드)

키 또는 신원이 설정되지 않아 암호화 또는 복호화 실패

로컬 공개 키가 계정에 등록된 키와 절대 일치하지 않음

메시지에 대한 대화 키 누락

상대방에게 공개 키가 없음

복호화 및 서명

복호화 실패

서명 검증 실패

답장에 `reply_preview_validation: "Invalid"`가 포함됨

오래된 이벤트가 영구적으로 검증에 실패함

전송 페이로드 구축

상태 변경 호출에서 API가 400을 반환함

미디어 암호화 및 복호화

안전한 디버깅

​키 및 안전한 키 백업

​잠금 해제 실패 (잘못된 패스코드)

​키 또는 신원이 설정되지 않아 암호화 또는 복호화 실패

​로컬 공개 키가 계정에 등록된 키와 절대 일치하지 않음

​메시지에 대한 대화 키 누락

​상대방에게 공개 키가 없음

​복호화 및 서명

​복호화 실패

​서명 검증 실패

​답장에 reply_preview_validation: "Invalid"가 포함됨

​오래된 이벤트가 영구적으로 검증에 실패함

​전송 페이로드 구축

​상태 변경 호출에서 API가 400을 반환함

​미디어 암호화 및 복호화

​안전한 디버깅

키 및 안전한 키 백업

잠금 해제 실패 (잘못된 패스코드)

키 또는 신원이 설정되지 않아 암호화 또는 복호화 실패

로컬 공개 키가 계정에 등록된 키와 절대 일치하지 않음

메시지에 대한 대화 키 누락

상대방에게 공개 키가 없음

복호화 및 서명

복호화 실패

서명 검증 실패

답장에 `reply_preview_validation: "Invalid"`가 포함됨

오래된 이벤트가 영구적으로 검증에 실패함

전송 페이로드 구축

상태 변경 호출에서 API가 400을 반환함

미디어 암호화 및 복호화

안전한 디버깅