Export (0) Print
Expand All

IHttpRequest::GetClientCertificate Method

IIS 7.0

Retrieves the client certificate associated with the request.

HRESULT GetClientCertificate(
   OUT HTTP_SSL_CLIENT_CERT_INFO** ppClientCertInfo,
   OUT BOOL* pfClientCertNegotiated
);

ppClientCertInfo

[OUT] A pointer to an HTTP_SSL_CLIENT_CERT_INFO structure.

pfClientCertNegotiated

[OUT] true if the client certificate has been negotiated already; otherwise, false. For more information, see the Remarks section.

An HRESULT. Possible values include, but are not limited to, those in the following table.

Value

Definition

S_OK

Indicates that no error occurred, but does not guarantee that a certificate was found. For more information, see the Remarks section.

HRESULT_FROM_WIN32(ERROR_NOT_FOUND)

Indicates no client certificate was found. ERROR_NOT_FOUND is defined in Winerror.h.

ERROR_INVALID_PARAMETER

Indicates that the ppClientCertInfo or pfClientCertNegotiated parameter is NULL.

A successful HRESULT does not guarantee that a client certificate was found. Developers must also verify that ppClientCertInfo is not NULL.

A pfClientCertNegotiated value of true does not guarantee that the ppClientCertInfo is not NULL.

Developers can use the GetClientCertificate method to retrieve the client certificate associated with the current request. After you call the GetClientCertificate method, the ppClientCertInfo parameter will contain a pointer to an HTTP_SSL_CLIENT_CERT_INFO structure, which will contain the client certificate if one is available or NULL if no certificate is available.

For URLs that do not require a client certificate, you can call the NegotiateClientCertificate method before you call GetClientCertificate to attempt a manual loading of the client certificate.

The following example demonstrates how to get a pointer to the HTTP_SSL_CLIENT_CERT_INFO structure by implementing the CHttpModule::OnBeginRequest method.

void   checkForClientCert(IHttpContext*  pHttpContext)
{
   static long cnt;     
   // keep track of how many times we are called
   InterlockedIncrement (&cnt);  
   HRESULT hr = S_OK;
   IHttpRequest *pIHTTPR = pHttpContext->GetRequest();
   HTTP_REQUEST * pRawRequest = pIHTTPR->GetRawHttpRequest();
   HTTP_COOKED_URL hcu = pRawRequest->CookedUrl;

   // Send URL and count to the trace window
   TRC_MSGW_FULL(L"cnt = " << cnt << " URI: " << hcu.pFullUrl);

   // return immediately if not a HTTPS request
   if ( pRawRequest->pSslInfo == NULL ){
      TRC_MSG( "connection is not using SSL");
      return;
   }

   HTTP_SSL_CLIENT_CERT_INFO *pClientCertInfo=NULL;
   BOOL fccNeg;
   hr = pIHTTPR->GetClientCertificate(&pClientCertInfo,&fccNeg);

   // If you have not selected "Require Client Certificates" or called
   // NegotiateClientCertificate(), you  may get  ERROR_NOT_FOUND 

   if( hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
      pClientCertInfo == NULL ){
         TRC_HR_MSG(hr, "Cert not found" );
         return;
   }
   if(FAILED(hr)){
      LOG_ERR_HR("GetClientCertificate", hr);
      return;
   }	

   // You must verify pClientCertInfo != NULL

   if( fccNeg && pClientCertInfo != NULL){
      ULONG uSiz = pClientCertInfo->CertEncodedSize;
      TRC_MSG( "cert size: " << uSiz \
         << " Previously negotiated " << fccNeg );
      // compute the CRC check sum of the certificate
      unsigned long certCrc = genCRC(pClientCertInfo->pCertEncoded,
         pClientCertInfo->CertEncodedSize);
      TRC_MSG( "cert crc: " << certCrc );
   }
   else
      TRC_MSG( "No client certificate. fccNeg = " << fccNeg );
}

REQUEST_NOTIFICATION_STATUS
CMyHttpModule::OnBeginRequest(
                              IHttpContext*       pHttpContext,
                              IHttpEventProvider* // pProvider  
                              )
{
   checkForClientCert(pHttpContext);
   return RQ_NOTIFICATION_CONTINUE;
}



For more information about how to create and deploy a native DLL module, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Type

Description

Client

  • IIS 7.0 on Windows Vista

  • IIS 7.5 on Windows 7

  • IIS Express 7.5 on Windows XP, Windows Vista, Windows 7

  • IIS 8.0 on Windows 8 Client

Server

  • IIS 7.0 on Windows Server 2008

  • IIS 7.5 on Windows Server 2008 R2

  • IIS Express 7.5 on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2

  • IIS 8.0 on Windows Server 2012

Product

IIS 7.0, IIS 7.5, IIS Express 7.5, IIS 8.0

Header

Httpserv.h

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft