IWinHttpRequest::SetClientCertificate method

Article
01/07/2021

The SetClientCertificate method selects a client certificate to send to a Secure Hypertext Transfer Protocol (HTTPS) server.

Syntax

HRESULT SetClientCertificate(
  [in] BSTR ClientCertificate
);

Parameters

ClientCertificate [in]: Specifies the location, certificate store, and subject of a client certificate.

Return value

The return value is S_OK on success or an error value otherwise.

Remarks

The string specified in the ClientCertificate parameter consists of the certificate location, certificate store, and subject name delimited by backslashes. For more information about the components of the certificate string, see Client Certificates.

The certificate store name and location are optional. However, if you specify a certificate store, you must also specify the location of that certificate store. The default location is CURRENT_USER and the default certificate store is "MY". A blank subject indicates that the first certificate in the certificate store should be used.

Call SetClientCertificate to select a certificate before calling Send to send the request.

Microsoft Windows HTTP Services (WinHTTP) does not provide client certificates to proxy servers that request certificates for authentication.

Note

For Windows XP and Windows 2000, see the Run-Time Requirements section of the WinHTTP Start Page.

Examples

The following scripting example shows how to select a client certificate to send with a request. A certificate with the subject "My Middle-Tier Certificate" is chosen from the "Personal" certificate store in the registry under HKEY_LOCAL_MACHINE. Because this code example is specific to Microsoft JScript, which uses the backslash as an escape character, two adjacent backslashes are required to delimit components of the certificate string.

// Instantiate a WinHttpRequest object.
var HttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");
    
// Open an HTTP connection.
HttpReq.Open("GET", "https://www.fabrikam.com/", false);
    
// Select a client certificate.
HttpReq.SetClientCertificate(
            "LOCAL_MACHINE\\Personal\\My Middle-Tier Certificate");

// Send the HTTP Request.
HttpReq.Send();

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows 2000 Professional with SP3 [desktop apps only]
Minimum supported server	Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only]
Redistributable	WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000.
IDL	HttpRequest.idl
Library	Winhttp.lib
DLL	Winhttp.dll