HttpReceiveClientCertificate-Funktion (http.h)

Artikel
08/24/2023

Die HttpReceiveClientCertificate-Funktion wird von einer Serveranwendung verwendet, um ein Client-SSL-Zertifikat oder kanalbindungstoken (CBT) abzurufen.

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

Parameter

[in] RequestQueueHandle

Ein Handle für die Anforderungswarteschlange, der der angegebene SSL-Client oder CBT zugeordnet ist. Eine Anforderungswarteschlange wird erstellt, und ihr Handle wird durch einen Aufruf der HttpCreateRequestQueue-Funktion zurückgegeben.

Windows Server 2003 mit SP1 und Windows XP mit SP2: Das Handle für die Anforderungswarteschlange wird von der HttpCreateHttpHandle-Funktion erstellt.

[in] ConnectionId

Ein Wert, der die Verbindung mit dem Client identifiziert. Dieser Wert wird vom ConnectionId-Element einer HTTP_REQUEST Struktur abgerufen, die von der HttpReceiveHttpRequest-Funktion ausgefüllt wird.

[in] Flags

Ein Wert, der das Verhalten der HttpReceiveClientCertificate-Funktion ändert

Wert	Bedeutung
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	Der Parameter pSslClientCertInfo wird mit CBT-Daten aufgefüllt. Dieser Wert wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.

[out] SslClientCertInfo

Wenn der Flags-Parameter 0 ist, verweist dieser Parameter auf eine HTTP_SSL_CLIENT_CERT_INFO Struktur, in die die Funktion die angeforderten Clientzertifikatinformationen schreibt. Der Puffer, auf den das pSslClientCertInfo verweist, sollte ausreichend groß sein, um die HTTP_SSL_CLIENT_CERT_INFO Struktur plus den Wert des CertEncodedSize-Members dieser Struktur zu enthalten.

Wenn der Flags-ParameterHTTP_RECEIVE_SECURE_CHANNEL_TOKEN ist, verweist dieser Parameter auf eine HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur , in die die Funktion die angeforderten CBT-Informationen schreibt. Der Puffer, auf den das pSslClientCertInfo verweist, sollte ausreichend groß sein, um die HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur plus den Wert des ChannelTokenSize-Members dieser Struktur zu enthalten.

[in] SslClientCertInfoSize

Die Größe des Puffers in Bytes, auf die der pSslClientCertInfo-Parameter verweist.

[out, optional] BytesReceived

Ein optionaler Zeiger auf eine Variable, die die Anzahl der Bytes empfängt, die in die Struktur geschrieben werden sollen, auf die pSslClientCertInfo verweist. Wenn nicht verwendet, legen Sie es auf NULL fest.

Wenn Sie einen asynchronen Aufruf mithilfe von pOverlapped ausführen, legen Sie pBytesReceived auf NULL fest. Andernfalls muss pBytesReceived eine gültige Speicheradresse enthalten und nicht auf NULL festgelegt werden, wenn pOverlapped auf NULL festgelegt ist.

[in, optional] Overlapped

Legen Sie bei asynchronen Aufrufen pOverlapped auf eine OVERLAPPED-Struktur fest, oder legen Sie sie bei synchronen Aufrufen auf NULL fest.

Ein synchroner Aufruf blockiert, bis das Clientzertifikat abgerufen wird, während ein asynchroner Aufruf sofort ERROR_IO_PENDING zurückgibt, und die aufrufende Anwendung verwendet dann GetOverlappedResult - oder E/A-Vervollständigungsports, um zu bestimmen, wann der Vorgang abgeschlossen ist. Weitere Informationen zur Verwendung von OVERLAPPED-Strukturen für die Synchronisierung finden Sie im Abschnitt Synchronisierung und überlappende Eingabe und Ausgabe.

Rückgabewert

Wert	Bedeutung
NO_ERROR	Die Funktion wurde erfolgreich ausgeführt. Alle Daten wurden in den Puffer geschrieben, auf den der pSslClientCertInfo-Parameter verweist. NumberOfBytesTransferred gibt an, wie viele Bytes in den Puffer geschrieben wurden.
ERROR_IO_PENDING	Die Funktion wird asynchron verwendet. Der Vorgang wurde initiiert und wird später über normale überlappende E/A-Vervollständigungsmechanismen abgeschlossen.
ERROR_INVALID_PARAMETER	Mindestens ein der angegebenen Parameter ist ungültig.
ERROR_INSUFFICIENT_BUFFER	Der Puffer, auf den der pSslClientCertInfo-Parameter verweist, ist zu klein, um die Daten zu empfangen, und es wurden keine Daten geschrieben.
ERROR_MORE_DATA	Der Puffer, auf den der pSslClientCertInfo-Parameter verweist, ist nicht groß genug, um alle Daten zu empfangen. Nur die Grundstruktur wurde geschrieben und nur teilweise aufgefüllt. Wenn der Flags-Parameter 0 ist, wurde die HTTP_SSL_CLIENT_CERT_INFO-Struktur mit aufgefülltem CertEncodedSize-Member geschrieben. Der Aufrufer sollte die Funktion erneut mit einem Puffer aufrufen, der mindestens die Größe der HTTP_SSL_CLIENT_CERT_INFO-Struktur in Bytes und den Wert des CertEncodedSize-Members aufweist. Wenn der Flags-ParameterHTTP_RECEIVE_SECURE_CHANNEL_TOKEN ist, wurde die HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur mit aufgefülltem ChannelTokenSize-Member geschrieben. Der Aufrufer sollte die Funktion erneut mit einem Puffer aufrufen, der mindestens die Größe des HTTP_REQUEST_CHANNEL_BIND_STATUS in Bytes plus den Wert des ChannelTokenSize-Elements aufweist.
ERROR_NOT_FOUND	Die Funktion kann das Clientzertifikat oder CBT nicht finden.
Andere	Ein Systemfehlercode , der in der WinError.h-Headerdatei definiert ist.

Hinweise

Das Verhalten der HttpReceiveClientCertificate-Funktion variiert je nachdem, ob ein Client-SSL-Zertifikat oder ein Kanalbindungstoken angefordert wird.

Bei einem synchronen Aufruf der HttpReceiveClientCertificate-Funktion wird die Anzahl der empfangenen Bytes im Wert zurückgegeben, auf den der pBytesReceived-Parameter verweist.

Bei einem asynchronen Aufruf der HttpReceiveClientCertificate-Funktion wird die Anzahl der empfangenen Bytes von den Standardmechanismen zurückgegeben, die für asynchrone Aufrufe verwendet werden. Der lpNumberOfBytesTransferred-Parameter , der von der GetOverlappedResult-Funktion zurückgegeben wird, enthält die Anzahl der empfangenen Bytes.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP2 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	http.h
Bibliothek	Httpapi.lib
DLL	Httpapi.dll