Edit

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface method (bits10_3.h)

  • Article

Server certificates are sent when an HTTPS connection is opened. Use this method to set a callback to be called to validate those server certificates.

Syntax

HRESULT SetServerCertificateValidationInterface(
  IUnknown *certValidationCallback
);

Parameters

certValidationCallback

Type: IUnknown*

A pointer to an object that implements IBackgroundCopyServerCertificateValidationCallback. To remove the current callback interface pointer, set this parameter to nullptr.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Return value Description
E_NOINTERFACE You pass an interface pointer that cannot be queried for IBackgroundCopyServerCertificateValidationCallback.
BG_E_READ_ONLY_WHEN_JOB_ACTIVE The state of a job must be PAUSED to set the callback.

Remarks

Use this method when you want to perform your own checks on the server certificate.

Call this method only if you implement the IBackgroundCopyServerCertificateValidationCallback interface.

The validation interface becomes invalid when your application terminates; BITS does not maintain a record of the validation interface. As a result, your application's initialization process should call SetServerCertificateValidationInterface on those existing jobs for which you want to receive certificate validation requests.

If more than one application calls SetServerCertificateValidationInterface to set the notification interface for the job, the last application to call it is the one that will receive notifications. The other applications will not receive notifications.

If any certificate errors are found during the OS validation of the certificate, then the connection is aborted, and the custom callback is never called. You can customize the OS validation logic with a call to IBackgroundCopyJobHttpOptions::SetSecurityFlags. For example, you can ignore expected certificate validation errors.

If OS validation passes, then the IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate method is called before completing the TLS handshake and before the HTTP request is sent.

If your validation method declines the certificate, the job will transition to BG_JOB_STATE_TRANSIENT_ERROR with a job error context of BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK and the error HRESULT from your callback. If your callback couldn't be called (for example, because BITS needed to validate a server certificate after your program exited), then the job error code will be BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. When your application is next run, it can fix this error by setting the validation callback again and resuming the job.

Requirements

Requirement Value
Minimum supported client Windows 10, version 1809 [desktop apps only]
Minimum supported server Windows Server 2016 [desktop apps only]
Header bits10_3.h (include Bits.h)
Library Bits.lib
DLL Bits.dll

See also

IBackgroundCopyServerCertificateValidationCallback