#include "conf.h"
#include "util-base64.h"
#include "util-file.h"

Include dependency graph for util-decode-mime.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	MimeDecConfig
	Structure for containing configuration options. More...

struct	MimeDecField
	This represents a header field name and associated value. More...

struct	MimeDecUrl
	This represents a URL value node in a linked list. More...

struct	MimeDecEntity
	This represents the MIME Entity (or also top level message) in a child-sibling tree. More...

struct	MimeDecStackNode
	Structure contains boundary and entity for the current node (entity) in the stack. More...

struct	MimeDecStack
	Structure holds the top of the stack along with some free reusable nodes. More...

struct	DataValue
	Structure contains a list of value and lengths for robust data processing. More...

struct	MimeDecParseState
	Structure contains the current state of the MIME parser. More...

Macros
#define	CTNT_IS_MSG 1

#define	CTNT_IS_ENV 2

#define	CTNT_IS_ENCAP 4

#define	CTNT_IS_BODYPART 8

#define	CTNT_IS_MULTIPART 16

#define	CTNT_IS_ATTACHMENT 32

#define	CTNT_IS_BASE64 64

#define	CTNT_IS_QP 128

#define	CTNT_IS_TEXT 256

#define	CTNT_IS_HTML 512

#define	URL_IS_IP4 1

#define	URL_IS_IP6 2

#define	URL_IS_EXE 4

#define	ANOM_INVALID_BASE64 1 /* invalid base64 chars */

#define	ANOM_INVALID_QP 2 /* invalid quoted-printable chars */

#define	ANOM_LONG_HEADER_NAME 4 /* header is abnormally long */

#define	ANOM_LONG_HEADER_VALUE

#define	ANOM_LONG_LINE 16 /* Lines that exceed 998 octets */

#define	ANOM_LONG_ENC_LINE 32 /* Lines that exceed 76 octets */

#define	ANOM_MALFORMED_MSG 64 /* Misc msg format errors found */

#define	ANOM_LONG_BOUNDARY 128 /* Boundary too long */

#define	ANOM_LONG_FILENAME 256 /* filename truncated */

#define	DATA_CHUNK_SIZE 3072 /* Should be divisible by 3 */

#define	HEADER_READY 0x01

#define	HEADER_STARTED 0x02

#define	HEADER_DONE 0x03

#define	BODY_STARTED 0x04

#define	BODY_DONE 0x05

#define	BODY_END_BOUND 0x06

#define	PARSE_DONE 0x07

#define	PARSE_ERROR 0x08

Typedefs
typedef enum MimeDecRetCode	MimeDecRetCode
	Mime Decoder Error Codes. More...

typedef struct MimeDecConfig	MimeDecConfig
	Structure for containing configuration options. More...

typedef struct MimeDecField	MimeDecField
	This represents a header field name and associated value. More...

typedef struct MimeDecUrl	MimeDecUrl
	This represents a URL value node in a linked list. More...

typedef struct MimeDecEntity	MimeDecEntity
	This represents the MIME Entity (or also top level message) in a child-sibling tree. More...

typedef struct MimeDecStackNode	MimeDecStackNode
	Structure contains boundary and entity for the current node (entity) in the stack. More...

typedef struct MimeDecStack	MimeDecStack
	Structure holds the top of the stack along with some free reusable nodes. More...

typedef struct DataValue	DataValue
	Structure contains a list of value and lengths for robust data processing. More...

typedef struct MimeDecParseState	MimeDecParseState
	Structure contains the current state of the MIME parser. More...

Enumerations
enum	MimeDecRetCode { MIME_DEC_OK = 0, MIME_DEC_MORE = 1, MIME_DEC_ERR_DATA = -1, MIME_DEC_ERR_MEM = -2, MIME_DEC_ERR_PARSE = -3, MIME_DEC_ERR_STATE = -4, MIME_DEC_ERR_OVERFLOW = -5 }
	Mime Decoder Error Codes. More...

Functions
void	MimeDecSetConfig (MimeDecConfig *config)
	Set global config policy. More...

MimeDecConfig *	MimeDecGetConfig (void)
	Get global config policy. More...

void	MimeDecFreeEntity (MimeDecEntity *entity)
	Frees a mime entity tree. More...

void	MimeDecFreeField (MimeDecField *field)
	Iteratively frees a header field entry list. More...

