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