File espos_sk_tls_policy.h¶

FileList > espos_sk > include > espos_sk_tls_policy.h

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

Classes¶

Type	Name
struct	espos_sk_tls_decision_t
struct	espos_sk_tls_facts_t

Public Types¶

Type	Name
enum	espos_sk_tls_anchor_kind_t
enum	espos_sk_tls_reason_t
enum	espos_sk_tls_trust_t
enum	espos_sk_tls_verdict_t

Public Functions¶

Type	Name
esp_err_t	espos_sk_tls_attach (void * ssl_conf) The esp-tls attach hook, in the shape esp_http_client's `crt_bundle_attach` and esp_transport_ssl_crt_bundle_attach() both want.
espos_sk_tls_decision_t	espos_sk_tls_decide (const espos_sk_tls_facts_t * f) The whole trust decision, as a table.
const char *	espos_sk_tls_reason_str (espos_sk_tls_reason_t r) A human sentence for a reason code; never NULL, never empty.
bool	espos_sk_tls_san_equal (const char * a, const char * b) Compare two normalised SAN sets.
esp_err_t	espos_sk_tls_san_normalise (const char const in, size_t n, char * out, size_t out_size, bool * truncated) Normalise a SAN set into the stored form: each name lower-cased, the set sorted and de-duplicated, entries joined with a single ',' and no spaces — so that two certificates naming the same hosts in a different order compare equal with strcmp() and the record stays one flat NVS string.
espos_sk_tls_trust_t	espos_sk_tls_trust_mode (void) The trust mode in force, for call sites deciding about the CN check.

Macros¶

Type	Name
define	ESPOS_SK_TLS_CN_MAX `64`
define	ESPOS_SK_TLS_FP_LEN `32 /\* SHA-256, raw bytes \*/`
define	ESPOS_SK_TLS_SAN_MAX `256`

Public Types Documentation¶

enum espos_sk_tls_anchor_kind_t¶

enum espos_sk_tls_anchor_kind_t {
    ESPOS_SK_TLS_ANCHOR_NONE = 0,
    ESPOS_SK_TLS_ANCHOR_CA = 1,
    ESPOS_SK_TLS_ANCHOR_LEAF = 2
};

enum espos_sk_tls_reason_t¶

enum espos_sk_tls_reason_t {
    ESPOS_SK_TLS_R_OK = 0,
    ESPOS_SK_TLS_R_FIRST_USE,
    ESPOS_SK_TLS_R_LEAF_CHANGED,
    ESPOS_SK_TLS_R_CA_CHANGED,
    ESPOS_SK_TLS_R_SAN_CHANGED,
    ESPOS_SK_TLS_R_NO_IDENTITY
};

enum espos_sk_tls_trust_t¶

enum espos_sk_tls_trust_t {
    ESPOS_SK_TLS_TRUST_TOFU = 0,
    ESPOS_SK_TLS_TRUST_CA = 1,
    ESPOS_SK_TLS_TRUST_BUNDLE = 2
};

enum espos_sk_tls_verdict_t¶

enum espos_sk_tls_verdict_t {
    ESPOS_SK_TLS_ACCEPT = 0,
    ESPOS_SK_TLS_CAPTURE = 1,
    ESPOS_SK_TLS_REJECT = 2
};

Public Functions Documentation¶

function espos_sk_tls_attach¶

The esp-tls attach hook, in the shape esp_http_client's crt_bundle_attach and esp_transport_ssl_crt_bundle_attach() both want.

esp_err_t espos_sk_tls_attach (
    void * ssl_conf
)

In bundle mode it is esp_crt_bundle_attach(); otherwise it installs the pinning verify callback, so a socket that uses it trusts exactly what the SignalK stream trusts.

Any component that opens its own TLS connection to the same server should attach this rather than the certificate bundle directly otherwise that one socket refuses the self-signed certificate the rest of the device has already accepted. Pair it with skipping the common-name check whenever espos_sk_tls_trust_mode() is not ESPOS_SK_TLS_TRUST_BUNDLE: a pinned anchor identifies the server, and the CN rarely matches an IP address.

Returns ESP_ERR_INVALID_STATE in a build without CONFIG_ESPOS_SK_TLS.

function espos_sk_tls_decide¶

The whole trust decision, as a table.

espos_sk_tls_decision_t espos_sk_tls_decide (
    const espos_sk_tls_facts_t * f
)

No allocation, no clock, no I/O: the same call runs on the device inside the mbedTLS verify callback and on the host inside Unity.

Not consulted at all in bundle mode — there mbedTLS's own chain validation against the Mozilla roots is the decision, and nothing is pinned.

function espos_sk_tls_reason_str¶

A human sentence for a reason code; never NULL, never empty.

const char * espos_sk_tls_reason_str (
    espos_sk_tls_reason_t r
)

function espos_sk_tls_san_equal¶

Compare two normalised SAN sets.

bool espos_sk_tls_san_equal (
    const char * a,
    const char * b
)

False when either is empty or either was truncated (marked by a leading '!'): "we could not see the whole set" must never read as "the sets are the same".

function espos_sk_tls_san_normalise¶

Normalise a SAN set into the stored form: each name lower-cased, the set sorted and de-duplicated, entries joined with a single ',' and no spaces — so that two certificates naming the same hosts in a different order compare equal with strcmp() and the record stays one flat NVS string.

esp_err_t espos_sk_tls_san_normalise (
    const char *const * in,
    size_t n,
    char * out,
    size_t out_size,
    bool * truncated
)

in is the raw set as the callback collected it, one name per entry. Returns ESP_OK, or ESP_ERR_INVALID_SIZE when the joined set does not fit in out_size — in which case out holds the names that did fit, still normalised, and *truncated is set. A truncated set never compares equal to anything (espos_sk_tls_san_equal), so it can only ever narrow what is accepted, never widen it.

function espos_sk_tls_trust_mode¶

The trust mode in force, for call sites deciding about the CN check.

espos_sk_tls_trust_t espos_sk_tls_trust_mode (
    void
)

Macro Definition Documentation¶

define ESPOS_SK_TLS_CN_MAX¶

#define ESPOS_SK_TLS_CN_MAX `64`

define ESPOS_SK_TLS_FP_LEN¶

#define ESPOS_SK_TLS_FP_LEN `32 /* SHA-256, raw bytes */`

define ESPOS_SK_TLS_SAN_MAX¶

#define ESPOS_SK_TLS_SAN_MAX `256`

The documentation for this class was generated from the following file espos_sk/include/espos_sk_tls_policy.h