void	MimeDecFreeUrl (MimeDecUrl *url)
	Iteratively frees a URL entry list. More...

MimeDecField *	MimeDecAddField (MimeDecEntity *entity)
	Creates and adds a header field entry to an entity. More...

MimeDecField *	MimeDecFindField (const MimeDecEntity entity, const char name)
	Searches for a header field with the specified name. More...

int	MimeDecFindFieldsForEach (const MimeDecEntity entity, const char name, int(DataCallback)(const uint8_t val, const size_t, void data), void data)
	Searches for header fields with the specified name. More...

MimeDecEntity *	MimeDecAddEntity (MimeDecEntity *parent)
	Creates and adds a child entity to the specified parent entity. More...

MimeDecParseState *	MimeDecInitParser (void data, int(dcpfunc)(const uint8_t chunk, uint32_t len, MimeDecParseState state))
	Init the parser by allocating memory for the state and top-level entity. More...

void	MimeDecDeInitParser (MimeDecParseState *state)
	De-Init parser by freeing up any residual memory. More...

int	MimeDecParseComplete (MimeDecParseState *state)
	Called to indicate that the last message line has been processed and the parsing operation is complete. More...

int	MimeDecParseLine (const uint8_t line, const uint32_t len, const uint8_t delim_len, MimeDecParseState state)
	Parse a line of a MIME message and update the parser state. More...

MimeDecEntity *	MimeDecParseFullMsg (const uint8_t buf, uint32_t blen, void data, int(DataChunkProcessorFunc)(const uint8_t chunk, uint32_t len, MimeDecParseState *state))
	Parses an entire message when available in its entirety (wraps the line-based parsing functions) More...

const char *	MimeDecParseStateGetStatus (MimeDecParseState *state)

void	MimeDecRegisterTests (void)

Detailed Description

Author: David Abarbanel david.nosp@m..aba.nosp@m.rbane.nosp@m.l@ba.nosp@m.esyst.nosp@m.ems..nosp@m.com

Definition in file util-decode-mime.h.

Macro Definition Documentation

◆ ANOM_INVALID_BASE64

#define ANOM_INVALID_BASE64 1 /* invalid base64 chars */

Definition at line 52 of file util-decode-mime.h.

◆ ANOM_INVALID_QP

#define ANOM_INVALID_QP 2 /* invalid quoted-printable chars */

Definition at line 53 of file util-decode-mime.h.

◆ ANOM_LONG_BOUNDARY

#define ANOM_LONG_BOUNDARY 128 /* Boundary too long */

Definition at line 59 of file util-decode-mime.h.

◆ ANOM_LONG_ENC_LINE

#define ANOM_LONG_ENC_LINE 32 /* Lines that exceed 76 octets */

Definition at line 57 of file util-decode-mime.h.

◆ ANOM_LONG_FILENAME

#define ANOM_LONG_FILENAME 256 /* filename truncated */

Definition at line 60 of file util-decode-mime.h.

◆ ANOM_LONG_HEADER_NAME

#define ANOM_LONG_HEADER_NAME 4 /* header is abnormally long */

Definition at line 54 of file util-decode-mime.h.

◆ ANOM_LONG_HEADER_VALUE

#define ANOM_LONG_HEADER_VALUE

Value:

8 /* header value is abnormally long

* (includes multi-line) */

Definition at line 55 of file util-decode-mime.h.

◆ ANOM_LONG_LINE

#define ANOM_LONG_LINE 16 /* Lines that exceed 998 octets */

Definition at line 56 of file util-decode-mime.h.

◆ ANOM_MALFORMED_MSG

#define ANOM_MALFORMED_MSG 64 /* Misc msg format errors found */

Definition at line 58 of file util-decode-mime.h.

◆ BODY_DONE

#define BODY_DONE 0x05

Definition at line 70 of file util-decode-mime.h.

◆ BODY_END_BOUND

#define BODY_END_BOUND 0x06

Definition at line 71 of file util-decode-mime.h.

◆ BODY_STARTED

#define BODY_STARTED 0x04

Definition at line 69 of file util-decode-mime.h.

◆ CTNT_IS_ATTACHMENT

#define CTNT_IS_ATTACHMENT 32

Definition at line 40 of file util-decode-mime.h.

