HSTSEnforcer

class HSTSEnforcer(**properties: Any)

Superclasses: Object

Subclasses: HSTSEnforcerDB

Implemented Interfaces: SessionFeature

Automatic HTTP Strict Transport Security enforcing for Session.

A HSTSEnforcer stores HSTS policies and enforces them when required. HSTSEnforcer implements SessionFeature, so you can add an HSTS enforcer to a session with add_feature or add_feature_by_type.

HSTSEnforcer keeps track of all the HTTPS destinations that, when connected to, return the Strict-Transport-Security header with valid values. HSTSEnforcer will forget those destinations upon expiry or when the server requests it.

When the Session the HSTSEnforcer is attached to queues or restarts a message, the HSTSEnforcer will rewrite the URI to HTTPS if the destination is a known HSTS host and is contacted over an insecure transport protocol (HTTP). Users of HSTSEnforcer are advised to listen to changes in the uri property in order to be aware of changes in the message URI.

Note that HSTSEnforcer does not support any form of long-term HSTS policy persistence. See HSTSEnforcerDB for a persistent enforcer.

Constructors

class HSTSEnforcer
classmethod new() → HSTSEnforcer

Creates a new HSTSEnforcer.

The base HSTSEnforcer class does not support persistent storage of HSTS policies, see HSTSEnforcerDB for that.

Methods

class HSTSEnforcer
get_domains(session_policies: bool) → list[str]

Gets a list of domains for which there are policies in enforcer.

Parameters:

session_policies – whether to include session policies

get_policies(session_policies: bool) → list[HSTSPolicy]

Gets a list with the policies in enforcer.

Parameters:

session_policies – whether to include session policies

has_valid_policy(domain: str) → bool

Gets whether hsts_enforcer has a currently valid policy for domain.

Parameters:

domain – a domain.

is_persistent() → bool

Gets whether hsts_enforcer stores policies persistenly.

set_policy(policy: HSTSPolicy) → None

Sets policy to hsts_enforcer.

If policy is expired, any existing HSTS policy for its host will be removed instead. If a policy existed for this host, it will be replaced. Otherwise, the new policy will be inserted. If the policy is a session policy, that is, one created with new_session_policy, the policy will not expire and will be enforced during the lifetime of hsts_enforcer’s Session.

Parameters:

policy – the policy of the HSTS host

set_session_policy(domain: str, include_subdomains: bool) → None

Sets a session policy for domain.

A session policy is a policy that is permanent to the lifetime of hsts_enforcer’s Session and doesn’t expire.

Parameters:

  • domain – policy domain or hostname

  • include_subdomains – True if the policy applies on sub domains

Signals

class HSTSEnforcer.signals
changed(old_policy: HSTSPolicy, new_policy: HSTSPolicy) → None

Emitted when hsts_enforcer changes.

If a policy has been added, new_policy will contain the newly-added policy and old_policy will be None. If a policy has been deleted, old_policy will contain the to-be-deleted policy and new_policy will be None. If a policy has been changed, old_policy will contain its old value, and new_policy its new value.

Note that you shouldn’t modify the policies from a callback to this signal.

Parameters:

Virtual Methods

class HSTSEnforcer
do_changed(old_policy: HSTSPolicy, new_policy: HSTSPolicy) → None
Parameters:

  • old_policy

  • new_policy

do_has_valid_policy(domain: str) → bool

Gets whether hsts_enforcer has a currently valid policy for domain.

Parameters:

domain – a domain.

do_is_persistent() → bool

Gets whether hsts_enforcer stores policies persistenly.

Fields

class HSTSEnforcer
parent_instance