SoupHSTSEnforcer

SoupHSTSEnforcer — Automatic HTTP Strict Transport Security enforcing for SoupSession

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── SoupHSTSEnforcer
        ╰── SoupHSTSEnforcerDB

Implemented Interfaces

SoupHSTSEnforcer implements SoupSessionFeature.

Includes

#include <libsoup/soup.h>

Description

A SoupHSTSEnforcer stores HSTS policies and enforces them when required. SoupHSTSEnforcer implements SoupSessionFeature, so you can add an HSTS enforcer to a session with soup_session_add_feature() or soup_session_add_feature_by_type().

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

When the SoupSession the SoupHSTSEnforcer is attached to queues or restarts a message, the SoupHSTSEnforcer 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 SoupHSTSEnforcer are advised to listen to changes in SoupMessage:uri in order to be aware of changes in the message URI.

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

Functions

soup_hsts_enforcer_new ()

SoupHSTSEnforcer *
soup_hsts_enforcer_new (void);

Creates a new SoupHSTSEnforcer. The base SoupHSTSEnforcer class does not support persistent storage of HSTS policies, see SoupHSTSEnforcerDB for that.

Returns

a new SoupHSTSEnforcer


soup_hsts_enforcer_is_persistent ()

gboolean
soup_hsts_enforcer_is_persistent (SoupHSTSEnforcer *hsts_enforcer);

Gets whether hsts_enforcer stores policies persistenly.

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

Returns

TRUE if hsts_enforcer storage is persistent or FALSE otherwise.


soup_hsts_enforcer_has_valid_policy ()

gboolean
soup_hsts_enforcer_has_valid_policy (SoupHSTSEnforcer *hsts_enforcer,
                                     const char *domain);

Gets whether hsts_enforcer has a currently valid policy for domain .

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

domain

a domain.

 

Returns

TRUE if access to domain should happen over HTTPS, false otherwise.


soup_hsts_enforcer_set_policy ()

void
soup_hsts_enforcer_set_policy (SoupHSTSEnforcer *hsts_enforcer,
                               SoupHSTSPolicy *policy);

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 soup_hsts_policy_new_session_policy(), the policy will not expire and will be enforced during the lifetime of hsts_enforcer 's SoupSession.

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

policy

the policy of the HSTS host.

[transfer none]

soup_hsts_enforcer_set_session_policy ()

void
soup_hsts_enforcer_set_session_policy (SoupHSTSEnforcer *hsts_enforcer,
                                       const char *domain,
                                       gboolean include_subdomains);

Sets a session policy for domain . A session policy is a policy that is permanent to the lifetime of hsts_enforcer 's SoupSession and doesn't expire.

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

domain

policy domain or hostname

 

include_subdomains

TRUE if the policy applies on sub domains

 

soup_hsts_enforcer_get_domains ()

GList *
soup_hsts_enforcer_get_domains (SoupHSTSEnforcer *hsts_enforcer,
                                gboolean session_policies);

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

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

session_policies

whether to include session policies

 

Returns

a newly allocated list of domains. Use g_list_free_full() and g_free() to free the list.

[element-type utf8][transfer full]


soup_hsts_enforcer_get_policies ()

GList *
soup_hsts_enforcer_get_policies (SoupHSTSEnforcer *hsts_enforcer,
                                 gboolean session_policies);

Gets a list with the policies in enforcer .

Parameters

hsts_enforcer

a SoupHSTSEnforcer

 

session_policies

whether to include session policies

 

Returns

a newly allocated list of policies. Use g_list_free_full() and soup_hsts_policy_free() to free the list.

[element-type SoupHSTSPolicy][transfer full]

Types and Values

SoupHSTSEnforcer

typedef struct _SoupHSTSEnforcer SoupHSTSEnforcer;

Class for storing and enforcing a SoupHSTSPolicy.


struct SoupHSTSEnforcerClass

struct SoupHSTSEnforcerClass {
	GObjectClass parent_class;

	gboolean (*is_persistent) (SoupHSTSEnforcer *hsts_enforcer);
	gboolean (*has_valid_policy) (SoupHSTSEnforcer *hsts_enforcer, const char *domain);

	/* signals */
	void (*changed) (SoupHSTSEnforcer *enforcer,
			 SoupHSTSPolicy	  *old_policy,
			 SoupHSTSPolicy	  *new_policy);
};

Class structure for SoupHSTSEnforcer.

Members

is_persistent ()

The is_persistent function advertises whether the enforcer is persistent or whether changes made to it will be lost when the underlying SoupSession is finished.

 

has_valid_policy ()

The has_valid_policy function is called to check whether there is a valid policy for the given domain. This method should return TRUE for SoupHSTSEnforcer to change the scheme of the GUri in the SoupMessage to HTTPS. Implementations might want to chain up to the has_valid_policy in the parent class to check, for instance, for runtime policies.

 

changed ()

The class closure for the “changed” signal.

 

Signal Details

The “changed” signal

void
user_function (SoupHSTSEnforcer *hsts_enforcer,
               SoupHSTSPolicy   *old_policy,
               SoupHSTSPolicy   *new_policy,
               gpointer          user_data)

Emitted when hsts_enforcer changes. If a policy has been added, new_policy will contain the newly-added policy and old_policy will be NULL. If a policy has been deleted, old_policy will contain the to-be-deleted policy and new_policy will be NULL. 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

hsts_enforcer

the SoupHSTSEnforcer

 

old_policy

the old SoupHSTSPolicy value

 

new_policy

the new SoupHSTSPolicy value

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First