MsQuic

2025-05-01

이 항목에서는 Microsoft GDK(게임 개발 키트)와 함께 MsQuic을 사용하는 방법을 설명합니다. MsQuic는 IETF QUIC 프로토콜의 Microsoft 구현입니다. C로 작성되고 범용 QUIC 라이브러리로 설계된 교차 플랫폼입니다.

QUIC는 원래 HTTP와 같은 "TLS over TCP"를 사용하는 시나리오를 대체하도록 설계되었지만 이후 단일 연결을 통해 실시간 신뢰할 수 없는 데이터그램 메시지 및 신뢰할 수 있는 TCP와 유사한 스트림을 멀티플렉싱하는 데 적합한 범용 UDP 데이터 전송 계층으로 확장되었습니다. 따라서 특히 클라이언트/서버 전송 계층으로 그리고 실시간 게임 트래픽 데이터 흐름을 기반으로 하는 것이 좋습니다.

MsQuic은 GDK 타이틀에 맞게 조정되었으며 Windows Server, Linux 데스크톱 및 서버, iOS, Android 및 MacOS를 비롯한 다양한 플랫폼에서도 사용할 수 있습니다.

MsQuic API 설명서에서는 여러 가지 중요한 MsQuic 개념을 다루며 MsQuic API 화면에 대해 코딩하는 방법을 보여줍니다.

QUIC 기능

모든 패킷이 암호화되고 핸드셰이크가 TLS 1.3으로 인증됩니다.
안정적이고 신뢰할 수 없는 애플리케이션 데이터의 병렬 스트림입니다.
첫 번째 왕복(0-RTT)에서 애플리케이션 데이터를 교환합니다.
정체 제어 및 손실 복구가 향상되었습니다.
클라이언트 IP 주소 또는 포트의 변경 내용이 유지됩니다.
상태 비지정 부하 분산입니다.
새 기능 및 확장에 쉽게 확장할 수 있습니다.

MsQuic 구현

MsQuic에는 GDK 타이틀과 함께 사용하도록 조정될 뿐만 아니라 다른 QUIC 구현과 차별화되는 몇 가지 기능이 있습니다.

클라이언트 및 서버에 최적화되었습니다.
최대 처리량 및 최소 대기 시간에 최적화되었습니다.
비동기 IO입니다.
RSS(수신측 배율) 지원입니다.
UDP는 병합 지원을 보내고 받습니다.

MsQuic는 다음 QUIC RFC를 구현합니다.

MsQuic는 다음 QUIC 초안 확장을 구현합니다.

MsQuic 획득

MsQuic는 오픈 소스 github 리포지토리에서 호스트됩니다. 여기에 있는 공식 릴리스 중 하나를 통해 MsQuic을 확보해야 합니다. Xbox Series X|S 콘솔 지원은 시험판/1.9에 추가되었지만, Microsoft GDK(게임 개발 키트) 타이틀에 대해 가능한 경우 최신 공식 릴리스 버전을 사용하는 것이 좋습니다.

지정된 릴리스에 대해 미리 빌드된 MsQuic 바이너리는 특정 릴리스의 자산 섹션에서 사용할 수 있습니다. 특정 버전의 MsQuic에 대한 모든 빌드 버전은 서로 완전히 호환됩니다. 또한 MsQuic은 릴리스에 대한 이전 버전과의 호환성을 유지하려고 하지만 MsQuic 설명서 및 릴리스 정보를 참조하여 다양한 버전 간의 호환성 기대치를 확인하세요.

Microsoft GDK(게임 개발 키트).PC

미리 빌드된 msquic_windows_x64_Release_openssl 바이너리는 Microsoft GDK(게임 개발 키트).PC 타이틀에 권장됩니다.

PC의 Microsoft GDK(게임 개발 키트) 타이틀은 네이티브 x64 Win32 애플리케이션으로 실행됩니다. x64 플랫폼용으로 빌드된 MsQuic 버전을 사용해야 합니다. PC에서는 Windows 11 OS 이상에서만 지원되는 Schannel과는 달리 Microsoft GDK(게임 개발 키트)에서 지원하는 모든 OS 버전을 지원하므로 OpenSSL로 빌드된 MsQuic 버전을 사용하는 것이 좋습니다.

