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