◆ CTNT_IS_BASE64

#define CTNT_IS_BASE64 64

Definition at line 41 of file util-decode-mime.h.

◆ CTNT_IS_BODYPART

#define CTNT_IS_BODYPART 8

Definition at line 38 of file util-decode-mime.h.

◆ CTNT_IS_ENCAP

#define CTNT_IS_ENCAP 4

Definition at line 37 of file util-decode-mime.h.

◆ CTNT_IS_ENV

#define CTNT_IS_ENV 2

Definition at line 36 of file util-decode-mime.h.

◆ CTNT_IS_HTML

#define CTNT_IS_HTML 512

Definition at line 44 of file util-decode-mime.h.

◆ CTNT_IS_MSG

#define CTNT_IS_MSG 1

Definition at line 35 of file util-decode-mime.h.

◆ CTNT_IS_MULTIPART

#define CTNT_IS_MULTIPART 16

Definition at line 39 of file util-decode-mime.h.

◆ CTNT_IS_QP

#define CTNT_IS_QP 128

Definition at line 42 of file util-decode-mime.h.

◆ CTNT_IS_TEXT

#define CTNT_IS_TEXT 256

Definition at line 43 of file util-decode-mime.h.

◆ DATA_CHUNK_SIZE

#define DATA_CHUNK_SIZE 3072 /* Should be divisible by 3 */

Definition at line 63 of file util-decode-mime.h.

◆ HEADER_DONE

#define HEADER_DONE 0x03

Definition at line 68 of file util-decode-mime.h.

◆ HEADER_READY

#define HEADER_READY 0x01

Definition at line 66 of file util-decode-mime.h.

◆ HEADER_STARTED

#define HEADER_STARTED 0x02

Definition at line 67 of file util-decode-mime.h.

◆ PARSE_DONE

#define PARSE_DONE 0x07

Definition at line 72 of file util-decode-mime.h.

◆ PARSE_ERROR

#define PARSE_ERROR 0x08

Definition at line 73 of file util-decode-mime.h.

◆ URL_IS_EXE

#define URL_IS_EXE 4

Definition at line 49 of file util-decode-mime.h.

◆ URL_IS_IP4

#define URL_IS_IP4 1

Definition at line 47 of file util-decode-mime.h.

◆ URL_IS_IP6

#define URL_IS_IP6 2

Definition at line 48 of file util-decode-mime.h.

Typedef Documentation

◆ DataValue

typedef struct DataValue DataValue

Structure contains a list of value and lengths for robust data processing.

◆ MimeDecConfig

typedef struct MimeDecConfig MimeDecConfig

Structure for containing configuration options.

◆ MimeDecEntity

typedef struct MimeDecEntity MimeDecEntity

This represents the MIME Entity (or also top level message) in a child-sibling tree.

◆ MimeDecField

typedef struct MimeDecField MimeDecField

This represents a header field name and associated value.

◆ MimeDecParseState

typedef struct MimeDecParseState MimeDecParseState

Structure contains the current state of the MIME parser.

◆ MimeDecRetCode

typedef enum MimeDecRetCode MimeDecRetCode

Mime Decoder Error Codes.

◆ MimeDecStack

typedef struct MimeDecStack MimeDecStack

Structure holds the top of the stack along with some free reusable nodes.

◆ MimeDecStackNode

typedef struct MimeDecStackNode MimeDecStackNode

Structure contains boundary and entity for the current node (entity) in the stack.

◆ MimeDecUrl

typedef struct MimeDecUrl MimeDecUrl

This represents a URL value node in a linked list.

Since HTML can sometimes contain a high number of URLs, this structure only features the URL host name/IP or those that are pointing to an executable file (see url_flags to determine which).

Enumeration Type Documentation

◆ MimeDecRetCode

enum MimeDecRetCode

Mime Decoder Error Codes.

Enumerator
MIME_DEC_OK
MIME_DEC_MORE
MIME_DEC_ERR_DATA
MIME_DEC_ERR_MEM
MIME_DEC_ERR_PARSE
MIME_DEC_ERR_STATE	parser in error state
MIME_DEC_ERR_OVERFLOW

Definition at line 77 of file util-decode-mime.h.

Function Documentation

◆ MimeDecAddEntity()

MimeDecEntity* MimeDecAddEntity ( MimeDecEntity * parent )

