HTP  0.5
Functions
htp_transaction.c File Reference
#include "htp_config_auto.h"
#include "htp_private.h"

Functions

htp_tx_thtp_tx_create (htp_connp_t *connp)
 
htp_status_t htp_tx_destroy (htp_tx_t *tx)
 
void htp_tx_destroy_incomplete (htp_tx_t *tx)
 
int htp_tx_get_is_config_shared (const htp_tx_t *tx)
 
void * htp_tx_get_user_data (const htp_tx_t *tx)
 
void htp_tx_set_config (htp_tx_t *tx, htp_cfg_t *cfg, int is_cfg_shared)
 
void htp_tx_set_user_data (htp_tx_t *tx, void *user_data)
 
htp_status_t htp_tx_req_add_param (htp_tx_t *tx, htp_param_t *param)
 
htp_param_thtp_tx_req_get_param (htp_tx_t *tx, const char *name, size_t name_len)
 
htp_param_thtp_tx_req_get_param_ex (htp_tx_t *tx, enum htp_data_source_t source, const char *name, size_t name_len)
 
int htp_tx_req_has_body (const htp_tx_t *tx)
 
htp_status_t htp_tx_req_set_header (htp_tx_t *tx, const char *name, size_t name_len, const char *value, size_t value_len, enum htp_alloc_strategy_t alloc)
 
htp_status_t htp_tx_req_set_method (htp_tx_t *tx, const char *method, size_t method_len, enum htp_alloc_strategy_t alloc)
 
void htp_tx_req_set_method_number (htp_tx_t *tx, enum htp_method_t method_number)
 
htp_status_t htp_tx_req_set_uri (htp_tx_t *tx, const char *uri, size_t uri_len, enum htp_alloc_strategy_t alloc)
 
htp_status_t htp_tx_req_set_protocol (htp_tx_t *tx, const char *protocol, size_t protocol_len, enum htp_alloc_strategy_t alloc)
 
void htp_tx_req_set_protocol_number (htp_tx_t *tx, int protocol_number)
 
void htp_tx_req_set_protocol_0_9 (htp_tx_t *tx, int is_protocol_0_9)
 
htp_status_t htp_tx_req_process_body_data (htp_tx_t *tx, const void *data, size_t len)
 
htp_status_t htp_tx_req_process_body_data_ex (htp_tx_t *tx, const void *data, size_t len)
 
htp_status_t htp_tx_req_set_headers_clear (htp_tx_t *tx)
 
htp_status_t htp_tx_req_set_line (htp_tx_t *tx, const char *line, size_t line_len, enum htp_alloc_strategy_t alloc)
 
void htp_tx_req_set_parsed_uri (htp_tx_t *tx, htp_uri_t *parsed_uri)
 
htp_status_t htp_tx_res_set_status_line (htp_tx_t *tx, const char *line, size_t line_len, enum htp_alloc_strategy_t alloc)
 
void htp_tx_res_set_protocol_number (htp_tx_t *tx, int protocol_number)
 
void htp_tx_res_set_status_code (htp_tx_t *tx, int status_code)
 
htp_status_t htp_tx_res_set_status_message (htp_tx_t *tx, const char *msg, size_t msg_len, enum htp_alloc_strategy_t alloc)
 
htp_status_t htp_tx_state_response_line (htp_tx_t *tx)
 
htp_status_t htp_tx_res_set_header (htp_tx_t *tx, const char *name, size_t name_len, const char *value, size_t value_len, enum htp_alloc_strategy_t alloc)
 
htp_status_t htp_tx_res_set_headers_clear (htp_tx_t *tx)
 
void htp_connp_destroy_decompressors (htp_connp_t *connp)
 
htp_status_t htp_tx_res_process_body_data (htp_tx_t *tx, const void *data, size_t len)
 
htp_status_t htp_tx_res_process_body_data_ex (htp_tx_t *tx, const void *data, size_t len)
 
htp_status_t htp_tx_state_request_complete_partial (htp_tx_t *tx)
 
htp_status_t htp_tx_state_request_complete (htp_tx_t *tx)
 
htp_status_t htp_tx_state_request_start (htp_tx_t *tx)
 
htp_status_t htp_tx_state_request_headers (htp_tx_t *tx)
 
htp_status_t htp_tx_state_request_line (htp_tx_t *tx)
 
htp_status_t htp_tx_state_response_complete (htp_tx_t *tx)
 
htp_status_t htp_tx_finalize (htp_tx_t *tx)
 
