Data Structures
struct	lws_ss_info

Macros
#define	LWS_SS_MTU 1540

#define	LWSSS_TIMEOUT_FROM_POLICY 0

Typedefs
typedef uint32_t	lws_ss_tx_ordinal_t

typedef enum lws_ss_state_return	lws_ss_state_return_t

typedef lws_ss_state_return_t(*	lws_sscb_rx) (void userobj, const uint8_t buf, size_t len, int flags)

typedef lws_ss_state_return_t(*	lws_sscb_tx) (void userobj, lws_ss_tx_ordinal_t ord, uint8_t buf, size_t len, int flags)

typedef lws_ss_state_return_t(*	lws_sscb_state) (void userobj, void h_src, lws_ss_constate_t state, lws_ss_tx_ordinal_t ack)

typedef struct lws_ss_info	lws_ss_info_t

typedef void(*	lws_sssfec_cb) (struct lws_ss_handle h, void arg)

Enumerations
enum	lws_ss_constate_t { LWSSSCS_CREATING = 1 , LWSSSCS_DISCONNECTED , LWSSSCS_UNREACHABLE , LWSSSCS_AUTH_FAILED , LWSSSCS_CONNECTED , LWSSSCS_CONNECTING , LWSSSCS_DESTROYING , LWSSSCS_POLL , LWSSSCS_ALL_RETRIES_FAILED , LWSSSCS_QOS_ACK_REMOTE , LWSSSCS_QOS_NACK_REMOTE , LWSSSCS_QOS_ACK_LOCAL , LWSSSCS_QOS_NACK_LOCAL , LWSSSCS_TIMEOUT , LWSSSCS_SERVER_TXN , LWSSSCS_SERVER_UPGRADE , LWSSSCS_EVENT_WAIT_CANCELLED , LWSSSCS_SINK_JOIN , LWSSSCS_SINK_PART , LWSSSCS_USER_BASE = 1000 }

enum	{ LWSSS_FLAG_SOM = (1 << 0) , LWSSS_FLAG_EOM = (1 << 1) , LWSSS_FLAG_POLL = (1 << 2) , LWSSS_FLAG_RELATED_START = (1 << 3) , LWSSS_FLAG_RELATED_END = (1 << 4) , LWSSS_FLAG_RIDESHARE = (1 << 5) , LWSSS_FLAG_PERF_JSON = (1 << 6) , LWSSS_SER_RXPRE_RX_PAYLOAD = 0x55 , LWSSS_SER_RXPRE_CREATE_RESULT , LWSSS_SER_RXPRE_CONNSTATE , LWSSS_SER_RXPRE_TXCR_UPDATE , LWSSS_SER_RXPRE_METADATA , LWSSS_SER_RXPRE_TLSNEG_ENCLAVE_SIGN , LWSSS_SER_RXPRE_PERF , LWSSS_SER_TXPRE_STREAMTYPE = 0xaa , LWSSS_SER_TXPRE_ONWARD_CONNECT , LWSSS_SER_TXPRE_DESTROYING , LWSSS_SER_TXPRE_TX_PAYLOAD , LWSSS_SER_TXPRE_METADATA , LWSSS_SER_TXPRE_TXCR_UPDATE , LWSSS_SER_TXPRE_TIMEOUT_UPDATE , LWSSS_SER_TXPRE_PAYLOAD_LENGTH_HINT , LWSSS_SER_TXPRE_TLSNEG_ENCLAVE_SIGNED }

enum	lws_ss_conn_states_t { LPCSPROX_WAIT_INITIAL_TX = 1 , LPCSPROX_REPORTING_FAIL , LPCSPROX_REPORTING_OK , LPCSPROX_OPERATIONAL , LPCSPROX_DESTROYED , LPCSCLI_SENDING_INITIAL_TX , LPCSCLI_WAITING_CREATE_RESULT , LPCSCLI_LOCAL_CONNECTED , LPCSCLI_ONWARD_CONNECT , LPCSCLI_OPERATIONAL }

enum	lws_ss_state_return { LWSSSSRET_TX_DONT_SEND = 1 , LWSSSSRET_OK = 0 , LWSSSSRET_DISCONNECT_ME = -1 , LWSSSSRET_DESTROY_ME = -2 }

