lws-secure-streams.h

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2019 - 2020 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * included from libwebsockets.h
 *
 *
 * Secure Streams is a *payload-only* client communication channel where all the
 * details about the connection are held in a systemwide policy database and
 * are keyed by the streamtype field... the user of the communication channel
 * does not know or manage the choice of endpoint, tls CA, or even wire
 * protocol.  The advantage is he then does not have any dependency on any of
 * those and they can be changed just by changing the policy database without
 * touching the code using the stream.
 *
 * There are two ways secure streams interfaces to user code:
 *
 * 1) [Linux / RTOS] the natural, smallest interface is to call back to user
 *    code that only operates directly from the lws event loop thread context
 *    (direct callbacks from lws_ss_t)
 *
 *    lws_thread( [user code] ---- lws )
 *
 * 2) [Linux] where the user code is in a different process and communicates
 *    asynchronously via a proxy socket
 *
 *    user_process{ [user code] | shim | socket-}------ lws_process{ lws }
 *
 * In the second, IPC, case, all packets are prepended by one or more bytes
 * indicating the packet type and serializing any associated data, known as
 * Serialized Secure Streams or SSS.
 *
 * Serialized Secure Streams
 * -------------------------
 *
 * On the transport, adjacent packets may be coalesced, that is, the original
 * packet sizes are lost and two or more packets are combined.  For that reason
 * the serialization format always contains a 1-byte type and then a 2-byte
 * frame length.
 *
 * Client to proxy
 *
 * - Proxied connection setup
 *
 *   -  0: LWSSS_SER_TXPRE_STREAMTYPE
 *   -  1: 2-byte MSB-first rest-of-frame length
 *   -  3: 1-byte Client SSS protocol version (introduced in SSSv1)
 *   -  4: 4-byte Client PID (introduced in SSSv1)
 *   -  8: 4-byte MSB-first initial tx credit
 *   - 12: the streamtype name with no NUL
 *
 * - Proxied tx
 *
 *   -  0: LWSSS_SER_TXPRE_TX_PAYLOAD
 *   -  1: 2 byte MSB-first rest-of-frame length
 *   -  3: 4-byte MSB-first flags
 *   -  7: 4-byte MSB-first us between client requested write and wrote to proxy
 *   - 11: 8-byte MSB-first us resolution unix time client wrote to proxy
 *   - 19: payload
 *
 * - Proxied secure stream destroy
 *
 *   -  0: LWSSS_SER_TXPRE_DESTROYING
 *   -  1: 00, 00
 *
 * - Proxied metadata - sent when one metadata item set clientside
 *
 *   -  0: LWSSS_SER_TXPRE_METADATA
 *   -  1: 2-byte MSB-first rest-of-frame length
 *   -  3: 1-byte metadata name length
 *   -  4: metadata name
 *   -  ...: metadata value (for rest of packet)
 *
 * - TX credit management - sent when using tx credit apis, cf METADATA
 *
 *   - 0: LWSSS_SER_TXPRE_TXCR_UPDATE
 *   - 1: 2-byte MSB-first rest-of-frame length 00, 04
 *   - 3: 4-byte additional tx credit adjust value
 *
 * - Stream timeout management - forwarded when user applying or cancelling t.o.
 *
 *   -  0: LWSSS_SER_TXPRE_TIMEOUT_UPDATE
 *   -  1: 2-byte MSB-first rest-of-frame length 00, 04
 *   -  3: 4-byte MSB-first unsigned 32-bit timeout, 0 = use policy, -1 = cancel
 *
 * - Passing up payload length hint
 *
 *   -  0: LWSSS_SER_TXPRE_PAYLOAD_LENGTH_HINT
 *   -  1: 2-byte MSB-first rest-of-frame length 00, 04
 *   -  3: 4-byte MSB-first unsigned 32-bit payload length hint
 *
 * Proxy to client
 *
 * - Proxied connection setup result
 *
 *   -  0: LWSSS_SER_RXPRE_CREATE_RESULT
 *   -  1: 2 byte MSB-first rest-of-frame length (usually 00, 03)
 *   -  3: 1 byte result, 0 = success.  On failure, proxy will close connection.
 *   -  4: 4 byte client dsh allocation recommended for stream type, from policy
 *         (introduced in SSSv1)
 *   -  8: 2 byte MSB-first initial tx credit
 *   - 10: if present, comma-sep list of rideshare types from policy
 *
 * - Proxied rx
 *
 *   -  0: LWSSS_SER_RXPRE_RX_PAYLOAD
 *   -  1: 2 byte MSB-first rest-of-frame length
 *   -  3: 4-byte MSB-first flags
 *   -  7: 4-byte MSB-first us between inbound read and wrote to client
 *   - 11: 8-byte MSB-first us resolution unix time proxy wrote to client
 *   - 17: (rideshare name len + rideshare name if flags & LWSSS_FLAG_RIDESHARE)
 *          payload
 *
 * - Proxied tx credit
 *
 *   -  0: LWSSS_SER_RXPRE_TXCR_UPDATE
 *   -  1: 00, 04
 *   -  3: 4-byte MSB-first addition tx credit bytes
 *
 * - Proxied rx metadata
 *
 *   -  0: LWSSS_SER_RXPRE_METADATA
 *   -  1: 2-byte MSB-first rest-of-frame length
 *   -  3: 1-byte metadata name length
 *   -  4: metadata name
 *   -  ...: metadata value (for rest of packet)
 *
 * - Proxied state (8 or 11 byte packet)
 *
 *   -  0: LWSSS_SER_RXPRE_CONNSTATE
 *   -  1: 00, 05 if state < 256, else 00, 08
 *   -  3: 1 byte state index if state < 256, else 4-byte MSB-first state index
 *   -  4 or 7: 4-byte MSB-first ordinal
 *
 * - Proxied performance information
 *
 *   -  0: LWSSS_SER_RXPRE_PERF
 *   -  1: 2-byte MSB-first rest-of-frame length
 *   -  3: ... performance JSON (for rest of packet)
 *
 * Proxied tx may be read by the proxy but rejected due to lack of buffer space
 * at the proxy.  For that reason, tx must be held at the sender until it has
 * been acknowledged or denied.
 *
 * Sinks
 * -----
 *
 * Sinks are logical "servers", you can register as a sink for a particular
 * streamtype by using the lws_ss_create() api with ssi->register_sink set to 1.
 *
 * For directly fulfilled Secure Streams, new streams of that streamtype bind
 * to the rx, tx and state handlers given when it was registered.
 *
 *  - When new streams are created the registered sink handler for (*state) is
 *    called with event LWSSSCS_SINK_JOIN and the new client stream handle in
 *    the h_src parameter.
 *
 *  - When the client stream sends something to the sink, it calls the sink's
 *    (*rx) with the client stream's
 */
 
 
