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)

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():

data = (char *)FlowGetStorageById(f, AppLayerExpectationGetFlowId());

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 72 of file app-layer-expectation.c.

◆ EXPECTATION_TIMEOUT

#define EXPECTATION_TIMEOUT 30

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

Typedef Documentation

◆ Expectation

typedef struct Expectation_ Expectation

◆ ExpectationData

typedef struct ExpectationData_ ExpectationData

◆ ExpectationList

typedef struct ExpectationList_ 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.

Parameters

f	a pointer to the original Flow
direction	the direction of the data in the expectation flow
src	source port of the expected flow, use 0 for any
dst	destination port of the expected flow, use 0 for any
alproto	the protocol that need to be set on the expected flow
data	pointer to data that will be attached to the expected flow

Returns: -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

Returns: 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.

Returns: an AppProto value if found; ALPROTO_UNKNOWN if not found

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

References ALPROTO_UNKNOWN, and SC_ATOMIC_GET.

◆ 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.