htp_status_t htp_tx_state_response_complete_ex (htp_tx_t *tx, int hybrid_mode)
 
htp_status_t htp_tx_state_response_headers (htp_tx_t *tx)
 
htp_status_t htp_tx_state_response_start (htp_tx_t *tx)
 
void htp_tx_register_request_body_data (htp_tx_t *tx, int(*callback_fn)(htp_tx_data_t *))
 
void htp_tx_register_response_body_data (htp_tx_t *tx, int(*callback_fn)(htp_tx_data_t *))
 
int htp_tx_is_complete (htp_tx_t *tx)
 

Detailed Description

Author
Ivan Ristic ivanr.nosp@m.@web.nosp@m.kreat.nosp@m.or.c.nosp@m.om

Function Documentation

void htp_connp_destroy_decompressors ( htp_connp_t connp)
htp_tx_t* htp_tx_create ( htp_connp_t connp)

Creates a new transaction structure.

Parameters
[in]connpConnection parser pointer. Must not be NULL.
Returns
The newly created transaction, or NULL on memory allocation failure.
htp_status_t htp_tx_destroy ( htp_tx_t tx)

Destroys the supplied transaction.

Parameters
[in]txTransaction pointer. Must not be NULL.
void htp_tx_destroy_incomplete ( htp_tx_t tx)
htp_status_t htp_tx_finalize ( htp_tx_t tx)
int htp_tx_get_is_config_shared ( const htp_tx_t tx)

Determines if the transaction used a shared configuration structure. See the documentation for htp_tx_set_config() for more information why you might want to know that.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_CFG_SHARED or HTP_CFG_PRIVATE.
void* htp_tx_get_user_data ( const htp_tx_t tx)

Returns the user data associated with this transaction.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
A pointer to user data or NULL.
int htp_tx_is_complete ( htp_tx_t tx)
void htp_tx_register_request_body_data ( htp_tx_t tx,
int(*)(htp_tx_data_t *)  callback_fn 
)

Register callback for the transaction-specific REQUEST_BODY_DATA hook.

Parameters
[in]tx
[in]callback_fn
void htp_tx_register_response_body_data ( htp_tx_t tx,
int(*)(htp_tx_data_t *)  callback_fn 
)

Register callback for the transaction-specific RESPONSE_BODY_DATA hook.

Parameters
[in]tx
[in]callback_fn
htp_status_t htp_tx_req_add_param ( htp_tx_t tx,
htp_param_t param 
)

Adds one parameter to the request. THis function will take over the responsibility for the provided htp_param_t structure.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]paramParameter pointer. Must not be NULL.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_param_t* htp_tx_req_get_param ( htp_tx_t tx,
const char *  name,
size_t  name_len 
)

Returns the first request parameter that matches the given name, using case-insensitive matching.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]nameName data pointer. Must not be NULL.
[in]name_lenName data length.
Returns
htp_param_t instance, or NULL if parameter not found.
htp_param_t* htp_tx_req_get_param_ex ( htp_tx_t tx,
enum htp_data_source_t  source,
const char *  name,
size_t  name_len 
)

Returns the first request parameter from the given source that matches the given name, using case-insensitive matching.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]sourceParameter source (where in request the parameter was located).
[in]nameName data pointer. Must not be NULL.
[in]name_lenName data length.
Returns
htp_param_t instance, or NULL if parameter not found.
int htp_tx_req_has_body ( const htp_tx_t tx)

Determine if the request has a body.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
1 if there is a body, 0 otherwise.
htp_status_t htp_tx_req_process_body_data ( htp_tx_t tx,
const void *  data,
size_t  len 
)

Process a chunk of request body data. This function assumes that handling of chunked encoding is implemented by the container. When you're done submitting body data, invoke a state change (to REQUEST) to finalize any processing that might be pending. The supplied data is fully consumed and there is no expectation that it will be available afterwards. The protocol parsing code makes no copies of the data, but some parsers might.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]dataData pointer. Must not be NULL.
[in]lenData length.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_req_process_body_data_ex ( htp_tx_t tx,
const void *  data,
size_t  len 
)
htp_status_t htp_tx_req_set_header ( htp_tx_t tx,
const char *  name,
size_t  name_len,
const char *  value,
size_t  value_len,
enum htp_alloc_strategy_t  alloc 
)

Set one request header. This function should be invoked once for each available header, and in the order in which headers were seen in the request.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]nameName data pointer. Must not be NULL.
[in]name_lenName data length.
[in]valueValue data pointer. Must not be NULL.
[in]value_lenValue data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_req_set_headers_clear ( htp_tx_t tx)

