HstsDomainPolicyCollection Class

Namespace: Meziantou.Framework.Http
Assembly: Meziantou.Framework.Http.Hsts.dll
Package: Meziantou.Framework.Http.Hsts 2.1.12
Source: HstsDomainPolicyCollection.cs
Available in package assets: net10.0net11.0

A collection of HSTS (HTTP Strict Transport Security) domain policies that determines which domains should be accessed over HTTPS.

public sealed class HstsDomainPolicyCollection : IEnumerable<HstsDomainPolicy>, IEnumerable

Remarks

Host names are IDNA-canonicalized to their Punycode form and then matched with an ordinal, case-insensitive comparison, so an internationalized domain matches whichever of its two forms is used. The preload list stores Punycode names, and HstsClientHandler looks policies up with Uri.IdnHost, which is already in that form; an ASCII host name is never converted.

HstsDomainPolicy.Host reports the canonicalized name, which may differ from the one that was passed to HstsDomainPolicyCollection.Add.

The built-in preload list is a separate, immutable layer. A policy learned from a response header may widen the coverage of a preloaded host but can never narrow it, expire it or delete it; only HstsDomainPolicyCollection.Remove takes a host off the preload list, and only for this collection. Learned policies are bounded by HstsDomainPolicyCollection.MaxLearnedPolicies.

Enumeration is a moment-in-time view: it may miss a policy added concurrently, it includes learned policies whose HstsDomainPolicy.ExpiresAt has already passed, and it materializes the preload entries as it goes. HstsDomainPolicyCollection.MustUpgradeRequest and HstsDomainPolicyCollection.TryGetPolicy are the authority on whether a host is covered.

Example

// Create a collection with preloaded domains from the Chromium HSTS preload list
var policies = new HstsDomainPolicyCollection(includePreloadDomains: true);
Assert.True(policies.MustUpgradeRequest("github.com"));

// Add a custom domain policy
policies.Add("example.com", TimeSpan.FromDays(365), includeSubdomains: true);

// Check if a domain should be upgraded to HTTPS
Assert.True(policies.MustUpgradeRequest("example.com"));
Assert.True(policies.MustUpgradeRequest("www.example.com"));

Implements

Constructors

Name	Description
HstsDomainPolicyCollection(bool, int)	Initializes a new instance of the `HstsDomainPolicyCollection` class.
HstsDomainPolicyCollection(TimeProvider?, bool, int)	Initializes a new instance of the `HstsDomainPolicyCollection` class with a custom time provider.

HstsDomainPolicyCollection overloads

HstsDomainPolicyCollection(bool, int)

HstsDomainPolicyCollection.cs

Initializes a new instance of the HstsDomainPolicyCollection class.

public HstsDomainPolicyCollection(bool includePreloadDomains = true, int maxLearnedPolicies = 10000)

Parameters

includePreloadDomains bool: If true, includes preloaded domains from the Chromium HSTS preload list. Default is true.
maxLearnedPolicies int: The maximum number of policies learned from response headers that the collection keeps.

HstsDomainPolicyCollection(TimeProvider?, bool, int)

HstsDomainPolicyCollection.cs

Initializes a new instance of the HstsDomainPolicyCollection class with a custom time provider.

public HstsDomainPolicyCollection(TimeProvider? timeProvider, bool includePreloadDomains = true, int maxLearnedPolicies = 10000)

Parameters

timeProvider TimeProvider?: The time provider to use for determining policy expiration. If null, uses TimeProvider.System.
includePreloadDomains bool: If true, includes preloaded domains from the Chromium HSTS preload list. Default is true.
maxLearnedPolicies int: The maximum number of policies learned from response headers that the collection keeps.

Exceptions

ArgumentOutOfRangeException: maxLearnedPolicies is not positive.

Properties

Name	Description
Default	Gets the default HSTS policy collection that includes preloaded domains from the Chromium HSTS preload list.
MaxLearnedPolicies	Gets the maximum number of policies learned from response headers that this collection keeps.

Default

HstsDomainPolicyCollection.cs

Gets the default HSTS policy collection that includes preloaded domains from the Chromium HSTS preload list.

public static HstsDomainPolicyCollection Default { get; }

Property value

HstsDomainPolicyCollection

Remarks

This instance is shared by the whole process, so every HstsClientHandler built without an explicit collection observes the policies learned by the others. Create a dedicated collection to isolate a client, and see HstsDomainPolicyCollection.ClearLearnedPolicies to return this one to its initial state.

MaxLearnedPolicies

HstsDomainPolicyCollection.cs

Gets the maximum number of policies learned from response headers that this collection keeps.

public int MaxLearnedPolicies { get; }

Property value

int

Remarks

Preloaded entries do not count towards this limit.

Methods

