Application Layer Expectation

Handling of dynamic parallel connection for application layer similar to FTP. More...


file  app-layer-expectation.c

Data Structures

struct  Expectation_
struct  ExpectationData_
struct  ExpectationList_




typedef struct Expectation_ Expectation
typedef struct ExpectationData_ ExpectationData
typedef struct ExpectationList_ ExpectationList


 SC_ATOMIC_DECLARE (uint32_t, expectation_count)
uint64_t ExpectationGetCounter (void)
void AppLayerExpectationSetup (void)
int AppLayerExpectationCreate (Flow *f, int direction, Port src, Port dst, AppProto alproto, void *data)
FlowStorageId AppLayerExpectationGetFlowId (void)
AppProto AppLayerExpectationHandle (Flow *f, uint8_t flags)
void AppLayerExpectationClean (Flow *f)

Detailed Description

Handling of dynamic parallel connection for application layer similar to FTP.

Some protocols like FTP create dynamic parallel flow (called expectation). In order to assign a application layer protocol to these expectation, Suricata needs to parse message of the initial protocol and create and maintain a list of expected flow.

Application layers must use the here described API to implement this mechanism.

When parsing a application layer message describing a parallel flow, the application layer can call AppLayerExpectationCreate() to declare an expectation. By doing that the next flow coming with corresponding IP parameters will be assigned the specified application layer. The resulting Flow will also have a Flow storage set that can be retrieved at index AppLayerExpectationGetDataId():

This storage can be used to store information that are only available in the parent connection and could be useful in the parent connection. For instance this is used by the FTP protocol to propagate information such as file name and ftp operation to the FTP data connection.

Macro Definition Documentation



Definition at line 72 of file app-layer-expectation.c.



Definition at line 71 of file app-layer-expectation.c.

Typedef Documentation

◆ Expectation

typedef struct Expectation_ Expectation

◆ ExpectationData

◆ ExpectationList

Function Documentation

◆ AppLayerExpectationClean()

void AppLayerExpectationClean ( Flow f)

Definition at line 361 of file app-layer-expectation.c.

References SC_ATOMIC_GET.

Referenced by FlowClearMemory().

Here is the caller graph for this function:

◆ AppLayerExpectationCreate()

int AppLayerExpectationCreate ( Flow f,
int  direction,
Port  src,
Port  dst,
AppProto  alproto,
void *  data 

Create an entry in expectation list

Create a expectation from an existing Flow. Currently, only Flow between the two original IP addresses are supported. In case of success, the ownership of the data pointer is taken. In case of error, the pointer to data has to be freed by the caller.

fa pointer to the original Flow
directionthe direction of the data in the expectation flow
srcsource port of the expected flow, use 0 for any
dstdestination port of the expected flow, use 0 for any
alprotothe protocol that need to be set on the expected flow
datapointer to data that will be attached to the expected flow
-1 if error
0 if success

Definition at line 219 of file app-layer-expectation.c.

References Expectation_::alproto, Expectation_::data, Expectation_::direction, Expectation_::dp, dst, Flow_::lastts, Expectation_::orig_f, SCCalloc, Expectation_::sp, src, and Expectation_::ts.

◆ AppLayerExpectationGetFlowId()

FlowStorageId AppLayerExpectationGetFlowId ( void  )

Return Flow storage identifier corresponding to expectation data

expectation data identifier

Definition at line 288 of file app-layer-expectation.c.

◆ AppLayerExpectationHandle()

AppProto AppLayerExpectationHandle ( Flow f,
uint8_t  flags 

Function doing a lookup in expectation list and updating Flow if needed.

This function lookup for a existing expectation that could match the Flow. If found and if the expectation contains data it store the data in the expectation storage of the Flow.

an AppProto value if found
ALPROTO_UNKNOWN if not found

Definition at line 303 of file app-layer-expectation.c.


◆ AppLayerExpectationSetup()

void AppLayerExpectationSetup ( void  )

Definition at line 146 of file app-layer-expectation.c.

◆ ExpectationGetCounter()

uint64_t ExpectationGetCounter ( void  )

Definition at line 140 of file app-layer-expectation.c.

References SC_ATOMIC_GET.

Referenced by AppLayerRegisterGlobalCounters().

Here is the caller graph for this function:


SC_ATOMIC_DECLARE ( uint32_t  ,
FlowStorageId AppLayerExpectationGetFlowId(void)
Definition: app-layer-expectation.c:288
void * FlowGetStorageById(const Flow *f, FlowStorageId id)
Definition: flow-storage.c:40