suricata
util-decode-mime.h File Reference
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include "suricata.h"
#include "util-base64.h"
#include "util-debug.h"
Include dependency graph for util-decode-mime.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of 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 LINEREM_SIZE   256
 
#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 Decoder Error Codes. More...
 

Functions

void MimeDecSetConfig (MimeDecConfig *config)
 Set global config policy. More...
 
MimeDecConfigMimeDecGetConfig (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...
 
MimeDecFieldMimeDecAddField (MimeDecEntity *entity)
 Creates and adds a header field entry to an entity. More...
 
MimeDecFieldMimeDecFindField (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...
 
MimeDecEntityMimeDecAddEntity (MimeDecEntity *parent)
 Creates and adds a child entity to the specified parent entity. More...
 
MimeDecParseStateMimeDecInitParser (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...
 
MimeDecEntityMimeDecParseFullMsg (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

Macro Definition Documentation

◆ ANOM_INVALID_BASE64

#define ANOM_INVALID_BASE64   1 /* invalid base64 chars */

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

◆ ANOM_INVALID_QP

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

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

◆ ANOM_LONG_BOUNDARY

#define ANOM_LONG_BOUNDARY   128 /* Boundary too long */

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

◆ ANOM_LONG_ENC_LINE

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

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

◆ ANOM_LONG_FILENAME

#define ANOM_LONG_FILENAME   256 /* filename truncated */

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

◆ ANOM_LONG_HEADER_NAME

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

Definition at line 56 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 57 of file util-decode-mime.h.

◆ ANOM_LONG_LINE

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

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

◆ ANOM_MALFORMED_MSG

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

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

◆ BODY_DONE

#define BODY_DONE   0x05

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

◆ BODY_END_BOUND

#define BODY_END_BOUND   0x06

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

◆ BODY_STARTED

#define BODY_STARTED   0x04

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

◆ CTNT_IS_ATTACHMENT

#define CTNT_IS_ATTACHMENT   32

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

◆ CTNT_IS_BASE64

#define CTNT_IS_BASE64   64

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

◆ CTNT_IS_BODYPART

#define CTNT_IS_BODYPART   8

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

◆ CTNT_IS_ENCAP

#define CTNT_IS_ENCAP   4

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

◆ CTNT_IS_ENV

#define CTNT_IS_ENV   2

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

◆ CTNT_IS_HTML

#define CTNT_IS_HTML   512

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

◆ CTNT_IS_MSG

#define CTNT_IS_MSG   1

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

◆ CTNT_IS_MULTIPART

#define CTNT_IS_MULTIPART   16

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

◆ CTNT_IS_QP

#define CTNT_IS_QP   128

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

◆ CTNT_IS_TEXT

#define CTNT_IS_TEXT   256

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

◆ DATA_CHUNK_SIZE

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

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

◆ HEADER_DONE

#define HEADER_DONE   0x03

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

◆ HEADER_READY

#define HEADER_READY   0x01

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

◆ HEADER_STARTED

#define HEADER_STARTED   0x02

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

◆ LINEREM_SIZE

#define LINEREM_SIZE   256

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

◆ PARSE_DONE

#define PARSE_DONE   0x07

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

◆ PARSE_ERROR

#define PARSE_ERROR   0x08

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

◆ URL_IS_EXE

#define URL_IS_EXE   4

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

◆ URL_IS_IP4

#define URL_IS_IP4   1

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

◆ URL_IS_IP6

#define URL_IS_IP6   2

Definition at line 50 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

Structure contains the current state of the MIME parser.

◆ MimeDecRetCode

Mime Decoder Error Codes.

◆ MimeDecStack

typedef struct MimeDecStack MimeDecStack

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

◆ 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

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

Definition at line 81 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
parentThe parent entity
Returns
The child entity, or NULL if the operation fails

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

References MimeDecEntity::child, MimeDecEntity::next, SC_ERR_MEM_ALLOC, SCLogError, 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
entityThe parent entity
Returns
The field object, or NULL if the operation fails

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

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

◆ MimeDecDeInitParser()

void MimeDecDeInitParser ( MimeDecParseState state)

De-Init parser by freeing up any residual memory.

Parameters
stateThe parser state
Returns
none

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

References MimeDecStackNode::data, SCLogDebug, MimeDecParseState::stack, and MimeDecStack::top.

◆ MimeDecFindField()

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

Searches for a header field with the specified name.

Parameters
entityThe entity to search
nameThe header name (lowercase)
Returns
The field object, or NULL if not found

Definition at line 339 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
entityThe entity to search
nameThe header name (lowercase)
Returns
number of items found

Definition at line 311 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
entityThe root entity
Returns
none

Move child to next Transform tree into list

Move to next element

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

◆ MimeDecFreeField()

void MimeDecFreeField ( MimeDecField field)

Iteratively frees a header field entry list.

Parameters
fieldThe header field
Returns
none

Definition at line 221 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
urlThe url entry
Returns
none

Definition at line 250 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 152 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
dataA caller-specified pointer to data for access within the data chunk processor callback function
dcpfuncThe data chunk processor callback function
Returns
A pointer to the state object, or NULL if the operation fails

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

References MimeDecEntity::ctnt_flags, CTNT_IS_MSG, MimeDecParseState::msg, SC_ERR_MEM_ALLOC, SCFree, SCLogError, 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
stateThe parser state
Returns
MIME_DEC_OK on success, otherwise < 0 on failure

Definition at line 2525 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
bufBuffer pointing to the full message
blenLength of the buffer
dataCaller data to be available in callback
dcpfuncCallback for processing each decoded body data chunk
Returns
A pointer to the decoded MIME message, or NULL if the operation fails

Definition at line 2621 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
lineA string representing the line (w/out CRLF)
lenThe length of the line
delim_lenThe length of the line end delimiter
stateThe parser state
Returns
MIME_DEC_OK on success, otherwise < 0 on failure

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

References len, and MIME_DEC_OK.

◆ MimeDecParseStateGetStatus()

const char* MimeDecParseStateGetStatus ( MimeDecParseState state)

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

◆ MimeDecRegisterTests()

void MimeDecRegisterTests ( void  )

Definition at line 3147 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
configConfig policy to set
Returns
none

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