wget2: HTTP Strict Transport Security (RFC 6797) routines

| wget2 2.2.1

Loading...
Searching...
No Matches
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_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, 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_db | An HSTS database
  [in] | host | Hostname to search for
  [in] | 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.

## ◆ 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,
|  | uint16_t | port,
|  | 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] | port | Port number used for connecting to the host
  [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 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_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.