libwebsockets
Lightweight C library for HTML5 websockets
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_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_tlws_ss_policy_get (struct lws_context *context)
 
LWS_VISIBLE LWS_EXTERN const lws_ss_auth_tlws_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

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

◆ lws_ss_metadata_t

◆ lws_ss_http_respmap_t

◆ lws_ss_auth_t

typedef struct lws_ss_auth lws_ss_auth_t

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

81  {
82  LWSSSPOLF_OPPORTUNISTIC = (1 << 0),
84  LWSSSPOLF_NAILED_UP = (1 << 1),
86  LWSSSPOLF_URGENT_TX = (1 << 2),
88  LWSSSPOLF_URGENT_RX = (1 << 3),
90  LWSSSPOLF_TLS = (1 << 4),
92  LWSSSPOLF_LONG_POLL = (1 << 5),
94  LWSSSPOLF_AUTH_BEARER = (1 << 6),
104  LWSSSPOLF_HTTP_MULTIPART = (1 << 11),
112  LWSSSPOLF_LOCAL_SINK = (1 << 13),
118  LWSSSPOLF_SERVER = (1 << 15),
120  LWSSSPOLF_ALLOW_REDIRECTS = (1 << 16),
122  LWSSSPOLF_HTTP_MULTIPART_IN = (1 << 17),
125  LWSSSPOLF_ATTR_LOW_LATENCY = (1 << 18),
127  LWSSSPOLF_ATTR_HIGH_THROUGHPUT = (1 << 19),
131  LWSSSPOLF_ATTR_LOW_COST = (1 << 21),
133  LWSSSPOLF_PERF = (1 << 22),
135  LWSSSPOLF_DIRECT_PROTO_STR = (1 << 23),
137  LWSSSPOLF_HTTP_CACHE_COOKIES = (1 << 24),
139  LWSSSPOLF_PRIORITIZE_READS = (1 << 25),
142 };
@ LWSSSPOLF_HTTP_CACHE_COOKIES
@ LWSSSPOLF_OPPORTUNISTIC
@ LWSSSPOLF_ATTR_HIGH_RELIABILITY
@ LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE
@ LWSSSPOLF_WAKE_SUSPEND__VALIDITY
@ LWSSSPOLF_ALLOW_REDIRECTS
@ LWSSSPOLF_ATTR_LOW_LATENCY
@ LWSSSPOLF_AUTH_BEARER
@ LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM
@ LWSSSPOLF_LONG_POLL
@ LWSSSPOLF_HTTP_MULTIPART_IN
@ LWSSSPOLF_URGENT_TX
@ LWSSSPOLF_NAILED_UP
@ LWSSSPOLF_URGENT_RX
@ LWSSSPOLF_ATTR_LOW_COST
@ LWSSSPOLF_LOCAL_SINK
@ LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED
@ LWSSSPOLF_HTTP_NO_CONTENT_LENGTH
@ LWSSSPOLF_HTTP_MULTIPART
@ LWSSSPOLF_PRIORITIZE_READS
@ LWSSSPOLF_DIRECT_PROTO_STR
@ LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR
@ LWSSSPOLF_ATTR_HIGH_THROUGHPUT

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

152  {
153  LWSSSP_H1,
154  LWSSSP_H2,
155  LWSSSP_WS,
156  LWSSSP_MQTT,
157  LWSSSP_RAW,
158 
159 
160  LWSSS_HBI_AUTH = 0,
164 
165  _LWSSS_HBI_COUNT /* always last */
166 };

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)