IBackgroundCopyJobHttpOptions::SetSecurityFlags method (bits2_5.h)

Article
10/13/2021

Sets flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors are ignored, and the policy to use when a server redirects the HTTP request.

Syntax

HRESULT SetSecurityFlags(
  [in] ULONG Flags
);

Parameters

[in] Flags

HTTP security flags that indicate which errors to ignore when connecting to the server. You can set one or more of the following flags:

Value	Meaning
BG_SSL_ENABLE_CRL_CHECK 0x0001	Check the certificate revocation list (CRL) to verify that the server certificate has not been revoked.
BG_SSL_IGNORE_CERT_CN_INVALID 0x0002	Ignores errors caused when the certificate host name of the server does not match the host name in the request.
BG_SSL_IGNORE_CERT_DATE_INVALID 0x0004	Ignores errors caused by an expired certificate.
BG_SSL_IGNORE_UNKNOWN_CA 0x0008	Ignore errors associated with an unknown certification authority (CA).
BG_SSL_IGNORE_CERT_WRONG_USAGE 0x0010	Ignore errors associated with the use of a certificate.
BG_HTTP_REDIRECT_POLICY_ALLOW_SILENT 0x0000	Allows the server to redirect your request to another server. This is the default.
BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT 0x0100	Allows the server to redirect your request to another server. BITS updates the remote name with the final URL.
BG_HTTP_REDIRECT_POLICY_DISALLOW 0x0200	Places the job in the fatal error state when the server redirects your request to another server. BITS updates the remote name with the redirected URL.
BG_HTTP_REDIRECT_POLICY_MASK 0x0700	Bitmask that you can use with the security flag value to determine which redirect policy is in effect. It does not include the flag ALLOW_HTTPS_TO_HTTP.
BG_HTTP_REDIRECT_POLICY_ALLOW_HTTPS_TO_HTTP 0x0800	Allows the server to redirect an HTTPS request to an HTTP URL. You can combine this flag with BG_HTTP_REDIRECT_POLICY_ALLOW_SILENT and BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT.

Return value

The following table lists some of the possible return values.

Return code	Description
S_OK	Successfully retrieved the headers.
E_NOTIMPL	The flag value is not supported.

Remarks

If CRL checking is requested, BITS performs the check for all files in the job that specify the HTTPS protocol. The check is made for each file before the file begins transferring. If you set this value to TRUE after BITS has partially downloaded a file, BITS will reschedule the job and begin downloading the file again. Files that are already downloaded are not affected.

BITS uses the CRL on the local computer if the CRL is up-to-date; otherwise, BITS downloads the CRL from the certification authority (CA) that signed the certificate.

The job goes into the fatal error state if the following errors occur.

Error code	Description
ERROR_WINHTTP_SECURE_CERT_REV_FAILED	Unable to request CRL checking because the certificate server is offline or the CRL cannot be downloaded.
ERROR_WINHTTP_SECURE_CERT_REVOKED	The certificate is revoked.

The redirect policy applies to all files in a download job (the policy does not apply to upload jobs).

Prior to BITS 3.0: The redirect policies are not supported.

If the policy is BG_HTTP_REDIRECT_POLICY_DISALLOW and the server redirects your request, the job is placed in the fatal error state with one of the following error codes. For descriptions of the error codes, see HTTP Status Codes.

HRESULT_FROM_WIN32(HTTP_STATUS_AMBIGUOUS)
HRESULT_FROM_WIN32(HTTP_STATUS_MOVED)
HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT)
HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_METHOD)
HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_KEEP_VERB)

BITS does not support redirection from HTTP or HTTPs to SMB.

If peer caching is enabled and you specify BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT, the file is stored in the cache with the final redirected URL. If a peer then tries to download the file with the original URL, the peer will not find the file in the peer's cache and will end up downloading the file from the origin server.

If you specify and the file is downloaded from the

Note that setting BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT may affect the result when calling the IBackgroundCopyJob3::ReplaceRemotePrefix method. If a server redirected your request, BITS will have already changed the original URL to the final redirected URL, so calling the ReplaceRemotePrefix method will not find files with the original URL.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	bits2_5.h (include Bits.h)
Library	Bits.lib