/*************************************************************************** * 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 */ #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 */