Removes all request headers associated with this transaction. This function is needed because in some cases the container does not differentiate between standard and trailing headers. In that case, you set request headers once at the beginning of the transaction, read the body (at this point the request headers should contain the mix of regular and trailing headers), clear all headers, and then set them all again.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_req_set_line ( htp_tx_t tx,
const char *  line,
size_t  line_len,
enum htp_alloc_strategy_t  alloc 
)

Set request line. When used, this function should always be called first, with more specific functions following. Must not contain line terminators.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]lineLine data pointer. Must not be NULL.
[in]line_lenLine data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_req_set_method ( htp_tx_t tx,
const char *  method,
size_t  method_len,
enum htp_alloc_strategy_t  alloc 
)

Set transaction request method. This function will enable you to keep track of the text representation of the method.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]methodMethod data pointer. Must not be NULL.
[in]method_lenMethod data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
void htp_tx_req_set_method_number ( htp_tx_t tx,
enum htp_method_t  method_number 
)

Set transaction request method number. This function enables you to keep track how a particular method string is interpreted. This function is useful with web servers that ignore invalid methods; for example, some web servers will treat them as a GET.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]method_numberMethod number.
void htp_tx_req_set_parsed_uri ( htp_tx_t tx,
htp_uri_t parsed_uri 
)

Set parsed request URI. You don't need to use this function if you are already providing the request line or request URI. But if your container already has this data available, feeding it to LibHTP will minimize any potential data differences. This function assumes management of the data provided in parsed_uri. This function will not change htp_tx_t::parsed_uri_raw (which may have data in it from the parsing of the request URI).

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]parsed_uriURI pointer. Must not be NULL.
htp_status_t htp_tx_req_set_protocol ( htp_tx_t tx,
const char *  protocol,
size_t  protocol_len,
enum htp_alloc_strategy_t  alloc 
)

Sets the request protocol string (e.g., "HTTP/1.0"). The information provided is only stored, not parsed. Use htp_tx_req_set_protocol_number() to set the actual protocol number, as interpreted by the container.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]protocolProtocol data pointer. Must not be NULL.
[in]protocol_lenProtocol data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
void htp_tx_req_set_protocol_0_9 ( htp_tx_t tx,
int  is_protocol_0_9 
)

Forces HTTP/0.9 as the transaction protocol. This method exists to ensure that both LibHTP and the container treat the transaction as HTTP/0.9, despite potential differences in how the protocol version is determined.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]is_protocol_0_9Zero if protocol is not HTTP/0.9, or 1 if it is.
void htp_tx_req_set_protocol_number ( htp_tx_t tx,
int  protocol_number 
)

Set request protocol version number. Must be invoked after htp_txh_set_req_protocol(), because it will overwrite the previously extracted version number. Convert the protocol version number to an integer by multiplying it with 100. For example, 1.1 becomes 110. Alternatively, use the HTP_PROTOCOL_0_9, HTP_PROTOCOL_1_0, and HTP_PROTOCOL_1_1 constants. Note: setting protocol to HTP_PROTOCOL_0_9 alone will not get the library to treat the transaction as HTTP/0.9. You need to also invoke htp_tx_req_set_protocol_0_9(). This is because HTTP 0.9 is used only when protocol information is absent from the request line, and not when it is explicitly stated (as "HTTP/0.9"). This behavior is consistent with that of Apache httpd.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]protocol_numberProtocol number.
htp_status_t htp_tx_req_set_uri ( htp_tx_t tx,
const char *  uri,
size_t  uri_len,
enum htp_alloc_strategy_t  alloc 
)

Set transaction request URI. The value provided here will be stored in htp_tx_t::request_uri and subsequently parsed. If htp_tx_req_set_line() was previously used, the uri provided when calling this function will overwrite any previously parsed value.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]uriURI data pointer. Must not be NULL.
[in]uri_lenURI data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_res_process_body_data ( htp_tx_t tx,
const void *  data,
size_t  len 
)

Process a chunk of response body data. This function assumes that handling of chunked encoding is implemented by the container. When you're done submitting body data, invoking a state change (to RESPONSE) will finalize any processing that might be pending.

