libwget-hsts(3)

NAME
libwget-hsts - HTTP Strict Transport Security (RFC 6797) routines

SYNOPSIS

  Data Structures
struct wget_hsts_db_st
struct hsts_entry

  Typedefs
typedef struct wget_hsts_db_st wget_hsts_db
typedef int wget_hsts_host_match_fn(const wget_hsts_db *hsts_db, const char *host, uint16_t port)

  Functions
void wget_hsts_set_plugin (const wget_hsts_db_vtable *vtable)
int wget_hsts_host_match (const wget_hsts_db *hsts_db, const char *host, uint16_t port)
void wget_hsts_db_deinit (wget_hsts_db *hsts_db)
void wget_hsts_db_free (wget_hsts_db **hsts_db)
void wget_hsts_db_add (wget_hsts_db *hsts_db, const char *host, uint16_t port, int64_t maxage, bool include_subdomains)
int wget_hsts_db_load (wget_hsts_db *hsts_db)
int wget_hsts_db_save (wget_hsts_db *hsts_db)
wget_hsts_db * wget_hsts_db_init (wget_hsts_db *hsts_db, const char *fname)
void wget_hsts_db_set_fname (wget_hsts_db *hsts_db, const char *fname)

Detailed Description

This is an implementation of RFC 6797.

Typedef Documentation

  typedef struct wget_hsts_db_st wget_hsts_db
Structure representing HSTS database for storing HTTP Strict Transport Security (HSTS) entries

  typedef int wget_hsts_host_match_fn(const wget_hsts_db *hsts_db, const char *host, uint16_t port)
It is possible to implement a custom HSTS database as a plugin. See tests/test-plugin-dummy.c and tests/Makefile.am for details.

Function Documentation

  int wget_hsts_host_match (const wget_hsts_db * hsts_db, const char * host, uint16_t port)

Parameters
    hsts_db An HSTS database
    host Hostname to search for
    port Port number in the original URI/IRI. Port number 80 is treated similar to 443, as 80 is default port for HTTP.

Returns
    1 if the host must be accessed only through TLS, 0 if there is no such condition.

Searches for a given host in the database for any previously added entry.

HSTS entries older than amount of time specified by maxage are considered expired and are ignored.

This function is thread-safe and can be called from multiple threads concurrently. Any implementation for this function must be thread-safe as well.

  void wget_hsts_db_deinit (wget_hsts_db * hsts_db)

Parameters
    hsts_db HSTS database created by wget_hsts_db_init()

Frees all resources allocated for HSTS database, except for the structure itself. The hsts_db pointer can then be passed to wget_hsts_db_init() for reinitialization.

If hsts_db is NULL this function does nothing.

This function only works with databases created by wget_hsts_db_init().

  void wget_hsts_db_free (wget_hsts_db ** hsts_db)

Parameters
    hsts_db Pointer to the HSTS database handle (will be set to NULL)

Frees all resources allocated for the HSTS database.

A double pointer is required because this function will set the handle (pointer) to the HPKP database to NULL to prevent potential use-after-free conditions.

If hsts_db or pointer it points to is NULL, then the function does nothing.

Newly added entries will be lost unless committed to persistent storage using wget_hsts_db_save().

  void wget_hsts_db_add (wget_hsts_db * hsts_db, const char * host, uint16_t port, int64_t maxage, bool include_subdomains)

Parameters
    hsts_db An HSTS database
    host Hostname from where Strict-Transport-Security header was received
    port Port number used for connecting to the host
    maxage The time from now till the entry is valid, in seconds, or 0 to remove existing entry. Corresponds to the max-age directive in Strict-Transport-Security header.
    include_subdomains Nonzero if includeSubDomains directive was present in the header, zero otherwise

Add an entry to the HSTS database. An entry corresponds to the Strict-Transport-Security HTTP response header. Any existing entry with same host and port is replaced. If maxage is zero, any existing entry with matching host and port is removed.

This function is thread-safe and can be called from multiple threads concurrently. Any implementation for this function must be thread-safe as well.

  int wget_hsts_db_load (wget_hsts_db * hsts_db)

Parameters
    hsts_db An HSTS database

Returns
    0 if the operation succeeded, -1 in case of error

Performs all operations necessary to access the HSTS database entries from persistent storage using wget_hsts_host_match() for example.

For database created by wget_hsts_db_init() this function will load all the entries from the file specified in fname parameter of wget_hsts_db_init().

If hsts_db is NULL this function does nothing and returns 0.

  int wget_hsts_db_save (wget_hsts_db * hsts_db)

Parameters
    hsts_db HSTS database

Returns
    0 if the operation succeeded, -1 otherwise

Saves all changes to the HSTS database (via wget_hsts_db_add() for example) to persistent storage.

For databases created by wget_hsts_db_init(), the data is stored into file specified by fname parameter of wget_hsts_db_init().

If hsts_db is NULL this function does nothing.

  wget_hsts_db * wget_hsts_db_init (wget_hsts_db * hsts_db, const char * fname)

Parameters
    hsts_db Previously created HSTS database on which wget_hsts_db_deinit() has been called, or NULL
    fname The file where the data is stored, or NULL.

Returns
    A new wget_hsts_db

Constructor for the default implementation of HSTS database.

This function does no file IO, data is read only when wget_hsts_db_load() is called.

  void wget_hsts_db_set_fname (wget_hsts_db * hsts_db, const char * fname)

Parameters
    hsts_db HSTS database created by wget_hsts_db_init().
    fname Filename where database should be stored, or NULL

Changes the file where HSTS database entries are stored.

Works only for the HSTS databases created by wget_hsts_db_init(). This function does no file IO, data is read or written only when wget_hsts_db_load() or wget_hsts_db_save() is called.

Author

Generated automatically by Doxygen for wget2 from the source code.