lws-secure-streams-policy.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lws_metric_policy
struct	lws_ss_x509
struct	lws_ss_trust_store
struct	lws_ss_metadata
struct	lws_ss_http_respmap
struct	lws_ss_auth
struct	lws_ss_policy
union	lws_ss_policy.u
union	lws_ss_policy.trust
struct	lws_ss_policy.trust.server

Typedefs
typedef int(*	plugin_auth_status_cb) (struct lws_ss_handle *ss, int status)
typedef struct lws_metric_policy	lws_metric_policy_t
typedef struct lws_ss_x509	lws_ss_x509_t
typedef struct lws_ss_trust_store	lws_ss_trust_store_t
typedef struct lws_ss_metadata	lws_ss_metadata_t
typedef struct lws_ss_http_respmap	lws_ss_http_respmap_t
typedef struct lws_ss_auth	lws_ss_auth_t
typedef struct lws_ss_policy	lws_ss_policy_t

Enumerations
enum	{   LWSSSPOLF_OPPORTUNISTIC = (1 << 0) , LWSSSPOLF_NAILED_UP = (1 << 1) , LWSSSPOLF_URGENT_TX = (1 << 2) , LWSSSPOLF_URGENT_RX = (1 << 3) ,   LWSSSPOLF_TLS = (1 << 4) , LWSSSPOLF_LONG_POLL = (1 << 5) , LWSSSPOLF_AUTH_BEARER = (1 << 6) , LWSSSPOLF_HTTP_NO_CONTENT_LENGTH = (1 << 7) ,   LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM = (1 << 8) , LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR = (1 << 9) , LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE = (1 << 10) , LWSSSPOLF_HTTP_MULTIPART = (1 << 11) ,   LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED = (1 << 12) , LWSSSPOLF_LOCAL_SINK = (1 << 13) , LWSSSPOLF_WAKE_SUSPEND__VALIDITY = (1 << 14) , LWSSSPOLF_SERVER = (1 << 15) ,   LWSSSPOLF_ALLOW_REDIRECTS = (1 << 16) , LWSSSPOLF_HTTP_MULTIPART_IN = (1 << 17) , LWSSSPOLF_ATTR_LOW_LATENCY = (1 << 18) , LWSSSPOLF_ATTR_HIGH_THROUGHPUT = (1 << 19) ,   LWSSSPOLF_ATTR_HIGH_RELIABILITY = (1 << 20) , LWSSSPOLF_ATTR_LOW_COST = (1 << 21) , LWSSSPOLF_PERF = (1 << 22) , LWSSSPOLF_DIRECT_PROTO_STR = (1 << 23) ,   LWSSSPOLF_HTTP_CACHE_COOKIES = (1 << 24) , LWSSSPOLF_PRIORITIZE_READS = (1 << 25) }
enum	{   LWSSSP_H1 , LWSSSP_H2 , LWSSSP_WS , LWSSSP_MQTT ,   LWSSSP_RAW , LWSSS_HBI_AUTH = 0 , LWSSS_HBI_DSN , LWSSS_HBI_FWV ,   LWSSS_HBI_TYPE , _LWSSS_HBI_COUNT }

