HTTP Strict Transport Security (RFC 6797) routines

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)

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

wget_hsts_db

typedef struct wget_hsts_db_st wget_hsts_db

Structure representing HSTS database for storing HTTP Strict Transport Security (HSTS) entries

wget_hsts_host_match_fn

typedef int wget_hsts_host_match_fn(const wget_hsts_db *hsts_db, const char *host)

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

wget_hsts_host_match()

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

Parameters

[in]	hsts_db	An HSTS database
[in]	host	Hostname to search for

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.

wget_hsts_db_deinit()

void wget_hsts_db_deinit

(

wget_hsts_db *

hsts_db

)

Parameters

[in]

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

wget_hsts_db_free()

void wget_hsts_db_free

(

wget_hsts_db **

hsts_db

)

Parameters

[in]

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

wget_hsts_db_add()

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

Parameters

[in]	hsts_db	An HSTS database
[in]	host	Hostname from where Strict-Transport-Security header was received
[in]	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.
[in]	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 for host is replaced. If maxage is zero, an existing entry with matching host 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.

wget_hsts_db_load()

int wget_hsts_db_load

(

wget_hsts_db *

hsts_db

)

Parameters

[in]

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.

wget_hsts_db_save()

int wget_hsts_db_save

(

wget_hsts_db *

hsts_db

)

Parameters

[in]

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

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

Parameters

[in]	hsts_db	Previously created HSTS database on which wget_hsts_db_deinit() has been called, or NULL
[in]	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.

wget_hsts_db_set_fname()

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

Parameters

[in]	hsts_db	HSTS database created by wget_hsts_db_init().
[in]	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.