{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1713549251, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"796e321b85a77d74939047515b542f56", "oid":{ "oid": "f28a45246e7ea479718ddba5e80deb355b23f5f3", "alias": [ "refs/heads/main"]},"blobname": "include/libwebsockets/lws-secure-streams.h", "blob": "/*\n * libwebsockets - small server side websockets and web server implementation\n *\n * Copyright (C) 2019 - 2021 Andy Green \u003candy@warmcat.com\u003e\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \u0022Software\u0022), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \u0022AS IS\u0022, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n *\n * included from libwebsockets.h\n *\n *\n * Secure Streams is a *payload-only* client communication channel where all the\n * details about the connection are held in a systemwide policy database and\n * are keyed by the streamtype field... the user of the communication channel\n * does not know or manage the choice of endpoint, tls CA, or even wire\n * protocol. The advantage is he then does not have any dependency on any of\n * those and they can be changed just by changing the policy database without\n * touching the code using the stream.\n *\n * There are two ways secure streams interfaces to user code:\n *\n * 1) [Linux / RTOS] the natural, smallest interface is to call back to user\n * code that only operates directly from the lws event loop thread context\n * (direct callbacks from lws_ss_t)\n *\n * lws_thread( [user code] ---- lws )\n *\n * 2) [Linux] where the user code is in a different process and communicates\n * asynchronously via a proxy socket\n *\n * user_process{ [user code] | shim | socket-}------ lws_process{ lws }\n *\n * In the second, IPC, case, all packets are prepended by one or more bytes\n * indicating the packet type and serializing any associated data, known as\n * Serialized Secure Streams or SSS.\n */\n\n/** \u005cdefgroup secstr Secure Streams\n* ##Secure Streams\n*\n* Secure Streams related apis\n*/\n///@{\n\n#define LWS_SS_MTU 1540\n\nstruct lws_ss_handle;\ntypedef uint32_t lws_ss_tx_ordinal_t;\n\n#if defined(STANDALONE)\n#define lws_context lws_context_standalone\nstruct lws_context_standalone;\n#endif\n\n/*\n * connection state events\n *\n * If you add states, take care about the state names and state transition\n * validity enforcement tables too\n */\ntypedef enum {\n\t/* zero means unset */\n\tLWSSSCS_CREATING\t\t\u003d 1,\n\tLWSSSCS_DISCONNECTED,\n\tLWSSSCS_UNREACHABLE,\t\t/* oridinal arg \u003d 1 \u003d caused by dns\n\t\t\t\t\t * server reachability failure */\n\tLWSSSCS_AUTH_FAILED,\n\tLWSSSCS_CONNECTED,\n\tLWSSSCS_CONNECTING,\n\tLWSSSCS_DESTROYING,\n\tLWSSSCS_POLL,\n\tLWSSSCS_ALL_RETRIES_FAILED,\t/* all retries in bo policy failed */\n\tLWSSSCS_QOS_ACK_REMOTE,\t\t/* remote peer received and acked tx */\n\tLWSSSCS_QOS_NACK_REMOTE,\n\tLWSSSCS_QOS_ACK_LOCAL,\t\t/* local proxy accepted our tx */\n\tLWSSSCS_QOS_NACK_LOCAL,\t\t/* local proxy refused our tx */\n\tLWSSSCS_TIMEOUT,\t\t/* optional timeout timer fired */\n\n\tLWSSSCS_SERVER_TXN,\n\tLWSSSCS_SERVER_UPGRADE,\t\t/* the server protocol upgraded */\n\n\tLWSSSCS_EVENT_WAIT_CANCELLED, /* somebody called lws_cancel_service */\n\n\tLWSSSCS_UPSTREAM_LINK_RETRY,\t/* if we are being proxied over some\n\t\t\t\t\t * intermediate link, this transient\n\t\t\t\t\t * state may be sent to indicate we are\n\t\t\t\t\t * waiting to establish that link before\n\t\t\t\t\t * creation can proceed.. ack is the\n\t\t\t\t\t * number of ms we have been trying */\n\n\tLWSSSCS_SINK_JOIN,\t\t/* sinks get this when a new source\n\t\t\t\t\t * stream joins the sink */\n\tLWSSSCS_SINK_PART,\t\t/* sinks get this when a new source\n\t\t\t\t\t * stream leaves the sink */\n\n\tLWSSSCS_USER_BASE \u003d 1000\n} lws_ss_constate_t;\n\nenum {\n\tLWSSS_FLAG_SOM\t\t\t\t\t\t\u003d (1 \u003c\u003c 0),\n\t/* payload contains the start of new message */\n\tLWSSS_FLAG_EOM\t\t\t\t\t\t\u003d (1 \u003c\u003c 1),\n\t/* payload contains the end of message */\n\tLWSSS_FLAG_POLL\t\t\t\t\t\t\u003d (1 \u003c\u003c 2),\n\t/* Not a real transmit... poll for rx if protocol needs it */\n\tLWSSS_FLAG_RELATED_START\t\t\t\t\u003d (1 \u003c\u003c 3),\n\t/* Appears in a zero-length message indicating a message group of zero\n\t * or more messages is now starting. */\n\tLWSSS_FLAG_RELATED_END\t\t\t\t\t\u003d (1 \u003c\u003c 4),\n\t/* Appears in a zero-length message indicating a message group of zero\n\t * or more messages has now finished. */\n\tLWSSS_FLAG_RIDESHARE\t\t\t\t\t\u003d (1 \u003c\u003c 5),\n\t/* Serialized payload starts with non-default rideshare name length and\n\t * name string without NUL, then payload */\n\tLWSSS_FLAG_PERF_JSON\t\t\t\t\t\u003d (1 \u003c\u003c 6),\n\t/* This RX is JSON performance data, only on streams with \u0022perf\u0022 flag\n\t * set */\n};\n\n/*\n * Returns from state() callback can tell the caller what the user code\n * wants to do\n */\n\ntypedef enum lws_ss_state_return {\n\tLWSSSSRET_TX_DONT_SEND\t\t\u003d 1, /* (*tx) only, or failure */\n\n\tLWSSSSRET_OK\t\t\t\u003d 0, /* no error */\n\tLWSSSSRET_DISCONNECT_ME\t\t\u003d -1, /* caller should disconnect us */\n\tLWSSSSRET_DESTROY_ME\t\t\u003d -2, /* caller should destroy us */\n} lws_ss_state_return_t;\n\n/**\n * lws_ss_info_t: information about stream to be created\n *\n * Prepare this struct with information about what the stream type is and how\n * the stream should interface with your code, and pass it to lws_ss_create()\n * to create the requested stream.\n */\n\nenum {\n\tLWSSSINFLAGS_REGISTER_SINK\t\t\t\u003d\t(1 \u003c\u003c 0),\n\t/**\u003c If set, we're not creating a specific stream, but registering\n\t * ourselves as the \u0022sink\u0022 for .streamtype. It's analogous to saying\n\t * we want to be the many-to-one \u0022server\u0022 for .streamtype; when other\n\t * streams are created with that streamtype, they should be forwarded\n\t * to this stream owner, where they join and part from the sink via\n\t * (*state) LWSSSCS_SINK_JOIN / _PART events, the new client handle\n\t * being provided in the h_src parameter.\n\t */\n\tLWSSSINFLAGS_PROXIED\t\t\t\t\u003d\t(1 \u003c\u003c 1),\n\t/**\u003c Set if the stream is being created as a stand-in at the proxy */\n\tLWSSSINFLAGS_SERVER\t\t\t\t\u003d\t(1 \u003c\u003c 2),\n\t/**\u003c Set on the server object copy of the ssi / info to indicate that\n\t * stream creation using this ssi is for Accepted connections belonging\n\t * to a server */\n\tLWSSSINFLAGS_ACCEPTED\t\t\t\t\u003d\t(1 \u003c\u003c 3),\n\t/**\u003c Set on the accepted object copy of the ssi / info to indicate that\n\t * we are an accepted connection from a server's listening socket */\n\tLWSSSINFLAGS_ACCEPTED_SINK\t\t\t\u003d\t(1 \u003c\u003c 4),\n\t/**\u003c Set on the accepted object copy of the ssi / info to indicate that\n\t * we are an accepted connection from a local sink */\n};\n\ntypedef lws_ss_state_return_t (*lws_sscb_rx)(void *userobj, const uint8_t *buf,\n\t\t\t\t\t size_t len, int flags);\ntypedef lws_ss_state_return_t (*lws_sscb_tx)(void *userobj,\n\t\t\t\t\t lws_ss_tx_ordinal_t ord,\n\t\t\t\t\t uint8_t *buf, size_t *len,\n\t\t\t\t\t int *flags);\ntypedef lws_ss_state_return_t (*lws_sscb_state)(void *userobj, void *h_src,\n\t\t\t\t\t\tlws_ss_constate_t state,\n\t\t\t\t\t\tlws_ss_tx_ordinal_t ack);\n\n#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)\ntypedef void (*lws_ss_buffer_dump_cb)(void *userobj, const uint8_t *buf,\n\t\tsize_t len, int done);\n#endif\n\nstruct lws_ss_policy;\n\ntypedef struct lws_ss_info {\n\tconst char *streamtype; /**\u003c type of stream we want to create */\n\tsize_t\t user_alloc; /**\u003c size of user allocation */\n\tsize_t\t handle_offset; /**\u003c offset of handle stg in user_alloc type,\n\t\t\t\t set to offsetof(mytype, my_handle_member) */\n\tsize_t\t opaque_user_data_offset;\n\t/**\u003c offset of opaque user data ptr in user_alloc type, set to\n\t offsetof(mytype, opaque_ud_member) */\n\n#if defined(LWS_WITH_SECURE_STREAMS_CPP)\n\tconst struct lws_ss_policy\t*policy;\n\t/**\u003c Normally NULL, or a locally-generated policy to apply to this\n\t * connection instead of a named streamtype */\n#endif\n\n#if defined(LWS_WITH_SYS_FAULT_INJECTION)\n\tlws_fi_ctx_t\t\t\t\tfic;\n\t/**\u003c Attach external Fault Injection context to the stream, hierarchy\n\t * is ss-\u003econtext */\n#endif\n\n\tlws_sscb_rx rx;\n\t/**\u003c callback with rx payload for this stream */\n\tlws_sscb_tx tx;\n\t/**\u003c callback to send payload on this stream... 0 \u003d send as set in\n\t * len and flags, 1 \u003d do not send anything (ie, not even 0 len frame) */\n\tlws_sscb_state state;\n\t/**\u003c advisory cb about state of stream and QoS status if applicable...\n\t * h_src is only used with sinks and LWSSSCS_SINK_JOIN/_PART events.\n\t * Return nonzero to indicate you want to destroy the stream. */\n#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)\n\tlws_ss_buffer_dump_cb dump;\n\t/**\u003c cb to record needed protocol buffer data*/\n#endif\n\tint\t manual_initial_tx_credit;\n\t/**\u003c 0 \u003d manage any tx credit automatically, nonzero explicitly sets the\n\t * peer stream to have the given amount of tx credit, if the protocol\n\t * can support it.\n\t *\n\t * In the special case of _lws_smd streamtype, this is used to indicate\n\t * the connection's rx class mask.\n\t * */\n\tuint32_t\tclient_pid;\n\t/**\u003c used in proxy / serialization case to hold the client pid this\n\t * proxied connection is to be tagged with\n\t */\n\tuint8_t\t\tflags;\n\tuint8_t\t\tsss_protocol_version;\n\t/**\u003c used in proxy / serialization case to hold the SS serialization\n\t * protocol level to use with this peer... clients automatically request\n\t * the most recent version they were built with\n\t * (LWS_SSS_CLIENT_PROTOCOL_VERSION) and the proxy stores the requested\n\t * version in here\n\t */\n\n} lws_ss_info_t;\n\n#define LWS_SS_USER_TYPEDEF \u005c\n\ttypedef struct { \u005c\n\t\tstruct lws_ss_handle \t*ss; \u005c\n\t\tvoid\t\t\t*opaque_data;\n\n#define LWS_SS_INFO(_streamtype, _type) \u005c\n\tconst lws_ss_info_t ssi_##_type \u003d { \u005c\n\t\t.handle_offset \u003d offsetof(_type, ss), \u005c\n\t\t.opaque_user_data_offset \u003d offsetof(_type, opaque_data), \u005c\n\t\t.user_alloc \u003d sizeof(_type), \u005c\n\t\t.streamtype \u003d _streamtype,\n\n#define lws_ss_from_user(_u)\t\t(_u)-\u003ess\n#define lws_ss_opaque_from_user(_u)\t(_u)-\u003eopaque_data\n#define lws_ss_cx_from_user(_u)\t\tlws_ss_get_context((_u)-\u003ess)\n\n#if defined(LWS_SS_USE_SSPC)\n#define lws_context_info_defaults(_x, _y) _lws_context_info_defaults(_x, NULL)\n#else\n#define lws_context_info_defaults(_x, _y) _lws_context_info_defaults(_x, _y)\n#endif\n\n/**\n * lws_ss_create() - Create secure stream\n *\n * \u005cparam context: the lws context to create this inside\n * \u005cparam tsi: service thread index to create on (normally 0)\n * \u005cparam ssi: pointer to lws_ss_info_t filled in with info about desired stream\n * \u005cparam opaque_user_data: opaque data to set in the stream's user object\n * \u005cparam ppss: pointer to secure stream handle pointer set on exit\n * \u005cparam ppayload_fmt: NULL or pointer to a string ptr to take payload format\n *\t\t\tname from the policy\n *\n * Requests a new secure stream described by \u005cp ssi be created. If successful,\n * the stream is created, its state callback called with LWSSSCS_CREATING, \u005cp *ppss\n * is set to point to the handle, and it returns 0. If it failed, it returns\n * nonzero.\n *\n * Along with the opaque stream object, streams overallocate\n *\n * 1) a user data struct whose size is set in ssi\n * 2) nauth plugin instantiation data (size set in the plugin struct)\n * 3) sauth plugin instantiation data (size set in the plugin struct)\n * 4) space for a copy of the stream type name\n *\n * The user data struct is initialized to all zeros, then the .handle_offset and\n * .opaque_user_data_offset fields of the ssi are used to prepare the user data\n * struct with the ss handle that was created, and a copy of the\n * opaque_user_data pointer given as an argument.\n *\n * If you want to set up the stream with specific information, point to it in\n * opaque_user_data and use the copy of that pointer in your user data member\n * for it starting from the LWSSSCS_CREATING state call.\n *\n * Since different endpoints chosen by the policy may require different payload\n * formats, \u005cp ppayload_fmt is set to point to the name of the needed payload\n * format from the policy database if non-NULL.\n */\nLWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT\nlws_ss_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi,\n\t void *opaque_user_data, struct lws_ss_handle **ppss,\n\t void *reserved, const char **ppayload_fmt);\n\n/**\n * lws_ss_destroy() - Destroy secure stream\n *\n * \u005cparam ppss: pointer to lws_ss_t pointer to be destroyed\n *\n * Destroys the lws_ss_t pointed to by \u005cp *ppss, and sets \u005cp *ppss to NULL.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_destroy(struct lws_ss_handle **ppss);\n\n/**\n * lws_ss_request_tx() - Schedule stream for tx\n *\n * \u005cparam pss: pointer to lws_ss_t representing stream that wants to transmit\n *\n * Schedules a write on the stream represented by \u005cp pss. When it's possible to\n * write on this stream, the \u005cp *tx callback will occur with an empty buffer for\n * the stream owner to fill in.\n *\n * Returns 0 or LWSSSSRET_DESTROY_ME\n */\nLWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT\nlws_ss_request_tx(struct lws_ss_handle *pss);\n\n/**\n * lws_ss_request_tx() - Schedule stream for tx\n *\n * \u005cparam pss: pointer to lws_ss_t representing stream that wants to transmit\n * \u005cparam len: the length of the write in bytes\n *\n * Schedules a write on the stream represented by \u005cp pss. When it's possible to\n * write on this stream, the \u005cp *tx callback will occur with an empty buffer for\n * the stream owner to fill in.\n *\n * This api variant should be used when it's possible the payload will go out\n * over h1 with x-web-form-urlencoded or similar Content-Type.\n */\nLWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT\nlws_ss_request_tx_len(struct lws_ss_handle *pss, unsigned long len);\n\n/**\n * lws_ss_client_connect() - Attempt the client connect\n *\n * \u005cparam h: secure streams handle\n *\n * Starts the connection process for the secure stream.\n *\n * Can return any of the lws_ss_state_return_t values depending on user\n * state callback returns.\n *\n * LWSSSSRET_OK means the connection is ongoing.\n *\n */\nLWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT\nlws_ss_client_connect(struct lws_ss_handle *h);\n\n/**\n * lws_ss_proxy_create() - Start a unix domain socket proxy for Secure Streams\n *\n * \u005cparam context: lws_context\n * \u005cparam bind: if port is 0, unix domain path with leading @ for abstract.\n *\t\tif port nonzero, NULL, or network interface to bind listen to\n * \u005cparam port: tcp port to listen on\n *\n * Creates a vhost that listens either on an abstract namespace unix domain\n * socket (port \u003d 0) or a tcp listen socket (port nonzero). If bind is NULL\n * and port is 0, the abstract unix domain socket defaults to \u0022proxy.ss.lws\u0022.\n *\n * Client connections to this proxy to Secure Streams are fulfilled using the\n * policy local to the proxy and the data passed between the client and the\n * proxy using serialized Secure Streams protocol.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_proxy_create(struct lws_context *context, const char *bind, int port);\n\n/**\n * lws_ss_state_name() - convenience helper to get a printable conn state name\n *\n * \u005cparam state: the connection state index\n *\n * Returns a printable name for the connection state index passed in.\n */\nLWS_VISIBLE LWS_EXTERN const char *\nlws_ss_state_name(int state);\n\n/**\n * lws_ss_get_context() - convenience helper to recover the lws context\n *\n * \u005cparam h: secure streams handle\n *\n * Returns the lws context. Dispenses with the need to pass a copy of it into\n * your secure streams handler.\n */\nLWS_VISIBLE LWS_EXTERN struct lws_context *\nlws_ss_get_context(struct lws_ss_handle *h);\n\n/**\n * lws_ss_get_vhost() - convenience helper to get the vhost the ss is bound to\n *\n * \u005cparam h: secure streams handle\n *\n * Returns NULL if disconnected, or the the lws_vhost of the ss' wsi connection. \n */\nLWS_VISIBLE LWS_EXTERN struct lws_vhost *\nlws_ss_get_vhost(struct lws_ss_handle *h);\n\n\n#define LWSSS_TIMEOUT_FROM_POLICY\t\t\t\t0\n\n/**\n * lws_ss_start_timeout() - start or restart the timeout on the stream\n *\n * \u005cparam h: secure streams handle\n * \u005cparam timeout_ms: LWSSS_TIMEOUT_FROM_POLICY for policy value, else use timeout_ms\n *\n * Starts or restarts the stream's own timeout timer. If the specified time\n * passes without lws_ss_cancel_timeout() being called on the stream, then the\n * stream state callback receives LWSSSCS_TIMEOUT\n *\n * The process being protected by the timeout is up to the user code, it may be\n * arbitrarily long and cross multiple protocol transactions or involve other\n * streams. It's up to the user to decide when to start and when / if to cancel\n * the stream timeout.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_start_timeout(struct lws_ss_handle *h, unsigned int timeout_ms);\n\n/**\n * lws_ss_cancel_timeout() - remove any timeout on the stream\n *\n * \u005cparam h: secure streams handle\n *\n * Disable any timeout that was applied to the stream by lws_ss_start_timeout().\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_cancel_timeout(struct lws_ss_handle *h);\n\n/**\n * lws_ss_to_user_object() - convenience helper to get user object from handle\n *\n * \u005cparam h: secure streams handle\n *\n * Returns the user allocation related to the handle. Normally you won't need\n * this since it's available in the rx, tx and state callbacks as \u0022userdata\u0022\n * already.\n */\nLWS_VISIBLE LWS_EXTERN void *\nlws_ss_to_user_object(struct lws_ss_handle *h);\n\n/**\n * lws_ss_rideshare() - find the current streamtype when types rideshare\n *\n * \u005cparam h: the stream handle\n *\n * Under some conditions, the payloads may be structured using protocol-\n * specific formatting, eg, http multipart mime. It's possible to map the\n * logical partitions in the payload to different stream types using\n * the policy \u0022rideshare\u0022 feature.\n *\n * This api lets the callback code find out which rideshare stream type the\n * current payload chunk belongs to.\n */\nLWS_VISIBLE LWS_EXTERN const char *\nlws_ss_rideshare(struct lws_ss_handle *h);\n\n\n/**\n * lws_ss_set_metadata() - allow user to bind external data to defined ss metadata\n *\n * \u005cparam h: secure streams handle\n * \u005cparam name: metadata name from the policy\n * \u005cparam value: pointer to user-managed data to bind to name\n * \u005cparam len: length of the user-managed data in value\n *\n * Binds user-managed data to the named metadata item from the ss policy.\n * If present, the metadata item is handled in a protocol-specific way using\n * the associated policy information. For example, in the policy\n *\n * \t\u0022\u005c\u0022metadata\u005c\u0022:\u0022\t\t\u0022[\u0022\n *\t\t\u0022{\u005c\u0022uptag\u005c\u0022:\u0022 \u0022\u005c\u0022X-Upload-Tag:\u005c\u0022},\u0022\n *\t\t\u0022{\u005c\u0022ctype\u005c\u0022:\u0022 \u0022\u005c\u0022Content-Type:\u005c\u0022},\u0022\n *\t\t\u0022{\u005c\u0022xctype\u005c\u0022:\u0022 \u0022\u005c\u0022\u005c\u0022}\u0022\n *\t\u0022],\u0022\n *\n * when the policy is using h1 is interpreted to add h1 headers of the given\n * name with the value of the metadata on the left.\n *\n * Return 0 if OK or nonzero if, eg, metadata name does not exist on the\n * streamtype. You must check the result of this, eg, transient OOM can cause\n * these to fail and you should retry later.\n */\nLWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT\nlws_ss_set_metadata(struct lws_ss_handle *h, const char *name,\n\t\t const void *value, size_t len);\n\n/**\n * lws_ss_alloc_set_metadata() - copy data and bind to ss metadata\n *\n * \u005cparam h: secure streams handle\n * \u005cparam name: metadata name from the policy\n * \u005cparam value: pointer to user-managed data to bind to name\n * \u005cparam len: length of the user-managed data in value\n *\n * Same as lws_ss_set_metadata(), but allocates a heap buffer for the data\n * first and takes a copy of it, so the original can go out of scope\n * immediately after.\n */\nLWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT\nlws_ss_alloc_set_metadata(struct lws_ss_handle *h, const char *name,\n\t\t\t const void *value, size_t len);\n\n/**\n * lws_ss_get_metadata() - get current value of stream metadata item\n *\n * \u005cparam h: secure streams handle\n * \u005cparam name: metadata name from the policy\n * \u005cparam value: pointer to pointer to be set to point at the value\n * \u005cparam len: pointer to size_t to set to the length of the value\n *\n * Binds user-managed data to the named metadata item from the ss policy.\n * If present, the metadata item is handled in a protocol-specific way using\n * the associated policy information. For example, in the policy\n *\n * \t\u0022\u005c\u0022metadata\u005c\u0022:\u0022\t\t\u0022[\u0022\n *\t\t\u0022{\u005c\u0022uptag\u005c\u0022:\u0022 \u0022\u005c\u0022X-Upload-Tag:\u005c\u0022},\u0022\n *\t\t\u0022{\u005c\u0022ctype\u005c\u0022:\u0022 \u0022\u005c\u0022Content-Type:\u005c\u0022},\u0022\n *\t\t\u0022{\u005c\u0022xctype\u005c\u0022:\u0022 \u0022\u005c\u0022\u005c\u0022}\u0022\n *\t\u0022],\u0022\n *\n * when the policy is using h1 is interpreted to add h1 headers of the given\n * name with the value of the metadata on the left.\n *\n * Return 0 if \u005cp *value and \u005cp *len set OK, or nonzero if, eg, metadata \u005cp name does\n * not exist on the streamtype.\n *\n * The pointed-to values may only exist until the next time around the event\n * loop.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_get_metadata(struct lws_ss_handle *h, const char *name,\n\t\t const void **value, size_t *len);\n\n/**\n * lws_ss_server_ack() - indicate how we feel about what the server has sent\n *\n * \u005cparam h: ss handle of accepted connection\n * \u005cparam nack: 0 means we are OK with it, else some problem\n *\n * For SERVER secure streams\n *\n * Depending on the protocol, the server sending us something may be\n * transactional, ie, built into it sending something is the idea we will\n * respond somehow out-of-band; HTTP is like this with, eg, 200 response code.\n *\n * Calling this with nack\u003d0 indicates that when we later respond, we want to\n * acknowledge the transaction (eg, it means a 200 if http underneath), if\n * nonzero that the transaction should act like it failed.\n *\n * If the underlying protocol doesn't understand transactions (eg, ws) then this\n * has no effect either way.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_server_ack(struct lws_ss_handle *h, int nack);\n\ntypedef void (*lws_sssfec_cb)(struct lws_ss_handle *h, void *arg);\n\n/**\n * lws_ss_server_foreach_client() - callback for each live client connected to server\n *\n * \u005cparam h: server ss handle\n * \u005cparam cb: the callback\n * \u005cparam arg: arg passed to callback\n *\n * For SERVER secure streams\n *\n * Call the callback \u005cp cb once for each client ss connected to the server,\n * passing \u005cp arg as an additional callback argument each time.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_server_foreach_client(struct lws_ss_handle *h, lws_sssfec_cb cb,\n\t\t\t void *arg);\n\n/**\n * lws_ss_change_handlers() - helper for dynamically changing stream handlers\n *\n * \u005cparam h: ss handle\n * \u005cparam rx: the new RX handler\n * \u005cparam tx: the new TX handler\n * \u005cparam state: the new state handler\n *\n * Handlers set to NULL are left unchanged.\n *\n * This works on any handle, client or server and takes effect immediately.\n *\n * Depending on circumstances this may be helpful when\n *\n * a) a server stream undergoes an LWSSSCS_SERVER_UPGRADE (as in http -\u003e ws) and\n * the payloads in the new protocol have a different purpose that is best\n * handled in their own rx and tx callbacks, and\n *\n * b) you may want to serve several different, possibly large things based on\n * what was requested. Setting a customized handler allows clean encapsulation\n * of the different serving strategies.\n *\n * If the stream is long-lived, like ws, you should set the changed handler back\n * to the default when the transaction wanting it is completed.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_ss_change_handlers(struct lws_ss_handle *h, lws_sscb_rx rx, lws_sscb_tx tx,\n\t\t lws_sscb_state state);\n\n/**\n * lws_ss_add_peer_tx_credit() - allow peer to transmit more to us\n *\n * \u005cparam h: secure streams handle\n * \u005cparam add: additional tx credit (signed)\n *\n * Indicate to remote peer that we can accept \u005cp add bytes more payload being\n * sent to us.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_add_peer_tx_credit(struct lws_ss_handle *h, int32_t add);\n\n/**\n * lws_ss_get_est_peer_tx_credit() - get our current estimate of peer's tx credit\n *\n * \u005cparam h: secure streams handle\n *\n * Based on what credit we gave it, and what we have received, report our\n * estimate of peer's tx credit usable to transmit to us. This may be outdated\n * in that some or all of its credit may already have been expended by sending\n * stuff to us that is in flight already.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_get_est_peer_tx_credit(struct lws_ss_handle *h);\n\nLWS_VISIBLE LWS_EXTERN const char *\nlws_ss_tag(struct lws_ss_handle *h);\n\n/**\n * lws_ss_adopt_raw() - bind ss to existing fd\n *\n * \u005cparam ss: pointer to lws_ss_t to adopt the fd\n * \u005cparam fd: the existing fd\n *\n * \u0022connects\u0022 the existing ss to a wsi adoption of fd, it's useful for cases\n * like local representation of eg a pipe() fd using ss.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_adopt_raw(struct lws_ss_handle *ss, lws_sock_file_fd_type fd);\n\n#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)\n/**\n * lws_ss_sigv4_set_aws_key() - set aws credential into system blob\n *\n * \u005cparam context: lws_context\n * \u005cparam idx: the system blob index specified in the policy, currently\n * up to 4 blobs.\n * \u005cparam keyid: aws access keyid\n * \u005cparam key: aws access key\n *\n * Return 0 if OK or nonzero if e.g. idx is invalid; system blob heap appending\n * fails.\n */\n\nLWS_VISIBLE LWS_EXTERN int\nlws_ss_sigv4_set_aws_key(struct lws_context* context, uint8_t idx,\n\t\t const char * keyid, const char * key);\n\n/**\n * lws_aws_filesystem_credentials_helper() - read aws credentials from file\n *\n * \u005cparam path: path to read, ~ at start is converted to $HOME contents if any\n * \u005cparam kid: eg, \u0022aws_access_key_id\u0022\n * \u005cparam ak: eg, \u0022aws_secret_access_key\u0022\n * \u005cparam aws_keyid: pointer to pointer for allocated keyid from credentials file\n * \u005cparam aws_key: pointer to pointer for allocated key from credentials file\n *\n * Return 0 if both *aws_keyid and *aws_key allocated from the config file, else\n * nonzero, and neither *aws_keyid or *aws_key are allocated.\n *\n * If *aws_keyid and *aws_key are set, it's the user's responsibility to\n * free() them when they are no longer needed.\n */\n\nLWS_VISIBLE LWS_EXTERN int\nlws_aws_filesystem_credentials_helper(const char *path, const char *kid,\n\t\t\t\t const char *ak, char **aws_keyid,\n\t\t\t\t char **aws_key);\n#endif\n\n#if defined(STANDALONE)\n#undef lws_context\n#endif\n\n///@}\n\n","s":{"c":1713528310,"u": 643}} ],"g": 725,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 0, "si": 0, "db":0, "di":0, "sat":0, "lfc": "7d0a"}