Skip to content

7. TCP API Description

Jump to bottom
Chema García edited this page Jan 11, 2016 · 1 revision

Data structures

Possible connection status:

/** @brief connection status **/
enum _ntoh_tcp_status_
{
	NTOH_STATUS_CLOSED = 0,
	NTOH_STATUS_LISTEN,
	NTOH_STATUS_SYNSENT,
	NTOH_STATUS_SYNRCV,
	NTOH_STATUS_ESTABLISHED,
	NTOH_STATUS_CLOSING,
	NTOH_STATUS_CLOSEWAIT,
	NTOH_STATUS_FINWAIT1,
	NTOH_STATUS_FINWAIT2,
	NTOH_STATUS_LASTACK,
	NTOH_STATUS_TIMEWAIT
};

Constant to identify which hash table to be resized:

/** @brief connection status **/
enum tcprs_resize_table
{
	NTOH_RESIZE_STREAMS = 0,
	NTOH_RESIZE_TIMEWAIT
};

Values to identify which peer has closed the connection:

/** @brief who closed the connection? **/
enum tcprs_who_closed
{
	NTOH_CLOSEDBY_UNKNOWN = 0,
	NTOH_CLOSEDBY_CLIENT,
	NTOH_CLOSEDBY_SERVER
};

Values to identify which peer has sent the segment:

/** @brief who send the segment **/
enum tcprs_who_sent
{
	NTOH_SENT_BY_CLIENT = 0,
	NTOH_SENT_BY_SERVER
};

Check timeouts based on connection status:

/** @brief control switch **/
enum check_timeout
{
	NTOH_CHECK_TCP_SYNSENT_TIMEOUT = (1 << 0),
	NTOH_CHECK_TCP_SYNRCV_TIMEOUT = (1 << 1),
	NTOH_CHECK_TCP_ESTABLISHED_TIMEOUT = (1 << 2),
	NTOH_CHECK_TCP_FINWAIT2_TIMEOUT = (1 << 3),
	NTOH_CHECK_TCP_TIMEWAIT_TIMEOUT = (1 << 4),
};

Structure to idenfity a TCP stream:

/** @brief data to generate the connection key **/
typedef struct
{
	///source address
	unsigned int source[IP6_ADDR_LEN];
	///destination address
	unsigned int destination[IP6_ADDR_LEN];
	///source port
	unsigned short sport;
	///destination port
	unsigned short dport;
	///protocol
	unsigned char  protocol;
} ntoh_tcp_tuple5_t, *pntoh_tcp_tuple5_t;

Structure to store all the information of a segment:

/** @brief data sent to user-function **/
typedef struct _tcp_segment_
{
	struct _tcp_segment_ *next;
	///SEQ number
	unsigned long seq;
	///ACK number
	unsigned long ack;
	///flags
	unsigned char flags;
	///payload length
	unsigned int payload_len;
	///segment origin
	unsigned short origin;
	///TCP timestamp
	struct timeval tv;
	///user provided data
	void *user_data;
} ntoh_tcp_segment_t, *pntoh_tcp_segment_t;

Structure to store all needed information for a peer:

/** @brief peer information **/
typedef struct
{
	///IP address
	unsigned int addr[IP6_ADDR_LEN];
	///connection port
	unsigned short port;
	///first SEQ. number
	unsigned long isn;
	///first ACK. number
	unsigned long ian;
	///NEXT SEQ. number
	unsigned long next_seq;
	///TH_FIN | TH_RST sequence
	unsigned long final_seq;
	///TCP window size
	unsigned int wsize;
	///peer status
	unsigned int status;
	///segments list
	pntoh_tcp_segment_t segments;
	///Max. Segment Size
	unsigned int mss;
	///Selective ACK.
	unsigned int sack;
	///window scale factor
	unsigned int wscale;
	///total window size
	unsigned long totalwin;
	// last ts
	unsigned int lastts;
	// send peer segments to user?
	unsigned short receive;
} ntoh_tcp_peer_t, *pntoh_tcp_peer_t;

Structure to store all the information needed for a TCP stream:

/** @brief connection data **/
typedef struct _tcp_stream_
{
	struct _tcp_stream_ *next;

	///data to generate the key to identify the connection
	ntoh_tcp_tuple5_t tuple;
	///client data
	ntoh_tcp_peer_t client;
	///server data
	ntoh_tcp_peer_t server;
	///connection key
	ntoh_tcp_key_t key;
	///connection status
	unsigned int status;
	///who closed the connection
	unsigned short closedby;
	///user defined function to receive data
	void *function;
	///last activity
	struct timeval last_activ;
	///max. allowed SYN retries
	unsigned int syn_retries;
	///max. allowed SYN/ACK retries
	unsigned int synack_retries;
	void *udata;
	ntoh_lock_t lock;
	/// enable timeout check
	unsigned short enable_check_timeout;
	/// enable TCP Window size check
	unsigned short enable_check_nowindow;
} ntoh_tcp_stream_t, *pntoh_tcp_stream_t;

Structure to store all the needed information of a TCP session:

/** @brief TCP session data **/
typedef struct _tcp_session_
{
	struct _tcp_session_ *next;

	/// max. streams
	sem_t max_streams;
	sem_t max_timewait;

	/// connections hash table
	ptcprs_streams_table_t streams;

	/// TIME-WAIT connections
	ptcprs_streams_table_t timewait;
	int rand;
	ntoh_lock_t lock;
	pthread_t tID;
} ntoh_tcp_session_t , *pntoh_tcp_session_t;

Structure to store the sessions list and the initialization status:

/** @brief TCP Parameters **/
typedef struct
{
	/// is the library initialized?
	unsigned short init;
	/// TCP sessions list
	pntoh_tcp_session_t sessions_list;
	/// global mutex to create and free existing TCP sessions
	ntoh_lock_t lock;
} ntoh_tcp_params_t, *pntoh_tcp_params_t;

Functions

Function to initialize all needed resources for TCP streams reassembly:

void ntoh_tcp_init ( void );

Function to flush all TCP sessions and release all resources:

void ntoh_tcp_exit ( void );

Function to create a new TCP session:

pntoh_tcp_session_t ntoh_tcp_new_session ( unsigned int max_streams , unsigned int max_timewait , unsigned int *error );
  • max_streams: Maximum number of allowed streams in this session
  • max_timewait: Maximum number of streams with TIME-WAIT status in this session
  • *error: Returned error code

This function returns a pointer to the new session, or NULL when it fails (sets the appropiate value to "*error").

Function to flush all TCP streams and release all resources used by a session:

void ntoh_tcp_free_session ( pntoh_tcp_session_t session );
  • session: Session to be released

Function to create a new TCP stream:

pntoh_tcp_stream_t ntoh_tcp_new_stream ( pntoh_tcp_session_t session , pntoh_tcp_tuple5_t tuple5 , pntoh_tcp_callback_t function , void *udata , unsigned int *error, unsigned short enable_check_timeout , unsigned short enable_check_nowindow );
  • session: TCP Session
  • tuple5: Tuple5 identifying the new stream
  • function: User-defined callback function to receive the reassembled segments
  • udata: User-data linked to the new stream
  • *error: Returned error code
  • enable_check_timeout: enables/disables idle time verification for established connections
  • enable_check_nowindow: enables/disables TCP Window verification

This function returns a pointer to the new stream or NULL when it fails (sets the appropiate value to "*error").

Function to find a TCP stream:

pntoh_tcp_stream_t ntoh_tcp_find_stream ( pntoh_tcp_session_t session , pntoh_tcp_tuple5_t tuple5 );
  • session: TCP Session
  • tuple5: Tuple5 structure identifying the session we're looking for

This function returns a pointer to the stream if it was found, or NULL if it wasn't found.

Function to free a TCP stream:

void ntoh_tcp_free_stream ( pntoh_tcp_session_t session , pntoh_tcp_stream_t stream , int reason , int extra );
  • session: TCP Session
  • stream: TCP stream to be released
  • reason: "reason" parameter to be sent to the user-defined callback function
  • extra: "extra" parameter to be sent to the user-defined callback function

This function returns no data.

Function to add a TCP segment to a stream:

int ntoh_tcp_add_segment ( pntoh_tcp_session_t session , pntoh_tcp_stream_t stream , void *ip , size_t len , void *udata );
  • session: TCP Session
  • stream: TCP stream where the new segment will be added
  • ip: IP header
  • len: Total length (IP header + payload)
  • udata: User-defined data to be linked with the new segment

This function returns NTOH_OK on success and an error code when it fails.

Note: It's better not allocate memory for segment that have a zero size payload. (Or free it when this function returns a different value of NTOH_OK).

Function to count the number of stored streams in a session:

unsigned int ntoh_tcp_count_streams ( pntoh_tcp_session_t session );
  • session: TCP Session

This function returns the current number of stored streams.

Function to get the description about the status of a TCP stream:

const char *ntoh_tcp_get_status ( unsigned int status );
  • status: TCP stream status code

This function returns a string indicating the status of the stream.

Function to get the size of the TCP sessions table (max allowed streams):

unsigned int *ntoh_tcp_get_size ( pntoh_tcp_session_t session );
  • session: TCP session

This function returns the size of the TCP sessions table.

Function to get the tuple5 of a segment:

unsigned int ntoh_tcp_get_tuple5 ( void *ip , struct tcphdr *tcp , pntoh_tcp_tuple5_t tuple );
  • ip: IP Header
  • tcp: TCP Header
  • tuple: Pointer to the output tuple5 struct

This function returns NTOH_OK on success and an error code when it fails.

Function to get the tuple5 of a segment:

int ntoh_tcp_resize_session ( pntoh_tcp_session_t session , unsigned short table , size_t size );
  • session: Session to be modified
  • table: Table to be resized: streams/timeout hash table.
  • size: New size

This function returns NTOH_OK on success and an error code when it fails.

Data types

User-defined callback function:

typedef void(*pntoh_tcp_callback_t) ( pntoh_tcp_stream_t stream , pntoh_tcp_peer_t origin, pntoh_tcp_peer_t destination, pntoh_tcp_segment_t segment, int reason, int extra );
  • stream: TCP Stream
  • origin: Sender of this segment
  • destination: Receiver of this segment
  • segment: Reassembled segment
  • reason: Why the segment is sent?
  • extra: Why the datagram is sent? (extra information)

The "reason" parameter can be one of the following values:

  • NTOH_REASON_DATA: We got a new segment
  • NTOH_REASON_SYNC: Not a segment but synchronization

The "extra" parameter can be one of the following values, depending of "reason" parameter:

  • Reason: NTOH_REASON_DATA

    • NTOH_REASON_OOO
    • NTOH_REASON_NOWINDOW
    • NTOH_REASON_EXIT
    • NTOH_REASON_CLOSED
    • NTOH_REASON_TIMEDOUT

  • Reason: NTOH_REASON_SYNC

    • NTOH_REASON_MAX_SYN_RETRIES_REACHED
    • NTOH_REASON_MAX_SYNACK_RETRIES_REACHED
    • NTOH_REASON_HSFAILED
    • NTOH_REASON_EXIT
    • NTOH_REASON_TIMEDOUT
    • NTOH_REASON_CLOSED
    • NTOH_REASON_ESTABLISHED
    • NTOH_REASON_SYNC

Clone this wiki locally