suricata
app-layer-detect-proto.h
Go to the documentation of this file.
1 /* Copyright (C) 2007-2014 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Victor Julien <victor@inliniac.net>
22  * \author Anoop Saldanha <anoopsaldanha@gmail.com>
23  */
24 
25 #ifndef SURICATA_APP_LAYER_DETECT_PROTO__H
26 #define SURICATA_APP_LAYER_DETECT_PROTO__H
27 
28 // only forward declaration for bindgen
29 typedef struct Flow_ Flow;
30 #include "app-layer-protos.h"
31 
33 
35  const Flow *f, uint8_t flags, const uint8_t *input, uint32_t input_len, uint8_t *rdir);
36 
37 /***** Protocol Retrieval *****/
38 
39 /**
40  * \brief Returns the app layer protocol given a buffer.
41  *
42  * \param tctx Pointer to the app layer protocol detection thread context.
43  * \param f Pointer to the flow.
44  * \param buf The buffer to be inspected.
45  * \param buflen The length of the above buffer.
46  * \param ipproto The ip protocol.
47  * \param flags The direction bitfield - STREAM_TOSERVER/STREAM_TOCLIENT.
48  * \param[out] reverse_flow true if flow is detected to be reversed
49  *
50  * \retval The app layer protocol.
51  */
53  const uint8_t *buf, uint32_t buflen, uint8_t ipproto, uint8_t flags, bool *reverse_flow);
54 
55 /***** State Preparation *****/
56 
57 /**
58  * \brief Prepares the internal state for protocol detection.
59  * This needs to be called once all the patterns and probing parser
60  * ports have been registered.
61  */
63 
64 /***** PP registration *****/
65 
66 void SCAppLayerProtoDetectPPRegister(uint8_t ipproto, const char *portstr, AppProto alproto,
67  uint16_t min_depth, uint16_t max_depth, uint8_t direction, ProbingParserFPtr ProbingParser1,
68  ProbingParserFPtr ProbingParser2);
69 /**
70  * \retval bool 0 if no config was found, 1 if config was found
71  */
72 int SCAppLayerProtoDetectPPParseConfPorts(const char *ipproto_name, uint8_t ipproto,
73  const char *alproto_name, AppProto alproto, uint16_t min_depth, uint16_t max_depth,
74  ProbingParserFPtr ProbingParserTs, ProbingParserFPtr ProbingParserTc);
75 
76 /***** PM registration *****/
77 
78 /**
79  * \brief Registers a case-sensitive pattern for protocol detection.
80  */
81 int SCAppLayerProtoDetectPMRegisterPatternCS(uint8_t ipproto, AppProto alproto, const char *pattern,
82  uint16_t depth, uint16_t offset, uint8_t direction);
83 int SCAppLayerProtoDetectPMRegisterPatternCSwPP(uint8_t ipproto, AppProto alproto,
84  const char *pattern, uint16_t depth, uint16_t offset, uint8_t direction,
85  ProbingParserFPtr PPFunc, uint16_t pp_min_depth, uint16_t pp_max_depth);
86 
87 /**
88  * \brief Registers a case-insensitive pattern for protocol detection.
89  */
90 int SCAppLayerProtoDetectPMRegisterPatternCI(uint8_t ipproto, AppProto alproto, const char *pattern,
91  uint16_t depth, uint16_t offset, uint8_t direction);
92 
93 /***** Setup/General Registration *****/
94 
95 /**
96  * \brief The first function to be called. This initializes a global
97  * protocol detection context.
98  *
99  * \retval 0 On success;
100  * \retval -1 On failure.
101  */
102 int AppLayerProtoDetectSetup(void);
103 
104 /**
105  * \brief Reset proto detect for flow
106  */
108 
109 bool AppLayerRequestProtocolChange(Flow *f, uint16_t dp, AppProto expect_proto);
111 
112 void SCAppLayerForceProtocolChange(Flow *f, AppProto new_proto);
113 
114 /**
115  * \brief Cleans up the app layer protocol detection phase.
116  */
118 
119 /**
120  * \brief Registers a protocol for protocol detection phase.
121  *
122  * This is the first function to be called after calling the
123  * setup function, AppLayerProtoDetectSetup(), before calling any other
124  * app layer functions, AppLayerParser or AppLayerProtoDetect, alike.
125  * With this function you are associating/registering a string
126  * that can be used by users to write rules, i.e.
127  * you register the http protocol for protocol detection using
128  * AppLayerProtoDetectRegisterProtocol(ctx, ALPROTO_HTTP1, "http"),
129  * following which you can write rules like -
130  * alert http any any -> any any (sid:1;)
131  * which basically matches on the HTTP protocol.
132  *
133  * \param alproto The protocol.
134  * \param alproto_str The string to associate with the above "alproto".
135  * Please send a static string that won't be destroyed
136  * post making this call, since this function won't
137  * create a copy of the received argument.
138  *
139  * \retval 0 On success;
140  * -1 On failure.
141  */
142 void AppLayerProtoDetectRegisterProtocol(AppProto alproto, const char *alproto_name);
143 
144 void AppLayerProtoDetectRegisterAlias(const char *proto_name, const char *proto_alias);
145 
146 /**
147  * \brief Given a protocol name, checks if proto detection is enabled in
148  * the conf file.
149  *
150  * \param alproto Name of the app layer protocol.
151  *
152  * \retval 1 If enabled.
153  * \retval 0 If disabled.
154  */
155 int SCAppLayerProtoDetectConfProtoDetectionEnabled(const char *ipproto, const char *alproto);
156 
157 /**
158  * \brief Given a protocol name, checks if proto detection is enabled in
159  * the conf file.
160  *
161  * \param alproto Name of the app layer protocol.
162  * \param default_enabled enable by default if not in the configuration file
163  *
164  * \retval 1 If enabled.
165  * \retval 0 If disabled.
166  */
168  const char *ipproto, const char *alproto, bool default_enabled);
169 
170 /**
171  * \brief Inits and returns an app layer protocol detection thread context.
172 
173  * \param ctx Pointer to the app layer protocol detection context.
174  *
175  * \retval Pointer to the thread context, on success;
176  * NULL, on failure.
177  */
179 
180 /**
181  * \brief Destroys the app layer protocol detection thread context.
182  *
183  * \param tctx Pointer to the app layer protocol detection thread context.
184  */
186 
187 /***** Utility *****/
188 
189 void AppLayerProtoDetectSupportedIpprotos(AppProto alproto, uint8_t *ipprotos);
190 AppProto AppLayerProtoDetectGetProtoByName(const char *alproto_name);
191 const char *AppLayerProtoDetectGetProtoName(AppProto alproto);
193 
194 void AppLayerRegisterExpectationProto(uint8_t proto, AppProto alproto);
195 
196 /***** Unittests *****/
197 
198 #ifdef UNITTESTS
199 
200 /**
201  * \brief Backs up the internal context used by the app layer proto detection
202  * module.
203  */
205 
206 /**
207  * \brief Restores back the internal context used by the app layer proto
208  * detection module, that was previously backed up by calling
209  * AppLayerProtoDetectUnittestCtxBackup().
210  */
212 
213 /**
214  * \brief Register unittests for app layer proto detection module.
215  */
217 
218 #endif /* UNITTESTS */
219 
220 #endif /* SURICATA_APP_LAYER_DETECT_PROTO__H */
SCAppLayerProtoDetectPMRegisterPatternCS
int SCAppLayerProtoDetectPMRegisterPatternCS(uint8_t ipproto, AppProto alproto, const char *pattern, uint16_t depth, uint16_t offset, uint8_t direction)
Registers a case-sensitive pattern for protocol detection.
Definition: app-layer-detect-proto.c:1626
SCAppLayerForceProtocolChange
void SCAppLayerForceProtocolChange(Flow *f, AppProto new_proto)
Forces a flow app-layer protocol change. Happens for instance when a HTTP2 flow is seen as DOH2.
Definition: app-layer-detect-proto.c:1844
offset
uint64_t offset
Definition: util-streaming-buffer.h:0
AppProto
uint16_t AppProto
Definition: app-layer-protos.h:86
AppLayerProtoDetectRegisterProtocol
void AppLayerProtoDetectRegisterProtocol(AppProto alproto, const char *alproto_name)
Registers a protocol for protocol detection phase.
Definition: app-layer-detect-proto.c:1742
Flow_
Flow data structure.
Definition: flow.h:356
AppLayerProtoDetectGetProtoName
const char * AppLayerProtoDetectGetProtoName(AppProto alproto)
Definition: app-layer-detect-proto.c:2071
SCAppLayerProtoDetectPPRegister
void SCAppLayerProtoDetectPPRegister(uint8_t ipproto, const char *portstr, AppProto alproto, uint16_t min_depth, uint16_t max_depth, uint8_t direction, ProbingParserFPtr ProbingParser1, ProbingParserFPtr ProbingParser2)
register parser at a port
Definition: app-layer-detect-proto.c:1527
proto
uint8_t proto
Definition: decode-template.h:0
SCAppLayerProtoDetectConfProtoDetectionEnabledDefault
int SCAppLayerProtoDetectConfProtoDetectionEnabledDefault(const char *ipproto, const char *alproto, bool default_enabled)
Given a protocol name, checks if proto detection is enabled in the conf file.
Definition: app-layer-detect-proto.c:1872
AppLayerProtoDetectSetup
int AppLayerProtoDetectSetup(void)
The first function to be called. This initializes a global protocol detection context.
Definition: app-layer-detect-proto.c:1662
AppLayerProtoDetectDeSetup
int AppLayerProtoDetectDeSetup(void)
Cleans up the app layer protocol detection phase.
Definition: app-layer-detect-proto.c:1703
AppLayerProtoDetectPrepareState
int AppLayerProtoDetectPrepareState(void)
Prepares the internal state for protocol detection. This needs to be called once all the patterns and...
Definition: app-layer-detect-proto.c:1483
AppLayerProtoDetectSupportedAppProtocols
void AppLayerProtoDetectSupportedAppProtocols(AppProto *alprotos)
Definition: app-layer-detect-proto.c:2088
AppLayerProtoDetectGetProtoByName
AppProto AppLayerProtoDetectGetProtoByName(const char *alproto_name)
Definition: app-layer-detect-proto.c:2046
AppLayerProtoDetectThreadCtx_
The app layer protocol detection thread context.
Definition: app-layer-detect-proto.c:179
SCAppLayerRequestProtocolTLSUpgrade
bool SCAppLayerRequestProtocolTLSUpgrade(Flow *f)
request applayer to wrap up this protocol and rerun protocol detection with expectation of TLS....
Definition: app-layer-detect-proto.c:1833
AppLayerProtoDetectGetProto
AppProto AppLayerProtoDetectGetProto(AppLayerProtoDetectThreadCtx *tctx, Flow *f, const uint8_t *buf, uint32_t buflen, uint8_t ipproto, uint8_t flags, bool *reverse_flow)
Returns the app layer protocol given a buffer.
Definition: app-layer-detect-proto.c:1395
AppLayerProtoDetectUnittestsRegister
void AppLayerProtoDetectUnittestsRegister(void)
Register unittests for app layer proto detection module.
Definition: app-layer-detect-proto.c:3515
AppLayerProtoDetectGetCtxThread
AppLayerProtoDetectThreadCtx * AppLayerProtoDetectGetCtxThread(void)
Inits and returns an app layer protocol detection thread context.
Definition: app-layer-detect-proto.c:1947
SCAppLayerProtoDetectPPParseConfPorts
int SCAppLayerProtoDetectPPParseConfPorts(const char *ipproto_name, uint8_t ipproto, const char *alproto_name, AppProto alproto, uint16_t min_depth, uint16_t max_depth, ProbingParserFPtr ProbingParserTs, ProbingParserFPtr ProbingParserTc)
Definition: app-layer-detect-proto.c:1563
SCAppLayerProtoDetectConfProtoDetectionEnabled
int SCAppLayerProtoDetectConfProtoDetectionEnabled(const char *ipproto, const char *alproto)
Given a protocol name, checks if proto detection is enabled in the conf file.
Definition: app-layer-detect-proto.c:1942
AppLayerProtoDetectUnittestCtxRestore
void AppLayerProtoDetectUnittestCtxRestore(void)
Restores back the internal context used by the app layer proto detection module, that was previously ...
Definition: app-layer-detect-proto.c:2145
AppLayerProtoDetectRegisterAlias
void AppLayerProtoDetectRegisterAlias(const char *proto_name, const char *proto_alias)
Definition: app-layer-detect-proto.c:1762
AppLayerProtoDetectSupportedIpprotos
void AppLayerProtoDetectSupportedIpprotos(AppProto alproto, uint8_t *ipprotos)
Definition: app-layer-detect-proto.c:2026
AppLayerRequestProtocolChange
bool AppLayerRequestProtocolChange(Flow *f, uint16_t dp, AppProto expect_proto)
request applayer to wrap up this protocol and rerun protocol detection.
Definition: app-layer-detect-proto.c:1802
flags
uint8_t flags
Definition: decode-gre.h:0
SCAppLayerProtoDetectPMRegisterPatternCSwPP
int SCAppLayerProtoDetectPMRegisterPatternCSwPP(uint8_t ipproto, AppProto alproto, const char *pattern, uint16_t depth, uint16_t offset, uint8_t direction, ProbingParserFPtr PPFunc, uint16_t pp_min_depth, uint16_t pp_max_depth)
Definition: app-layer-detect-proto.c:1637
AppLayerRegisterExpectationProto
void AppLayerRegisterExpectationProto(uint8_t proto, AppProto alproto)
Definition: app-layer-detect-proto.c:2118
AppLayerProtoDetectReset
void AppLayerProtoDetectReset(Flow *)
Reset proto detect for flow.
Definition: app-layer-detect-proto.c:1854
app-layer-protos.h
ProbingParserFPtr
AppProto(* ProbingParserFPtr)(const Flow *f, uint8_t flags, const uint8_t *input, uint32_t input_len, uint8_t *rdir)
Definition: app-layer-detect-proto.h:34
SCAppLayerProtoDetectPMRegisterPatternCI
int SCAppLayerProtoDetectPMRegisterPatternCI(uint8_t ipproto, AppProto alproto, const char *pattern, uint16_t depth, uint16_t offset, uint8_t direction)
Registers a case-insensitive pattern for protocol detection.
Definition: app-layer-detect-proto.c:1649
AppLayerProtoDetectDestroyCtxThread
void AppLayerProtoDetectDestroyCtxThread(AppLayerProtoDetectThreadCtx *tctx)
Destroys the app layer protocol detection thread context.
Definition: app-layer-detect-proto.c:2000
AppLayerProtoDetectUnittestCtxBackup
void AppLayerProtoDetectUnittestCtxBackup(void)
Backs up the internal context used by the app layer proto detection module.
Definition: app-layer-detect-proto.c:2137