241 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=========================4Stream Parser (strparser)5=========================6 7Introduction8============9 10The stream parser (strparser) is a utility that parses messages of an11application layer protocol running over a data stream. The stream12parser works in conjunction with an upper layer in the kernel to provide13kernel support for application layer messages. For instance, Kernel14Connection Multiplexor (KCM) uses the Stream Parser to parse messages15using a BPF program.16 17The strparser works in one of two modes: receive callback or general18mode.19 20In receive callback mode, the strparser is called from the data_ready21callback of a TCP socket. Messages are parsed and delivered as they are22received on the socket.23 24In general mode, a sequence of skbs are fed to strparser from an25outside source. Message are parsed and delivered as the sequence is26processed. This modes allows strparser to be applied to arbitrary27streams of data.28 29Interface30=========31 32The API includes a context structure, a set of callbacks, utility33functions, and a data_ready function for receive callback mode. The34callbacks include a parse_msg function that is called to perform35parsing (e.g. BPF parsing in case of KCM), and a rcv_msg function36that is called when a full message has been completed.37 38Functions39=========40 41 ::42 43 strp_init(struct strparser *strp, struct sock *sk,44 const struct strp_callbacks *cb)45 46 Called to initialize a stream parser. strp is a struct of type47 strparser that is allocated by the upper layer. sk is the TCP48 socket associated with the stream parser for use with receive49 callback mode; in general mode this is set to NULL. Callbacks50 are called by the stream parser (the callbacks are listed below).51 52 ::53 54 void strp_pause(struct strparser *strp)55 56 Temporarily pause a stream parser. Message parsing is suspended57 and no new messages are delivered to the upper layer.58 59 ::60 61 void strp_unpause(struct strparser *strp)62 63 Unpause a paused stream parser.64 65 ::66 67 void strp_stop(struct strparser *strp);68 69 strp_stop is called to completely stop stream parser operations.70 This is called internally when the stream parser encounters an71 error, and it is called from the upper layer to stop parsing72 operations.73 74 ::75 76 void strp_done(struct strparser *strp);77 78 strp_done is called to release any resources held by the stream79 parser instance. This must be called after the stream processor80 has been stopped.81 82 ::83 84 int strp_process(struct strparser *strp, struct sk_buff *orig_skb,85 unsigned int orig_offset, size_t orig_len,86 size_t max_msg_size, long timeo)87 88 strp_process is called in general mode for a stream parser to89 parse an sk_buff. The number of bytes processed or a negative90 error number is returned. Note that strp_process does not91 consume the sk_buff. max_msg_size is maximum size the stream92 parser will parse. timeo is timeout for completing a message.93 94 ::95 96 void strp_data_ready(struct strparser *strp);97 98 The upper layer calls strp_tcp_data_ready when data is ready on99 the lower socket for strparser to process. This should be called100 from a data_ready callback that is set on the socket. Note that101 maximum messages size is the limit of the receive socket102 buffer and message timeout is the receive timeout for the socket.103 104 ::105 106 void strp_check_rcv(struct strparser *strp);107 108 strp_check_rcv is called to check for new messages on the socket.109 This is normally called at initialization of a stream parser110 instance or after strp_unpause.111 112Callbacks113=========114 115There are six callbacks:116 117 ::118 119 int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);120 121 parse_msg is called to determine the length of the next message122 in the stream. The upper layer must implement this function. It123 should parse the sk_buff as containing the headers for the124 next application layer message in the stream.125 126 The skb->cb in the input skb is a struct strp_msg. Only127 the offset field is relevant in parse_msg and gives the offset128 where the message starts in the skb.129 130 The return values of this function are:131 132 ========= ===========================================================133 >0 indicates length of successfully parsed message134 0 indicates more data must be received to parse the message135 -ESTRPIPE current message should not be processed by the136 kernel, return control of the socket to userspace which137 can proceed to read the messages itself138 other < 0 Error in parsing, give control back to userspace139 assuming that synchronization is lost and the stream140 is unrecoverable (application expected to close TCP socket)141 ========= ===========================================================142 143 In the case that an error is returned (return value is less than144 zero) and the parser is in receive callback mode, then it will set145 the error on TCP socket and wake it up. If parse_msg returned146 -ESTRPIPE and the stream parser had previously read some bytes for147 the current message, then the error set on the attached socket is148 ENODATA since the stream is unrecoverable in that case.149 150 ::151 152 void (*lock)(struct strparser *strp)153 154 The lock callback is called to lock the strp structure when155 the strparser is performing an asynchronous operation (such as156 processing a timeout). In receive callback mode the default157 function is to lock_sock for the associated socket. In general158 mode the callback must be set appropriately.159 160 ::161 162 void (*unlock)(struct strparser *strp)163 164 The unlock callback is called to release the lock obtained165 by the lock callback. In receive callback mode the default166 function is release_sock for the associated socket. In general167 mode the callback must be set appropriately.168 169 ::170 171 void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);172 173 rcv_msg is called when a full message has been received and174 is queued. The callee must consume the sk_buff; it can175 call strp_pause to prevent any further messages from being176 received in rcv_msg (see strp_pause above). This callback177 must be set.178 179 The skb->cb in the input skb is a struct strp_msg. This180 struct contains two fields: offset and full_len. Offset is181 where the message starts in the skb, and full_len is the182 the length of the message. skb->len - offset may be greater183 then full_len since strparser does not trim the skb.184 185 ::186 187 int (*read_sock_done)(struct strparser *strp, int err);188 189 read_sock_done is called when the stream parser is done reading190 the TCP socket in receive callback mode. The stream parser may191 read multiple messages in a loop and this function allows cleanup192 to occur when exiting the loop. If the callback is not set (NULL193 in strp_init) a default function is used.194 195 ::196 197 void (*abort_parser)(struct strparser *strp, int err);198 199 This function is called when stream parser encounters an error200 in parsing. The default function stops the stream parser and201 sets the error in the socket if the parser is in receive callback202 mode. The default function can be changed by setting the callback203 to non-NULL in strp_init.204 205Statistics206==========207 208Various counters are kept for each stream parser instance. These are in209the strp_stats structure. strp_aggr_stats is a convenience structure for210accumulating statistics for multiple stream parser instances.211save_strp_stats and aggregate_strp_stats are helper functions to save212and aggregate statistics.213 214Message assembly limits215=======================216 217The stream parser provide mechanisms to limit the resources consumed by218message assembly.219 220A timer is set when assembly starts for a new message. In receive221callback mode the message timeout is taken from rcvtime for the222associated TCP socket. In general mode, the timeout is passed as an223argument in strp_process. If the timer fires before assembly completes224the stream parser is aborted and the ETIMEDOUT error is set on the TCP225socket if in receive callback mode.226 227In receive callback mode, message length is limited to the receive228buffer size of the associated TCP socket. If the length returned by229parse_msg is greater than the socket buffer size then the stream parser230is aborted with EMSGSIZE error set on the TCP socket. Note that this231makes the maximum size of receive skbuffs for a socket with a stream232parser to be 2*sk_rcvbuf of the TCP socket.233 234In general mode the message length limit is passed in as an argument235to strp_process.236 237Author238======239 240Tom Herbert (tom@quantonium.net)241