libwget-ocsp(3)

NAME
libwget-ocsp - Online Certificate Status Protocol (RFC 2560) routines

SYNOPSIS

  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

  typedef struct wget_ocsp_db_st wget_ocsp_db
structure for Online Certificate Status Protocol (OCSP) entries

  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

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

Parameters
    ocsp_db an OCSP database
    fingerprint The public key fingerprint to search for
    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.

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

Parameters
    ocsp_db an OCSP database
    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

  void wget_ocsp_db_deinit (wget_ocsp_db * ocsp_db)

Parameters
    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.

  void wget_ocsp_db_free (wget_ocsp_db ** ocsp_db)

Parameters
    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.

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

Parameters
    ocsp_db an OCSP database
    fingerprint Public key fingerprint
    maxage The time till which this entry should be considered valid (in seconds from epoch), or 0 to remove existing entry.
    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.

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

Parameters
    ocsp_db an OCSP database
    host The host to add
    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.

  int wget_ocsp_db_load (wget_ocsp_db * ocsp_db)

Parameters
    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.

  int wget_ocsp_db_save (wget_ocsp_db * ocsp_db)

Parameters
    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 * wget_ocsp_db_init (wget_ocsp_db * ocsp_db, const char * fname)

Parameters
    ocsp_db OCSP database handle previously passed to wget_ocsp_db_deinit(), or NULL
    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.

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

Parameters
    ocsp_db an OCSP database
    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().

Author

Generated automatically by Doxygen for wget2 from the source code.