Name	Description
Add(string, DateTimeOffset, bool)	Adds or updates an HSTS policy for the specified host with an expiration date.
Add(string, TimeSpan, bool)	Adds or updates an HSTS policy for the specified host with a maximum age.
ClearLearnedPolicies()	Drops every policy learned from a response header and restores any preloaded host that `HstsDomainPolicyCollection.Remove` took off the list.
GetEnumerator()
MustUpgradeRequest(ReadOnlySpan<char>)	Determines whether an HTTP request to the specified host should be upgraded to HTTPS based on HSTS policies.
MustUpgradeRequest(string)	Determines whether an HTTP request to the specified host should be upgraded to HTTPS based on HSTS policies.
Remove(string)	Removes the HSTS policy for the specified host, including a policy from the preload list.
System.Collections.IEnumerable.GetEnumerator()
TryGetPolicy(string, HstsDomainPolicy?)	Gets the effective HSTS policy for the specified host, if the host has one of its own.

Add overloads

Add(string, DateTimeOffset, bool)

HstsDomainPolicyCollection.cs

Adds or updates an HSTS policy for the specified host with an expiration date.

public void Add(string host, DateTimeOffset expiresAt, bool includeSubdomains)

Parameters

host string: The domain host name. An internationalized domain may be given in either its Unicode or its Punycode form.
expiresAt DateTimeOffset: The date and time when the HSTS policy expires.
includeSubdomains bool: If true, the policy applies to all subdomains of the host.

Exceptions

ArgumentException: host is not a valid host name, or cannot be converted to its Punycode form.

Remarks

A host on the built-in preload list keeps its preloaded coverage: this policy can widen it but not narrow it.

Add(string, TimeSpan, bool)

HstsDomainPolicyCollection.cs

Adds or updates an HSTS policy for the specified host with a maximum age.

public void Add(string host, TimeSpan maxAge, bool includeSubdomains)

Parameters

host string: The domain host name. An internationalized domain may be given in either its Unicode or its Punycode form.
maxAge TimeSpan: The duration for which the HSTS policy should be in effect.
includeSubdomains bool: If true, the policy applies to all subdomains of the host.

Exceptions

ArgumentException: host is not a valid host name, or cannot be converted to its Punycode form.

ClearLearnedPolicies()

HstsDomainPolicyCollection.cs

Drops every policy learned from a response header and restores any preloaded host that HstsDomainPolicyCollection.Remove took off the list.

public void ClearLearnedPolicies()

Remarks

This returns the collection to the state it was constructed in. It is the supported way to reset HstsDomainPolicyCollection.Default, which is shared by the whole process.

GetEnumerator()

HstsDomainPolicyCollection.cs

public IEnumerator<HstsDomainPolicy> GetEnumerator()

Returns

IEnumerator<HstsDomainPolicy>

No documentation is available.

MustUpgradeRequest overloads

MustUpgradeRequest(ReadOnlySpan<char>)

HstsDomainPolicyCollection.cs

Determines whether an HTTP request to the specified host should be upgraded to HTTPS based on HSTS policies.

public bool MustUpgradeRequest(ReadOnlySpan<char> host)

Parameters

host ReadOnlySpan<char>: The domain host name to check. An internationalized domain may be given in either its Unicode or its Punycode form.

Returns

bool true if the request should be upgraded to HTTPS; otherwise, false.

MustUpgradeRequest(string)

HstsDomainPolicyCollection.cs

Determines whether an HTTP request to the specified host should be upgraded to HTTPS based on HSTS policies.

public bool MustUpgradeRequest(string host)

Parameters

host string: The domain host name to check. An internationalized domain may be given in either its Unicode or its Punycode form.

Returns

bool true if the request should be upgraded to HTTPS; otherwise, false.

Remove(string)

HstsDomainPolicyCollection.cs

Removes the HSTS policy for the specified host, including a policy from the preload list.

public bool Remove(string host)

Parameters

host string: The domain host name. An internationalized domain may be given in either its Unicode or its Punycode form.

Returns

bool true if a policy was removed; otherwise, false.

Remarks

Removing a preloaded host masks it for this collection only; the built-in list is shared and immutable. HstsDomainPolicyCollection.ClearLearnedPolicies restores it.

System.Collections.IEnumerable.GetEnumerator()

HstsDomainPolicyCollection.cs

IEnumerator IEnumerable.GetEnumerator()

Returns

IEnumerator

No documentation is available.

TryGetPolicy(string, HstsDomainPolicy?)

HstsDomainPolicyCollection.cs

Gets the effective HSTS policy for the specified host, if the host has one of its own.

public bool TryGetPolicy(string host, out HstsDomainPolicy? policy)

Parameters

host string: The domain host name. An internationalized domain may be given in either its Unicode or its Punycode form.
policy HstsDomainPolicy?: When this method returns, the policy registered for that exact host name.

Returns

bool true if the host has a policy of its own; otherwise, false.

Remarks

This reports the policy registered for host itself. A host covered only by a parent domain's HstsDomainPolicy.IncludeSubdomains has no policy of its own and returns false here while HstsDomainPolicyCollection.MustUpgradeRequest returns true.

Constants

Name	Description
DefaultMaxLearnedPolicies	The number of learned policies a collection keeps by default.

DefaultMaxLearnedPolicies

The number of learned policies a collection keeps by default.

public const int DefaultMaxLearnedPolicies = 10000