IHttpRequest：：NegotiateClientCertificate 方法

起始與 Web 用戶端的用戶端憑證交涉。

語法

HRESULT NegotiateClientCertificate(  
   IN BOOL fAsync,  
   OUT BOOL* pfCompletionPending = NULL  
)   

參數

fAsync
[IN] true 表示應該以非同步方式發生交涉;否則為 false 。

pfCompletionPending
[OUT] true 表示指定非同步完成擱置中;否則為 false 。

傳回值

HRESULT。 可能的值包括 (但不限於) 下表中的這些值。

值	定義
S_OK	表示作業成功。
E_FAIL	表示作業失敗。

備註

開發人員可以使用 NegotiateClientCertificate 方法來手動起始與 Web 用戶端的用戶端憑證交涉，即使 IIS 設定為接受或忽略用戶端憑證也一樣。 NegotiateClientCertificate 藉由在 參數中 fAsync 指定適當的設定，支援同步和非同步作業。 當您的模組以非同步方式呼叫 NegotiateClientCertificate 時，如果 pfCompletionPending 值指出非同步完成擱置，則模組必須在呼叫 方法之後，立即將處理傳回整合式要求處理管線。

範例

下列範例示範如何呼叫 NegotiateClientCertificate 方法。

REQUEST_NOTIFICATION_STATUS
CMyHttpModule::OnBeginRequest(
                              IHttpContext*       pHttpContext,
                              IHttpEventProvider* // pProvider  
                              )
{
   static long cnt;     
   InterlockedIncrement (&cnt);  // keep track of how many times we are called
   HRESULT hr = E_FAIL;
   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 RQ_NOTIFICATION_CONTINUE;
   }

   // change the bForce flag to test behavior of forcing load of client cert
   bool bForce=true;
   if(bForce){
      TRC_MSG("forcing load of client cert");
      hr = pIHTTPR->NegotiateClientCertificate(FALSE);
      if(FAILED(hr)){
         LOG_ERR_HR(hr, "NegotiateClientCertificate : HR = ");
         return RQ_NOTIFICATION_CONTINUE;
      }
   }
   else
      TRC_MSG("Not forcing load of client cert");

   HTTP_SSL_CLIENT_CERT_INFO *pClientCertInfo;
   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)){
      TRC_MSG( "Cert not found" );
      return RQ_NOTIFICATION_CONTINUE;
   }
   if(FAILED(hr)){
      LOG_ERR_HR("GetClientCertificate", hr);
      return RQ_NOTIFICATION_CONTINUE;
   }	

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

   return RQ_NOTIFICATION_CONTINUE;
}

如需如何建立及部署原生 DLL 模組的詳細資訊，請參閱逐步解說 ：使用機器碼建立Request-Level HTTP 模組。

您可以選擇性地使用呼叫慣例編譯器代碼， __stdcall (/Gz) 而不是明確宣告每個函式的呼叫慣例。

規格需求

類型	描述
Client	- Windows Vista 上的 IIS 7.0 - Windows 7 上的 IIS 7.5 - Windows 8 上的 IIS 8.0 - Windows 10上的 IIS 10.0
伺服器	- Windows Server 2008 上的 IIS 7.0 - Windows Server 2008 R2 上的 IIS 7.5 - Windows Server 2012 上的 IIS 8.0 - Windows Server 2012 R2 上的 IIS 8.5 - Windows Server 2016上的 IIS 10.0
產品	- IIS 7.0、IIS 7.5、IIS 8.0、IIS 8.5、IIS 10.0 - IIS Express 7.5、IIS Express 8.0、IIS Express 10.0
標頭	Httpserv.h

另請參閱

IHttpRequest 介面
IHttpRequest：：GetClientCertificate 方法