HSTS Support

<refentry> <refmeta> <refentrytitle>SoupHSTSEnforcer</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupHSTSEnforcer</refentrytitle>

<refname>SoupHSTSEnforcer</refname> <refpurpose>Automatic HTTP Strict Transport Security enforcing for <type>SoupSession</type></refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupHSTSEnforcer</returnvalue> * </entry><entry>soup_hsts_enforcer_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_enforcer_is_persistent <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_enforcer_has_valid_policy <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_hsts_enforcer_set_policy <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_hsts_enforcer_set_session_policy <phrase>()</phrase></entry></row> <row><entry><returnvalue>GList</returnvalue> * </entry><entry>soup_hsts_enforcer_get_domains <phrase>()</phrase></entry></row> <row><entry><returnvalue>GList</returnvalue> * </entry><entry>soup_hsts_enforcer_get_policies <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Signals</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>void</returnvalue></entry><entry>changed</entry><entry>Run First</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupHSTSEnforcer</entry></row> <row><entry>struct</entry><entry>SoupHSTSEnforcerClass</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupHSTSEnforcer <phrase>╰──</phrase> SoupHSTSEnforcerDB </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupHSTSEnforcer implements SoupSessionFeature.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para>A <type>SoupHSTSEnforcer</type> stores HSTS policies and enforces them when required. <type>SoupHSTSEnforcer</type> implements <type>SoupSessionFeature</type>, so you can add an HSTS enforcer to a session with <function>soup_session_add_feature()</function> or <function>soup_session_add_feature_by_type()</function>.</para> <para><type>SoupHSTSEnforcer</type> keeps track of all the HTTPS destinations that, when connected to, return the Strict-Transport-Security header with valid values. <type>SoupHSTSEnforcer</type> will forget those destinations upon expiry or when the server requests it.</para> <para>When the <type>SoupSession</type> the <type>SoupHSTSEnforcer</type> is attached to queues or restarts a message, the <type>SoupHSTSEnforcer</type> 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 <type>SoupHSTSEnforcer</type> are advised to listen to changes in SoupMessage:uri in order to be aware of changes in the message URI.</para> <para>Note that <type>SoupHSTSEnforcer</type> does not support any form of long-term HSTS policy persistence. See <type>SoupHSTSEnforcerDB</type> for a persistent enforcer.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_hsts_enforcer_new ()</title> <programlisting><returnvalue>SoupHSTSEnforcer</returnvalue> * soup_hsts_enforcer_new (<parameter><type>void</type></parameter>);</programlisting> <para>Creates a new <type>SoupHSTSEnforcer</type>. The base <type>SoupHSTSEnforcer</type> class does not support persistent storage of HSTS policies, see <type>SoupHSTSEnforcerDB</type> for that.</para> <refsect3> <title>Returns</title> <para> a new <type>SoupHSTSEnforcer</type></para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_is_persistent ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_enforcer_is_persistent (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>);</programlisting> <para>Gets whether <parameter>hsts_enforcer</parameter> stores policies persistenly.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>hsts_enforcer</parameter> storage is persistent or <literal>FALSE</literal> otherwise.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_has_valid_policy ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_enforcer_has_valid_policy (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>, <parameter>const <type>char</type> *domain</parameter>);</programlisting> <para>Gets whether <parameter>hsts_enforcer</parameter> has a currently valid policy for <parameter>domain</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>domain</para></entry> <entry><para>a domain.</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if access to <parameter>domain</parameter> should happen over HTTPS, false otherwise.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_set_policy ()</title> <programlisting><returnvalue>void</returnvalue> soup_hsts_enforcer_set_policy (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>, <parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Sets <parameter>policy</parameter> to <parameter>hsts_enforcer</parameter> . If <parameter>policy</parameter> 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 <function>soup_hsts_policy_new_session_policy()</function>, the policy will not expire and will be enforced during the lifetime of <parameter>hsts_enforcer</parameter> 's <type>SoupSession</type>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>policy</para></entry> <entry><para>the policy of the HSTS host. </para></entry> <entry><emphasis>[transfer none]</emphasis></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_set_session_policy ()</title> <programlisting><returnvalue>void</returnvalue> soup_hsts_enforcer_set_session_policy (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>, <parameter>const <type>char</type> *domain</parameter>, <parameter><type>gboolean</type> include_subdomains</parameter>);</programlisting> <para>Sets a session policy for <parameter>domain</parameter> . A session policy is a policy that is permanent to the lifetime of <parameter>hsts_enforcer</parameter> 's <type>SoupSession</type> and doesn't expire.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>domain</para></entry> <entry><para>policy domain or hostname</para></entry> <entry></entry></row> <row><entry><para>include_subdomains</para></entry> <entry><para><literal>TRUE</literal> if the policy applies on sub domains</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_get_domains ()</title> <programlisting><returnvalue>GList</returnvalue> * soup_hsts_enforcer_get_domains (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>, <parameter><type>gboolean</type> session_policies</parameter>);</programlisting> <para>Gets a list of domains for which there are policies in <parameter>enforcer</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>session_policies</para></entry> <entry><para>whether to include session policies</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>a newly allocated list of domains. Use <function>g_list_free_full()</function> and <function>g_free()</function> to free the list. </para> <para><emphasis>[element-type utf8][transfer full]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_enforcer_get_policies ()</title> <programlisting><returnvalue>GList</returnvalue> * soup_hsts_enforcer_get_policies (<parameter><type>SoupHSTSEnforcer</type> *hsts_enforcer</parameter>, <parameter><type>gboolean</type> session_policies</parameter>);</programlisting> <para>Gets a list with the policies in <parameter>enforcer</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>a <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>session_policies</para></entry> <entry><para>whether to include session policies</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>a newly allocated list of policies. Use <function>g_list_free_full()</function> and <function>soup_hsts_policy_free()</function> to free the list. </para> <para><emphasis>[element-type SoupHSTSPolicy][transfer full]</emphasis></para> </refsect3></refsect2> </refsect1>
<refsect1> <title>Types and Values</title> <refsect2> <title>SoupHSTSEnforcer</title> <programlisting>typedef struct _SoupHSTSEnforcer SoupHSTSEnforcer;</programlisting> <para>Class for storing and enforcing a <type>SoupHSTSPolicy</type>.</para> </refsect2>
<refsect2> <title>struct SoupHSTSEnforcerClass</title> <programlisting>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); }; </programlisting> <para>Class structure for <type>SoupHSTSEnforcer</type>.</para> <refsect3> <title>Members</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para><structfield>is_persistent</structfield> ()</para></entry> <entry><para>The <parameter>is_persistent</parameter> function advertises whether the enforcer is persistent or whether changes made to it will be lost when the underlying <type>SoupSession</type> is finished.</para></entry> <entry></entry> </row> <row><entry><para><structfield>has_valid_policy</structfield> ()</para></entry> <entry><para>The <parameter>has_valid_policy</parameter> function is called to check whether there is a valid policy for the given domain. This method should return <literal>TRUE</literal> for <type>SoupHSTSEnforcer</type> to change the scheme of the <type>GUri</type> in the <type>SoupMessage</type> to HTTPS. Implementations might want to chain up to the <parameter>has_valid_policy</parameter> in the parent class to check, for instance, for runtime policies.</para></entry> <entry></entry> </row> <row><entry><para><structfield>changed</structfield> ()</para></entry> <entry><para>The class closure for the <type>“changed”</type> signal.</para></entry> <entry></entry> </row> </tbody></tgroup></informaltable> </refsect3> </refsect2> </refsect1>
<refsect1> <title>Signal Details</title> <refsect2><title>The <literal>“changed”</literal> signal</title> <programlisting><returnvalue>void</returnvalue> user_function (<type>SoupHSTSEnforcer</type> *hsts_enforcer, <type>SoupHSTSPolicy</type> *old_policy, <type>SoupHSTSPolicy</type> *new_policy, <type>gpointer</type> user_data)</programlisting> <para>Emitted when <parameter>hsts_enforcer</parameter> changes. If a policy has been added, <parameter>new_policy</parameter> will contain the newly-added policy and <parameter>old_policy</parameter> will be <literal>NULL</literal>. If a policy has been deleted, <parameter>old_policy</parameter> will contain the to-be-deleted policy and <parameter>new_policy</parameter> will be <literal>NULL</literal>. If a policy has been changed, <parameter>old_policy</parameter> will contain its old value, and <parameter>new_policy</parameter> its new value.</para> <para>Note that you shouldn't modify the policies from a callback to this signal.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>hsts_enforcer</para></entry> <entry><para>the <type>SoupHSTSEnforcer</type></para></entry> <entry></entry></row> <row><entry><para>old_policy</para></entry> <entry><para>the old <type>SoupHSTSPolicy</type> value</para></entry> <entry></entry></row> <row><entry><para>new_policy</para></entry> <entry><para>the new <type>SoupHSTSPolicy</type> value</para></entry> <entry></entry></row> <row><entry><simpara>user_data</simpara></entry> <entry><simpara>user data set when the signal handler was connected.</simpara></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><para>Flags: Run First</para> </refsect2> </refsect1> </refentry>
<refentry> <refmeta> <refentrytitle>SoupHSTSEnforcerDB</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupHSTSEnforcerDB</refentrytitle>

