Função HttpReceiveClientCertificate (http.h)

Artigo
08/24/2023

A função HttpReceiveClientCertificate é usada por um aplicativo de servidor para recuperar um certificado SSL do cliente ou cbt (token de associação de canal).

Sintaxe

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

Um identificador para a fila de solicitação com a qual o cliente SSL especificado ou CBT está associado. Uma fila de solicitação é criada e seu identificador retornado por uma chamada para a função HttpCreateRequestQueue .

Windows Server 2003 com SP1 e Windows XP com SP2: O identificador para a fila de solicitação é criado pela função HttpCreateHttpHandle .

[in] ConnectionId

Um valor que identifica a conexão com o cliente. Esse valor é obtido do elemento ConnectionId de uma estrutura HTTP_REQUEST preenchida pela função HttpReceiveHttpRequest .

[in] Flags

Um valor que modifica o comportamento da função HttpReceiveClientCertificate

Valor	Significado
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	O parâmetro pSslClientCertInfo será preenchido com dados CBT. Esse valor tem suporte no Windows 7, Windows Server 2008 R2 e posterior.

[out] SslClientCertInfo

Se o parâmetro Flags for 0, esse parâmetro apontará para uma estrutura HTTP_SSL_CLIENT_CERT_INFO na qual a função grava as informações de certificado do cliente solicitadas. O buffer apontado pelo pSslClientCertInfo deve ser suficientemente grande o suficiente para manter a estrutura HTTP_SSL_CLIENT_CERT_INFO mais o valor do membro CertEncodedSize dessa estrutura.

Se o parâmetro Flags for HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, esse parâmetro apontará para uma estrutura HTTP_REQUEST_CHANNEL_BIND_STATUS na qual a função grava as informações de CBT solicitadas. O buffer apontado pelo pSslClientCertInfo deve ser suficientemente grande o suficiente para manter a estrutura HTTP_REQUEST_CHANNEL_BIND_STATUS mais o valor do membro ChannelTokenSize dessa estrutura.

[in] SslClientCertInfoSize

O tamanho, em bytes, do buffer apontado pelo parâmetro pSslClientCertInfo .

[out, optional] BytesReceived

Um ponteiro opcional para uma variável que recebe o número de bytes a serem gravados na estrutura apontada por pSslClientCertInfo. Se não for usado, defina-o como NULL.

Ao fazer uma chamada assíncrona usando pOverlapped, defina pBytesReceived como NULL. Caso contrário, quando pOverlapped é definido como NULL, pBytesReceived deve conter um endereço de memória válido e não ser definido como NULL.

[in, optional] Overlapped

Para chamadas assíncronas, defina pOverlapped para apontar para uma estrutura OVERLAPPED ou, para chamadas síncronas, defina-a como NULL.

Uma chamada síncrona é bloqueada até que o certificado do cliente seja recuperado, enquanto uma chamada assíncrona retorna imediatamente ERROR_IO_PENDING e o aplicativo de chamada usa as portas de conclusão GetOverlappedResult ou de E/S para determinar quando a operação é concluída. Para obter mais informações sobre como usar estruturas OVERLAPPED para sincronização, consulte a seção Sincronização e entrada e saída sobrepostas.

Valor retornado

Valor	Significado
NO_ERROR	A função foi bem-sucedida. Todos os dados foram gravados no buffer apontado pelo parâmetro pSslClientCertInfo . O NumberOfBytesTransferred indica quantos bytes foram gravados no buffer.
ERROR_IO_PENDING	A função está sendo usada de forma assíncrona. A operação foi iniciada e será concluída posteriormente por meio de mecanismos normais de conclusão de E/S sobrepostos.
ERROR_INVALID_PARAMETER	Um ou mais dos parâmetros fornecidos não são válidos.
ERROR_INSUFFICIENT_BUFFER	O buffer apontado pelo parâmetro pSslClientCertInfo é muito pequeno para receber os dados e nenhum dado foi gravado.
ERROR_MORE_DATA	O buffer apontado pelo parâmetro pSslClientCertInfo não é grande o suficiente para receber todos os dados. Somente a estrutura básica foi escrita e apenas parcialmente preenchida. Quando o parâmetro Flags é 0, a estrutura HTTP_SSL_CLIENT_CERT_INFO foi gravada com o membro CertEncodedSize preenchido. O chamador deve chamar a função novamente com um buffer que tenha pelo menos o tamanho, em bytes, da estrutura HTTP_SSL_CLIENT_CERT_INFO mais o valor do membro CertEncodedSize . Quando o parâmetro Flags é HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, a estrutura HTTP_REQUEST_CHANNEL_BIND_STATUS foi gravada com o membro ChannelTokenSize preenchido. O chamador deve chamar a função novamente com um buffer que tenha pelo menos o tamanho, em bytes, do HTTP_REQUEST_CHANNEL_BIND_STATUS mais o valor do membro ChannelTokenSize .
ERROR_NOT_FOUND	A função não pode localizar o certificado do cliente ou CBT.
Outros	Um código de erro do sistema definido no arquivo de cabeçalho WinError.h .

Comentários

O comportamento da função HttpReceiveClientCertificate varia de acordo com a solicitação de um certificado SSL do cliente ou de um token de associação de canal.

No caso de uma chamada síncrona para a função HttpReceiveClientCertificate , o número de bytes recebidos é retornado no valor apontado pelo parâmetro pBytesReceived .

No caso de uma chamada assíncrona para a função HttpReceiveClientCertificate , o número de bytes recebidos é retornado pelos mecanismos padrão usados para chamadas assíncronas. O parâmetro lpNumberOfBytesTransferred retornado pela função GetOverlappedResult contém o número de bytes recebidos.

Requisitos


Cliente mínimo com suporte	Windows Vista, Windows XP com SP2 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	http.h
Biblioteca	Httpapi.lib
DLL	Httpapi.dll