#define LWS_SS_MTU 1540
 
struct lws_ss_handle;
typedef uint32_t lws_ss_tx_ordinal_t;
 
/*
 * connection state events
 *
 * If you add states, take care about the state names and state transition
 * validity enforcement tables too
 */
typedef enum {
        /* zero means unset */
        LWSSSCS_CREATING                = 1,
        LWSSSCS_DISCONNECTED,
        LWSSSCS_UNREACHABLE,            /* oridinal arg = 1 = caused by dns
                                         * server reachability failure */
        LWSSSCS_AUTH_FAILED,
        LWSSSCS_CONNECTED,
        LWSSSCS_CONNECTING,
        LWSSSCS_DESTROYING,
        LWSSSCS_POLL,
        LWSSSCS_ALL_RETRIES_FAILED,     /* all retries in bo policy failed */
        LWSSSCS_QOS_ACK_REMOTE,         /* remote peer received and acked tx */
        LWSSSCS_QOS_NACK_REMOTE,
        LWSSSCS_QOS_ACK_LOCAL,          /* local proxy accepted our tx */
        LWSSSCS_QOS_NACK_LOCAL,         /* local proxy refused our tx */
        LWSSSCS_TIMEOUT,                /* optional timeout timer fired */
 
        LWSSSCS_SERVER_TXN,
        LWSSSCS_SERVER_UPGRADE,         /* the server protocol upgraded */
 
        LWSSSCS_EVENT_WAIT_CANCELLED, /* somebody called lws_cancel_service */
 
        LWSSSCS_SINK_JOIN,              /* sinks get this when a new source
                                         * stream joins the sink */
        LWSSSCS_SINK_PART,              /* sinks get this when a new source
                                         * stream leaves the sink */
 
        LWSSSCS_USER_BASE = 1000
} lws_ss_constate_t;
 