<refname>SoupHSTSEnforcerDB</refname> <refpurpose>Persistent HTTP Strict Transport Security enforcer</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupHSTSEnforcer</returnvalue> * </entry><entry>soup_hsts_enforcer_db_new <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>char</type> *</entry><entry>filename</entry><entry>Read / Write / Construct Only</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupHSTSEnforcerDB</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupHSTSEnforcer <phrase>╰──</phrase> SoupHSTSEnforcerDB </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupHSTSEnforcerDB implements SoupSessionFeature.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupHSTSEnforcerDB</type> is a <type>SoupHSTSEnforcer</type> that uses a SQLite database as a backend for persistency.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_hsts_enforcer_db_new ()</title> <programlisting><returnvalue>SoupHSTSEnforcer</returnvalue> * soup_hsts_enforcer_db_new (<parameter>const <type>char</type> *filename</parameter>);</programlisting> <para>Creates a <type>SoupHSTSEnforcerDB</type>.</para> <para><parameter>filename</parameter> will be read in during the initialization of a <type>SoupHSTSEnforcerDB</type>, in order to create an initial set of HSTS policies. If the file doesn't exist, a new database will be created and initialized. Changes to the policies during the lifetime of a <type>SoupHSTSEnforcerDB</type> will be written to <parameter>filename</parameter> when <type>“changed”</type> is emitted.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>filename</para></entry> <entry><para>the filename of the database to read/write from.</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the new <type>SoupHSTSEnforcer</type></para> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupHSTSEnforcerDB</title> <programlisting>typedef struct _SoupHSTSEnforcerDB SoupHSTSEnforcerDB;</programlisting> <para>Subclass of <type>SoupHSTSEnforcer</type> using an sqlite database.</para> </refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“filename”</literal> property</title> <programlisting> “filename” <type>char</type> *</programlisting> <para>The filename of the SQLite database where HSTS policies are stored.</para> <para>Owner: SoupHSTSEnforcerDB</para> <para>Flags: Read / Write / Construct Only</para> <para>Default value: NULL</para> </refsect2> </refsect1> </refentry>
<refentry> <refmeta> <refentrytitle>SoupHSTSPolicy</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupHSTSPolicy</refentrytitle>

