HttpReceiveClientCertificate function (http.h)
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 |
|---|---|
|
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 |
|---|---|
|
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. |
|
The function is being used asynchronously. The operation has been initiated and will complete later through normal overlapped I/O completion mechanisms. |
|
One or more of the supplied parameters is not valid. |
|
The buffer pointed to by the pSslClientCertInfo parameter is too small to receive the data and no data was written. |
|
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. |
|
The function cannot find the client certificate or CBT. |
|
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 |
See also
HTTP Server API Version 1.0 Functions