suricata
Application Layer Expectation

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

Files

file  app-layer-expectation.c
 

Data Structures

struct  Expectation_
 
struct  ExpectationData_
 
struct  ExpectationList_
 

Macros

#define EXPECTATION_TIMEOUT   30
 
#define EXPECTATION_MAX_LEVEL   10
 

Typedefs

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

Functions

 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)
 
int AppLayerExpectationGetDataId (void)
 
AppProto AppLayerExpectationHandle (Flow *f, int direction)
 
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

◆ EXPECTATION_MAX_LEVEL

#define EXPECTATION_MAX_LEVEL   10

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

◆ EXPECTATION_TIMEOUT

#define EXPECTATION_TIMEOUT   30

Definition at line 72 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 359 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.

Parameters
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
Returns
-1 if error
0 if success

Definition at line 218 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.

◆ AppLayerExpectationGetDataId()

int AppLayerExpectationGetDataId ( void  )

Return Flow storage identifier corresponding to expectation data

Returns
expectation data identifier

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

◆ AppLayerExpectationHandle()

AppProto AppLayerExpectationHandle ( Flow f,
int  direction 
)

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.

Returns
an AppProto value if found
ALPROTO_UNKNOWN if not found

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

References ALPROTO_UNKNOWN, and SC_ATOMIC_GET.

◆ AppLayerExpectationSetup()

void AppLayerExpectationSetup ( void  )

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

◆ ExpectationGetCounter()

uint64_t ExpectationGetCounter ( void  )

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

References SC_ATOMIC_GET.

Referenced by AppLayerRegisterGlobalCounters().

Here is the caller graph for this function:

◆ SC_ATOMIC_DECLARE()

SC_ATOMIC_DECLARE ( uint32_t  ,
expectation_count   
)
AppLayerExpectationGetDataId
int AppLayerExpectationGetDataId(void)
Definition: app-layer-expectation.c:287
FlowGetStorageById
void * FlowGetStorageById(Flow *f, int id)
Definition: flow-storage.c:39