enum	{ LWSSSINFLAGS_REGISTER_SINK = (1 << 0) , LWSSSINFLAGS_PROXIED = (1 << 1) , LWSSSINFLAGS_SERVER = (1 << 2) , LWSSSINFLAGS_ACCEPTED = (1 << 3) }

Functions
LWS_VISIBLE LWS_EXTERN int	lws_ss_create (struct lws_context context, int tsi, const lws_ss_info_t ssi, void opaque_user_data, struct lws_ss_handle ppss, struct lws_sequencer seq_owner, const char **ppayload_fmt)

LWS_VISIBLE LWS_EXTERN void	lws_ss_destroy (struct lws_ss_handle **ppss)

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t	lws_ss_request_tx (struct lws_ss_handle *pss)

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t	lws_ss_request_tx_len (struct lws_ss_handle *pss, unsigned long len)

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t	lws_ss_client_connect (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN struct lws_sequencer *	lws_ss_get_sequencer (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN int	lws_ss_proxy_create (struct lws_context context, const char bind, int port)

LWS_VISIBLE LWS_EXTERN const char *	lws_ss_state_name (int state)

LWS_VISIBLE LWS_EXTERN struct lws_context *	lws_ss_get_context (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN void	lws_ss_start_timeout (struct lws_ss_handle *h, unsigned int timeout_ms)

LWS_VISIBLE LWS_EXTERN void	lws_ss_cancel_timeout (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN void *	lws_ss_to_user_object (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN const char *	lws_ss_rideshare (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_ss_set_metadata (struct lws_ss_handle h, const char name, const void *value, size_t len)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_ss_alloc_set_metadata (struct lws_ss_handle h, const char name, const void *value, size_t len)

LWS_VISIBLE LWS_EXTERN int	lws_ss_get_metadata (struct lws_ss_handle h, const char name, const void *value, size_t len)

LWS_VISIBLE LWS_EXTERN void	lws_ss_server_ack (struct lws_ss_handle *h, int nack)

LWS_VISIBLE LWS_EXTERN void	lws_ss_server_foreach_client (struct lws_ss_handle h, lws_sssfec_cb cb, void arg)

LWS_VISIBLE LWS_EXTERN void	lws_ss_change_handlers (struct lws_ss_handle *h, lws_sscb_rx rx, lws_sscb_tx tx, lws_sscb_state state)

LWS_VISIBLE LWS_EXTERN int	lws_ss_add_peer_tx_credit (struct lws_ss_handle *h, int32_t add)

LWS_VISIBLE LWS_EXTERN int	lws_ss_get_est_peer_tx_credit (struct lws_ss_handle *h)

LWS_VISIBLE LWS_EXTERN const char *	lws_ss_tag (struct lws_ss_handle *h)

Detailed Description

Secure Streams

Secure Streams related apis

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_info_t: information about stream to be created

Prepare this struct with information about what the stream type is and how the stream should interface with your code, and pass it to lws_ss_create() to create the requested stream.

Enumerator
LWSSSINFLAGS_REGISTER_SINK	If set, we're not creating a specific stream, but registering ourselves as the "sink" for .streamtype. It's analogous to saying we want to be the many-to-one "server" for .streamtype; when other streams are created with that streamtype, they should be forwarded to this stream owner, where they join and part from the sink via (*state) LWSSSCS_SINK_JOIN / _PART events, the new client handle being provided in the h_src parameter.
LWSSSINFLAGS_PROXIED	Set if the stream is being created as a stand-in at the proxy
LWSSSINFLAGS_SERVER	Set on the server object copy of the ssi / info to indicate that stream creation using this ssi is for Accepted connections belonging to a server
LWSSSINFLAGS_ACCEPTED	Set on the accepted object copy of the ssi / info to indicate that we are an accepted connection from a server's listening socket

      {
         LWSSSINFLAGS_REGISTER_SINK                      =       (1 << 0),
         LWSSSINFLAGS_PROXIED                            =       (1 << 1),
         LWSSSINFLAGS_SERVER                             =       (1 << 2),
         LWSSSINFLAGS_ACCEPTED                           =       (1 << 3),
 };

Function Documentation

◆ lws_ss_add_peer_tx_credit()

LWS_VISIBLE LWS_EXTERN int lws_ss_add_peer_tx_credit	(	struct lws_ss_handle *	h,
		int32_t	add
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_add_peer_tx_credit() - allow peer to transmit more to us

Parameters

h	secure streams handle
add	additional tx credit (signed)

Indicate to remote peer that we can accept add bytes more payload being sent to us.

◆ lws_ss_alloc_set_metadata()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ss_alloc_set_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void *	value,
		size_t	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_alloc_set_metadata() - copy data and bind to ss metadata

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to user-managed data to bind to name
len	length of the user-managed data in value

Same as lws_ss_set_metadata(), but allocates a heap buffer for the data first and takes a copy of it, so the original can go out of scope immediately after.

◆ lws_ss_cancel_timeout()

LWS_VISIBLE LWS_EXTERN void lws_ss_cancel_timeout ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_cancel_timeout() - remove any timeout on the stream

Parameters

h	secure streams handle

Disable any timeout that was applied to the stream by lws_ss_start_timeout().

◆ lws_ss_change_handlers()

LWS_VISIBLE LWS_EXTERN void lws_ss_change_handlers	(	struct lws_ss_handle *	h,
		lws_sscb_rx	rx,
		lws_sscb_tx	tx,
		lws_sscb_state	state
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_change_handlers() - helper for dynamically changing stream handlers

Parameters

h	ss handle
rx	the new RX handler
tx	the new TX handler
state	the new state handler

Handlers set to NULL are left unchanged.

This works on any handle, client or server and takes effect immediately.

Depending on circumstances this may be helpful when

a) a server stream undergoes an LWSSSCS_SERVER_UPGRADE (as in http -> ws) and the payloads in the new protocol have a different purpose that is best handled in their own rx and tx callbacks, and

b) you may want to serve several different, possibly large things based on what was requested. Setting a customized handler allows clean encapsulation of the different serving strategies.

If the stream is long-lived, like ws, you should set the changed handler back to the default when the transaction wanting it is completed.

◆ lws_ss_client_connect()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t lws_ss_client_connect ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_client_connect() - Attempt the client connect

Parameters

h	secure streams handle

Starts the connection process for the secure stream.

Can return any of the lws_ss_state_return_t values depending on user state callback returns.

LWSSSSRET_OK means the connection is ongoing.

◆ lws_ss_create()

LWS_VISIBLE LWS_EXTERN int lws_ss_create	(	struct lws_context *	context,
		int	tsi,
		const lws_ss_info_t *	ssi,
		void *	opaque_user_data,
		struct lws_ss_handle **	ppss,
		struct lws_sequencer *	seq_owner,
		const char **	ppayload_fmt
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_create() - Create secure stream

Parameters

context	the lws context to create this inside
tsi	service thread index to create on (normally 0)
ssi	pointer to lws_ss_info_t filled in with info about desired stream
opaque_user_data	opaque data to set in the stream's user object
ppss	pointer to secure stream handle pointer set on exit
ppayload_fmt	NULL or pointer to a string ptr to take payload format name from the policy

Requests a new secure stream described by ssi be created. If successful, the stream is created, its state callback called with LWSSSCS_CREATING, *ppss is set to point to the handle, and it returns 0. If it failed, it returns nonzero.

Along with the opaque stream object, streams overallocate

1) a user data struct whose size is set in ssi 2) nauth plugin instantiation data (size set in the plugin struct) 3) sauth plugin instantiation data (size set in the plugin struct) 4) space for a copy of the stream type name

The user data struct is initialized to all zeros, then the .handle_offset and .opaque_user_data_offset fields of the ssi are used to prepare the user data struct with the ss handle that was created, and a copy of the opaque_user_data pointer given as an argument.

If you want to set up the stream with specific information, point to it in opaque_user_data and use the copy of that pointer in your user data member for it starting from the LWSSSCS_CREATING state call.

Since different endpoints chosen by the policy may require different payload formats, ppayload_fmt is set to point to the name of the needed payload format from the policy database if non-NULL.

◆ lws_ss_destroy()

LWS_VISIBLE LWS_EXTERN void lws_ss_destroy ( struct lws_ss_handle ** ppss )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_destroy() - Destroy secure stream

Parameters

ppss	pointer to lws_ss_t pointer to be destroyed

Destroys the lws_ss_t pointed to by *ppss, and sets *ppss to NULL.

◆ lws_ss_get_context()

LWS_VISIBLE LWS_EXTERN struct lws_context* lws_ss_get_context ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_context() - convenience helper to recover the lws context

Parameters

h	secure streams handle

Returns the lws context. Dispenses with the need to pass a copy of it into your secure streams handler.

◆ lws_ss_get_est_peer_tx_credit()

LWS_VISIBLE LWS_EXTERN int lws_ss_get_est_peer_tx_credit ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_est_peer_tx_credit() - get our current estimate of peer's tx credit

Parameters

h	secure streams handle

Based on what credit we gave it, and what we have received, report our estimate of peer's tx credit usable to transmit to us. This may be outdated in that some or all of its credit may already have been expended by sending stuff to us that is in flight already.

◆ lws_ss_get_metadata()

LWS_VISIBLE LWS_EXTERN int lws_ss_get_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void **	value,
		size_t *	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_metadata() - get current value of stream metadata item

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to pointer to be set to point at the value
len	pointer to size_t to set to the length of the value

Binds user-managed data to the named metadata item from the ss policy. If present, the metadata item is handled in a protocol-specific way using the associated policy information. For example, in the policy

    "\"metadata\":"         "["
    "{\"uptag\":"  "\"X-Upload-Tag:\"},"
    "{\"ctype\":"  "\"Content-Type:\"},"
    "{\"xctype\":" "\"\"}"
 "],"

when the policy is using h1 is interpreted to add h1 headers of the given name with the value of the metadata on the left.

Return 0 if *value and *len set OK, or nonzero if, eg, metadata name does not exist on the streamtype.

The pointed-to values may only exist until the next time around the event loop.

◆ lws_ss_get_sequencer()

LWS_VISIBLE LWS_EXTERN struct lws_sequencer* lws_ss_get_sequencer ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_sequencer() - Return parent sequencer pointer if any

Parameters

h	secure streams handle

Returns NULL if the secure stream is not associated with a sequencer. Otherwise returns a pointer to the owning sequencer. You can use this to identify which sequencer to direct messages to, from the secure stream callback.

◆ lws_ss_proxy_create()

LWS_VISIBLE LWS_EXTERN int lws_ss_proxy_create	(	struct lws_context *	context,
		const char *	bind,
		int	port
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_proxy_create() - Start a unix domain socket proxy for Secure Streams

Parameters

context	lws_context
bind	if port is 0, unix domain path with leading @ for abstract. if port nonzero, NULL, or network interface to bind listen to
port	tcp port to listen on

Creates a vhost that listens either on an abstract namespace unix domain socket (port = 0) or a tcp listen socket (port nonzero). If bind is NULL and port is 0, the abstract unix domain socket defaults to "proxy.ss.lws".

Client connections to this proxy to Secure Streams are fulfilled using the policy local to the proxy and the data passed between the client and the proxy using serialized Secure Streams protocol.

◆ lws_ss_request_tx()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t lws_ss_request_tx ( struct lws_ss_handle * pss )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_request_tx() - Schedule stream for tx

Parameters

pss	pointer to lws_ss_t representing stream that wants to transmit

Schedules a write on the stream represented by pss. When it's possible to write on this stream, the *tx callback will occur with an empty buffer for the stream owner to fill in.

Returns 0 or LWSSSSRET_SS_HANDLE_DESTROYED

◆ lws_ss_request_tx_len()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t lws_ss_request_tx_len	(	struct lws_ss_handle *	pss,
		unsigned long	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_request_tx() - Schedule stream for tx

Parameters

pss	pointer to lws_ss_t representing stream that wants to transmit
len	the length of the write in bytes

Schedules a write on the stream represented by pss. When it's possible to write on this stream, the *tx callback will occur with an empty buffer for the stream owner to fill in.

This api variant should be used when it's possible the payload will go out over h1 with x-web-form-urlencoded or similar Content-Type.

◆ lws_ss_rideshare()

LWS_VISIBLE LWS_EXTERN const char* lws_ss_rideshare ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_rideshare() - find the current streamtype when types rideshare

Parameters

h	the stream handle

Under some conditions, the payloads may be structured using protocol- specific formatting, eg, http multipart mime. It's possible to map the logical partitions in the payload to different stream types using the policy "rideshare" feature.

This api lets the callback code find out which rideshare stream type the current payload chunk belongs to.

◆ lws_ss_server_ack()

LWS_VISIBLE LWS_EXTERN void lws_ss_server_ack	(	struct lws_ss_handle *	h,
		int	nack
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_server_ack() - indicate how we feel about what the server has sent

Parameters

h	ss handle of accepted connection
nack	0 means we are OK with it, else some problem

For SERVER secure streams

Depending on the protocol, the server sending us something may be transactional, ie, built into it sending something is the idea we will respond somehow out-of-band; HTTP is like this with, eg, 200 response code.

Calling this with nack=0 indicates that when we later respond, we want to acknowledge the transaction (eg, it means a 200 if http underneath), if nonzero that the transaction should act like it failed.

If the underlying protocol doesn't understand transactions (eg, ws) then this has no effect either way.

◆ lws_ss_server_foreach_client()

LWS_VISIBLE LWS_EXTERN void lws_ss_server_foreach_client	(	struct lws_ss_handle *	h,
		lws_sssfec_cb	cb,
		void *	arg
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_server_foreach_client() - callback for each live client connected to server

Parameters

h	server ss handle
cb	the callback
arg	arg passed to callback

For SERVER secure streams

Call the callback cb once for each client ss connected to the server, passing arg as an additional callback argument each time.

◆ lws_ss_set_metadata()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ss_set_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void *	value,
		size_t	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_set_metadata() - allow user to bind external data to defined ss metadata

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to user-managed data to bind to name
len	length of the user-managed data in value

Binds user-managed data to the named metadata item from the ss policy. If present, the metadata item is handled in a protocol-specific way using the associated policy information. For example, in the policy

    "\"metadata\":"         "["
    "{\"uptag\":"  "\"X-Upload-Tag:\"},"
    "{\"ctype\":"  "\"Content-Type:\"},"
    "{\"xctype\":" "\"\"}"
 "],"

when the policy is using h1 is interpreted to add h1 headers of the given name with the value of the metadata on the left.

Return 0 if OK or nonzero if, eg, metadata name does not exist on the streamtype. You must check the result of this, eg, transient OOM can cause these to fail and you should retry later.

◆ lws_ss_start_timeout()

LWS_VISIBLE LWS_EXTERN void lws_ss_start_timeout	(	struct lws_ss_handle *	h,
		unsigned int	timeout_ms
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_start_timeout() - start or restart the timeout on the stream

Parameters

h	secure streams handle
timeout_ms	LWSSS_TIMEOUT_FROM_POLICY for policy value, else use timeout_ms

Starts or restarts the stream's own timeout timer. If the specified time passes without lws_ss_cancel_timeout() being called on the stream, then the stream state callback receives LWSSSCS_TIMEOUT

The process being protected by the timeout is up to the user code, it may be arbitrarily long and cross multiple protocol transactions or involve other streams. It's up to the user to decide when to start and when / if to cancel the stream timeout.

◆ lws_ss_state_name()

LWS_VISIBLE LWS_EXTERN const char* lws_ss_state_name ( int state )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_state_name() - convenience helper to get a printable conn state name

Parameters

state the connection state index

Returns a printable name for the connection state index passed in.

◆ lws_ss_to_user_object()

LWS_VISIBLE LWS_EXTERN void* lws_ss_to_user_object ( struct lws_ss_handle * h )

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_to_user_object() - convenience helper to get user object from handle

Parameters

h	secure streams handle

Returns the user allocation related to the handle. Normally you won't need this since it's available in the rx, tx and state callbacks as "userdata" already.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Secure Streams

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ lws_ss_add_peer_tx_credit()

◆ lws_ss_alloc_set_metadata()

◆ lws_ss_cancel_timeout()

◆ lws_ss_change_handlers()

◆ lws_ss_client_connect()

◆ lws_ss_create()

◆ lws_ss_destroy()

◆ lws_ss_get_context()

◆ lws_ss_get_est_peer_tx_credit()

◆ lws_ss_get_metadata()

◆ lws_ss_get_sequencer()

◆ lws_ss_proxy_create()

◆ lws_ss_request_tx()

◆ lws_ss_request_tx_len()

◆ lws_ss_rideshare()

◆ lws_ss_server_ack()

◆ lws_ss_server_foreach_client()

◆ lws_ss_set_metadata()

◆ lws_ss_start_timeout()

◆ lws_ss_state_name()

◆ lws_ss_to_user_object()