Functions
LWS_VISIBLE LWS_EXTERN int	lws_ss_policy_parse_begin (struct lws_context *context, int overlay)
LWS_VISIBLE LWS_EXTERN int	lws_ss_policy_parse_abandon (struct lws_context *context)
LWS_VISIBLE LWS_EXTERN int	lws_ss_policy_parse (struct lws_context *context, const uint8_t *buf, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_ss_policy_overlay (struct lws_context *context, const char *overlay)
LWS_VISIBLE LWS_EXTERN const lws_ss_policy_t *	lws_ss_policy_get (struct lws_context *context)
LWS_VISIBLE LWS_EXTERN const lws_ss_auth_t *	lws_ss_auth_get (struct lws_context *context)

---

Data Structure Documentation

lws_metric_policy

struct lws_metric_policy

lws_ss_plugin_auth_t - api for an auth plugin

Auth plugins create and sequence authenticated connections that can carry one or more streams to an endpoint. That may involve other connections to other places to eg, gather authenticated tokens and then make the real connection using the tokens.

The secure stream object contains members to record which auth plugin the stream is bound to and an over-allocation of the secure stream object to contain the plugin auth private data.

The auth plugin controls the state of the stream connection via the status callback, and handles retries.

Network connections may require one kind of auth sequencing, and streams inside those connections another kind of auth sequencing depending on their role. So the secure stream object allows defining plugins for both kinds.

Streams may disappear at any time and require reauth to bring a new one up. The auth plugin sequencer will connect / reconnect either on demand, or from the start and after any connectivity loss if any stream using the connection has the LWSSSPOLF_NAILED_UP flag.

Definition at line 56 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_metric_policy:

Data Fields
const struct lws_metric_policy *	next
const char *	name
const char *	report	the metrics policy name in the policy, used to bind to it
uint64_t	us_schedule	us interval between lws_system metrics api reports
uint32_t	us_decay_unit	how many us to decay avg by half, 0 = no decay
uint8_t	min_contributors	before we can judge something is an outlier

lws_ss_x509

struct lws_ss_x509

Definition at line 73 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_x509:

Data Fields
struct lws_ss_x509 *	next
const char *	vhost_name	vhost name using cert ctx
const uint8_t *	ca_der	DER x.509 cert
size_t	ca_der_len	length of DER cert
uint8_t	keep:1	ie, if used in server tls

lws_ss_trust_store

struct lws_ss_trust_store

Definition at line 144 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_trust_store:

Data Fields
struct lws_ss_trust_store *	next
const char *	name
const lws_ss_x509_t *	ssx509[6]
int	count

lws_ss_metadata

struct lws_ss_metadata

Definition at line 173 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_metadata:

Data Fields
struct lws_ss_metadata *	next
const char *	name
void *	value__may_own_heap
size_t	length
uint8_t	value_length
uint8_t	value_is_http_token
uint8_t	value_on_lws_heap:1

lws_ss_http_respmap

struct lws_ss_http_respmap

Definition at line 190 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_http_respmap:

Data Fields
uint16_t	resp
uint16_t	state

lws_ss_auth

struct lws_ss_auth

Definition at line 201 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_auth:

Data Fields
struct lws_ss_auth *	next
const char *	name
const char *	type
const char *	streamtype
uint8_t	blob_index

lws_ss_policy

struct lws_ss_policy

lws_ss_policy_t: policy database entry for a stream type

Decides the system policy for how to implement connections of name .streamtype.

Streams may need one kind of auth sequencing for the network connection and another kind of auth sequencing for the streams that are carried inside it, this is the purpose of .nauth and .sauth. Both are optional and may be NULL.

An array of these is set at context creation time, ending with one with a NULL streamtype.

Definition at line 223 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_policy:

Data Fields
struct lws_ss_policy *	next
const char *	streamtype	stream type lhs to match on
const char *	endpoint	DNS address to connect to
const char *	rideshare_streamtype	optional transport on another, preexisting stream of this streamtype name
const char *	payload_fmt
const char *	socks5_proxy
lws_ss_metadata_t *	metadata
const lws_metric_policy_t *	metrics
const lws_ss_auth_t *	auth
union lws_ss_policy	u
union lws_ss_policy	trust
const lws_retry_bo_t *	retry_bo	retry policy to use
int32_t	txc
int32_t	txc_peer
uint32_t	proxy_buflen	max dsh alloc for proxy
uint32_t	proxy_buflen_rxflow_on_above
uint32_t	proxy_buflen_rxflow_off_below
uint32_t	client_buflen	max dsh alloc for client
uint32_t	client_buflen_rxflow_on_above
uint32_t	client_buflen_rxflow_off_below
uint32_t	timeout_ms	default message response timeout in ms
uint32_t	flags	stream attribute flags
uint16_t	port	endpoint port
uint8_t	metadata_count	metadata count
uint8_t	protocol	protocol index
uint8_t	client_cert	which client cert to apply 0 = none, 1+ = cc 0+
uint8_t	priority

lws_ss_policy.u

union lws_ss_policy.u

Definition at line 243 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_policy.u:

lws_ss_policy.trust

union lws_ss_policy.trust

Definition at line 324 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_policy.trust:

Data Fields
const lws_ss_trust_store_t *	store	CA certs needed for conn validation, only set between policy parsing and vhost creation
trust	server

lws_ss_policy.trust.server

struct lws_ss_policy.trust.server

Definition at line 328 of file lws-secure-streams-policy.h.

Collaboration diagram for lws_ss_policy.trust.server:

Data Fields
const lws_ss_x509_t *	cert	the server's signed cert with the pubkey
const lws_ss_x509_t *	key	the server's matching private key

Typedef Documentation

plugin_auth_status_cb

typedef int(* plugin_auth_status_cb) (struct lws_ss_handle *ss, int status)

Definition at line 27 of file lws-secure-streams-policy.h.

lws_metric_policy_t

typedef struct lws_metric_policy lws_metric_policy_t

lws_ss_plugin_auth_t - api for an auth plugin

Auth plugins create and sequence authenticated connections that can carry one or more streams to an endpoint. That may involve other connections to other places to eg, gather authenticated tokens and then make the real connection using the tokens.

The secure stream object contains members to record which auth plugin the stream is bound to and an over-allocation of the secure stream object to contain the plugin auth private data.

The auth plugin controls the state of the stream connection via the status callback, and handles retries.

Network connections may require one kind of auth sequencing, and streams inside those connections another kind of auth sequencing depending on their role. So the secure stream object allows defining plugins for both kinds.

Streams may disappear at any time and require reauth to bring a new one up. The auth plugin sequencer will connect / reconnect either on demand, or from the start and after any connectivity loss if any stream using the connection has the LWSSSPOLF_NAILED_UP flag.

lws_ss_x509_t

typedef struct lws_ss_x509 lws_ss_x509_t

lws_ss_trust_store_t

typedef struct lws_ss_trust_store lws_ss_trust_store_t

lws_ss_metadata_t

typedef struct lws_ss_metadata lws_ss_metadata_t

lws_ss_http_respmap_t

typedef struct lws_ss_http_respmap lws_ss_http_respmap_t

lws_ss_auth_t

typedef struct lws_ss_auth lws_ss_auth_t

lws_ss_policy_t

typedef struct lws_ss_policy lws_ss_policy_t

lws_ss_policy_t: policy database entry for a stream type

Decides the system policy for how to implement connections of name .streamtype.

Streams may need one kind of auth sequencing for the network connection and another kind of auth sequencing for the streams that are carried inside it, this is the purpose of .nauth and .sauth. Both are optional and may be NULL.

An array of these is set at context creation time, ending with one with a NULL streamtype.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
LWSSSPOLF_OPPORTUNISTIC	the connection doesn't exist unless client asks to write
LWSSSPOLF_NAILED_UP	the connection tries to be connected the whole life of the ss
LWSSSPOLF_URGENT_TX	this connection carries critical tx data
LWSSSPOLF_URGENT_RX	this connection carries critical rx data
LWSSSPOLF_TLS	stream must be connected via a tls tunnel
LWSSSPOLF_LONG_POLL	stream used to receive async rx at arbitrary intervals
LWSSSPOLF_AUTH_BEARER	for http, use lws_system auth token 0 in authentication: bearer
LWSSSPOLF_HTTP_NO_CONTENT_LENGTH	don't add any content length even if we have it
LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM	set the client flag LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM
LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR	set the client flag LCCSCF_H2_QUIRK_OVERFLOWS_TXCR
LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE	HPACK decoder state does not end cleanly
LWSSSPOLF_HTTP_MULTIPART	indicates stream goes out as specifically a multipart mime POST section... if the tx has LWSSS_FLAG_COALESCE_CONTINUES flag then more multipart sections are expected. Without it, the multipart wrapper is closed and the http transaction issue completed when this message finishes.
LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED	set up lws_system client cert
LWSSSPOLF_LOCAL_SINK	expected to bind to a local sink only
LWSSSPOLF_WAKE_SUSPEND__VALIDITY	this stream's idle validity checks are critical enough we should arrange to wake from suspend to perform them
LWSSSPOLF_SERVER	we listen on a socket as a server
LWSSSPOLF_ALLOW_REDIRECTS	follow redirects
LWSSSPOLF_HTTP_MULTIPART_IN	handle inbound multipart mime at SS level
LWSSSPOLF_ATTR_LOW_LATENCY	stream requires low latency
LWSSSPOLF_ATTR_HIGH_THROUGHPUT	stream requires high throughput
LWSSSPOLF_ATTR_HIGH_RELIABILITY	stream requires high reliability
LWSSSPOLF_ATTR_LOW_COST	stream is not critical and should be handled as cheap as poss
LWSSSPOLF_PERF	capture and report performace information
LWSSSPOLF_DIRECT_PROTO_STR	metadata as direct protocol string, e.g. http header
LWSSSPOLF_HTTP_CACHE_COOKIES	Record http cookies and pass them back on future requests
LWSSSPOLF_PRIORITIZE_READS	prioritize clearing reads at expense of writes

Definition at line 81 of file lws-secure-streams-policy.h.

     {
        LWSSSPOLF_OPPORTUNISTIC                                 = (1 << 0),
        LWSSSPOLF_NAILED_UP                                     = (1 << 1),
        LWSSSPOLF_URGENT_TX                                     = (1 << 2),
        LWSSSPOLF_URGENT_RX                                     = (1 << 3),
        LWSSSPOLF_TLS                                           = (1 << 4),
        LWSSSPOLF_LONG_POLL                                     = (1 << 5),
        LWSSSPOLF_AUTH_BEARER                                   = (1 << 6),
        LWSSSPOLF_HTTP_NO_CONTENT_LENGTH                        = (1 << 7),
        LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM                      = (1 << 8),
        LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR                       = (1 << 9),
        LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE                  = (1 << 10),
        LWSSSPOLF_HTTP_MULTIPART                                = (1 << 11),
        LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED                    = (1 << 12),
        LWSSSPOLF_LOCAL_SINK                                    = (1 << 13),
        LWSSSPOLF_WAKE_SUSPEND__VALIDITY                        = (1 << 14),
        LWSSSPOLF_SERVER                                        = (1 << 15),
        LWSSSPOLF_ALLOW_REDIRECTS                               = (1 << 16),
        LWSSSPOLF_HTTP_MULTIPART_IN                             = (1 << 17),
        LWSSSPOLF_ATTR_LOW_LATENCY                              = (1 << 18),
        LWSSSPOLF_ATTR_HIGH_THROUGHPUT                          = (1 << 19),
        LWSSSPOLF_ATTR_HIGH_RELIABILITY                         = (1 << 20),
        LWSSSPOLF_ATTR_LOW_COST                                 = (1 << 21),
        LWSSSPOLF_PERF                                          = (1 << 22),
        LWSSSPOLF_DIRECT_PROTO_STR                              = (1 << 23),
        LWSSSPOLF_HTTP_CACHE_COOKIES                            = (1 << 24),
        LWSSSPOLF_PRIORITIZE_READS                              = (1 << 25),
};

anonymous enum

anonymous enum

Enumerator
LWSSSP_H1
LWSSSP_H2
LWSSSP_WS
LWSSSP_MQTT
LWSSSP_RAW
LWSSS_HBI_AUTH
LWSSS_HBI_DSN
LWSSS_HBI_FWV
LWSSS_HBI_TYPE
_LWSSS_HBI_COUNT

Definition at line 152 of file lws-secure-streams-policy.h.

     {
        LWSSSP_H1,
        LWSSSP_H2,
        LWSSSP_WS,
        LWSSSP_MQTT,
        LWSSSP_RAW,
 
 
        LWSSS_HBI_AUTH = 0,
        LWSSS_HBI_DSN,
        LWSSS_HBI_FWV,
        LWSSS_HBI_TYPE,
 
        _LWSSS_HBI_COUNT /* always last */
};

Function Documentation

lws_ss_policy_parse_begin()

LWS_VISIBLE LWS_EXTERN int lws_ss_policy_parse_begin	(	struct lws_context *	context,
		int	overlay
	)

lws_ss_policy_parse_abandon()

LWS_VISIBLE LWS_EXTERN int lws_ss_policy_parse_abandon

(

struct lws_context *

context

)

lws_ss_policy_parse()

LWS_VISIBLE LWS_EXTERN int lws_ss_policy_parse	(	struct lws_context *	context,
		const uint8_t *	buf,
		size_t	len
	)

lws_ss_policy_overlay()

LWS_VISIBLE LWS_EXTERN int lws_ss_policy_overlay	(	struct lws_context *	context,
		const char *	overlay
	)

lws_ss_policy_get()

LWS_VISIBLE LWS_EXTERN const lws_ss_policy_t* lws_ss_policy_get

(

struct lws_context *

context

)

lws_ss_auth_get()

LWS_VISIBLE LWS_EXTERN const lws_ss_auth_t* lws_ss_auth_get

(

struct lws_context *

context

)