Current File : //backups/router/usr/local/include/htp/htp_multipart.h
/***************************************************************************
* Copyright (c) 2009-2010 Open Information Security Foundation
* Copyright (c) 2010-2013 Qualys, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* - Neither the name of the Qualys, Inc. nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
***************************************************************************/
/**
* @file
* @author Ivan Ristic <ivanr@webkreator.com>
*/
#ifndef _HTP_MULTIPART_H
#define _HTP_MULTIPART_H
#ifdef __cplusplus
extern "C" {
#endif
#include "bstr.h"
#include "htp.h"
#include "htp_table.h"
// Constants and enums.
/**
* Seen a LF line in the payload. LF lines are not allowed, but
* some clients do use them and some backends do accept them. Mixing
* LF and CRLF lines within some payload might be unusual.
*/
#define HTP_MULTIPART_LF_LINE 0x0001
/** Seen a CRLF line in the payload. This is normal and expected. */
#define HTP_MULTIPART_CRLF_LINE 0x0002
/** Seen LWS after a boundary instance in the body. Unusual. */
#define HTP_MULTIPART_BBOUNDARY_LWS_AFTER 0x0004
/** Seen non-LWS content after a boundary instance in the body. Highly unusual. */
#define HTP_MULTIPART_BBOUNDARY_NLWS_AFTER 0x0008
/**
* Payload has a preamble part. Might not be that unusual.
*/
#define HTP_MULTIPART_HAS_PREAMBLE 0x0010
/**
* Payload has an epilogue part. Unusual.
*/
#define HTP_MULTIPART_HAS_EPILOGUE 0x0020
/**
* The last boundary was seen in the payload. Absence of the last boundary
* may not break parsing with some (most?) backends, but it means that the payload
* is not well formed. Can occur if the client gives up, or if the connection is
* interrupted. Incomplete payloads should be blocked whenever possible.
*/
#define HTP_MULTIPART_SEEN_LAST_BOUNDARY 0x0040
/**
* There was a part after the last boundary. This is highly irregular
* and indicative of evasion.
*/
#define HTP_MULTIPART_PART_AFTER_LAST_BOUNDARY 0x0080
/**
* The payloads ends abruptly, without proper termination. Can occur if the client gives up,
* or if the connection is interrupted. When this flag is raised, HTP_MULTIPART_PART_INCOMPLETE
* will also be raised for the part that was only partially processed. (But the opposite may not
* always be the case -- there are other ways in which a part can be left incomplete.)
*/
#define HTP_MULTIPART_INCOMPLETE 0x0100
/** The boundary in the Content-Type header is invalid. */
#define HTP_MULTIPART_HBOUNDARY_INVALID 0x0200
/**
* The boundary in the Content-Type header is unusual. This may mean that evasion
* is attempted, but it could also mean that we have encountered a client that does
* not do things in the way it should.
*/
#define HTP_MULTIPART_HBOUNDARY_UNUSUAL 0x0400
/**
* The boundary in the Content-Type header is quoted. This is very unusual,
* and may be indicative of an evasion attempt.
*/
#define HTP_MULTIPART_HBOUNDARY_QUOTED 0x0800
/** Header folding was used in part headers. Very unusual. */
#define HTP_MULTIPART_PART_HEADER_FOLDING 0x1000
/**
* A part of unknown type was encountered, which probably means that the part is lacking
* a Content-Disposition header, or that the header is invalid. Highly unusual.
*/
#define HTP_MULTIPART_PART_UNKNOWN 0x2000
/** There was a repeated part header, possibly in an attempt to confuse the parser. Very unusual. */
#define HTP_MULTIPART_PART_HEADER_REPEATED 0x4000
/** Unknown part header encountered. */
#define HTP_MULTIPART_PART_HEADER_UNKNOWN 0x8000
/** Invalid part header encountered. */
#define HTP_MULTIPART_PART_HEADER_INVALID 0x10000
/** Part type specified in the C-D header is neither MULTIPART_PART_TEXT nor MULTIPART_PART_FILE. */
#define HTP_MULTIPART_CD_TYPE_INVALID 0x20000
/** Content-Disposition part header with multiple parameters with the same name. */
#define HTP_MULTIPART_CD_PARAM_REPEATED 0x40000
/** Unknown Content-Disposition parameter. */
#define HTP_MULTIPART_CD_PARAM_UNKNOWN 0x80000
/** Invalid Content-Disposition syntax. */
#define HTP_MULTIPART_CD_SYNTAX_INVALID 0x100000
/**
* There is an abruptly terminated part. This can happen when the payload itself is abruptly
* terminated (in which case HTP_MULTIPART_INCOMPLETE) will be raised. However, it can also
* happen when a boundary is seen before any part data.
*/
#define HTP_MULTIPART_PART_INCOMPLETE 0x200000
/** A NUL byte was seen in a part header area. */
#define HTP_MULTIPART_NUL_BYTE 0x400000
/** A collection of flags that all indicate an invalid C-D header. */
#define HTP_MULTIPART_CD_INVALID ( \
HTP_MULTIPART_CD_TYPE_INVALID | \
HTP_MULTIPART_CD_PARAM_REPEATED | \
HTP_MULTIPART_CD_PARAM_UNKNOWN | \
HTP_MULTIPART_CD_SYNTAX_INVALID )
/** A collection of flags that all indicate an invalid part. */
#define HTP_MULTIPART_PART_INVALID ( \
HTP_MULTIPART_CD_INVALID | \
HTP_MULTIPART_NUL_BYTE | \
HTP_MULTIPART_PART_UNKNOWN | \
HTP_MULTIPART_PART_HEADER_REPEATED | \
HTP_MULTIPART_PART_INCOMPLETE | \
HTP_MULTIPART_PART_HEADER_UNKNOWN | \
HTP_MULTIPART_PART_HEADER_INVALID )
/** A collection of flags that all indicate an invalid Multipart payload. */
#define HTP_MULTIPART_INVALID ( \
HTP_MULTIPART_PART_INVALID | \
HTP_MULTIPART_PART_AFTER_LAST_BOUNDARY | \
HTP_MULTIPART_INCOMPLETE | \
HTP_MULTIPART_HBOUNDARY_INVALID )
/** A collection of flags that all indicate an unusual Multipart payload. */
#define HTP_MULTIPART_UNUSUAL ( \
HTP_MULTIPART_INVALID | \
HTP_MULTIPART_PART_HEADER_FOLDING | \
HTP_MULTIPART_BBOUNDARY_NLWS_AFTER | \
HTP_MULTIPART_HAS_EPILOGUE | \
HTP_MULTIPART_HBOUNDARY_UNUSUAL \
HTP_MULTIPART_HBOUNDARY_QUOTED )
/** A collection of flags that all indicate an unusual Multipart payload, with a low sensitivity to irregularities. */
#define HTP_MULTIPART_UNUSUAL_PARANOID ( \
HTP_MULTIPART_UNUSUAL | \
HTP_MULTIPART_LF_LINE | \
HTP_MULTIPART_BBOUNDARY_LWS_AFTER | \
HTP_MULTIPART_HAS_PREAMBLE )
#define HTP_MULTIPART_MIME_TYPE "multipart/form-data"
enum htp_multipart_type_t {
/** Unknown part. */
MULTIPART_PART_UNKNOWN = 0,
/** Text (parameter) part. */
MULTIPART_PART_TEXT = 1,
/** File part. */
MULTIPART_PART_FILE = 2,
/** Free-text part before the first boundary. */
MULTIPART_PART_PREAMBLE = 3,
/** Free-text part after the last boundary. */
MULTIPART_PART_EPILOGUE = 4
};
// Structures
/**
* Holds multipart parser configuration and state. Private.
*/
typedef struct htp_mpartp_t htp_mpartp_t;
/**
* Holds information related to a multipart body.
*/
typedef struct htp_multipart_t {
/** Multipart boundary. */
char *boundary;
/** Boundary length. */
size_t boundary_len;
/** How many boundaries were there? */
int boundary_count;
/** List of parts, in the order in which they appeared in the body. */
htp_list_t *parts;
/** Parsing flags. */
uint64_t flags;
} htp_multipart_t;
/**
* Holds information related to a part.
*/
typedef struct htp_multipart_part_t {
/** Pointer to the parser. */
htp_mpartp_t *parser;
/** Part type; see the MULTIPART_PART_* constants. */
enum htp_multipart_type_t type;
/** Raw part length (i.e., headers and data). */
size_t len;
/** Part name, from the Content-Disposition header. Can be NULL. */
bstr *name;
/**
* Part value; the contents depends on the type of the part:
* 1) NULL for files; 2) contains complete part contents for
* preamble and epilogue parts (they have no headers), and
* 3) data only (headers excluded) for text and unknown parts.
*/
bstr *value;
/** Part content type, from the Content-Type header. Can be NULL. */
bstr *content_type;
/** Part headers (htp_header_t instances), using header name as the key. */
htp_table_t *headers;
/** File data, available only for MULTIPART_PART_FILE parts. */
htp_file_t *file;
} htp_multipart_part_t;
// Functions
/**
* Creates a new multipart/form-data parser. On a successful invocation,
* the ownership of the boundary parameter is transferred to the parser.
*
* @param[in] cfg
* @param[in] boundary
* @param[in] flags
* @return New parser instance, or NULL on memory allocation failure.
*/
htp_mpartp_t *htp_mpartp_create(htp_cfg_t *cfg, bstr *boundary, uint64_t flags);
/**
* Looks for boundary in the supplied Content-Type request header. The extracted
* boundary will be allocated on the heap.
*
* @param[in] content_type
* @param[out] boundary
* @param[out] multipart_flags Multipart flags, which are not compatible from general LibHTP flags.
* @return HTP_OK on success (boundary found), HTP_DECLINED if boundary was not found,
* and HTP_ERROR on failure. Flags may be set on HTP_OK and HTP_DECLINED. For
* example, if a boundary could not be extracted but there is indication that
* one is present, HTP_MULTIPART_HBOUNDARY_INVALID will be set.
*/
htp_status_t htp_mpartp_find_boundary(bstr *content_type, bstr **boundary, uint64_t *multipart_flags);
/**
* Returns the multipart structure created by the parser.
*
* @param[in] parser
* @return The main multipart structure.
*/
htp_multipart_t *htp_mpartp_get_multipart(htp_mpartp_t *parser);
/**
* Destroys the provided parser.
*
* @param[in] parser
*/
void htp_mpartp_destroy(htp_mpartp_t *parser);
/**
* Finalize parsing.
*
* @param[in] parser
* @returns HTP_OK on success, HTP_ERROR on failure.
*/
htp_status_t htp_mpartp_finalize(htp_mpartp_t *parser);
/**
* Parses a chunk of multipart/form-data data. This function should be called
* as many times as necessary until all data has been consumed.
*
* @param[in] parser
* @param[in] data
* @param[in] len
* @return HTP_OK on success, HTP_ERROR on failure.
*/
htp_status_t htp_mpartp_parse(htp_mpartp_t *parser, const void *data, size_t len);
#ifdef __cplusplus
}
#endif
#endif /* _HTP_MULTIPART_H */
Mini Shell