HttpReceiveClientCertificate function (http.h)

Article
10/13/2021

The HttpReceiveClientCertificate function is used by a server application to retrieve a client SSL certificate or channel binding token (CBT).

Syntax

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
);

Parameters

[in] RequestQueueHandle

A handle to the request queue with which the specified SSL client or CBT is associated. A request queue is created and its handle returned by a call to the HttpCreateRequestQueue function.

Windows Server 2003 with SP1 and Windows XP with SP2: The handle to the request queue is created by the HttpCreateHttpHandle function.

[in] ConnectionId

A value that identifies the connection to the client. This value is obtained from the ConnectionId element of an HTTP_REQUEST structure filled in by the HttpReceiveHttpRequest function.

[in] Flags

A value that modifies the behavior of the HttpReceiveClientCertificate function

Value	Meaning
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	The pSslClientCertInfo parameter will be populated with CBT data. This value is supported on Windows 7, Windows Server 2008 R2, and later.

[out] SslClientCertInfo

If the Flags parameter is 0, then this parameter points to an HTTP_SSL_CLIENT_CERT_INFO structure into which the function writes the requested client certificate information. The buffer pointed to by the pSslClientCertInfo should be sufficiently large enough to hold the HTTP_SSL_CLIENT_CERT_INFO structure plus the value of the CertEncodedSize member of this structure.

If the Flags parameter is HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, then this parameter points to an HTTP_REQUEST_CHANNEL_BIND_STATUS structure into which the function writes the requested CBT information. The buffer pointed to by the pSslClientCertInfo should be sufficiently large enough to hold the HTTP_REQUEST_CHANNEL_BIND_STATUS structure plus the value of the ChannelTokenSize member of this structure.

[in] SslClientCertInfoSize

The size, in bytes, of the buffer pointed to by the pSslClientCertInfo parameter.

[out, optional] BytesReceived

An optional pointer to a variable that receives the number of bytes to be written to the structure pointed to by pSslClientCertInfo. If not used, set it to NULL.

When making an asynchronous call using pOverlapped, set pBytesReceived to NULL. Otherwise, when pOverlapped is set to NULL, pBytesReceived must contain a valid memory address, and not be set to NULL.

[in, optional] Overlapped

For asynchronous calls, set pOverlapped to point to an OVERLAPPED structure, or for synchronous calls, set it to NULL.

A synchronous call blocks until the client certificate is retrieved, whereas an asynchronous call immediately returns ERROR_IO_PENDING and the calling application then uses GetOverlappedResult or I/O completion ports to determine when the operation is completed. For more information about using OVERLAPPED structures for synchronization, see the section Synchronization and Overlapped Input and Output.

Return value

Value	Meaning
NO_ERROR	The function succeeded. All the data has been written into the buffer pointed to by the pSslClientCertInfo parameter. The NumberOfBytesTransferred indicates how many bytes were written into the buffer.
ERROR_IO_PENDING	The function is being used asynchronously. The operation has been initiated and will complete later through normal overlapped I/O completion mechanisms.
ERROR_INVALID_PARAMETER	One or more of the supplied parameters is not valid.
ERROR_INSUFFICIENT_BUFFER	The buffer pointed to by the pSslClientCertInfo parameter is too small to receive the data and no data was written.
ERROR_MORE_DATA	The buffer pointed to by the pSslClientCertInfo parameter is not large enough to receive all the data. Only the basic structure has been written and only partially populated. When the Flags parameter is 0, the HTTP_SSL_CLIENT_CERT_INFO structure has been written with the CertEncodedSize member populated. The caller should call the function again with a buffer that is at least the size, in bytes, of the HTTP_SSL_CLIENT_CERT_INFO structure plus the value of the CertEncodedSize member. When the Flags parameter is HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, the HTTP_REQUEST_CHANNEL_BIND_STATUS structure has been written with the ChannelTokenSize member populated. The caller should call the function again with a buffer that is at least the size, in bytes, of the HTTP_REQUEST_CHANNEL_BIND_STATUS plus the value of the ChannelTokenSize member.
ERROR_NOT_FOUND	The function cannot find the client certificate or CBT.
Other	A system error code defined in the WinError.h header file.

Remarks

The behavior of the HttpReceiveClientCertificate function varies based on whether a client SSL certificate or a channel binding token is requested.

In the case of a synchronous call to the HttpReceiveClientCertificate function , the number of bytes received is returned in the value pointed to by the pBytesReceived parameter.

In the case of an asynchronous call to the HttpReceiveClientCertificate function, the number of bytes received is returned by the standard mechanisms used for asynchronous calls. The lpNumberOfBytesTransferred parameter returned by the GetOverlappedResult function contains the number of bytes received.

Requirements

Requirement	Value
Minimum supported client	Windows Vista, Windows XP with SP2 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	http.h
Library	Httpapi.lib
DLL	Httpapi.dll