The response body data will be decompressed if two conditions are met: one, decompression is enabled in configuration and two, if the response headers indicate compression. Alternatively, you can control decompression from a RESPONSE_HEADERS callback, by setting tx->response_content_encoding either to COMPRESSION_NONE (to disable compression), or to one of the supported decompression algorithms.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]dataData pointer. Must not be NULL.
[in]lenData length.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_res_process_body_data_ex ( htp_tx_t tx,
const void *  data,
size_t  len 
)
htp_status_t htp_tx_res_set_header ( htp_tx_t tx,
const char *  name,
size_t  name_len,
const char *  value,
size_t  value_len,
enum htp_alloc_strategy_t  alloc 
)

Set one response header. This function should be invoked once for each available header, and in the order in which headers were seen in the response.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]nameName data pointer. Must not be NULL.
[in]name_lenName data length.
[in]valueValue data pointer. Must not be NULL.
[in]value_lenValue length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_res_set_headers_clear ( htp_tx_t tx)

Removes all response headers associated with this transaction. This function is needed because in some cases the container does not differentiate between standard and trailing headers. In that case, you set response headers once at the beginning of the transaction, read the body, clear all headers, and then set them all again. After the headers are set for the second time, they will potentially contain a mixture of standard and trailing headers.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success, HTP_ERROR on failure.
void htp_tx_res_set_protocol_number ( htp_tx_t tx,
int  protocol_number 
)

Set response protocol number. See htp_tx_res_set_protocol_number() for more information about the correct format of the protocol_parameter parameter.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]protocol_numberProtocol number.
Returns
HTP_OK on success, HTP_ERROR on failure.
void htp_tx_res_set_status_code ( htp_tx_t tx,
int  status_code 
)

Set response status code.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]status_codeResponse status code.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_res_set_status_line ( htp_tx_t tx,
const char *  line,
size_t  line_len,
enum htp_alloc_strategy_t  alloc 
)

Set response line. Use this function is you have a single buffer containing the entire line. If you have individual request line pieces, use the other available functions.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]lineLine data pointer. Must not be NULL.
[in]line_lenLine data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
htp_status_t htp_tx_res_set_status_message ( htp_tx_t tx,
const char *  msg,
size_t  msg_len,
enum htp_alloc_strategy_t  alloc 
)

Set response status message, which is the part of the response line that comes after the status code.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]msgMessage data pointer. Must not be NULL.
[in]msg_lenMessage data length.
[in]allocDesired allocation strategy.
Returns
HTP_OK on success, HTP_ERROR on failure.
void htp_tx_set_config ( htp_tx_t tx,
htp_cfg_t cfg,
int  is_cfg_shared 
)

Sets the configuration that is to be used for this transaction. If the second parameter is set to HTP_CFG_PRIVATE, the transaction will adopt the configuration structure and destroy it when appropriate. This function is useful if you need to make changes to configuration on per-transaction basis. Initially, all transactions will share the configuration with that of the connection; if you were to make changes on it, they would affect all current and future connections. To work around that, you make a copy of the configuration object, call this function with the second parameter set to HTP_CFG_PRIVATE, and modify configuration at will.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]cfgConfiguration pointer. Must not be NULL.
[in]is_cfg_sharedHTP_CFG_SHARED or HTP_CFG_PRIVATE
void htp_tx_set_user_data ( htp_tx_t tx,
void *  user_data 
)

Associates user data with this transaction.

Parameters
[in]txTransaction pointer. Must not be NULL.
[in]user_dataOpaque user data pointer.
htp_status_t htp_tx_state_request_complete ( htp_tx_t tx)

Change transaction state to REQUEST and invoke registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_request_complete_partial ( htp_tx_t tx)
htp_status_t htp_tx_state_request_headers ( htp_tx_t tx)

Change transaction state to REQUEST_HEADERS and invoke all registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_request_line ( htp_tx_t tx)

Change transaction state to REQUEST_LINE and invoke all registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_request_start ( htp_tx_t tx)

Initialize hybrid parsing mode, change state to TRANSACTION_START, and invoke all registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_response_complete ( htp_tx_t tx)

Change transaction state to RESPONSE and invoke registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_response_complete_ex ( htp_tx_t tx,
int  hybrid_mode 
)
htp_status_t htp_tx_state_response_headers ( htp_tx_t tx)

Change transaction state to RESPONSE_HEADERS and invoke registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_response_line ( htp_tx_t tx)

Change transaction state to HTP_RESPONSE_LINE and invoke registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.
htp_status_t htp_tx_state_response_start ( htp_tx_t tx)

Change transaction state to RESPONSE_START and invoke registered callbacks.

Parameters
[in]txTransaction pointer. Must not be NULL.
Returns
HTP_OK on success; HTP_ERROR on error, HTP_STOP if one of the callbacks does not want to follow the transaction any more.