<refname>SoupHSTSPolicy</refname> <refpurpose>HSTS policies</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupHSTSPolicy</returnvalue> * </entry><entry>soup_hsts_policy_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>SoupHSTSPolicy</returnvalue> * </entry><entry>soup_hsts_policy_new_full <phrase>()</phrase></entry></row> <row><entry><returnvalue>SoupHSTSPolicy</returnvalue> * </entry><entry>soup_hsts_policy_new_session_policy <phrase>()</phrase></entry></row> <row><entry><returnvalue>SoupHSTSPolicy</returnvalue> * </entry><entry>soup_hsts_policy_new_from_response <phrase>()</phrase></entry></row> <row><entry><returnvalue>SoupHSTSPolicy</returnvalue> * </entry><entry>soup_hsts_policy_copy <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_policy_equal <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_hsts_policy_free <phrase>()</phrase></entry></row> <row><entry>const <returnvalue>char</returnvalue> * </entry><entry>soup_hsts_policy_get_domain <phrase>()</phrase></entry></row> <row><entry><returnvalue>gulong</returnvalue> </entry><entry>soup_hsts_policy_get_max_age <phrase>()</phrase></entry></row> <row><entry><returnvalue>GDateTime</returnvalue> * </entry><entry>soup_hsts_policy_get_expires <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_policy_is_expired <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_policy_includes_subdomains <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_hsts_policy_is_session_policy <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupHSTSPolicy</entry></row> <row><entry>#define</entry><entry>SOUP_HSTS_POLICY_MAX_AGE_PAST</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GBoxed <phrase>╰──</phrase> SoupHSTSPolicy </screen> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para>Policies to be used with <type>SoupHSTSEnforcer</type>.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_hsts_policy_new ()</title> <programlisting><returnvalue>SoupHSTSPolicy</returnvalue> * soup_hsts_policy_new (<parameter>const <type>char</type> *domain</parameter>, <parameter><type>unsigned long </type> max_age</parameter>, <parameter><type>gboolean</type> include_subdomains</parameter>);</programlisting> <para>Creates a new <type>SoupHSTSPolicy</type> with the given attributes.</para> <para><parameter>domain</parameter> is a domain on which the strict transport security policy represented by this object must be enforced.</para> <para><parameter>max_age</parameter> 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.</para> <para>If <parameter>include_subdomains</parameter> is <literal>TRUE</literal>, the strict transport security policy must also be enforced on all subdomains of <parameter>domain</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>policy domain or hostname</para></entry> <entry></entry></row> <row><entry><para>max_age</para></entry> <entry><para>max age of the policy</para></entry> <entry></entry></row> <row><entry><para>include_subdomains</para></entry> <entry><para><literal>TRUE</literal> if the policy applies on subdomains</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> a new <type>SoupHSTSPolicy</type>.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_new_full ()</title> <programlisting><returnvalue>SoupHSTSPolicy</returnvalue> * soup_hsts_policy_new_full (<parameter>const <type>char</type> *domain</parameter>, <parameter><type>unsigned long </type> max_age</parameter>, <parameter><type>GDateTime</type> *expires</parameter>, <parameter><type>gboolean</type> include_subdomains</parameter>);</programlisting> <para>Full version of <function><function>soup_hsts_policy_new()</function></function>, to use with an existing expiration date. See <function><function>soup_hsts_policy_new()</function></function> for details.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>policy domain or hostname</para></entry> <entry></entry></row> <row><entry><para>max_age</para></entry> <entry><para>max age of the policy</para></entry> <entry></entry></row> <row><entry><para>expires</para></entry> <entry><para>the date of expiration of the policy or <literal>NULL</literal> for a permanent policy</para></entry> <entry></entry></row> <row><entry><para>include_subdomains</para></entry> <entry><para><literal>TRUE</literal> if the policy applies on subdomains</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> a new <type>SoupHSTSPolicy</type>.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_new_session_policy ()</title> <programlisting><returnvalue>SoupHSTSPolicy</returnvalue> * soup_hsts_policy_new_session_policy (<parameter>const <type>char</type> *domain</parameter>, <parameter><type>gboolean</type> include_subdomains</parameter>);</programlisting> <para>Creates a new session <type>SoupHSTSPolicy</type> with the given attributes. A session policy is a policy that is valid during the lifetime of the <type>SoupHSTSEnforcer</type> 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.</para> <para><parameter>domain</parameter> is a domain on which the strict transport security policy represented by this object must be enforced.</para> <para>If <parameter>include_subdomains</parameter> is <literal>TRUE</literal>, the strict transport security policy must also be enforced on all subdomains of <parameter>domain</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>policy domain or hostname</para></entry> <entry></entry></row> <row><entry><para>include_subdomains</para></entry> <entry><para><literal>TRUE</literal> if the policy applies on sub domains</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> a new <type>SoupHSTSPolicy</type>.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_new_from_response ()</title> <programlisting><returnvalue>SoupHSTSPolicy</returnvalue> * soup_hsts_policy_new_from_response (<parameter><type>SoupMessage</type> *msg</parameter>);</programlisting> <para>Parses <parameter>msg</parameter> 's first "Strict-Transport-Security" response header and returns a <type>SoupHSTSPolicy</type>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupMessage</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>a new <type>SoupHSTSPolicy</type>, or <literal>NULL</literal> if no valid "Strict-Transport-Security" response header was found. </para> <para><emphasis>[nullable]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_copy ()</title> <programlisting><returnvalue>SoupHSTSPolicy</returnvalue> * soup_hsts_policy_copy (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Copies <parameter>policy</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>a copy of <parameter>policy</parameter> . </para> <para><emphasis>[transfer full]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_equal ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_policy_equal (<parameter><type>SoupHSTSPolicy</type> *policy1</parameter>, <parameter><type>SoupHSTSPolicy</type> *policy2</parameter>);</programlisting> <para>Tests if <parameter>policy1</parameter> and <parameter>policy2</parameter> are equal.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy1</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> <row><entry><para>policy2</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> whether the policies are equal.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_free ()</title> <programlisting><returnvalue>void</returnvalue> soup_hsts_policy_free (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Frees <parameter>policy</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type>. </para></entry> <entry><emphasis>[transfer full]</emphasis></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_get_domain ()</title> <programlisting>const <returnvalue>char</returnvalue> * soup_hsts_policy_get_domain (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Gets <parameter>policy</parameter> 's domain.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para><parameter>policy</parameter> 's domain. </para> <para><emphasis>[transfer none]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_get_max_age ()</title> <programlisting><returnvalue>gulong</returnvalue> soup_hsts_policy_get_max_age (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Returns the max age for <parameter>policy</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> Max age in seconds</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_get_expires ()</title> <programlisting><returnvalue>GDateTime</returnvalue> * soup_hsts_policy_get_expires (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Returns the expiration date for <parameter>policy</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> A <type>GDateTime</type> or <literal>NULL</literal> if unset</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_is_expired ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_policy_is_expired (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Gets whether <parameter>policy</parameter> is expired. Permanent policies never expire.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>policy</parameter> is expired, <literal>FALSE</literal> otherwise.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_includes_subdomains ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_policy_includes_subdomains (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Gets whether <parameter>policy</parameter> include its subdomains.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>policy</parameter> includes subdomains, <literal>FALSE</literal> otherwise.</para> </refsect3></refsect2>
<refsect2> <title>soup_hsts_policy_is_session_policy ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_hsts_policy_is_session_policy (<parameter><type>SoupHSTSPolicy</type> *policy</parameter>);</programlisting> <para>Gets whether <parameter>policy</parameter> is a non-permanent, non-expirable session policy. see <function>soup_hsts_policy_new_session_policy()</function> for details.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>policy</para></entry> <entry><para>a <type>SoupHSTSPolicy</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>policy</parameter> is permanent, <literal>FALSE</literal> otherwise</para> </refsect3></refsect2> </refsect1>
<refsect1> <title>Types and Values</title> <refsect2> <title>SoupHSTSPolicy</title> <programlisting>typedef struct _SoupHSTSPolicy SoupHSTSPolicy;</programlisting> <para><type>SoupHSTSPolicy</type> implements HTTP policies, as described by <ulink>RFC 6797</ulink>.</para> <para><parameter>domain</parameter> represents the host that this policy applies to. The domain must be IDNA-canonicalized. <function>soup_hsts_policy_new()</function> and related methods will do this for you.</para> <para><parameter>max_age</parameter> contains the 'max-age' value from the Strict Transport Security header and indicates the time to live of this policy, in seconds.</para> <para><parameter>expires</parameter> will be non-<literal>NULL</literal> if the policy has been set by the host and hence has an expiry time. If <parameter>expires</parameter> is <literal>NULL</literal>, it indicates that the policy is a permanent session policy set by the user agent.</para> <para>If <parameter>include_subdomains</parameter> is <literal>TRUE</literal>, the Strict Transport Security policy must also be enforced on subdomains of <parameter>domain</parameter> .</para> </refsect2>
<refsect2> <title>SOUP_HSTS_POLICY_MAX_AGE_PAST</title> <programlisting>#define SOUP_HSTS_POLICY_MAX_AGE_PAST (0) </programlisting> <para>An expiration date that is always in the past.</para> </refsect2> </refsect1>
</refentry>