File espos_httpd_auth_policy.h¶

FileList > espos_httpd > include > espos_httpd_auth_policy.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"

Classes¶

Type	Name
struct	espos_httpd_auth_policy_t
struct	espos_httpd_auth_port_t
struct	espos_httpd_auth_request_t
struct	espos_httpd_auth_session_t

Public Types¶

Type	Name
enum	espos_httpd_auth_method_t
enum	espos_httpd_auth_verdict_t

Public Functions¶

Type	Name
const char *	espos_httpd_auth_method_str (espos_httpd_auth_method_t m)
bool	espos_httpd_auth_origin_matches (const char * origin_or_referer, const char * host) The authority of an Origin ("http://host:port") or Referer ("http://host:port/path?q") equals the Host header, case-insensitively; a default ":80" is ignored on either side.
espos_httpd_auth_verdict_t	espos_httpd_auth_policy_check_key (espos_httpd_auth_policy_t * p, const char * presented) Compare a presented key in constant time.
bool	espos_httpd_auth_policy_configured (const espos_httpd_auth_policy_t * p) A key is set.
espos_httpd_auth_verdict_t	espos_httpd_auth_policy_decide (espos_httpd_auth_policy_t * p, const espos_httpd_auth_request_t * rq, espos_httpd_auth_method_t * method) The decision for a protected endpoint.
void	espos_httpd_auth_policy_init (espos_httpd_auth_policy_t * p, const espos_httpd_auth_port_t * port, void * ctx, espos_httpd_auth_session_t * sessions, size_t session_count, uint32_t ttl_s, bool require_key)
void	espos_httpd_auth_policy_recovery_open (espos_httpd_auth_policy_t * p, uint32_t seconds) Exempt portal requests again for `seconds` , as proof that someone is at the device.
uint32_t	espos_httpd_auth_policy_recovery_s_left (const espos_httpd_auth_policy_t * p) Seconds left of an open recovery window; 0 when none is open.
bool	espos_httpd_auth_policy_required (const espos_httpd_auth_policy_t * p) Protected endpoints need a credential: a key is set, or the build requires one.
uint32_t	espos_httpd_auth_policy_retry_after_s (const espos_httpd_auth_policy_t * p) Seconds until key checks are answered again; 0 when not locked.
void	espos_httpd_auth_policy_session_close (espos_httpd_auth_policy_t * p, const char * id)
bool	espos_httpd_auth_policy_session_open (espos_httpd_auth_policy_t * p, char * id_out, size_t id_size) Mint a session id into id_out (needs ESPOS_HTTPD_AUTH_SID_LEN + 1 bytes).
bool	espos_httpd_auth_policy_session_valid (espos_httpd_auth_policy_t * p, const char * id) Live session with that id? Stamps it as seen; expired ones are freed on the way.
void	espos_httpd_auth_policy_sessions_clear (espos_httpd_auth_policy_t * p)
size_t	espos_httpd_auth_policy_sessions_live (espos_httpd_auth_policy_t * p)
void	espos_httpd_auth_policy_set_key (espos_httpd_auth_policy_t * p, const char * key) Install the configured key ("" or NULL = open).
void	espos_httpd_auth_policy_set_ttl (espos_httpd_auth_policy_t * p, uint32_t ttl_s)
bool	espos_httpd_auth_policy_throttled (const espos_httpd_auth_policy_t * p)

Macros¶

Type	Name
define	ESPOS_HTTPD_AUTH_FAIL_MAX `5 /\* failed key checks that start a lockout \*/`
define	ESPOS_HTTPD_AUTH_FAIL_WINDOW_S `60 /\* counted within this window \*/`
define	ESPOS_HTTPD_AUTH_KEY_MAX `64 /\* bytes of an API key, excluding NUL (httpd.api\_key maxLength) \*/`
define	ESPOS_HTTPD_AUTH_KEY_MIN `8 /\* shorter keys are accepted with a warning, not refused \*/`
define	ESPOS_HTTPD_AUTH_LOCKOUT_S `30 /\* how long every key check then answers 429 \*/`
define	ESPOS_HTTPD_AUTH_RECOVERY_MAX_S `86400`
define	ESPOS_HTTPD_AUTH_SID_LEN `32 /\* hex characters of a session id: 128 bits \*/`

Public Types Documentation¶

enum espos_httpd_auth_method_t¶

enum espos_httpd_auth_method_t {
    ESPOS_HTTPD_AUTH_NONE = 0,
    ESPOS_HTTPD_AUTH_BEARER = 1,
    ESPOS_HTTPD_AUTH_COOKIE = 2,
    ESPOS_HTTPD_AUTH_PORTAL = 3,
    ESPOS_HTTPD_AUTH_METHOD_MAX
};

enum espos_httpd_auth_verdict_t¶

enum espos_httpd_auth_verdict_t {
    ESPOS_HTTPD_AUTH_ALLOW = 0,
    ESPOS_HTTPD_AUTH_UNAUTHORIZED = 1,
    ESPOS_HTTPD_AUTH_FORBIDDEN_ORIGIN = 2,
    ESPOS_HTTPD_AUTH_UNCONFIGURED = 3,
    ESPOS_HTTPD_AUTH_THROTTLED = 4,
    ESPOS_HTTPD_AUTH_VERDICT_MAX
};

Public Functions Documentation¶

function espos_httpd_auth_method_str¶

const char * espos_httpd_auth_method_str (
    espos_httpd_auth_method_t m
)

function espos_httpd_auth_origin_matches¶

The authority of an Origin ("http://host:port") or Referer ("http://host:port/path?q") equals the Host header, case-insensitively; a default ":80" is ignored on either side.

bool espos_httpd_auth_origin_matches (
    const char * origin_or_referer,
    const char * host
)

