wget2  2.0.0
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, 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_dbwget_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, 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

◆ wget_hsts_host_match()

int wget_hsts_host_match ( const wget_hsts_db hsts_db,
const char *  host,
uint16_t  port 
)
Parameters
[in]hsts_dbAn HSTS database
[in]hostHostname to search for
[in]portPort 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.

◆ wget_hsts_db_deinit()

void wget_hsts_db_deinit ( wget_hsts_db hsts_db)
Parameters
[in]hsts_dbHSTS 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_dbPointer 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,
uint16_t  port,
int64_t  maxage,
bool  include_subdomains 
)
Parameters
[in]hsts_dbAn HSTS database
[in]hostHostname from where Strict-Transport-Security header was received
[in]portPort number used for connecting to the host
[in]maxageThe 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_subdomainsNonzero 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.

◆ wget_hsts_db_load()

int wget_hsts_db_load ( wget_hsts_db hsts_db)
Parameters
[in]hsts_dbAn 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_dbHSTS 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_dbPreviously created HSTS database on which wget_hsts_db_deinit() has been called, or NULL
[in]fnameThe 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_dbHSTS database created by wget_hsts_db_init().
[in]fnameFilename 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.