diff options
Diffstat (limited to 'src/include/ndpi_api.h')
| -rw-r--r-- | src/include/ndpi_api.h | 310 |
1 files changed, 198 insertions, 112 deletions
diff --git a/src/include/ndpi_api.h b/src/include/ndpi_api.h index b380c8b03..25a7612f2 100644 --- a/src/include/ndpi_api.h +++ b/src/include/ndpi_api.h @@ -1,7 +1,7 @@ /* * ndpi_api.h * - * Copyright (C) 2011-16 - ntop.org + * Copyright (C) 2011-17 - ntop.org * * This file is part of nDPI, an open source deep packet inspection * library based on the OpenDPI and PACE technology by ipoque GmbH @@ -31,6 +31,9 @@ extern "C" { #endif +#define SIZEOF_ID_STRUCT (sizeof(struct ndpi_id_struct)) +#define SIZEOF_FLOW_STRUCT (sizeof(struct ndpi_flow_struct)) + #define NDPI_DETECTION_ONLY_IPV4 ( 1 << 0 ) #define NDPI_DETECTION_ONLY_IPV6 ( 1 << 1 ) @@ -39,20 +42,20 @@ extern "C" { #define SAVE_DETECTION_BITMASK_AS_UNKNOWN 1 #define NO_SAVE_DETECTION_BITMASK_AS_UNKNOWN 0 - + /** * Check if a string is encoded with punycode * ( https://tools.ietf.org/html/rfc3492 ) * * @par buff = pointer to the string to ckeck * @par len = len of the string - * @return 1 if the string is punycoded; + * @return 1 if the string is punycoded; * else 0 * */ int check_punycode_string(char * buff , int len); - + /** * Get the size of the flow struct * @@ -61,16 +64,16 @@ extern "C" { */ u_int32_t ndpi_detection_get_sizeof_ndpi_flow_struct(void); - + /** - * Get the size of the id struct + * Get the size of the id struct * * @return the size of the id struct - * + * */ u_int32_t ndpi_detection_get_sizeof_ndpi_id_struct(void); - + /** * nDPI personal allocation and free functions **/ @@ -79,8 +82,9 @@ extern "C" { void * ndpi_realloc(void *ptr, size_t old_size, size_t new_size); char * ndpi_strdup(const char *s); void ndpi_free(void *ptr); + void * ndpi_flow_malloc(size_t size); + void ndpi_flow_free(void *ptr); - /** * Search the first occurrence of substring -find- in -s- * The search is limited to the first -slen- characters of the string @@ -94,7 +98,19 @@ extern "C" { */ char* ndpi_strnstr(const char *s, const char *find, size_t slen); - + /** + * Same as ndpi_strnstr but case insensitive + * + * @par s = string to parse + * @par find = string to match with -s- + * @par slen = max length to match between -s- and -find- + * @return a pointer to the beginning of the located substring; + * NULL if the substring is not found + * + */ + char* ndpi_strncasestr(const char *s, const char *find, size_t slen); + + /** * Returns the nDPI protocol id for IP-based protocol detection * @@ -102,7 +118,7 @@ extern "C" { * @par pin = IP host address (MUST BE in network byte order): * See man(7) ip for details * @return the nDPI protocol ID - * + * */ u_int16_t ndpi_network_ptree_match(struct ndpi_detection_module_struct *ndpi_struct, struct in_addr *pin); @@ -113,9 +129,9 @@ extern "C" { * @par ndpi_mod = the struct created for the protocol detection * @par match = the struct passed to match the protocol * - */ + */ void ndpi_init_protocol_match(struct ndpi_detection_module_struct *ndpi_mod, ndpi_protocol_match *match); - + /** * Returns a new initialized detection module * @@ -123,7 +139,7 @@ extern "C" { * */ struct ndpi_detection_module_struct *ndpi_init_detection_module(void); - + /** * Frees the memory allocated in the specified flow * @@ -132,7 +148,7 @@ extern "C" { */ void ndpi_free_flow(struct ndpi_flow_struct *flow); - + /** * Enables cache support. * In nDPI is used for some protocol (i.e. Skype) @@ -144,7 +160,7 @@ extern "C" { */ void ndpi_enable_cache(struct ndpi_detection_module_struct *ndpi_mod, char* host, u_int port); - + /** * Destroys the detection module * @@ -176,7 +192,7 @@ extern "C" { const NDPI_SELECTION_BITMASK_PROTOCOL_SIZE ndpi_selection_bitmask, u_int8_t b_save_bitmask_unknow, u_int8_t b_add_detection_bitmask); - + /** * Sets the protocol bitmask2 @@ -188,7 +204,7 @@ extern "C" { void ndpi_set_protocol_detection_bitmask2(struct ndpi_detection_module_struct *ndpi_struct, const NDPI_PROTOCOL_BITMASK * detection_bitmask); - + /** * Function to be called before we give up with detection for a given flow. * This function reduces the NDPI_UNKNOWN_PROTOCOL detection @@ -196,12 +212,34 @@ extern "C" { * @par ndpi_struct = the detection module * @par flow = the flow given for the detection module * @return the detected protocol even if the flow is not completed; - * + * */ ndpi_protocol ndpi_detection_giveup(struct ndpi_detection_module_struct *ndpi_struct, struct ndpi_flow_struct *flow); - + /** + * Processes an extra packet in order to get more information for a given protocol + * (like SSL getting both client and server certificate even if we already know after + * seeing the client certificate what the protocol is) + * + * @par ndpi_struct = the detection module + * @par flow = pointer to the connection state machine + * @par packet = unsigned char pointer to the Layer 3 (IP header) + * @par packetlen = the length of the packet + * @par current_tick = the current timestamp for the packet + * @par src = pointer to the source subscriber state machine + * @par dst = pointer to the destination subscriber state machine + * @return void + * + */ + void ndpi_process_extra_packet(struct ndpi_detection_module_struct *ndpi_struct, + struct ndpi_flow_struct *flow, + const unsigned char *packet, + const unsigned short packetlen, + const u_int64_t current_tick, + struct ndpi_id_struct *src, + struct ndpi_id_struct *dst); + /** * Processes one packet and returns the ID of the detected protocol. * This is the MAIN PACKET PROCESSING FUNCTION. @@ -226,52 +264,6 @@ extern "C" { /** - * Processes one packet of L4 and returns the ID of the detected protocol. - * L3 and L4 packet headers are passed in the arguments while payload - * points to the L4 body. - * This function mimics ndpi_detection_process_packet behaviour. - * - * @par ndpi_struct = the detection module - * @par flow = pointer to the connection state machine - * @par iph = IP packet header for IPv4 or NULL - * @par iph6 = IP packet header for IPv6 or NULL - * @par tcp = TCP packet header for TCP or NULL - * @par udp = UDP packet header for UDP or NULL - * @par src_to_dst_direction = order of src/dst state machines in a flow. - * @par l4_proto = L4 protocol of the packet. - * @par src = pointer to the source subscriber state machine - * @par dst = pointer to the destination subscriber state machine - * @par sport = source port of L4 packet, used for protocol guessing. - * @par dport = destination port of L4 packet, used for protocol guessing. - * @par current_tick_l = the current timestamp for the packet - * @par payload = unsigned char pointer to the Layer 4 (TCP/UDP body) - * @par payload_len = the length of the payload - * @return the detected ID of the protocol - * - * NOTE: in a current implementation flow->src and flow->dst are swapped with - * the src_to_dst_direction flag while ndpi_detection_process_packet does not swap - * these values. - * - */ - -ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_struct *ndpi_struct, - struct ndpi_flow_struct *flow, - const struct ndpi_iphdr *iph, - struct ndpi_ipv6hdr *iph6, - struct ndpi_tcphdr *tcp, - struct ndpi_udphdr *udp, - u_int8_t src_to_dst_direction, - u_int8_t l4_proto, - struct ndpi_id_struct *src, - u_int16_t sport, - struct ndpi_id_struct *dst, - u_int16_t dport, - const u_int64_t current_tick_l, - u_int8_t *payload, u_int16_t payload_len); - - - - /** * Get the main protocol of the passed flows for the detected module * * @@ -283,13 +275,13 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru u_int16_t ndpi_get_flow_masterprotocol(struct ndpi_detection_module_struct *ndpi_struct, struct ndpi_flow_struct *flow); - + /** * Query the pointer to the layer 4 packet * * @par l3 = pointer to the layer 3 data * @par l3_len = length of the layer 3 data - * @par l4_return = address to the pointer of the layer 4 data if return value == 0, else undefined + * @par l4_return = address to the pointer of the layer 4 data if return value == 0, else undefined * @par l4_len_return = length of the layer 4 data if return value == 0, else undefined * @par l4_protocol_return = protocol of the layer 4 data if return value == 0, undefined otherwise * @par flags = limit operation on ipv4 or ipv6 packets. Possible values: NDPI_DETECTION_ONLY_IPV4 - NDPI_DETECTION_ONLY_IPV6 - 0 (any) @@ -301,29 +293,15 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru u_int8_t *l4_protocol_return, u_int32_t flags); -#if 0 - /** - * returns true if the protocol history of the flow of the last packet given to the detection - * contains the given protocol. - * - * @param ndpi_struct the detection module - * @return 1 if protocol has been found, 0 otherwise - * - */ - u_int8_t ndpi_detection_flow_protocol_history_contains_protocol(struct ndpi_detection_module_struct *ndpi_struct, - struct ndpi_flow_struct *flow, - u_int16_t protocol_id); -#endif - /** * Search and return the protocol based on matched ports - * + * * @par ndpi_struct = the detection module * @par shost = source address in host byte order * @par sport = source port number * @par dhost = destination address in host byte order * @par dport = destination port number - * @return the struct ndpi_protocol that match the port base protocol + * @return the struct ndpi_protocol that match the port base protocol * */ ndpi_protocol ndpi_find_port_based_protocol(struct ndpi_detection_module_struct *ndpi_struct/* , u_int8_t proto */, @@ -332,17 +310,17 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru u_int32_t dhost, u_int16_t dport); - + /** * Search and return the protocol guessed that is undetected - * + * * @par ndpi_struct = the detection module * @par proto = the l4 protocol number * @par shost = source address in host byte order * @par sport = source port number * @par dhost = destination address in host byte order * @par dport = destination port number - * @return the struct ndpi_protocol that match the port base protocol + * @return the struct ndpi_protocol that match the port base protocol * */ ndpi_protocol ndpi_guess_undetected_protocol(struct ndpi_detection_module_struct *ndpi_struct, @@ -355,7 +333,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru /** * Check if the string passed match with a protocol - * + * * @par ndpi_struct = the detection module * @par string_to_match = the string to match * @par string_to_match_len = the length of the string @@ -371,7 +349,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru /** * Check if the host passed match with a protocol - * + * * @par ndpi_struct = the detection module * @par flow = the flow where match the host * @par string_to_match = the string to match @@ -389,7 +367,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru /** * Check if the string content passed match with a protocol - * + * * @par ndpi_struct = the detection module * @par flow = the flow where match the host * @par string_to_match = the string to match @@ -404,21 +382,34 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru u_int string_to_match_len, u_int16_t master_protocol_id); - + + /** + * Exclude protocol from search + * + * @par ndpi_struct = the detection module + * @par flow = the flow where match the host + * @par master_protocol_id = value of the ID associated to the master protocol detected + * + */ + void ndpi_exclude_protocol(struct ndpi_detection_module_struct *ndpi_struct, + struct ndpi_flow_struct *flow, + u_int16_t master_protocol_id, + const char *_file, const char *_func,int _line); + + /** * Check if the string -bigram_to_match- match with a bigram of -automa- * - * @par ndpi_struct = the detection module + * @par ndpi_mod = the detection module * @par automa = the struct ndpi_automa for the bigram * @par bigram_to_match = the bigram string to match * @return 0 * */ - int ndpi_match_bigram(struct ndpi_detection_module_struct *ndpi_struct, + int ndpi_match_bigram(struct ndpi_detection_module_struct *ndpi_mod, ndpi_automa *automa, char *bigram_to_match); - /** * Write the protocol name in the buffer -buf- as master_protocol.protocol * @@ -432,13 +423,69 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru char* ndpi_protocol2name(struct ndpi_detection_module_struct *ndpi_mod, ndpi_protocol proto, char *buf, u_int buf_len); /** + * Find out if a given category is custom/user-defined + * + * @par category = the category associated to the protocol + * @return 1 if this is a custom user category, 0 otherwise + * + */ + int ndpi_is_custom_category(ndpi_protocol_category_t category); + + /** + * Overwrite a protocol category defined by nDPI with the custom category + * + * @par ndpi_mod = the detection module + * @par protoId = the protocol identifier to overwrite + * @par breed = the breed to be associated to the protocol + * + */ + void ndpi_set_proto_breed(struct ndpi_detection_module_struct *ndpi_mod, + u_int16_t protoId, ndpi_protocol_breed_t breed); + + /** + * Overwrite a protocol category defined by nDPI with the custom category + * + * @par ndpi_mod = the detection module + * @par protoId = the protocol identifier to overwrite + * @par category = the category associated to the protocol + * + */ + void ndpi_set_proto_category(struct ndpi_detection_module_struct *ndpi_mod, + u_int16_t protoId, ndpi_protocol_category_t protoCategory); + + /** + * Check if subprotocols of the specified master protocol are just + * informative (and not real) + * + * @par mod = the detection module + * @par protoId = the (master) protocol identifier to query + * @return 1 = the subprotocol is informative, 0 otherwise. + * + */ + u_int8_t ndpi_is_subprotocol_informative(struct ndpi_detection_module_struct *ndpi_mod, + u_int16_t protoId); + + /** * Get protocol category as string * + * @par mod = the detection module * @par category = the category associated to the protocol * @return the string name of the category * */ - const char* ndpi_category_str(ndpi_protocol_category_t category); + const char* ndpi_category_get_name(struct ndpi_detection_module_struct *ndpi_mod, + ndpi_protocol_category_t category); + + /** + * Set protocol category string + * + * @par mod = the detection module + * @par category = the category associated to the protocol + * @paw name = the string name of the category + * + */ + void ndpi_category_set_name(struct ndpi_detection_module_struct *ndpi_mod, + ndpi_protocol_category_t category, char *name); /** * Get protocol category @@ -448,7 +495,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * @return the protocol category */ ndpi_protocol_category_t ndpi_get_proto_category(struct ndpi_detection_module_struct *ndpi_mod, ndpi_protocol proto); - + /** * Get the protocol name associated to the ID * @@ -470,13 +517,13 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru */ ndpi_protocol_breed_t ndpi_get_proto_breed(struct ndpi_detection_module_struct *ndpi_struct, u_int16_t proto); - + /** * Return the string name of the protocol breed * * @par ndpi_struct = the detection module * @par breed_id = the breed ID associated to the protocol - * @return the string name of the breed ID + * @return the string name of the breed ID * */ char* ndpi_get_proto_breed_name(struct ndpi_detection_module_struct *ndpi_struct, ndpi_protocol_breed_t breed_id); @@ -486,20 +533,31 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * Return the ID of the protocol * * @par ndpi_mod = the detection module - * @par proto = the ID of the protocol - * @return the string name of the breed ID + * @par proto = the protocol name + * @return the ID of the protocol * */ int ndpi_get_protocol_id(struct ndpi_detection_module_struct *ndpi_mod, char *proto); /** + * Return the ID of the category + * + * @par ndpi_mod = the detection module + * @par proto = the category name + * @return the ID of the category + * + */ + int ndpi_get_category_id(struct ndpi_detection_module_struct *ndpi_mod, char *cat); + + + /** * Write the list of the supported protocols * * @par ndpi_mod = the detection module */ void ndpi_dump_protocols(struct ndpi_detection_module_struct *mod); - + /** * Read a file and load the protocols @@ -523,12 +581,12 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * Get the total number of the supported protocols * * @par ndpi_mod = the detection module - * @return the number of protocols + * @return the number of protocols * */ u_int ndpi_get_num_supported_protocols(struct ndpi_detection_module_struct *ndpi_mod); - + /** * Get the nDPI version release * @@ -559,7 +617,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru */ ndpi_http_method ndpi_get_http_method(struct ndpi_detection_module_struct *ndpi_mod, struct ndpi_flow_struct *flow); - + /** * Get the HTTP url * @@ -582,7 +640,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru char* ndpi_get_http_content_type(struct ndpi_detection_module_struct *ndpi_mod, struct ndpi_flow_struct *flow); #endif - + #ifdef NDPI_PROTOCOL_TOR /** * Check if the flow could be detected as TOR protocol @@ -592,7 +650,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * @par certificate = the ssl certificate * @return 1 if the flow is TOR; * 0 else - * + * */ int ndpi_is_ssl_tor(struct ndpi_detection_module_struct *ndpi_struct, struct ndpi_flow_struct *flow, char *certificate); @@ -603,7 +661,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * Init Aho-Corasick automata * * @return The requested automata, or NULL if an error occurred - * + * */ void* ndpi_init_automa(void); @@ -612,7 +670,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * Free Aho-Corasick automata allocated with ndpi_init_automa(); * * @par The automata initialized with ndpi_init_automa(); - * + * */ void ndpi_free_automa(void *_automa); @@ -622,8 +680,20 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * * @par The automata initialized with ndpi_init_automa(); * @par The (sub)string to search + * @par The number associated with this string + * @return 0 in case of no error, or -1 if an error occurred. + * + */ + int ndpi_add_string_value_to_automa(void *_automa, char *str, unsigned long num); + + + /** + * Add a string to match to an automata. Same as ndpi_add_string_value_to_automa() with num set to 1 + * + * @par The automata initialized with ndpi_init_automa(); + * @par The (sub)string to search * @return 0 in case of no error, or -1 if an error occurred. - * + * */ int ndpi_add_string_to_automa(void *_automa, char *str); @@ -632,7 +702,7 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * Finalize the automa (necessary before start searching) * * @par The automata initialized with ndpi_init_automa(); - * + * */ void ndpi_finalize_automa(void *_automa); @@ -643,16 +713,32 @@ ndpi_protocol ndpi_l4_detection_process_packet(struct ndpi_detection_module_stru * @par The automata initialized with ndpi_init_automa(); * @par The (sub)string to search * @return 0 in case of match, or -1 if no match, or -2 if an error occurred. - * + * */ int ndpi_match_string(void *_automa, char *string_to_match); + /** + * Add a string to match to an automata + * + * @par The automata initialized with ndpi_init_automa(); + * @par The (sub)string to search + * @par The id associated with the matched string or 0 id not found. + * @return 0 in case of match, or -1 if no match, or -2 if an error occurred. + * + */ + int ndpi_match_string_id(void *_automa, char *string_to_match, unsigned long *id); + + /* Utility functions to set ndpi malloc/free/print wrappers */ void set_ndpi_malloc(void* (*__ndpi_malloc)(size_t size)); void set_ndpi_free(void (*__ndpi_free)(void *ptr)); + void set_ndpi_flow_malloc(void* (*__ndpi_flow_malloc)(size_t size)); + void set_ndpi_flow_free(void (*__ndpi_flow_free)(void *ptr)); void set_ndpi_debug_function(struct ndpi_detection_module_struct *ndpi_str, ndpi_debug_function_ptr ndpi_debug_printf); - + void * ndpi_malloc(size_t size); + void * ndpi_calloc(unsigned long count, size_t size); + void ndpi_free(void *ptr); #ifdef __cplusplus } #endif |