SoupHSTSEnforcer

SoupHSTSEnforcer — Automatic HTTP Strict Transport Security enforcing for SoupSession

Functions

Signals

Types and Values

Object Hierarchy

    GBoxed
    ╰── SoupHSTSPolicy
    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 SoupHSTSDBEnforcer 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

Since: 2.68


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.

Since: 2.68


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.

Since: 2.68


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]

Since: 2.68


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

 

Since: 2.68


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]

Since: 2.68


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]

Since: 2.68


soup_hsts_policy_new ()

SoupHSTSPolicy *
soup_hsts_policy_new (const char *domain,
                      unsigned long  max_age,
                      gboolean include_subdomains);

Creates a new SoupHSTSPolicy with the given attributes.

domain is a domain on which the strict transport security policy represented by this object must be enforced.

max_age is used to set the "expires" attribute on the policy; pass SOUP_HSTS_POLICY_MAX_AGE_PAST for an already-expired policy, or a lifetime in seconds.

If include_subdomains is TRUE, the strict transport security policy must also be enforced on all subdomains of domain .

Parameters

domain

policy domain or hostname

 

max_age

max age of the policy

 

include_subdomains

TRUE if the policy applies on subdomains

 

Returns

a new SoupHSTSPolicy.

Since: 2.68


soup_hsts_policy_new_full ()

SoupHSTSPolicy *
soup_hsts_policy_new_full (const char *domain,
                           unsigned long  max_age,
                           SoupDate *expires,
                           gboolean include_subdomains);

Full version of soup_hsts_policy_new(), to use with an existing expiration date. See soup_hsts_policy_new() for details.

Parameters

domain

policy domain or hostname

 

max_age

max age of the policy

 

expires

the date of expiration of the policy or NULL for a permanent policy

 

include_subdomains

TRUE if the policy applies on subdomains

 

Returns

a new SoupHSTSPolicy.

Since: 2.68


soup_hsts_policy_new_from_response ()

SoupHSTSPolicy *
soup_hsts_policy_new_from_response (SoupMessage *msg);

Parses msg 's first "Strict-Transport-Security" response header and returns a SoupHSTSPolicy.

Parameters

msg

a SoupMessage

 

Returns

a new SoupHSTSPolicy, or NULL if no valid "Strict-Transport-Security" response header was found.

[nullable]

Since: 2.68


soup_hsts_policy_copy ()

SoupHSTSPolicy *
soup_hsts_policy_copy (SoupHSTSPolicy *policy);

Copies policy .

Parameters

policy

a SoupHSTSPolicy

 

Returns

a copy of policy .

[transfer full]

Since: 2.68


soup_hsts_policy_equal ()

gboolean
soup_hsts_policy_equal (SoupHSTSPolicy *policy1,
                        SoupHSTSPolicy *policy2);

Tests if policy1 and policy2 are equal.

Parameters

policy1

a SoupHSTSPolicy

 

policy2

a SoupHSTSPolicy

 

Returns

whether the policies are equal.

Since: 2.68


soup_hsts_policy_free ()

void
soup_hsts_policy_free (SoupHSTSPolicy *policy);

Frees policy .

Parameters

policy

a SoupHSTSPolicy.

[transfer full]

Since: 2.68


soup_hsts_policy_get_domain ()

const char *
soup_hsts_policy_get_domain (SoupHSTSPolicy *policy);

Gets policy 's domain.

Parameters

policy

a SoupHSTSPolicy

 

Returns

policy 's domain.

[transfer none]

Since: 2.68


soup_hsts_policy_is_expired ()

gboolean
soup_hsts_policy_is_expired (SoupHSTSPolicy *policy);

Gets whether policy is expired. Permanent policies never expire.

Parameters

policy

a SoupHSTSPolicy

 

Returns

TRUE if policy is expired, FALSE otherwise.

Since: 2.68


soup_hsts_policy_includes_subdomains ()

gboolean
soup_hsts_policy_includes_subdomains (SoupHSTSPolicy *policy);

Gets whether policy include its subdomains.

Parameters

policy

a SoupHSTSPolicy

 

Returns

TRUE if policy includes subdomains, FALSE otherwise.

Since: 2.68


soup_hsts_policy_is_session_policy ()

gboolean
soup_hsts_policy_is_session_policy (SoupHSTSPolicy *policy);

Gets whether policy is a non-permanent, non-expirable session policy. see soup_hsts_policy_new_session_policy() for details.

Parameters

policy

a SoupHSTSPolicy

 

Returns

TRUE if policy is permanent, FALSE otherwise

Since: 2.68

Types and Values

SoupHSTSEnforcer

typedef struct _SoupHSTSEnforcer SoupHSTSEnforcer;

SoupHSTSEnforcerClass

typedef struct {
	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);

	void (*hsts_enforced) (SoupHSTSEnforcer *enforcer,
			       SoupMessage      *message);

	/* Padding for future expansion */
	void (*_libsoup_reserved1) (void);
	void (*_libsoup_reserved2) (void);
	void (*_libsoup_reserved3) (void);
	void (*_libsoup_reserved4) (void);
} SoupHSTSEnforcerClass;

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 SoupURI 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.

 

hsts_enforced ()

   

_libsoup_reserved1 ()

   

_libsoup_reserved2 ()

   

_libsoup_reserved3 ()

   

_libsoup_reserved4 ()

   

SoupHSTSPolicy

typedef struct {
	char                 *domain;
	unsigned long         max_age;
	SoupDate             *expires;
	gboolean              include_subdomains;
} SoupHSTSPolicy;

An HTTP Strict Transport Security policy.

domain represents the host that this policy applies to. The domain must be IDNA-canonicalized. soup_hsts_policy_new() and related methods will do this for you.

max_age contains the 'max-age' value from the Strict Transport Security header and indicates the time to live of this policy, in seconds.

expires will be non-NULL if the policy has been set by the host and hence has an expiry time. If expires is NULL, it indicates that the policy is a permanent session policy set by the user agent.

If include_subdomains is TRUE, the Strict Transport Security policy must also be enforced on subdomains of domain .

Members

char *domain;

The domain or hostname that the policy applies to

 

unsigned long max_age;

The maximum age, in seconds, that the policy is valid

 

SoupDate *expires;

the policy expiration time, or NULL for a permanent session policy

 

gboolean include_subdomains;

TRUE if the policy applies on subdomains

 

Since: 2.68


SOUP_HSTS_POLICY_MAX_AGE_PAST

#define SOUP_HSTS_POLICY_MAX_AGE_PAST (0)

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


The “hsts-enforced” signal

void
user_function (SoupHSTSEnforcer *hsts_enforcer,
               SoupMessage      *message,
               gpointer          user_data)

Emitted when hsts_enforcer has upgraded the protocol for message to HTTPS as a result of matching its domain with a HSTS policy.

Parameters

hsts_enforcer

the SoupHSTSEnforcer

 

message

the message for which HSTS is being enforced

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First