Soup.HSTSEnforcer¶

Subclasses:: Soup.HSTSEnforcerDB

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`get_domains` (session_policies)
	`get_policies` (session_policies)
	`has_valid_policy` (domain)
	`is_persistent` ()
	`set_policy` (policy)
	`set_session_policy` (domain, include_subdomains)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_changed` (old_policy, new_policy)
	`do_has_valid_policy` (domain)
	`do_is_persistent` ()

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`changed`	Emitted when hsts_enforcer changes.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Soup.HSTSEnforcer(**kwargs)¶

Bases:: GObject.Object, Soup.SessionFeature
Abstract:: No
Structure:: Soup.HSTSEnforcerClass

Automatic HTTP Strict Transport Security enforcing for [class`Session`].

A Soup.HSTSEnforcer stores HSTS policies and enforces them when required. Soup.HSTSEnforcer implements [iface`SessionFeature`], so you can add an HSTS enforcer to a session with [method`Session`.add_feature] or [method`Session`.add_feature_by_type].

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

When the [class`Session`] the Soup.HSTSEnforcer is attached to queues or restarts a message, the Soup.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 Soup.HSTSEnforcer are advised to listen to changes in the [property`Message`:py:data::uri<Soup.HSTSEnforcer.props.uri>] property in order to be aware of changes in the message URI.

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

classmethod new()¶

Returns:: a new Soup.HSTSEnforcer
Return type:: Soup.HSTSEnforcer

Creates a new Soup.HSTSEnforcer.

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

get_domains(session_policies)¶

Parameters:: session_policies (bool) – whether to include session policies
Returns:: a newly allocated list of domains. Use [func`GLib`.List.free_full] and [func`GLib`.free] to free the list.
Return type:: [str]

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

get_policies(session_policies)¶

Parameters:: session_policies (bool) – whether to include session policies
Returns:: a newly allocated list of policies. Use [func`GLib`.List.free_full] and [method`HSTSPolicy`.free] to free the list.
Return type:: [Soup.HSTSPolicy]

Gets a list with the policies in enforcer.

has_valid_policy(domain)¶

Parameters:: domain (str) – a domain.
Returns:: True if access to domain should happen over HTTPS, false otherwise.
Return type:: bool

Gets whether self has a currently valid policy for domain.

is_persistent()¶

Returns:: True if self storage is persistent or False otherwise.
Return type:: bool

Gets whether self stores policies persistenly.

set_policy(policy)¶

Parameters:: policy (Soup.HSTSPolicy) – the policy of the HSTS host

Sets policy to self.

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 [ctor`HSTSPolicy`.new_session_policy], the policy will not expire and will be enforced during the lifetime of self's [class`Session`].

set_session_policy(domain, include_subdomains)¶

Parameters:

domain (str) – policy domain or hostname
include_subdomains (bool) – True if the policy applies on sub domains

Sets a session policy for domain.

A session policy is a policy that is permanent to the lifetime of self's [class`Session`] and doesn’t expire.

do_changed(old_policy, new_policy) virtual¶

Parameters:

old_policy (Soup.HSTSPolicy) –
new_policy (Soup.HSTSPolicy) –

do_has_valid_policy(domain) virtual¶

Parameters:: domain (str) – a domain.
Returns:: True if access to domain should happen over HTTPS, false otherwise.
Return type:: bool

Gets whether hsts_enforcer has a currently valid policy for domain.

do_is_persistent() virtual¶

Returns:: True if hsts_enforcer storage is persistent or False otherwise.
Return type:: bool

Gets whether hsts_enforcer stores policies persistenly.

Signal Details¶

Soup.HSTSEnforcer.signals.changed(h_s_t_s_enforcer, old_policy, new_policy)¶

Signal Name:

changed

Flags:

RUN_FIRST

Parameters:

h_s_t_s_enforcer (Soup.HSTSEnforcer) – The object which received the signal
old_policy (Soup.HSTSPolicy) – the old Soup.HSTSPolicy value
new_policy (Soup.HSTSPolicy) – the new Soup.HSTSPolicy value

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.