libwebsockets
Lightweight C library for HTML5 websockets
Secure Streams

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

319  {
320  LWSSSINFLAGS_REGISTER_SINK = (1 << 0),
329  LWSSSINFLAGS_PROXIED = (1 << 1),
331  LWSSSINFLAGS_SERVER = (1 << 2),
335  LWSSSINFLAGS_ACCEPTED = (1 << 3),
338 };
@ LWSSSINFLAGS_REGISTER_SINK
Definition: lws-secure-streams.h:320
@ LWSSSINFLAGS_SERVER
Definition: lws-secure-streams.h:331
@ LWSSSINFLAGS_ACCEPTED
Definition: lws-secure-streams.h:335
@ LWSSSINFLAGS_PROXIED
Definition: lws-secure-streams.h:329

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
hsecure streams handle
addadditional 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
hsecure streams handle
namemetadata name from the policy
valuepointer to user-managed data to bind to name
lenlength 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
hsecure 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
hss handle
rxthe new RX handler
txthe new TX handler
statethe 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
hsecure 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
contextthe lws context to create this inside
tsiservice thread index to create on (normally 0)
ssipointer to lws_ss_info_t filled in with info about desired stream
opaque_user_dataopaque data to set in the stream's user object
ppsspointer to secure stream handle pointer set on exit
ppayload_fmtNULL 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
ppsspointer 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
hsecure 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
hsecure 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
hsecure streams handle
namemetadata name from the policy
valuepointer to pointer to be set to point at the value
lenpointer 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
hsecure 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
contextlws_context
bindif port is 0, unix domain path with leading @ for abstract. if port nonzero, NULL, or network interface to bind listen to
porttcp 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
psspointer 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
psspointer to lws_ss_t representing stream that wants to transmit
lenthe 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
hthe 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
hss handle of accepted connection
nack0 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
hserver ss handle
cbthe callback
argarg 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
hsecure streams handle
namemetadata name from the policy
valuepointer to user-managed data to bind to name
lenlength 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
hsecure streams handle
timeout_msLWSSS_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
statethe 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
hsecure 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.