Creates and adds a child entity to the specified parent entity.

Parameters

parent The parent entity

Returns: The child entity, or NULL if the operation fails

Definition at line 385 of file util-decode-mime.c.

References MimeDecEntity::child, MimeDecEntity::next, SCMalloc, and unlikely.

◆ MimeDecAddField()

MimeDecField* MimeDecAddField ( MimeDecEntity * entity )

Creates and adds a header field entry to an entity.

The entity is optional. If NULL is specified, than a new stand-alone field is created.

Parameters

entity The parent entity

Returns: The field object, or NULL if the operation fails

Definition at line 267 of file util-decode-mime.c.

References MimeDecEntity::field_list, MimeDecField::next, SCMalloc, and unlikely.

◆ MimeDecDeInitParser()

void MimeDecDeInitParser ( MimeDecParseState * state )

De-Init parser by freeing up any residual memory.

Parameters

state The parser state

Returns: none

Definition at line 2462 of file util-decode-mime.c.

◆ MimeDecFindField()

MimeDecField* MimeDecFindField	(	const MimeDecEntity *	entity,
		const char *	name
	)

Searches for a header field with the specified name.

Parameters

entity	The entity to search
name	The header name (lowercase)

Returns: The field object, or NULL if not found

Definition at line 326 of file util-decode-mime.c.

References MimeDecEntity::field_list, MimeDecField::name, MimeDecField::name_len, MimeDecField::next, and SCMemcmp.

◆ MimeDecFindFieldsForEach()

int MimeDecFindFieldsForEach	(	const MimeDecEntity *	entity,
		const char *	name,
		int()(const uint8_t val, const size_t, void *data)	DataCallback,
		void *	data
	)

Searches for header fields with the specified name.

Parameters

entity	The entity to search
name	The header name (lowercase)

Returns: number of items found

Definition at line 298 of file util-decode-mime.c.

References MimeDecEntity::field_list, MimeDecField::name, MimeDecField::name_len, MimeDecField::next, SCMemcmp, MimeDecField::value, and MimeDecField::value_len.

◆ MimeDecFreeEntity()

void MimeDecFreeEntity ( MimeDecEntity * entity )

Frees a mime entity tree.

Parameters

entity The root entity

Returns: none

Definition at line 176 of file util-decode-mime.c.

◆ MimeDecFreeField()

void MimeDecFreeField ( MimeDecField * field )

Iteratively frees a header field entry list.

Parameters

field The header field

Returns: none

Definition at line 209 of file util-decode-mime.c.

References MimeDecField::name, MimeDecField::next, SCFree, and MimeDecField::value.

◆ MimeDecFreeUrl()

void MimeDecFreeUrl ( MimeDecUrl * url )

Iteratively frees a URL entry list.

Parameters

url	The url entry

Returns: none

Definition at line 238 of file util-decode-mime.c.

References MimeDecUrl::next, SCFree, and MimeDecUrl::url.

◆ MimeDecGetConfig()

MimeDecConfig* MimeDecGetConfig ( void )

Get global config policy.

Returns: config data structure

Definition at line 146 of file util-decode-mime.c.

◆ MimeDecInitParser()

MimeDecParseState* MimeDecInitParser	(	void *	data,
		int()(const uint8_t chunk, uint32_t len, MimeDecParseState *state)	DataChunkProcessorFunc
	)

Init the parser by allocating memory for the state and top-level entity.

Parameters

data	A caller-specified pointer to data for access within the data chunk processor callback function
dcpfunc	The data chunk processor callback function

Returns: A pointer to the state object, or NULL if the operation fails

Definition at line 2410 of file util-decode-mime.c.

References MimeDecEntity::ctnt_flags, CTNT_IS_MSG, MimeDecParseState::msg, SCFree, SCMalloc, MimeDecParseState::stack, and unlikely.

Referenced by MimeDecParseFullMsg().

Here is the caller graph for this function:

◆ MimeDecParseComplete()

int MimeDecParseComplete ( MimeDecParseState * state )

Called to indicate that the last message line has been processed and the parsing operation is complete.

This function should be called directly by the caller.

Parameters

state The parser state

Returns: MIME_DEC_OK on success, otherwise < 0 on failure

Definition at line 2498 of file util-decode-mime.c.