Microsoft GDK(게임 개발 키트).콘솔

미리 빌드된 msquic_gamecore_console_x64_Release_schannel 바이너리는 Microsoft GDK(게임 개발 키트).PC 타이틀에 권장됩니다.

MsQuic은 Xbox 콘솔에서 Microsoft GDK(게임 개발 키트) 타이틀에 대한 특별한 빌드 버전을 제공합니다. 이 버전에서는 MsQuic을 WINAPI_PARTITION_GAMES 아래의 API로 제한하고 MsQuic이 XGamePlatform.lib에 연결하도록 합니다. 이 빌드 버전을 사용하려면 2021년 10월 릴리스 이상의 XGDK가 설치되어 있어야 합니다. MsQuic는 Microsoft GDK(게임 개발 키트) 콘솔용으로 빌드할 때 Schannel을 사용합니다.

클라이언트 및 서버 인증

MsQuic는 서버를 인증하기 위해 HTTPS 웹 요청에 사용되는 것과 동일한 인증 및 확인 경로를 자동으로 활용합니다. 클라이언트 인증은 보안 클라이언트/서버 통신에 대한 모범 사례(NDA 항목)권한 부여 필요에 설명된 모범 사례를 따라야 합니다.

MsQuic에서 클라이언트와 서버 모두에서 인증서를 구성하려면 적절한 QUIC_CREDENTIAL_CONFIG와 ConfigurationLoadCredential API를 사용해야 합니다. 기본적으로 MsQuic에 포함된 모든 암호화 그룹은 안전한 것으로 간주되지만, 보안 및 인증된 통신 채널이 설정되도록 MsQuic가 클라이언트와 서버 모두에서 인증서의 유효성을 검사하는 방법을 올바르게 설정하는 것이 중요합니다.

서버에서 XSTS 토큰 클라이언트 인증을 사용하려면 QUIC_CREDENTIAL_FLAG_REQUIRE_CLIENT_AUTHENTICATION, QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED및 QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 플래그를 지정해야 합니다. QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 플래그를 지정하는 경우 보안 클라이언트/서버 통신에 대한 모범 사례(NDA 항목)권한 부여 필요 섹션에 설명된 대로 QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED 이벤트 콜백 내에서 클라이언트 인증서의 유효성을 직접 확인해야 합니다.

또한 서버에서 클라이언트가 HTTPS 웹 서버에서와 같이 서버를 인증할 수 있도록 제대로 루팅된 인증서를 제공해야 합니다.

서버 인증에 대한 기본 MsQuic 동작이 ID의 유효성을 검사하는 가장 쉽고 안전한 방법이기 때문에 클라이언트에서 QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 플래그를 지정해서는 안 됩니다. 대신 XSTS 토큰 클라이언트 인증의 경우 보안 클라이언트/서버 통신에 대한 모범 사례(NDA 항목)권한 부여 필요 섹션에 설명된 대로 서버에서 생성된 인증서와 함께 QUIC_CREDENTIAL_FLAG_CLIENT 플래그를 지정해야 합니다. QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT 모드를 지정하고 CertCreateContext와 같은 API를 사용하여 웹 요청 응답 데이터에서 직접 컨텍스트를 생성하여 클라이언트 인증서를 제공하는 것이 좋습니다.

네트워크 초기화

MsQuic은 Microsoft GDK(게임 개발 키트) 타이틀에 대한 네트워크 초기화를 자동으로 처리하지 않습니다. MsQuicOpenVersion 또는 MsQuicOpen을사용하여 MsQuic를 초기화하기 전에 타이틀이 시작된 후 및 각 다시 시작 후 네트워크가 초기화될 때까지 기다립니다.

일시 중단 및 재개

RegisterAppStateChangeNotification을(를) 통해 일시 중단 및 다시 시작 이벤트를 등록해야 합니다. 일시 중단 시 열려 있는 스트림을 닫고 MsQuic를 닫아야 합니다. 그런 다음 다시 시작할 때 네트워크 초기화를 기다린 다음 MsQuic를 다시 열어야 합니다.

