SoupHSTSPolicy: libsoup Reference Manual

## SoupHSTSPolicy SoupHSTSPolicy — HSTS policies |

## Functions

SoupHSTSPolicy * | soup_hsts_policy_new ()
SoupHSTSPolicy * | soup_hsts_policy_new_full ()
SoupHSTSPolicy * | soup_hsts_policy_new_session_policy ()
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 ()
gulong | soup_hsts_policy_get_max_age ()
GDateTime * | soup_hsts_policy_get_expires ()
gboolean | soup_hsts_policy_is_expired ()
gboolean | soup_hsts_policy_includes_subdomains ()
gboolean | soup_hsts_policy_is_session_policy ()

## Types and Values

| SoupHSTSPolicy
#define | SOUP_HSTS_POLICY_MAX_AGE_PAST

## Object Hierarchy

        GBoxed
        ╰── SoupHSTSPolicy

## Includes

    #include <libsoup/soup.h>

## Description

Policies to be used with SoupHSTSEnforcer.

## Functions

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

### soup_hsts_policy_new_full ()

    SoupHSTSPolicy *
    soup_hsts_policy_new_full (const char *domain,
                               unsigned long  max_age,
                               GDateTime *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.

### soup_hsts_policy_new_session_policy ()

    SoupHSTSPolicy *
    soup_hsts_policy_new_session_policy (const char *domain,
                                         gboolean include_subdomains);

Creates a new session SoupHSTSPolicy with the given attributes. A session policy is a policy that is valid during the lifetime of the SoupHSTSEnforcer it is added to. Contrary to regular policies, it has no expiration date and is not stored in persistent enforcers. These policies are useful for user-agent to load their own or user-defined rules.

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

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 |
include_subdomains | `TRUE` if the policy applies on sub domains |

#### Returns

a new SoupHSTSPolicy.

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

### soup_hsts_policy_copy ()

    SoupHSTSPolicy *
    soup_hsts_policy_copy (SoupHSTSPolicy *policy);

Copies `policy` .

#### Parameters

policy | a SoupHSTSPolicy |

#### Returns

a copy of `policy` .

[transfer full]

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

### soup_hsts_policy_free ()

    void
    soup_hsts_policy_free (SoupHSTSPolicy *policy);

Frees `policy` .

#### Parameters

policy | a SoupHSTSPolicy. | [transfer full]

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

### soup_hsts_policy_get_max_age ()

    gulong
    soup_hsts_policy_get_max_age (SoupHSTSPolicy *policy);

Returns the max age for `policy` .

#### Parameters

policy | a SoupHSTSPolicy |

#### Returns

Max age in seconds

### soup_hsts_policy_get_expires ()

    GDateTime *
    soup_hsts_policy_get_expires (SoupHSTSPolicy *policy);

Returns the expiration date for `policy` .

#### Parameters

policy | a SoupHSTSPolicy |

#### Returns

A GDateTime or `NULL` if unset

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

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

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

## Types and Values

### SoupHSTSPolicy

    typedef struct _SoupHSTSPolicy SoupHSTSPolicy;

SoupHSTSPolicy implements HTTP policies, as described by RFC 6797.

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

### SOUP_HSTS_POLICY_MAX_AGE_PAST

    #define SOUP_HSTS_POLICY_MAX_AGE_PAST (0)

An expiration date that is always in the past.