Función HttpReceiveClientCertificate (http.h)

Artículo
08/24/2023

Una aplicación de servidor usa la función HttpReceiveClientCertificate para recuperar un certificado SSL de cliente o un token de enlace de canal (CBT).

Sintaxis

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

Parámetros

[in] RequestQueueHandle

Identificador de la cola de solicitudes con la que está asociado el cliente SSL o CBT especificado. Se crea una cola de solicitudes y se devuelve su identificador mediante una llamada a la función HttpCreateRequestQueue .

Windows Server 2003 con SP1 y Windows XP con SP2: El identificador de la cola de solicitudes se crea mediante la función HttpCreateHttpHandle .

[in] ConnectionId

Valor que identifica la conexión con el cliente. Este valor se obtiene del elemento ConnectionId de una estructura de HTTP_REQUEST rellenada por la función HttpReceiveHttpRequest .

[in] Flags

Valor que modifica el comportamiento de la función HttpReceiveClientCertificate .

Valor	Significado
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	El parámetro pSslClientCertInfo se rellenará con datos CBT. Este valor se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.

[out] SslClientCertInfo

Si el parámetro Flags es 0, este parámetro apunta a una estructura de HTTP_SSL_CLIENT_CERT_INFO en la que la función escribe la información de certificado de cliente solicitada. El búfer al que apunta pSslClientCertInfo debe ser lo suficientemente grande como para contener la estructura HTTP_SSL_CLIENT_CERT_INFO más el valor del miembro CertEncodedSize de esta estructura.

Si el parámetro Flags es HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, este parámetro apunta a una estructura de HTTP_REQUEST_CHANNEL_BIND_STATUS en la que la función escribe la información de CBT solicitada. El búfer al que apunta pSslClientCertInfo debe ser lo suficientemente grande como para contener la estructura HTTP_REQUEST_CHANNEL_BIND_STATUS más el valor del miembro ChannelTokenSize de esta estructura.

[in] SslClientCertInfoSize

Tamaño, en bytes, del búfer al que apunta el parámetro pSslClientCertInfo .

[out, optional] BytesReceived

Puntero opcional a una variable que recibe el número de bytes que se van a escribir en la estructura a la que apunta pSslClientCertInfo. Si no se usa, establézcalo en NULL.

Al realizar una llamada asincrónica mediante pOverlapped, establezca pBytesReceived enNULL. De lo contrario, cuando pOverlapped se establece en NULL, pBytesReceived debe contener una dirección de memoria válida y no establecerse en NULL.

[in, optional] Overlapped

Para las llamadas asincrónicas, establezca pOverlapped para que apunte a una estructura SUPERPUESTA o para llamadas sincrónicas, establézcalo en NULL.

Una llamada sincrónica se bloquea hasta que se recupera el certificado de cliente, mientras que una llamada asincrónica devuelve inmediatamente ERROR_IO_PENDING y la aplicación que realiza la llamada usa puertos getOverlappedResult o de finalización de E/S para determinar cuándo se completa la operación. Para obtener más información sobre el uso de estructuras SUPERPUESTAs para la sincronización, consulte la sección Sincronización y Entrada y salida superpuestas.

Valor devuelto

Valor	Significado
NO_ERROR	La función se ha realizado correctamente. Todos los datos se han escrito en el búfer al que apunta el parámetro pSslClientCertInfo . NumberOfBytesTransferred indica cuántos bytes se escribieron en el búfer.
ERROR_IO_PENDING	La función se usa de forma asincrónica. La operación se ha iniciado y se completará más adelante a través de mecanismos de finalización de E/S superpuestos normales.
ERROR_INVALID_PARAMETER	Uno o varios de los parámetros proporcionados no son válidos.
ERROR_INSUFFICIENT_BUFFER	El búfer al que apunta el parámetro pSslClientCertInfo es demasiado pequeño para recibir los datos y no se escribió ningún dato.
ERROR_MORE_DATA	El búfer al que apunta el parámetro pSslClientCertInfo no es lo suficientemente grande como para recibir todos los datos. Solo se ha escrito la estructura básica y solo se ha rellenado parcialmente. Cuando el parámetro Flags es 0, la estructura HTTP_SSL_CLIENT_CERT_INFO se ha escrito con el miembro CertEncodedSize rellenado. El autor de la llamada debe llamar de nuevo a la función con un búfer que tenga al menos el tamaño, en bytes, de la estructura HTTP_SSL_CLIENT_CERT_INFO más el valor del miembro CertEncodedSize . Cuando se HTTP_RECEIVE_SECURE_CHANNEL_TOKEN el parámetro Flags, la estructura HTTP_REQUEST_CHANNEL_BIND_STATUS se ha escrito con el miembro ChannelTokenSize rellenado. El autor de la llamada debe llamar de nuevo a la función con un búfer que tenga al menos el tamaño, en bytes, del HTTP_REQUEST_CHANNEL_BIND_STATUS más el valor del miembro ChannelTokenSize .
ERROR_NOT_FOUND	La función no encuentra el certificado de cliente o CBT.
Otros	Código de error del sistema definido en el archivo de encabezado WinError.h .

Comentarios

El comportamiento de la función HttpReceiveClientCertificate varía en función de si se solicita un certificado SSL de cliente o un token de enlace de canal.

En el caso de una llamada sincrónica a la función HttpReceiveClientCertificate , el número de bytes recibidos se devuelve en el valor al que apunta el parámetro pBytesReceived .

En el caso de una llamada asincrónica a la función HttpReceiveClientCertificate , los mecanismos estándar utilizados para las llamadas asincrónicas devuelven el número de bytes recibidos. El parámetro lpNumberOfBytesTransferred devuelto por la función GetOverlappedResult contiene el número de bytes recibidos.

Requisitos


Cliente mínimo compatible	Windows Vista, Windows XP con SP2 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	http.h
Library	Httpapi.lib
Archivo DLL	Httpapi.dll