wget2: Online Certificate Status Protocol (RFC 2560) routines

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Typedefs | Functions
Online Certificate Status Protocol (RFC 2560) routines

## Data Structures
struct | wget_ocsp_db_st
struct | ocsp_entry

## Typedefs
typedef struct wget_ocsp_db_st | wget_ocsp_db
typedef wget_ocsp_db * | wget_ocsp_db_init_fn(wget_ocsp_db *ocsp_db, const char *fname)

## Functions
void | wget_ocsp_set_plugin (const wget_ocsp_db_vtable *vtable)
bool | wget_ocsp_fingerprint_in_cache (const wget_ocsp_db *ocsp_db, const char *fingerprint, int *revoked)
bool | wget_ocsp_hostname_is_valid (const wget_ocsp_db *ocsp_db, const char *hostname)
void | wget_ocsp_db_deinit (wget_ocsp_db *ocsp_db)
void | wget_ocsp_db_free (wget_ocsp_db **ocsp_db)
void | wget_ocsp_db_add_fingerprint (wget_ocsp_db *ocsp_db, const char *fingerprint, int64_t maxage, bool valid)
void | wget_ocsp_db_add_host (wget_ocsp_db *ocsp_db, const char *host, int64_t maxage)
int | wget_ocsp_db_load (wget_ocsp_db *ocsp_db)
int | wget_ocsp_db_save (wget_ocsp_db *ocsp_db)
wget_ocsp_db * | wget_ocsp_db_init (wget_ocsp_db *ocsp_db, const char *fname)
void | wget_ocsp_db_set_fname (wget_ocsp_db *ocsp_db, const char *fname)

## Detailed Description

This is an implementation of RFC 2560.

## Typedef Documentation

## ◆ wget_ocsp_db

typedef struct wget_ocsp_db_st wget_ocsp_db

structure for Online Certificate Status Protocol (OCSP) entries

## ◆ wget_ocsp_db_init_fn

typedef wget_ocsp_db* wget_ocsp_db_init_fn(wget_ocsp_db *ocsp_db, const char *fname)

It is possible to implement a custom OCSP database as a plugin. See tests/test-plugin-dummy.c and tests/Makefile.am for details.

## Function Documentation

## ◆ wget_ocsp_fingerprint_in_cache()

bool wget_ocsp_fingerprint_in_cache | ( | const wget_ocsp_db * | ocsp_db,
|  | const char * | fingerprint,
|  | int * | revoked
| ) |  |

Parameters

  [in] | ocsp_db | an OCSP database
  [in] | fingerprint | The public key fingerprint to search for
  [out] | revoked | If the key is found, the value will be set to 1 if the key has been revoked, zero if not. If the key is not found, the value is unmodified.

Returns
  true if the fingerprint was found, false otherwise.

Searches for a cached OCSP response in the OCSP database. OCSP responses are added using wget_ocsp_db_add_fingerprint().

If `ocsp_db` is NULL then this function returns 0 and does nothing else.

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

bool wget_ocsp_hostname_is_valid | ( | const wget_ocsp_db * | ocsp_db,
|  | const char * | hostname
| ) |  |

Parameters

  [in] | ocsp_db | an OCSP database
  [in] | hostname | The host to search found.

Returns
  1 if a valid host entry was found, 0 otherwise

Checks if there exists an entry for the given host added by wget_ocsp_db_add_host() which has not expired.

If `ocsp_db` is NULL then this function returns 0 and does nothing else.

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

See also
  wget_ocsp_db_add_host

## ◆ wget_ocsp_db_deinit()

void wget_ocsp_db_deinit | ( | wget_ocsp_db * | ocsp_db | ) |

Parameters

  [in] | ocsp_db | an OCSP database

Frees all resources allocated for the OCSP database, except for the structure. Works only for databases created by wget_ocsp_db_init(). `ocsp_db` can then be passed to wget_ocsp_db_init().

If `ocsp_db` is NULL then this function does nothing.

## ◆ wget_ocsp_db_free()