일시 중단 시간 제한 내에 모든 MsQuic 스트림을 빠르게 닫으려면 먼저 QUIC_STREAM_SHUTDOWN_FLAG_ABORT 및 QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE 플래그를 사용하여 열려 있는 각 스트림에 대해 StreamShutdown을 호출해야 합니다. 그러면 StreamClose를 호출하여 스트림을 닫는 것이 안전한 시점에 QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE 이벤트가 즉시 트리거됩니다. 지정된 연결에 대해 모든 스트림이 닫힌 후에는 후에 QUIC_CONNECTION_SHUTDOWN_FLAG_SILENT 플래그를 사용하여 ConnectionShutdown을 호출하고 connectionClose를 호출해야 합니다. 모든 연결이 닫힌 후에는 미해결 등록 및 구성에 대해 RegistrationClose 및 ConfigurationClose를 호출한 다음 MsQuicClose를 호출해야 합니다.

기본 포트

Microsoft GDK(게임 개발 키트) 타이틀에서는 기본 로컬 UDP 멀티 플레이어 포트를 주 게임 트래픽에 사용하는 것이 좋습니다. ConnectionStart를 호출하기 전에 연결 개체 핸들에서 QUIC_PARAM_CONN_LOCAL_ADDRESS 설정을 사용하여 SetParam 함수를 통해 MsQuic에서 이 포트를 설정할 수 있습니다.

QUIC_PARAM_CONN_LOCAL_ADDRESS을(를) 설정할 때 이중 스택 IPv4 및 IPv6 소켓을 허용하려면 AF_UNSPEC 패밀리를 지정하는 것이 좋습니다. 다음은 MsQuicOpen에서 MsQuicCallTable이(가) 반환되고 ConnectionOpen에서 MsQuicConnectionHandle이(가) 반환된 기본 설정 포트를 설정하는 방법의 예입니다.

uint16_t preferredPort;
if (SUCCEEDED(XNetworkingQueryPreferredLocalUdpMultiplayerPort(&preferredPort)))
{
    QUIC_ADDR localAddress = {};
    localAddress.si_family = AF_UNSPEC;
    localAddress.Ipv4.sin_port = htons(preferredPort);

    QUIC_STATUS status = MsQuicCallTable->SetParam(
        MsQuicConnectionHandle,
        QUIC_PARAM_LEVEL_CONNECTION,
        QUIC_PARAM_CONN_LOCAL_ADDRESS,
        sizeof(localAddress),
        &localAddress);
}

메모리 고려 사항

MsQuic의 성능 구현을 통해 높은 대역폭을 Microsoft GDK(게임 개발 키트) 타이틀과 주고받을 수 있습니다. WinSock 메모리 고려 사항에 대한 확장으로 MsQuic를 사용할 때 커널의 메모리 소비를 최소화하려면 다음 모범 사례를 따라야 합니다.

Microsoft GDK(게임 개발 키트) 타이틀은 콜백에서 실행 시간을 최소한으로 유지해야 합니다. MsQuic는 프로토콜 실행에 별도의 스레드를 사용하지 않고 앱에 대한 업콜을 사용하지 않습니다. 따라서 콜백에서 상당한 지연이 발생하면 프로토콜이 지연되고 커널에 필요한 메모리 사용량이 증가합니다. 타이틀에서 완료해야 하는 중요한 시간 또는 작업은 자체 스레드에서 발생해야 합니다.

Microsoft GDK(게임 개발 키트) 타이틀은 커널 메모리 사용량을 최소화하기 위해 송신 버퍼를 효율적으로 관리해야 합니다. MsQuic에서 타이틀이 이를 관리하는 방법에 대한 자세한 내용은 MsQuic에서 버퍼링 보내기를 참조하세요.

받은 데이터가 사용자 모드 버퍼로 효율적으로 전송되도록 MsQuic에서 비동기 수신을 사용하는 것이 좋습니다. MsQuic에서 수신에는 비동기 수신을 처리하는 방법에 대한 추가 세부 정보가 있습니다. 또한 MsQuic GDK 클라이언트에서 부분 데이터 수용 기능을 사용하지 않고 사용된 커널 메모리 양을 최소화하는 것이 좋습니다.