False when either is missing — a browser always sends Origin on a state-changing request, so a cookie request without one is not a browser doing what its user meant.

function espos_httpd_auth_policy_check_key¶

Compare a presented key in constant time.

espos_httpd_auth_verdict_t espos_httpd_auth_policy_check_key (
    espos_httpd_auth_policy_t * p,
    const char * presented
)

A miss counts toward the throttle; a hit resets the count. ALLOW, UNAUTHORIZED, or THROTTLED while a lockout lasts (nothing is compared then, a correct key included). UNAUTHORIZED without counting when no key is configured.

function espos_httpd_auth_policy_configured¶

A key is set.

bool espos_httpd_auth_policy_configured (
    const espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_decide¶

The decision for a protected endpoint.

espos_httpd_auth_verdict_t espos_httpd_auth_policy_decide (
    espos_httpd_auth_policy_t * p,
    const espos_httpd_auth_request_t * rq,
    espos_httpd_auth_method_t * method
)

method (optional) receives how the request authenticated, NONE when it did not — also the answer for GET /api/v1/auth/status. A bearer is a key check (counted, throttled); a request that presents a wrong bearer is refused even if it also carries a live cookie, because it asked to be judged by the key.

function espos_httpd_auth_policy_init¶

void espos_httpd_auth_policy_init (
    espos_httpd_auth_policy_t * p,
    const espos_httpd_auth_port_t * port,
    void * ctx,
    espos_httpd_auth_session_t * sessions,
    size_t session_count,
    uint32_t ttl_s,
    bool require_key
)

function espos_httpd_auth_policy_recovery_open¶

Exempt portal requests again for seconds , as proof that someone is at the device.

void espos_httpd_auth_policy_recovery_open (
    espos_httpd_auth_policy_t * p,
    uint32_t seconds
)

Replaces any window already open, including with a shorter one; 0 closes it, and anything above ESPOS_HTTPD_AUTH_RECOVERY_MAX_S is clamped to it. The window applies ONLY to requests that arrived on the soft-AP interface it never relaxes anything on the station or Ethernet side and a lockout does not apply to it, because being locked out is one of the things it exists to recover from.

function espos_httpd_auth_policy_recovery_s_left¶

Seconds left of an open recovery window; 0 when none is open.

uint32_t espos_httpd_auth_policy_recovery_s_left (
    const espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_required¶

Protected endpoints need a credential: a key is set, or the build requires one.

bool espos_httpd_auth_policy_required (
    const espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_retry_after_s¶

Seconds until key checks are answered again; 0 when not locked.

uint32_t espos_httpd_auth_policy_retry_after_s (
    const espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_session_close¶

void espos_httpd_auth_policy_session_close (
    espos_httpd_auth_policy_t * p,
    const char * id
)

function espos_httpd_auth_policy_session_open¶

Mint a session id into id_out (needs ESPOS_HTTPD_AUTH_SID_LEN + 1 bytes).

bool espos_httpd_auth_policy_session_open (
    espos_httpd_auth_policy_t * p,
    char * id_out,
    size_t id_size
)

Evicts the least recently used session when the table is full; false only when the table has no slots at all or the buffer is too small.

function espos_httpd_auth_policy_session_valid¶

Live session with that id? Stamps it as seen; expired ones are freed on the way.

bool espos_httpd_auth_policy_session_valid (
    espos_httpd_auth_policy_t * p,
    const char * id
)

function espos_httpd_auth_policy_sessions_clear¶

void espos_httpd_auth_policy_sessions_clear (
    espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_sessions_live¶

size_t espos_httpd_auth_policy_sessions_live (
    espos_httpd_auth_policy_t * p
)

function espos_httpd_auth_policy_set_key¶

Install the configured key ("" or NULL = open).

void espos_httpd_auth_policy_set_key (
    espos_httpd_auth_policy_t * p,
    const char * key
)

Every session is dropped: whoever is logged in with the old key logs in again with the new one.

function espos_httpd_auth_policy_set_ttl¶

void espos_httpd_auth_policy_set_ttl (
    espos_httpd_auth_policy_t * p,
    uint32_t ttl_s
)

function espos_httpd_auth_policy_throttled¶

bool espos_httpd_auth_policy_throttled (
    const espos_httpd_auth_policy_t * p
)

Macro Definition Documentation¶

define ESPOS_HTTPD_AUTH_FAIL_MAX¶

#define ESPOS_HTTPD_AUTH_FAIL_MAX `5  /* failed key checks that start a lockout */`

define ESPOS_HTTPD_AUTH_FAIL_WINDOW_S¶

#define ESPOS_HTTPD_AUTH_FAIL_WINDOW_S `60 /* counted within this window */`

define ESPOS_HTTPD_AUTH_KEY_MAX¶

#define ESPOS_HTTPD_AUTH_KEY_MAX `64 /* bytes of an API key, excluding NUL (httpd.api_key maxLength) */`

define ESPOS_HTTPD_AUTH_KEY_MIN¶

#define ESPOS_HTTPD_AUTH_KEY_MIN `8  /* shorter keys are accepted with a warning, not refused */`

define ESPOS_HTTPD_AUTH_LOCKOUT_S¶

#define ESPOS_HTTPD_AUTH_LOCKOUT_S `30 /* how long every key check then answers 429 */`

define ESPOS_HTTPD_AUTH_RECOVERY_MAX_S¶

#define ESPOS_HTTPD_AUTH_RECOVERY_MAX_S `86400`

define ESPOS_HTTPD_AUTH_SID_LEN¶

#define ESPOS_HTTPD_AUTH_SID_LEN `32 /* hex characters of a session id: 128 bits */`

The documentation for this class was generated from the following file espos_httpd/include/espos_httpd_auth_policy.h