void wget_ocsp_db_free | ( | wget_ocsp_db ** | ocsp_db | ) |

Parameters

  [in] | ocsp_db | pointer to an OCSP database handle

Frees all resources allocated for the OCSP 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.

New entries added to the database will be lost unless committed to the persistent storage using wget_ocsp_db_save().

If `ocsp_db` or the pointer it points to is NULL, then this function does nothing.

## ◆ wget_ocsp_db_add_fingerprint()

void wget_ocsp_db_add_fingerprint | ( | wget_ocsp_db * | ocsp_db,
|  | const char * | fingerprint,
|  | int64_t | maxage,
|  | bool | valid
| ) |  |

Parameters

  [in] | ocsp_db | an OCSP database
  [in] | fingerprint | Public key fingerprint
  [in] | maxage | The time till which this entry should be considered valid (in seconds from epoch), or 0 to remove existing entry.
  [in] | valid | Whether the public key is valid according to the OCSP responder

Adds an OCSP response into the OCSP database. The new entry replaces any existing entry with same `fingerprint`. If `maxage` is 0, any entry with matching `fingerprint` is removed.

If `ocsp_db` is NULL then this function does nothing.

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

void wget_ocsp_db_add_host | ( | wget_ocsp_db * | ocsp_db,
|  | const char * | host,
|  | int64_t | maxage
| ) |  |

Parameters

  [in] | ocsp_db | an OCSP database
  [in] | host | The host to add
  [in] | maxage | The time till which this entry should be considered valid (in seconds from epoch), or 0 to remove existing entry.

Adds a host entry into the given OCSP database. The new entry replaces any existing entry with same `host`. If `maxage` is 0, any entry with matching `host` is removed.

The intended use is to serve as a cache for hosts with certificate chains for which all OCSP responses are positive. The added entries can then be queried for by wget_ocsp_hostname_is_valid(). A positive response indicates fingerprints for each public key in the certificate chain are likely already added to the database, in which case OCSP responses are not needed.

If `ocsp_db` is NULL then this function does nothing.

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

int wget_ocsp_db_load | ( | wget_ocsp_db * | ocsp_db | ) |

Parameters

  [in] | ocsp_db | An OCSP database

Returns
  0 if the operation was successful, a negative number in case of error

Performs all necessary operations for accessing OCSP database entries from the persistent storage.

For databases created by wget_ocsp_db_init(), the data is fetched from file specified by `fname` parameter of wget_ocsp_db_load().

If `ocsp_db` is NULL then this function returns -1 and does nothing else.

## ◆ wget_ocsp_db_save()

int wget_ocsp_db_save | ( | wget_ocsp_db * | ocsp_db | ) |

Parameters

  [in] | ocsp_db | An OCSP database

Returns
  0 if the operation was successful, a negative number in case of error

Stores all changes to the OCSP database to persistent storage.

For databases created by wget_ocsp_db_init(), the data is stored into file specified by `fname` parameter of wget_ocsp_db_load(), overwriting any existing content.

If `ocsp_db` is NULL then this function returns -1 and does nothing else.

## ◆ wget_ocsp_db_init()

wget_ocsp_db* wget_ocsp_db_init | ( | wget_ocsp_db * | ocsp_db,
|  | const char * | fname
| ) |  |

Parameters

  [in] | ocsp_db | OCSP database handle previously passed to wget_ocsp_db_deinit(), or NULL
  [in] | fname | The filename from where OCSP entries should be loaded, or NULL

Returns
  A new OCSP database

Constructor for default implementation of OCSP database.

This function does no file IO, OCSP entries are read from `fname` into memory when wget_ocsp_db_load() is called.

## ◆ wget_ocsp_db_set_fname()

void wget_ocsp_db_set_fname | ( | wget_ocsp_db * | ocsp_db,
|  | const char * | fname
| ) |  |

Parameters

  [in] | ocsp_db | an OCSP database
  [in] | fname | The filename from where OCSP entries should be loaded, or NULL

Changes the file from where OCSP database entries would be loaded or saved. Works only with OCSP databases created with wget_ocsp_db_init().