메인 콘텐츠로 건너뛰기

증상

동일한 머신에서 curl을 대상으로 한 api.apiyi.com은 정상적으로 작동하지만, Python 프로그램(특히 Conda 환경)에서는 다음 오류가 발생합니다.
간혹 포트 443에서 연결 시간 초과가 발생하거나 핸드셰이크 중 연결이 끊기는 형태로 나타납니다. VPN은 사용하지 않으며, 네트워크를 변경하면(예: 휴대폰 핫스팟으로 전환) 다시 정상적으로 작동합니다.

간단한 답변

이는 APIYI 서버 측 문제도 인증서 문제도 아닙니다. 사용 중인 OpenSSL 버전이 네트워크의 미들박스와 호환되지 않습니다. 양쪽의 OpenSSL 버전을 비교합니다.
오류가 발생하는 쪽이 OpenSSL 3.5 이상이고 정상적으로 작동하는 쪽이 3.5 미만이라면, 이는 거의 확실하게 원인입니다.

발생 원인

OpenSSL 3.5부터 TLS 핸드셰이크에는 기본적으로 양자 내성 키 교환(X25519MLKEM768)이 포함됩니다. 이로 인해 첫 번째 핸드셰이크 메시지(ClientHello)가 약 300바이트에서 약 1500바이트로 커지며, 단일 TCP 세그먼트보다 커지기 때문에 두 개의 세그먼트로 분할되어야 합니다. 일부 기업 방화벽, TLS 검사 어플라이언스 및 ISP 측 심층 패킷 검사 장치는 분할된 ClientHello를 처리하지 못하거나 새로운 키 교환 알고리즘을 인식하지 못해 연결을 단순히 종료합니다. 클라이언트에는 “프로토콜 위반으로 EOF가 발생했습니다”라는 메시지가 표시됩니다. 모든 APIYI 엣지 노드는 이 양자 내성 핸드셰이크를 지원합니다. 2026-09-11 (UTC+8)에 OpenSSL 3.6.4를 사용하여 각 노드를 확인했으며, 모두 테스트를 통과했습니다. 핸드셰이크 패킷은 당사에 도달하기 전에 사용자 네트워크 내부에서 삭제되고 있으므로, 서버 측에서는 이 문제를 해결할 수 없습니다.

확인을 위한 세 가지 명령

먼저 Conda 환경을 활성화한 후 문제가 발생하는 환경에서 openssl 바이너리를 사용하여 다음을 실행합니다.

수정 방법(하나 선택)

1

옵션 1: 구성 파일을 통해 포스트 양자 키 교환 비활성화(권장)

예를 들어 다음과 같은 파일을 생성합니다 ~/no-pq.cnf:
프로그램을 실행하기 전에 환경 변수를 설정합니다:
해당 환경의 모든 OpenSSL 기반 프로그램(Python, curl, pip 등)은 포스트 양자 키 공유 전송을 중지하며, ClientHello 크기는 약 300바이트로 줄어듭니다. 암호화 강도는 변경되지 않습니다. 이는 3.5 이전의 기본 동작을 복원할 뿐입니다.
2

옵션 2: Conda에서 OpenSSL 버전 다운그레이드

3.5 이전 버전에서는 기본적으로 포스트 양자 키 교환이 활성화되지 않습니다. OpenSSL에 종속된 패키지도 변경될 수 있으므로, 먼저 스테이징 환경에서 테스트해야 합니다.
3

옵션 3: 네트워크 팀에 미들박스 업데이트 요청

주요 방화벽과 TLS 검사 어플라이언스는 2025년 이후 출시된 펌웨어에서 하이브리드 포스트 양자 핸드셰이크를 지원합니다. 이는 영구적인 해결 방법이며 다른 사이트에서도 동일한 오류가 발생하는 것을 방지합니다.

후속 질문

브라우저와 프로그램이 동일한 네트워크 경로를 사용하지 않을 수 있습니다(브라우저는 시스템 프록시를 사용할 수 있음). 또한 브라우저는 핸드셰이크가 실패하면 후양자 키 공유 없이 자동으로 다시 시도하지만, 프로그램은 그렇지 않습니다.
TLS 라이브러리가 OpenSSL 3.5 이상인 모든 클라이언트에서 발생할 수 있으며, 최신 OpenSSL을 기반으로 빌드된 curl 8.x도 포함됩니다. Go와 Java는 자체 TLS 스택을 사용하며, 후양자 교환이 기본적으로 활성화되는지는 해당 버전에 따라 다릅니다. 진단 방법은 동일합니다. 위의 세 명령을 사용하여 기본 핸드셰이크만 실패하는지 확인하십시오.
아닙니다. 연결은 인증서 검증이 시작되기도 전에 핸드셰이크 중에 종료됩니다. 검증을 비활성화해도 문제가 해결되지 않으며 보안 위험만 증가합니다.
첫 번째 핸드셰이크 메시지는 클라이언트가 보냅니다. 해당 메시지가 네트워크 내부에서 삭제되면 서버는 이를 수신하지 못하므로 서버 설정으로는 해결할 수 없습니다. 세 명령의 결과에서 다른 사이트에서는 기본 핸드셰이크가 성공하지만 api.apiyi.com에서만 실패하는 것으로 나타나면 결과를 보내 주십시오. 추가로 조사하겠습니다.

관련 문서

API를 사용하려면 프록시가 필요합니까?

APIYI는 프록시 또는 VPN 없이 직접 연결을 지원합니다

시간 제한 구성

연결 및 읽기 시간 제한을 설정하는 방법