wget2: HTTP Strict Transport Security (RFC 6797) routines

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Typedefs | Functions
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.