SoupHSTSEnforcer: libsoup Reference Manual

## SoupHSTSEnforcer SoupHSTSEnforcer — Automatic HTTP Strict Transport Security enforcing for SoupSession |

## Functions

SoupHSTSEnforcer * | soup_hsts_enforcer_new ()
gboolean | soup_hsts_enforcer_is_persistent ()
gboolean | soup_hsts_enforcer_has_valid_policy ()
void | soup_hsts_enforcer_set_policy ()
void | soup_hsts_enforcer_set_session_policy ()
GList * | soup_hsts_enforcer_get_domains ()
GList * | soup_hsts_enforcer_get_policies ()
SoupHSTSPolicy * | soup_hsts_policy_new ()
SoupHSTSPolicy * | soup_hsts_policy_new_full ()
SoupHSTSPolicy * | soup_hsts_policy_new_from_response ()
SoupHSTSPolicy * | soup_hsts_policy_copy ()
gboolean | soup_hsts_policy_equal ()
void | soup_hsts_policy_free ()
const char * | soup_hsts_policy_get_domain ()
gboolean | soup_hsts_policy_is_expired ()
gboolean | soup_hsts_policy_includes_subdomains ()
gboolean | soup_hsts_policy_is_session_policy ()

## Signals

void | changed | Run First
void | hsts-enforced | Run First

## Types and Values

| SoupHSTSEnforcer
| SoupHSTSEnforcerClass
| SoupHSTSPolicy
#define | SOUP_HSTS_POLICY_MAX_AGE_PAST

## 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