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 ()

## Signals

void | changed | Run First

## Types and Values

| SoupHSTSEnforcer
struct | SoupHSTSEnforcerClass

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