1.. SPDX-License-Identifier: GPL-2.0 2 3========================= 4Stream Parser (strparser) 5========================= 6 7Introduction 8============ 9 10The stream parser (strparser) is a utility that parses messages of an 11application layer protocol running over a TCP connection. The stream 12parser works in conjunction with an upper layer in the kernel to provide 13kernel support for application layer messages. For instance, Kernel 14Connection Multiplexor (KCM) uses the Stream Parser to parse messages 15using a BPF program. 16 17The strparser is called from the data_ready callback of a TCP 18socket. Messages are parsed and delivered as they are received on the 19socket. 20 21Interface 22========= 23 24The API includes a context structure, a set of callbacks, utility 25functions, and a data_ready function. The callbacks include a 26parse_msg function that is called to perform parsing (e.g. BPF parsing 27in case of KCM), and a rcv_msg function that is called when a full 28message has been completed. 29 30Functions 31========= 32 33 :: 34 35 int strp_init(struct strparser *strp, struct sock *sk, 36 const struct strp_callbacks *cb) 37 38 Called to initialize a stream parser. strp is a struct of type 39 strparser that is allocated by the upper layer. sk is the TCP 40 socket associated with the stream parser. Callbacks are called by 41 the stream parser (the callbacks are listed below). 42 43 :: 44 45 void strp_pause(struct strparser *strp) 46 47 Temporarily pause a stream parser. Message parsing is suspended 48 and no new messages are delivered to the upper layer. 49 50 :: 51 52 void strp_unpause(struct strparser *strp) 53 54 Unpause a paused stream parser. 55 56 :: 57 58 void strp_stop(struct strparser *strp); 59 60 strp_stop is called to completely stop stream parser operations. 61 This is called internally when the stream parser encounters an 62 error, and it is called from the upper layer to stop parsing 63 operations. 64 65 :: 66 67 void strp_done(struct strparser *strp); 68 69 strp_done is called to release any resources held by the stream 70 parser instance. This must be called after the stream processor 71 has been stopped. 72 73 :: 74 75 void strp_data_ready(struct strparser *strp); 76 77 The upper layer calls strp_data_ready when data is ready on 78 the lower socket for strparser to process. This should be called 79 from a data_ready callback that is set on the socket. Note that 80 maximum messages size is the limit of the receive socket 81 buffer and message timeout is the receive timeout for the socket. 82 83 :: 84 85 void strp_check_rcv(struct strparser *strp); 86 87 strp_check_rcv is called to check for new messages on the socket. 88 This is normally called at initialization of a stream parser 89 instance or after strp_unpause. 90 91Callbacks 92========= 93 94There are four callbacks: 95 96 :: 97 98 int (*parse_msg)(struct strparser *strp, struct sk_buff *skb); 99 100 parse_msg is called to determine the length of the next message in 101 the stream. It should parse the sk_buff as containing the headers 102 for the next application layer message in the stream. 103 104 The strparser metadata in the input skb can be accessed with 105 strp_msg(skb). Only the offset field is relevant in parse_msg and 106 gives the offset where the message starts in the skb. 107 108 The return values of this function are: 109 110 ========= =========================================================== 111 >0 indicates length of successfully parsed message 112 0 indicates more data must be received to parse the message 113 -ESTRPIPE current message should not be processed by the 114 kernel, return control of the socket to userspace which 115 can proceed to read the messages itself 116 other < 0 Error in parsing, give control back to userspace 117 assuming that synchronization is lost and the stream 118 is unrecoverable (application expected to close TCP socket) 119 ========= =========================================================== 120 121 In the case that an error is returned (return value is less than 122 zero), it will set the error on TCP socket and wake it up. If 123 parse_msg returned -ESTRPIPE and the stream parser had previously 124 read some bytes for the current message, then the error set on the 125 attached socket is ENODATA since the stream is unrecoverable in 126 that case. 127 128 This callback must be set. 129 130 :: 131 132 void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb); 133 134 rcv_msg is called when a full message has been received and 135 is queued. The callee must consume the sk_buff; it can 136 call strp_pause to prevent any further messages from being 137 received in rcv_msg (see strp_pause above). 138 139 The strparser metadata in the input skb can be accessed with 140 strp_msg(skb). This struct contains two fields: offset and full_len. 141 Offset is where the message starts in the skb, and full_len is 142 the length of the message. skb->len - offset may be greater than 143 full_len since strparser does not trim the skb. 144 145 This callback must be set. 146 147 :: 148 149 int (*read_sock)(struct strparser *strp, read_descriptor_t *desc, 150 sk_read_actor_t recv_actor); 151 152 The read_sock callback is used by strparser instead of 153 sock->ops->read_sock, if provided. 154 155 This callback is optional. 156 157 :: 158 159 int (*read_sock_done)(struct strparser *strp, int err); 160 161 read_sock_done is called when the stream parser is done reading 162 the TCP socket. The stream parser may read multiple messages in a 163 loop and this function allows cleanup to occur when exiting the 164 loop. If the callback is not set (NULL in strp_init) a default 165 function is used. 166 167 This callback is optional. 168 169Statistics 170========== 171 172Various counters are kept for each stream parser instance. These are in 173the strp_stats structure. strp_aggr_stats is a convenience structure for 174accumulating statistics for multiple stream parser instances. 175save_strp_stats and aggregate_strp_stats are helper functions to save 176and aggregate statistics. 177 178Message assembly limits 179======================= 180 181The stream parser provide mechanisms to limit the resources consumed by 182message assembly. 183 184A timer is set when assembly starts for a new message. The message 185timeout is taken from rcvtime for the associated TCP socket. If the 186timer fires before assembly completes the stream parser is aborted and 187the ETIMEDOUT error is set on the TCP socket. 188 189Message length is limited to the receive 190buffer size of the associated TCP socket. If the length returned by 191parse_msg is greater than the socket buffer size then the stream parser 192is aborted with EMSGSIZE error set on the TCP socket. Note that this 193makes the maximum size of receive skbuffs for a socket with a stream 194parser to be 2*sk_rcvbuf of the TCP socket. 195 196Author 197====== 198 199Tom Herbert (tom@quantonium.net) 200