enum {
        LWSSS_FLAG_SOM                                          = (1 << 0),
        /* payload contains the start of new message */
        LWSSS_FLAG_EOM                                          = (1 << 1),
        /* payload contains the end of message */
        LWSSS_FLAG_POLL                                         = (1 << 2),
        /* Not a real transmit... poll for rx if protocol needs it */
        LWSSS_FLAG_RELATED_START                                = (1 << 3),
        /* Appears in a zero-length message indicating a message group of zero
         * or more messages is now starting. */
        LWSSS_FLAG_RELATED_END                                  = (1 << 4),
        /* Appears in a zero-length message indicating a message group of zero
         * or more messages has now finished. */
        LWSSS_FLAG_RIDESHARE                                    = (1 << 5),
        /* Serialized payload starts with non-default rideshare name length and
         * name string without NUL, then payload */
        LWSSS_FLAG_PERF_JSON                                    = (1 << 6),
        /* This RX is JSON performance data, only on streams with "perf" flag
         * set */
 
        /*
         * In the case the secure stream is proxied across a process or thread
         * boundary, eg by proxying through a socket for IPC, metadata must be
         * carried in-band.  A byte is prepended to each rx payload to
         * differentiate what it is.
         *
         * Secure streams where the user is called back directly does not need
         * any of this and only pure payloads are passed.
         *
         * rx (received by client) prepends for proxied connections
         */
 
        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,
 
        /* tx (send by client) prepends for proxied connections */
 
        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,
};
 
typedef enum {
        LPCSPROX_WAIT_INITIAL_TX = 1, /* after connect, must send streamtype */
        LPCSPROX_REPORTING_FAIL, /* stream creation failed, wait to to tell */
        LPCSPROX_REPORTING_OK, /* stream creation succeeded, wait to to tell */
        LPCSPROX_OPERATIONAL, /* ready for payloads */
        LPCSPROX_DESTROYED,
 
        LPCSCLI_SENDING_INITIAL_TX,  /* after connect, must send streamtype */
        LPCSCLI_WAITING_CREATE_RESULT,   /* wait to hear if proxy ss create OK */
        LPCSCLI_LOCAL_CONNECTED,              /* we are in touch with the proxy */
        LPCSCLI_ONWARD_CONNECT,       /* request onward ss connection */
        LPCSCLI_OPERATIONAL, /* ready for payloads */
 
} lws_ss_conn_states_t;
 
/*
 * Returns from state() callback can tell the caller what the user code
 * wants to do
 */
 
typedef enum lws_ss_state_return {
        LWSSSSRET_TX_DONT_SEND          =  1, /* (*tx) only, or failure */
 
        LWSSSSRET_OK                    =  0, /* no error */
        LWSSSSRET_DISCONNECT_ME         = -1, /* caller should disconnect us */
        LWSSSSRET_DESTROY_ME            = -2, /* caller should destroy us */
} lws_ss_state_return_t;
 
enum {
        LWSSSINFLAGS_REGISTER_SINK                      =       (1 << 0),
        LWSSSINFLAGS_PROXIED                            =       (1 << 1),
        LWSSSINFLAGS_SERVER                             =       (1 << 2),
        LWSSSINFLAGS_ACCEPTED                           =       (1 << 3),
};
 
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);
 
#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)
typedef void (*lws_ss_buffer_dump_cb)(void *userobj, const uint8_t *buf,
                size_t len, int done);
#endif
 
struct lws_ss_policy;
 
typedef struct lws_ss_info {
        const char *streamtype; 
        size_t      user_alloc; 
        size_t      handle_offset; 
        size_t      opaque_user_data_offset;
#if defined(LWS_WITH_SECURE_STREAMS_CPP)
        const struct lws_ss_policy      *policy;
#endif
 
#if defined(LWS_WITH_SYS_FAULT_INJECTION)
        lws_fi_ctx_t                            fic;
#endif
 
        lws_sscb_rx rx;
        lws_sscb_tx tx;
        lws_sscb_state state;
#if defined(LWS_WITH_SECURE_STREAMS_BUFFER_DUMP)
        lws_ss_buffer_dump_cb dump;
#endif
        int         manual_initial_tx_credit;
        uint32_t        client_pid;
        uint8_t         flags;
        uint8_t         sss_protocol_version;
} lws_ss_info_t;
 
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);
 
#define LWSSS_TIMEOUT_FROM_POLICY                               0
 
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);
 
typedef void (*lws_sssfec_cb)(struct lws_ss_handle *h, void *arg);
 
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);
 
 
#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
LWS_VISIBLE LWS_EXTERN int
lws_ss_sigv4_set_aws_key(struct lws_context* context, uint8_t idx,
                                const char * keyid, const char * key);
 
LWS_VISIBLE LWS_EXTERN int
lws_aws_filesystem_credentials_helper(const char *path, const char *kid,
                                      const char *ak, char **aws_keyid,
                                      char **aws_key);
 
#endif