References MIME_DEC_ERR_STATE, MIME_DEC_OK, PARSE_ERROR, SCLogDebug, and MimeDecParseState::state_flag.

◆ MimeDecParseFullMsg()

MimeDecEntity* MimeDecParseFullMsg	(	const uint8_t *	buf,
		uint32_t	blen,
		void *	data,
		int()(const uint8_t chunk, uint32_t len, MimeDecParseState *state)	dcpfunc
	)

Parses an entire message when available in its entirety (wraps the line-based parsing functions)

Parameters

buf	Buffer pointing to the full message
blen	Length of the buffer
data	Caller data to be available in callback
dcpfunc	Callback for processing each decoded body data chunk

Returns: A pointer to the decoded MIME message, or NULL if the operation fails

Definition at line 2600 of file util-decode-mime.c.

References MIME_DEC_OK, MimeDecInitParser(), MimeDecParseState::msg, msg, and SCLogDebug.

Here is the call graph for this function:

◆ MimeDecParseLine()

int MimeDecParseLine	(	const uint8_t *	line,
		const uint32_t	len,
		const uint8_t	delim_len,
		MimeDecParseState *	state
	)

Parse a line of a MIME message and update the parser state.

Parameters

line	A string representing the line (w/out CRLF)
len	The length of the line
delim_len	The length of the line end delimiter
state	The parser state

Returns: MIME_DEC_OK on success, otherwise < 0 on failure

Definition at line 2566 of file util-decode-mime.c.

References len, and MIME_DEC_OK.

◆ MimeDecParseStateGetStatus()

const char* MimeDecParseStateGetStatus ( MimeDecParseState * state )

Definition at line 2325 of file util-decode-mime.c.

◆ MimeDecRegisterTests()

void MimeDecRegisterTests ( void )

Definition at line 3570 of file util-decode-mime.c.

References UtRegisterTest().

Here is the call graph for this function:

◆ MimeDecSetConfig()

void MimeDecSetConfig ( MimeDecConfig * config )

Set global config policy.

Parameters

config Config policy to set

Returns: none

Definition at line 127 of file util-decode-mime.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ANOM_INVALID_BASE64

◆ ANOM_INVALID_QP

◆ ANOM_LONG_BOUNDARY

◆ ANOM_LONG_ENC_LINE

◆ ANOM_LONG_FILENAME

◆ ANOM_LONG_HEADER_NAME

◆ ANOM_LONG_HEADER_VALUE

◆ ANOM_LONG_LINE

◆ ANOM_MALFORMED_MSG

◆ BODY_DONE

◆ BODY_END_BOUND

◆ BODY_STARTED

◆ CTNT_IS_ATTACHMENT

◆ CTNT_IS_BASE64

◆ CTNT_IS_BODYPART

◆ CTNT_IS_ENCAP

◆ CTNT_IS_ENV

◆ CTNT_IS_HTML

◆ CTNT_IS_MSG

◆ CTNT_IS_MULTIPART

◆ CTNT_IS_QP

◆ CTNT_IS_TEXT

◆ DATA_CHUNK_SIZE

◆ HEADER_DONE

◆ HEADER_READY

◆ HEADER_STARTED

◆ PARSE_DONE

◆ PARSE_ERROR

◆ URL_IS_EXE

◆ URL_IS_IP4

◆ URL_IS_IP6

Typedef Documentation

◆ DataValue

◆ MimeDecConfig

◆ MimeDecEntity

◆ MimeDecField

◆ MimeDecParseState

◆ MimeDecRetCode

◆ MimeDecStack

◆ MimeDecStackNode

◆ MimeDecUrl

Enumeration Type Documentation

◆ MimeDecRetCode

Function Documentation

◆ MimeDecAddEntity()

◆ MimeDecAddField()

◆ MimeDecDeInitParser()

◆ MimeDecFindField()

◆ MimeDecFindFieldsForEach()

◆ MimeDecFreeEntity()

◆ MimeDecFreeField()

◆ MimeDecFreeUrl()

◆ MimeDecGetConfig()

◆ MimeDecInitParser()

◆ MimeDecParseComplete()

◆ MimeDecParseFullMsg()

◆ MimeDecParseLine()

◆ MimeDecParseStateGetStatus()

◆ MimeDecRegisterTests()

◆ MimeDecSetConfig()