HttpReceiveClientCertificate 함수(http.h)

아티클
08/24/2023

HttpReceiveClientCertificate 함수는 서버 애플리케이션에서 클라이언트 SSL 인증서 또는 CBT(채널 바인딩 토큰)를 검색하는 데 사용됩니다.

구문

HTTPAPI_LINKAGE ULONG HttpReceiveClientCertificate(
  [in]            HANDLE                     RequestQueueHandle,
  [in]            HTTP_CONNECTION_ID         ConnectionId,
  [in]            ULONG                      Flags,
  [out]           PHTTP_SSL_CLIENT_CERT_INFO SslClientCertInfo,
  [in]            ULONG                      SslClientCertInfoSize,
  [out, optional] PULONG                     BytesReceived,
  [in, optional]  LPOVERLAPPED               Overlapped
);

매개 변수

[in] RequestQueueHandle

지정된 SSL 클라이언트 또는 CBT가 연결된 요청 큐에 대한 핸들입니다. 요청 큐가 생성되고 HttpCreateRequestQueue 함수에 대한 호출에서 해당 핸들이 반환됩니다.

WINDOWS Server 2003 SP1 및 Windows XP SP2: 요청 큐에 대한 핸들은 HttpCreateHttpHandle 함수에 의해 만들어집니다.

[in] ConnectionId

클라이언트에 대한 연결을 식별하는 값입니다. 이 값은 HttpReceiveHttpRequest 함수로 채워진 HTTP_REQUEST 구조체의 ConnectionId 요소에서 가져옵니다.

[in] Flags

HttpReceiveClientCertificate 함수의 동작을 수정하는 값입니다.

값	의미
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	pSslClientCertInfo 매개 변수는 CBT 데이터로 채워집니다. 이 값은 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.

[out] SslClientCertInfo

Flags 매개 변수가 0이면 이 매개 변수는 함수가 요청된 클라이언트 인증서 정보를 작성하는 HTTP_SSL_CLIENT_CERT_INFO 구조를 가리킵니다. pSslClientCertInfo가 가리키는 버퍼는 HTTP_SSL_CLIENT_CERT_INFO 구조체와 이 구조체의 CertEncodedSize 멤버 값을 포함할 만큼 충분히 커야 합니다.

Flags 매개 변수가 HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 경우 이 매개 변수는 함수가 요청된 CBT 정보를 작성하는 HTTP_REQUEST_CHANNEL_BIND_STATUS 구조를 가리킵니다. pSslClientCertInfo가 가리키는 버퍼는 HTTP_REQUEST_CHANNEL_BIND_STATUS 구조체와 이 구조체의 ChannelTokenSize 멤버 값을 포함할 만큼 충분히 커야 합니다.

[in] SslClientCertInfoSize

pSslClientCertInfo 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

[out, optional] BytesReceived

pSslClientCertInfo가 가리키는 구조체에 쓸 바이트 수를 수신하는 변수에 대한 선택적 포인터입니다. 사용하지 않으면 NULL로 설정합니다.

pOverlapped를 사용하여 비동기 호출을 수행하면 pBytesReceived를NULL로 설정합니다. 그렇지 않으면 pOverlapped 가 NULL로 설정된 경우 pBytesReceived 는 유효한 메모리 주소를 포함해야 하며 NULL로 설정되지 않아야 합니다.

[in, optional] Overlapped

비동기 호출의 경우 pOverlapped 를 OVERLAPPED 구조를 가리키도록 설정하거나 동기 호출의 경우 NULL로 설정합니다.

동기 호출은 클라이언트 인증서가 검색될 때까지 차단되지만 비동기 호출은 즉시 ERROR_IO_PENDING 반환하고 호출 애플리케이션은 GetOverlappedResult 또는 I/O 완료 포트를 사용하여 작업이 완료되는 시기를 결정합니다. 동기화에 OVERLAPPED 구조를 사용하는 방법에 대한 자세한 내용은 동기화 및 겹치는 입력 및 출력 섹션을 참조하세요.

반환 값

값	의미
NO_ERROR	함수가 성공했습니다. 모든 데이터는 pSslClientCertInfo 매개 변수가 가리키는 버퍼에 기록되었습니다. NumberOfBytesTransferred는 버퍼에 기록된 바이트 수를 나타냅니다.
ERROR_IO_PENDING	함수가 비동기적으로 사용되고 있습니다. 작업이 시작되었으며 나중에 일반적인 겹치는 I/O 완료 메커니즘을 통해 완료됩니다.
ERROR_INVALID_PARAMETER	제공된 매개 변수 중 하나 이상이 잘못되었습니다.
ERROR_INSUFFICIENT_BUFFER	pSslClientCertInfo 매개 변수가 가리키는 버퍼가 너무 작아서 데이터를 받을 수 없으며 데이터가 기록되지 않았습니다.
ERROR_MORE_DATA	pSslClientCertInfo 매개 변수가 가리키는 버퍼가 모든 데이터를 수신할 만큼 크지는 않습니다. 기본 구조만 작성되었으며 부분적으로만 채워졌습니다. Flags 매개 변수가 0이면 certEncodedSize 멤버가 채워진 HTTP_SSL_CLIENT_CERT_INFO 구조체가 작성되었습니다. 호출자는 HTTP_SSL_CLIENT_CERT_INFO 구조체의 크기(바이트)와 CertEncodedSize 멤버 값 이상의 버퍼를 사용하여 함수를 다시 호출해야 합니다. Flags 매개 변수가 HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 경우 HTTP_REQUEST_CHANNEL_BIND_STATUS 구조체가 ChannelTokenSize 멤버가 채워진 상태에서 작성되었습니다. 호출자는 HTTP_REQUEST_CHANNEL_BIND_STATUS 크기(바이트)와 ChannelTokenSize 멤버 값 이상의 버퍼를 사용하여 함수를 다시 호출해야 합니다.
ERROR_NOT_FOUND	함수는 클라이언트 인증서 또는 CBT를 찾을 수 없습니다.
기타	WinError.h 헤더 파일에 정의된 시스템 오류 코드입니다.

설명

HttpReceiveClientCertificate 함수의 동작은 클라이언트 SSL 인증서 또는 채널 바인딩 토큰이 요청되었는지 여부에 따라 달라집니다.

HttpReceiveClientCertificate 함수에 대한 동기 호출의 경우 수신된 바이트 수는 pBytesReceived 매개 변수가 가리키는 값으로 반환됩니다.

HttpReceiveClientCertificate 함수에 대한 비동기 호출의 경우 수신된 바이트 수는 비동기 호출에 사용되는 표준 메커니즘에 의해 반환됩니다. GetOverlappedResult 함수에서 반환된 lpNumberOfBytesTransferred 매개 변수에는 수신된 바이트 수가 포함됩니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista, WINDOWS XP SP2 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	http.h
라이브러리	Httpapi.lib
DLL	Httpapi.dll