1/* 2 * ndpi_api.h 3 * 4 * Copyright (C) 2011-20 - ntop.org 5 * 6 * This file is part of nDPI, an open source deep packet inspection 7 * library based on the OpenDPI and PACE technology by ipoque GmbH 8 * 9 * nDPI is free software: you can redistribute it and/or modify 10 * it under the terms of the GNU Lesser General Public License as published by 11 * the Free Software Foundation, either version 3 of the License, or 12 * (at your option) any later version. 13 * 14 * nDPI is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public License 20 * along with nDPI. If not, see <http://www.gnu.org/licenses/>. 21 * 22 */ 23 24 25#ifndef __NDPI_API_H__ 26#define __NDPI_API_H__ 27 28#include "ndpi_main.h" 29 30#ifdef __cplusplus 31extern "C" { 32#endif 33 34 /* The #define below is used for apps that dynamically link with nDPI to make 35 sure that datastructures and in sync across versions 36 */ 37#define NDPI_API_VERSION @NDPI_API_VERSION@ 38 39#define SIZEOF_ID_STRUCT ( sizeof(struct ndpi_id_struct) ) 40#define SIZEOF_FLOW_STRUCT ( sizeof(struct ndpi_flow_struct) ) 41 42#define NDPI_DETECTION_ONLY_IPV4 ( 1 << 0 ) 43#define NDPI_DETECTION_ONLY_IPV6 ( 1 << 1 ) 44 45#define ADD_TO_DETECTION_BITMASK 1 46#define NO_ADD_TO_DETECTION_BITMASK 0 47#define SAVE_DETECTION_BITMASK_AS_UNKNOWN 1 48#define NO_SAVE_DETECTION_BITMASK_AS_UNKNOWN 0 49 50 /* 51 In case a custom DGA function is used, the fucntion 52 below must be overwritten, 53 */ 54 extern ndpi_custom_dga_predict_fctn ndpi_dga_function; 55 56 /** 57 * Check if a string is encoded with punycode 58 * ( https://tools.ietf.org/html/rfc3492 ) 59 * 60 * @par buff = pointer to the string to ckeck 61 * @par len = len of the string 62 * @return 1 if the string is punycoded; 63 * else 0 64 * 65 */ 66 int ndpi_check_punycode_string(char *buff, int len); 67 68 69 /** 70 * Get the size of the flow struct 71 * 72 * @return the size of the flow struct 73 * 74 */ 75 u_int32_t ndpi_detection_get_sizeof_ndpi_flow_struct(void); 76 77 78 /** 79 * Get the size of the id struct 80 * 81 * @return the size of the id struct 82 * 83 */ 84 u_int32_t ndpi_detection_get_sizeof_ndpi_id_struct(void); 85 86 87 /** 88 * Get the size of the flow tcp struct 89 * 90 * @return the size of the flow tcp struct 91 * 92 */ 93 u_int32_t ndpi_detection_get_sizeof_ndpi_flow_tcp_struct(void); 94 95 96 /** 97 * Get the size of the flow udp struct 98 * 99 * @return the size of the flow udp struct 100 * 101 */ 102 u_int32_t ndpi_detection_get_sizeof_ndpi_flow_udp_struct(void); 103 104 /* 105 Same as the API call above but used for matching raw id's added 106 via ndpi_add_string_value_to_automa() 107 */ 108 int ndpi_match_string_value(void *_automa, char *string_to_match, 109 u_int match_len, u_int32_t *num); 110 111 /** 112 * nDPI personal allocation and free functions 113 **/ 114 void * ndpi_malloc(size_t size); 115 void * ndpi_calloc(unsigned long count, size_t size); 116 void * ndpi_realloc(void *ptr, size_t old_size, size_t new_size); 117 char * ndpi_strdup(const char *s); 118 void ndpi_free(void *ptr); 119 void * ndpi_flow_malloc(size_t size); 120 void ndpi_flow_free(void *ptr); 121 122 /** 123 * Search the first occurrence of substring -find- in -s- 124 * The search is limited to the first -slen- characters of the string 125 * 126 * @par s = string to parse 127 * @par find = string to match with -s- 128 * @par slen = max length to match between -s- and -find- 129 * @return a pointer to the beginning of the located substring; 130 * NULL if the substring is not found 131 * 132 */ 133 char* ndpi_strnstr(const char *s, const char *find, size_t slen); 134 135 /** 136 * Same as ndpi_strnstr but case insensitive 137 * 138 * @par s = string to parse 139 * @par find = string to match with -s- 140 * @par slen = max length to match between -s- and -find- 141 * @return a pointer to the beginning of the located substring; 142 * NULL if the substring is not found 143 * 144 */ 145 const char* ndpi_strncasestr(const char *s, const char *find, size_t slen); 146 147 /** 148 * Returns the nDPI protocol id for IP-based protocol detection 149 * 150 * @par ndpi_struct = the struct created for the protocol detection 151 * @par pin = IP host address (MUST BE in network byte order): 152 * See man(7) ip for details 153 * @return the nDPI protocol ID 154 * 155 */ 156 u_int16_t ndpi_network_ptree_match(struct ndpi_detection_module_struct *ndpi_struct, 157 struct in_addr *pin); 158 159 /** 160 * Returns the nDPI protocol id for IP+port-based protocol detection 161 * 162 * @par ndpi_struct = the struct created for the protocol detection 163 * @par pin = IP host address (MUST BE in network byte order): 164 * See man(7) ip for details 165 * @par port = The port (MUST BE in network byte order) or 166 * 0 if ignored 167 * @return the nDPI protocol ID 168 * 169 */ 170 u_int16_t ndpi_network_port_ptree_match(struct ndpi_detection_module_struct *ndpi_struct, 171 struct in_addr *pin /* network byte order */, 172 u_int16_t port /* network byte order */); 173 174 /** 175 * Init single protocol match 176 * 177 * @par ndpi_mod = the struct created for the protocol detection 178 * @par match = the struct passed to match the protocol 179 * 180 */ 181 void ndpi_init_protocol_match(struct ndpi_detection_module_struct *ndpi_mod, 182 ndpi_protocol_match *match); 183 184 /** 185 * Returns a new initialized detection module 186 * Note that before you can use it you can still load 187 * hosts and do other things. As soon as you are ready to use 188 * it do not forget to call first ndpi_finalize_initialization() 189 * 190 * You can call this function multiple times, (i.e. to create multiple 191 * indipendent detection contexts) but all these calls MUST NOT run 192 * in parallel 193 * 194 * @par prefs = load preferences 195 * @return the initialized detection module 196 * 197 */ 198 struct ndpi_detection_module_struct *ndpi_init_detection_module(ndpi_init_prefs prefs); 199 200 /** 201 * Completes the initialization (2nd step) 202 * 203 * @par ndpi_str = the struct created for the protocol detection 204 * 205 */ 206 void ndpi_finalize_initialization(struct ndpi_detection_module_struct *ndpi_str); 207 208 /** 209 * Frees the dynamic memory allocated members in the specified flow 210 * 211 * @par flow = the flow struct which dynamic allocated members should be deallocated 212 * 213 */ 214 void ndpi_free_flow_data(struct ndpi_flow_struct *flow); 215 216 /** 217 * Frees the dynamic memory allocated members in the specified flow and the flow struct itself 218 * 219 * @par flow = the flow struct and its dynamic allocated members that should be deallocated 220 * 221 */ 222 void ndpi_free_flow(struct ndpi_flow_struct *flow); 223 224 /** 225 * Enables cache support. 226 * In nDPI is used for some protocol (i.e. Skype) 227 * 228 * @par ndpi_mod = the struct created for the protocol detection 229 * @par host = string for the host name 230 * @par port = unsigned int for the port number 231 * 232 */ 233 void ndpi_enable_cache(struct ndpi_detection_module_struct *ndpi_mod, 234 char* host, u_int port); 235 236 /** 237 * Destroys the detection module 238 * 239 * @par ndpi_struct = the struct to clearing for the detection module 240 * 241 */ 242 void ndpi_exit_detection_module(struct ndpi_detection_module_struct *ndpi_struct); 243 244 /** 245 * Sets a single protocol bitmask 246 * This function does not increment the index of the callback_buffer 247 * 248 * @par label = string for the protocol name 249 * @par ndpi_struct = the detection module 250 * @par detection_bitmask = the protocol bitmask 251 * @par idx = the index of the callback_buffer 252 * @par func = function pointer of the protocol search 253 * @par ndpi_selection_bitmask = the protocol selected bitmask 254 * @par b_save_bitmask_unknow = if set as "true" save the detection bitmask as unknow 255 * @par b_add_detection_bitmask = if set as "true" add the protocol bitmask to the detection bitmask 256 * 257 */ 258 void ndpi_set_bitmask_protocol_detection(char *label, 259 struct ndpi_detection_module_struct *ndpi_struct, 260 const NDPI_PROTOCOL_BITMASK *detection_bitmask, 261 const u_int32_t idx, 262 u_int16_t ndpi_protocol_id, 263 void (*func) (struct ndpi_detection_module_struct *, 264 struct ndpi_flow_struct *flow), 265 const NDPI_SELECTION_BITMASK_PROTOCOL_SIZE ndpi_selection_bitmask, 266 u_int8_t b_save_bitmask_unknow, 267 u_int8_t b_add_detection_bitmask); 268 269 /** 270 * Sets the protocol bitmask2 271 * 272 * @par ndpi_struct = the detection module 273 * @par detection_bitmask = the protocol bitmask to set 274 * 275 */ 276 void ndpi_set_protocol_detection_bitmask2(struct ndpi_detection_module_struct *ndpi_struct, 277 const NDPI_PROTOCOL_BITMASK * detection_bitmask); 278 279 /** 280 * Function to be called before we give up with detection for a given flow. 281 * This function reduces the NDPI_UNKNOWN_PROTOCOL detection 282 * 283 * @par ndpi_struct = the detection module 284 * @par flow = the flow given for the detection module 285 * @par enable_guess = guess protocol if unknown 286 * @par protocol_was_guessed = 1 if the protocol was guesses (requires enable_guess = 1), 0 otherwise 287 * @return the detected protocol even if the flow is not completed; 288 * 289 */ 290 ndpi_protocol ndpi_detection_giveup(struct ndpi_detection_module_struct *ndpi_struct, 291 struct ndpi_flow_struct *flow, 292 u_int8_t enable_guess, 293 u_int8_t *protocol_was_guessed); 294 295 /** 296 * Processes an extra packet in order to get more information for a given protocol 297 * (like SSL getting both client and server certificate even if we already know after 298 * seeing the client certificate what the protocol is) 299 * 300 * @par ndpi_struct = the detection module 301 * @par flow = pointer to the connection state machine 302 * @par packet = unsigned char pointer to the Layer 3 (IP header) 303 * @par packetlen = the length of the packet 304 * @par packet_time_ms = the current timestamp for the packet (expressed in msec) 305 * @par src = pointer to the source subscriber state machine 306 * @par dst = pointer to the destination subscriber state machine 307 * @return void 308 * 309 */ 310 void ndpi_process_extra_packet(struct ndpi_detection_module_struct *ndpi_struct, 311 struct ndpi_flow_struct *flow, 312 const unsigned char *packet, 313 const unsigned short packetlen, 314 const u_int64_t packet_time_ms, 315 struct ndpi_id_struct *src, 316 struct ndpi_id_struct *dst); 317 318 /** 319 * Processes one packet and returns the ID of the detected protocol. 320 * This is the MAIN PACKET PROCESSING FUNCTION. 321 * 322 * @par ndpi_struct = the detection module 323 * @par flow = pointer to the connection state machine 324 * @par packet = unsigned char pointer to the Layer 3 (IP header) 325 * @par packetlen = the length of the packet 326 * @par packet_time_ms = the current timestamp for the packet (expressed in msec) 327 * @par src = pointer to the source subscriber state machine 328 * @par dst = pointer to the destination subscriber state machine 329 * @return the detected ID of the protocol 330 * 331 */ 332 ndpi_protocol ndpi_detection_process_packet(struct ndpi_detection_module_struct *ndpi_struct, 333 struct ndpi_flow_struct *flow, 334 const unsigned char *packet, 335 const unsigned short packetlen, 336 const u_int64_t packet_time_ms, 337 struct ndpi_id_struct *src, 338 struct ndpi_id_struct *dst); 339 /** 340 * Get the main protocol of the passed flows for the detected module 341 * 342 * 343 * @par ndpi_struct = the detection module 344 * @par flow = the flow given for the detection module 345 * @return the ID of the master protocol detected 346 * 347 */ 348 u_int16_t ndpi_get_flow_masterprotocol(struct ndpi_detection_module_struct *ndpi_struct, 349 struct ndpi_flow_struct *flow); 350 351 /** 352 * API call that is called internally by ndpi_detection_process_packet or by apps 353 * that want to avoid calling ndpi_detection_process_packet as they have already 354 * parsed the packet and thus want to avoid this. 355 * 356 * 357 * @par ndpi_struct = the detection module 358 * @par flow = the flow given for the detection module 359 * @par ndpi_selection_bitmask = the protocol selected bitmask 360 * @return number of protocol dissector that have been tried (0 = no more dissectors) 361 * 362 */ 363 u_int32_t ndpi_check_flow_func(struct ndpi_detection_module_struct *ndpi_struct, 364 struct ndpi_flow_struct *flow, 365 NDPI_SELECTION_BITMASK_PROTOCOL_SIZE *ndpi_selection_packet); 366 367 368 /** 369 * Query the pointer to the layer 4 packet 370 * 371 * @par l3 = pointer to the layer 3 data 372 * @par l3_len = length of the layer 3 data 373 * @par l4_return = address to the pointer of the layer 4 data if return value == 0, else undefined 374 * @par l4_len_return = length of the layer 4 data if return value == 0, else undefined 375 * @par l4_protocol_return = protocol of the layer 4 data if return value == 0, undefined otherwise 376 * @par flags = limit operation on ipv4 or ipv6 packets. Possible values: NDPI_DETECTION_ONLY_IPV4 - NDPI_DETECTION_ONLY_IPV6 - 0 (any) 377 * @return 0 if layer 4 data could be found correctly; 378 else != 0 379 * 380 */ 381 u_int8_t ndpi_detection_get_l4(const u_int8_t *l3, u_int16_t l3_len, const u_int8_t **l4_return, u_int16_t *l4_len_return, 382 u_int8_t *l4_protocol_return, u_int32_t flags); 383 384 /** 385 * Search and return the protocol based on matched ports 386 * 387 * @par ndpi_struct = the detection module 388 * @par shost = source address in host byte order 389 * @par sport = source port number 390 * @par dhost = destination address in host byte order 391 * @par dport = destination port number 392 * @return the struct ndpi_protocol that match the port base protocol 393 * 394 */ 395 ndpi_protocol ndpi_find_port_based_protocol(struct ndpi_detection_module_struct *ndpi_struct/* , u_int8_t proto */, 396 u_int32_t shost, 397 u_int16_t sport, 398 u_int32_t dhost, 399 u_int16_t dport); 400 /** 401 * Search and return the protocol guessed that is undetected 402 * 403 * @par ndpi_struct = the detection module 404 * @par flow = the flow we're trying to guess, NULL if not available 405 * @par proto = the l4 protocol number 406 * @par shost = source address in host byte order 407 * @par sport = source port number 408 * @par dhost = destination address in host byte order 409 * @par dport = destination port number 410 * @return the struct ndpi_protocol that match the port base protocol 411 * 412 */ 413 ndpi_protocol ndpi_guess_undetected_protocol(struct ndpi_detection_module_struct *ndpi_struct, 414 struct ndpi_flow_struct *flow, 415 u_int8_t proto, 416 u_int32_t shost, 417 u_int16_t sport, 418 u_int32_t dhost, 419 u_int16_t dport); 420 /** 421 * Check if the string passed match with a protocol 422 * 423 * @par ndpi_struct = the detection module 424 * @par string_to_match = the string to match 425 * @par string_to_match_len = the length of the string 426 * @par ret_match = completed returned match information 427 * @par is_host_match = value of the second field of struct ndpi_automa 428 * @return the ID of the matched subprotocol; 429 * -1 if automa is not finalized; 430 * -2 if automa==NULL or string_to_match==NULL or empty string_to_match 431 * 432 */ 433 int ndpi_match_string_subprotocol(struct ndpi_detection_module_struct *ndpi_struct, 434 char *string_to_match, 435 u_int string_to_match_len, 436 ndpi_protocol_match_result *ret_match, 437 u_int8_t is_host_match); 438 /** 439 * Check if the host passed match with a protocol 440 * 441 * @par ndpi_struct = the detection module 442 * @par flow = the flow where match the host 443 * @par string_to_match = the string to match 444 * @par string_to_match_len = the length of the string 445 * @par ret_match = completed returned match information 446 * @par master_protocol_id = value of the ID associated to the master protocol detected 447 * @return the ID of the matched subprotocol 448 * 449 */ 450 u_int16_t ndpi_match_host_subprotocol(struct ndpi_detection_module_struct *ndpi_struct, 451 struct ndpi_flow_struct *flow, 452 char *string_to_match, 453 u_int string_to_match_len, 454 ndpi_protocol_match_result *ret_match, 455 u_int16_t master_protocol_id); 456 457 /** 458 * Check if the string content passed match with a protocol 459 * 460 * @par ndpi_struct = the detection module 461 * @par flow = the flow where match the host 462 * @par subprotocol_id = subprotocol id 463 */ 464 void ndpi_check_subprotocol_risk(struct ndpi_detection_module_struct *ndpi_str, 465 struct ndpi_flow_struct *flow, u_int16_t subprotocol_id); 466 467 /** 468 * Check if the string content passed match with a protocol 469 * 470 * @par ndpi_struct = the detection module 471 * @par flow = the flow where match the host 472 * @par string_to_match = the string to match 473 * @par string_to_match_len = the length of the string 474 * @par ret_match = completed returned match information 475 * @par master_protocol_id = value of the ID associated to the master protocol detected 476 * @return the ID of the matched subprotocol 477 * 478 */ 479 u_int16_t ndpi_match_content_subprotocol(struct ndpi_detection_module_struct *ndpi_struct, 480 struct ndpi_flow_struct *flow, 481 char *string_to_match, 482 u_int string_to_match_len, 483 ndpi_protocol_match_result *ret_match, 484 u_int16_t master_protocol_id); 485 /** 486 * Exclude protocol from search 487 * 488 * @par ndpi_struct = the detection module 489 * @par flow = the flow where match the host 490 * @par master_protocol_id = value of the ID associated to the master protocol detected 491 * 492 */ 493 void ndpi_exclude_protocol(struct ndpi_detection_module_struct *ndpi_struct, 494 struct ndpi_flow_struct *flow, 495 u_int16_t master_protocol_id, 496 const char *_file, const char *_func,int _line); 497 /** 498 * Check if the string -bigram_to_match- match with a bigram of -automa- 499 * 500 * @par ndpi_mod = the detection module 501 * @par automa = the struct ndpi_automa for the bigram 502 * @par bigram_to_match = the bigram string to match 503 * @return 0 504 * 505 */ 506 int ndpi_match_bigram(const char *bigram_to_match); 507 508 /** 509 * Write the protocol name in the buffer -buf- as master_protocol.protocol 510 * 511 * @par ndpi_mod = the detection module 512 * @par proto = the struct ndpi_protocol contain the protocols name 513 * @par buf = the buffer to write the name of the protocols 514 * @par buf_len = the length of the buffer 515 * @return the buffer contains the master_protocol and protocol name 516 * 517 */ 518 char* ndpi_protocol2name(struct ndpi_detection_module_struct *ndpi_mod, 519 ndpi_protocol proto, char *buf, u_int buf_len); 520 521 /** 522 * Same as ndpi_protocol2name() with the difference that the numeric protocol 523 * name is returned 524 * 525 * @par ndpi_mod = the detection module 526 * @par proto = the struct ndpi_protocol contain the protocols name 527 * @par buf = the buffer to write the name of the protocols 528 * @par buf_len = the length of the buffer 529 * @return the buffer contains the master_protocol and protocol name 530 * 531 */ 532 char* ndpi_protocol2id(struct ndpi_detection_module_struct *ndpi_mod, 533 ndpi_protocol proto, char *buf, u_int buf_len); 534 535 /** 536 * Find out if a given category is custom/user-defined 537 * 538 * @par category = the category associated to the protocol 539 * @return 1 if this is a custom user category, 0 otherwise 540 * 541 */ 542 int ndpi_is_custom_category(ndpi_protocol_category_t category); 543 544 /** 545 * Overwrite a protocol category defined by nDPI with the custom category 546 * 547 * @par ndpi_mod = the detection module 548 * @par protoId = the protocol identifier to overwrite 549 * @par breed = the breed to be associated to the protocol 550 * 551 */ 552 void ndpi_set_proto_breed(struct ndpi_detection_module_struct *ndpi_mod, 553 u_int16_t protoId, ndpi_protocol_breed_t breed); 554 555 /** 556 * Overwrite a protocol category defined by nDPI with the custom category 557 * 558 * @par ndpi_mod = the detection module 559 * @par protoId = the protocol identifier to overwrite 560 * @par category = the category associated to the protocol 561 * 562 */ 563 void ndpi_set_proto_category(struct ndpi_detection_module_struct *ndpi_mod, 564 u_int16_t protoId, ndpi_protocol_category_t protoCategory); 565 566 /** 567 * Check if subprotocols of the specified master protocol are just 568 * informative (and not real) 569 * 570 * @par mod = the detection module 571 * @par protoId = the (master) protocol identifier to query 572 * @return 1 = the subprotocol is informative, 0 otherwise. 573 * 574 */ 575 u_int8_t ndpi_is_subprotocol_informative(struct ndpi_detection_module_struct *ndpi_mod, 576 u_int16_t protoId); 577 578 /** 579 * Set hostname-based protocol 580 * 581 * @par ndpi_mod = the detection module 582 * @par flow = the flow to which this communication belongs to 583 * @par master_protocol = the master protocol for this flow 584 * @par name = the host name 585 * @par name_len = length of the host name 586 * 587 */ 588 int ndpi_match_hostname_protocol(struct ndpi_detection_module_struct *ndpi_mod, 589 struct ndpi_flow_struct *flow, 590 u_int16_t master_protocol, 591 char *name, u_int name_len); 592 593 /** 594 * Get protocol category as string 595 * 596 * @par mod = the detection module 597 * @par category = the category associated to the protocol 598 * @return the string name of the category 599 * 600 */ 601 const char* ndpi_category_get_name(struct ndpi_detection_module_struct *ndpi_mod, 602 ndpi_protocol_category_t category); 603 604 /** 605 * Set protocol category string 606 * 607 * @par mod = the detection module 608 * @par category = the category associated to the protocol 609 * @paw name = the string name of the category 610 * 611 */ 612 void ndpi_category_set_name(struct ndpi_detection_module_struct *ndpi_mod, 613 ndpi_protocol_category_t category, char *name); 614 615 /** 616 * Get protocol category 617 * 618 * @par ndpi_mod = the detection module 619 * @par proto = the struct ndpi_protocol contain the protocols name 620 * @return the protocol category 621 */ 622 ndpi_protocol_category_t ndpi_get_proto_category(struct ndpi_detection_module_struct *ndpi_mod, 623 ndpi_protocol proto); 624 625 /** 626 * Get the protocol name associated to the ID 627 * 628 * @par mod = the detection module 629 * @par proto_id = the ID of the protocol 630 * @return the buffer contains the master_protocol and protocol name 631 * 632 */ 633 char* ndpi_get_proto_name(struct ndpi_detection_module_struct *mod, u_int16_t proto_id); 634 635 636 /** 637 * Return the protocol breed ID associated to the protocol 638 * 639 * @par ndpi_struct = the detection module 640 * @par proto = the ID of the protocol 641 * @return the breed ID associated to the protocol 642 * 643 */ 644 ndpi_protocol_breed_t ndpi_get_proto_breed(struct ndpi_detection_module_struct *ndpi_struct, 645 u_int16_t proto); 646 647 /** 648 * Return the string name of the protocol breed 649 * 650 * @par ndpi_struct = the detection module 651 * @par breed_id = the breed ID associated to the protocol 652 * @return the string name of the breed ID 653 * 654 */ 655 char* ndpi_get_proto_breed_name(struct ndpi_detection_module_struct *ndpi_struct, 656 ndpi_protocol_breed_t breed_id); 657 658 /** 659 * Return the ID of the protocol 660 * 661 * @par ndpi_mod = the detection module 662 * @par proto = the protocol name 663 * @return the ID of the protocol 664 * 665 */ 666 int ndpi_get_protocol_id(struct ndpi_detection_module_struct *ndpi_mod, char *proto); 667 668 /** 669 * Return the ID of the category 670 * 671 * @par ndpi_mod = the detection module 672 * @par proto = the category name 673 * @return the ID of the category 674 * 675 */ 676 int ndpi_get_category_id(struct ndpi_detection_module_struct *ndpi_mod, char *cat); 677 678 /** 679 * Write the list of the supported protocols 680 * 681 * @par ndpi_mod = the detection module 682 */ 683 void ndpi_dump_protocols(struct ndpi_detection_module_struct *mod); 684 685 /** 686 * Write the list of the scores and their associated risks 687 * 688 * @par ndpi_mod = the detection module 689 */ 690 void ndpi_dump_risks_score(); 691 692 /** 693 * Read a file and load the protocols 694 * 695 * Format: <tcp|udp>:<port>,<tcp|udp>:<port>,.....@<proto> 696 * 697 * Example: 698 * tcp:80,tcp:3128@HTTP 699 * udp:139@NETBIOS 700 * 701 * @par ndpi_mod = the detection module 702 * @par path = the path of the file 703 * @return 0 if the file is loaded correctly; 704 * -1 else 705 * 706 */ 707 int ndpi_load_protocols_file(struct ndpi_detection_module_struct *ndpi_mod, 708 const char* path); 709 710 /** 711 * Add an IP-address based risk mask 712 * 713 * @par ndpi_mod = the detection module 714 * @par ip = the IP address for which you wanna set the mask 715 * @par mask = the IP risk mask 716 * @return 0 if the rule is loaded correctly; 717 * -1 else 718 */ 719 int ndpi_add_ip_risk_mask(struct ndpi_detection_module_struct *ndpi_mod, char *ip, ndpi_risk mask); 720 721 /** 722 * Add a host-address based risk mask 723 * 724 * @par ndpi_mod = the detection module 725 * @par host = the hostname/domain for which you wanna set the mask 726 * @par mask = the host risk mask 727 * @return 0 if the rule is loaded correctly; 728 * -1 else 729 */ 730 int ndpi_add_host_risk_mask(struct ndpi_detection_module_struct *ndpi_mod, char *host, ndpi_risk mask); 731 732 /** 733 * Read a file and load the categories 734 * 735 * @par ndpi_mod = the detection module 736 * @par path = the path of the file 737 * @return 0 if the file is loaded correctly; 738 * -1 else 739 */ 740 int ndpi_load_categories_file(struct ndpi_detection_module_struct *ndpi_str, const char* path); 741 742 /** 743 * Read a file and load the list of risky domains 744 * 745 * @par ndpi_mod = the detection module 746 * @par path = the path of the file 747 * @return 0 if the file is loaded correctly; 748 * -1 else 749 */ 750 int ndpi_load_risk_domain_file(struct ndpi_detection_module_struct *ndpi_str, const char* path); 751 752 /** 753 * Read a file and load the list of malicious JA3 signatures 754 * 755 * @par ndpi_mod = the detection module 756 * @par path = the path of the file 757 * @return 0 if the file is loaded correctly; 758 * -1 else 759 */ 760 int ndpi_load_malicious_ja3_file(struct ndpi_detection_module_struct *ndpi_str, const char *path); 761 762 /** 763 * Read a file and load the list of malicious SSL certificate SHA1 fingerprints. 764 * @par ndpi_mod = the detection module 765 * @par path = the path of the file 766 * @return 0 if the file is loaded correctly; 767 * -1 else 768 */ 769 int ndpi_load_malicious_sha1_file(struct ndpi_detection_module_struct *ndpi_str, const char *path); 770 771 /** 772 * Get the total number of the supported protocols 773 * 774 * @par ndpi_mod = the detection module 775 * @return the number of protocols 776 * 777 */ 778 u_int ndpi_get_num_supported_protocols(struct ndpi_detection_module_struct *ndpi_mod); 779 780 /** 781 * Get the nDPI version release 782 * 783 * @return the NDPI_GIT_RELEASE 784 * 785 */ 786 char* ndpi_revision(void); 787 788 /** 789 * Set the automa for the protocol search 790 * 791 * @par ndpi_struct = the detection module 792 * @par automa = the automa to match 793 * 794 */ 795 void ndpi_set_automa(struct ndpi_detection_module_struct *ndpi_struct, 796 void* automa); 797 798 /* NDPI_PROTOCOL_HTTP */ 799 /** 800 * Retrieve information for HTTP flows 801 * 802 * @par ndpi_mod = the detection module 803 * @par flow = the detected flow 804 * @return the HTTP method information about the flow 805 * 806 */ 807 ndpi_http_method ndpi_get_http_method(struct ndpi_detection_module_struct *ndpi_mod, 808 struct ndpi_flow_struct *flow); 809 810 /** 811 * Get the HTTP url 812 * 813 * @par ndpi_mod = the detection module 814 * @par flow = the detected flow 815 * @return the HTTP method information about the flow 816 * 817 */ 818 char* ndpi_get_http_url(struct ndpi_detection_module_struct *ndpi_mod, 819 struct ndpi_flow_struct *flow); 820 821 /** 822 * Get the HTTP content-type 823 * 824 * @par ndpi_mod = the detection module 825 * @par flow = the detected flow 826 * @return the HTTP method information about the flow 827 * 828 */ 829 char* ndpi_get_http_content_type(struct ndpi_detection_module_struct *ndpi_mod, 830 struct ndpi_flow_struct *flow); 831 832 /* NDPI_PROTOCOL_TOR */ 833 /** 834 * Check if the flow could be detected as TOR protocol 835 * 836 * @par ndpi_struct = the detection module 837 * @par flow = the detected flow 838 * @par certificate = the SSL/TLS certificate 839 * @return 1 if the flow is TOR; 840 * 0 else 841 * 842 */ 843 int ndpi_is_tls_tor(struct ndpi_detection_module_struct *ndpi_struct, 844 struct ndpi_flow_struct *flow, char *certificate); 845 846 /* Wrappers functions */ 847 /** 848 * Init Aho-Corasick automata 849 * 850 * @return The requested automata, or NULL if an error occurred 851 * 852 */ 853 void* ndpi_init_automa(void); 854 855 /** 856 * Free Aho-Corasick automata allocated with ndpi_init_automa(); 857 * 858 * @par The automata initialized with ndpi_init_automa(); 859 * 860 */ 861 void ndpi_free_automa(void *_automa); 862 863 /** 864 * Add a string to match to an automata 865 * 866 * @par The automata initialized with ndpi_init_automa(); 867 * @par The (sub)string to search (malloc'ed memory) 868 * @par The number associated with this string 869 * @return 0 in case of no error, or -1 if an error occurred. 870 * 871 */ 872 int ndpi_add_string_value_to_automa(void *_automa, char *str, u_int32_t num); 873 874 /** 875 * Add a string to match to an automata. Same as ndpi_add_string_value_to_automa() with num set to 1 876 * 877 * @par The automata initialized with ndpi_init_automa(); 878 * @par The (sub)string to search (malloc'ed memory) 879 * @return 0 in case of no error, or -1 if an error occurred. 880 * 881 */ 882 int ndpi_add_string_to_automa(void *_automa, char *str); 883 884 /** 885 * Finalize the automa (necessary before start searching) 886 * 887 * @par The automata initialized with ndpi_init_automa(); 888 * 889 */ 890 void ndpi_finalize_automa(void *_automa); 891 892 /** 893 * Add a string to match to an automata 894 * 895 * @par The automata initialized with ndpi_init_automa(); 896 * @par The (sub)string to search 897 * @return 0 in case of match, or -1 if no match, or -2 if an error occurred. 898 * 899 */ 900 int ndpi_match_string(void *_automa, char *string_to_match); 901 902 int ndpi_load_ip_category(struct ndpi_detection_module_struct *ndpi_struct, 903 const char *ip_address_and_mask, ndpi_protocol_category_t category); 904 int ndpi_load_hostname_category(struct ndpi_detection_module_struct *ndpi_struct, 905 const char *name_to_add, ndpi_protocol_category_t category); 906 int ndpi_load_category(struct ndpi_detection_module_struct *ndpi_struct, 907 const char *ip_or_name, ndpi_protocol_category_t category); 908 int ndpi_enable_loaded_categories(struct ndpi_detection_module_struct *ndpi_struct); 909 int ndpi_fill_ip_protocol_category(struct ndpi_detection_module_struct *ndpi_struct, 910 u_int32_t saddr, 911 u_int32_t daddr, 912 ndpi_protocol *ret); 913 int ndpi_match_custom_category(struct ndpi_detection_module_struct *ndpi_struct, 914 char *name, u_int name_len, ndpi_protocol_category_t *id); 915 void ndpi_fill_protocol_category(struct ndpi_detection_module_struct *ndpi_struct, 916 struct ndpi_flow_struct *flow, 917 ndpi_protocol *ret); 918 int ndpi_get_custom_category_match(struct ndpi_detection_module_struct *ndpi_struct, 919 char *name_or_ip, u_int name_len, 920 ndpi_protocol_category_t *id); 921 int ndpi_set_detection_preferences(struct ndpi_detection_module_struct *ndpi_mod, 922 ndpi_detection_preference pref, 923 int value); 924 925 /* Tells to called on what l4 protocol given application protocol can be found */ 926 ndpi_l4_proto_info ndpi_get_l4_proto_info(struct ndpi_detection_module_struct *ndpi_struct, u_int16_t ndpi_proto_id); 927 const char* ndpi_get_l4_proto_name(ndpi_l4_proto_info proto); 928 929 u_int16_t ndpi_get_lower_proto(ndpi_protocol proto); 930 u_int16_t ndpi_get_upper_proto(ndpi_protocol proto); 931 932 ndpi_proto_defaults_t* ndpi_get_proto_defaults(struct ndpi_detection_module_struct *ndpi_mod); 933 u_int ndpi_get_ndpi_num_supported_protocols(struct ndpi_detection_module_struct *ndpi_mod); 934 u_int ndpi_get_ndpi_num_custom_protocols(struct ndpi_detection_module_struct *ndpi_mod); 935 u_int ndpi_get_ndpi_detection_module_size(void); 936 void ndpi_set_log_level(struct ndpi_detection_module_struct *ndpi_mod, u_int l); 937 void ndpi_set_debug_bitmask(struct ndpi_detection_module_struct *ndpi_mod, NDPI_PROTOCOL_BITMASK debug_bitmask); 938 939 /* LRU cache */ 940 struct ndpi_lru_cache* ndpi_lru_cache_init(u_int32_t num_entries); 941 void ndpi_lru_free_cache(struct ndpi_lru_cache *c); 942 u_int8_t ndpi_lru_find_cache(struct ndpi_lru_cache *c, u_int32_t key, 943 u_int16_t *value, u_int8_t clean_key_when_found); 944 void ndpi_lru_add_to_cache(struct ndpi_lru_cache *c, u_int32_t key, u_int16_t value); 945 946 /** 947 * Find a protocol id associated with a string automata 948 * 949 * @par The automata initialized with ndpi_init_automa(); 950 * @par The (sub)string to search 951 * @par The (sub)string length 952 * @par The protocol id associated with the matched string or 0 id not found. 953 * @return 0 in case of match, or -1 if no match, or -2 if an error occurred. 954 * 955 */ 956 int ndpi_match_string_protocol_id(void *_automa, char *string_to_match, u_int match_len, 957 u_int16_t *protocol_id, 958 ndpi_protocol_category_t *category, 959 ndpi_protocol_breed_t *breed); 960 961 /* Utility functions to set ndpi malloc/free/print wrappers */ 962 void set_ndpi_malloc(void* (*__ndpi_malloc)(size_t size)); 963 void set_ndpi_free(void (*__ndpi_free)(void *ptr)); 964 void set_ndpi_flow_malloc(void* (*__ndpi_flow_malloc)(size_t size)); 965 void set_ndpi_flow_free(void (*__ndpi_flow_free)(void *ptr)); 966 void set_ndpi_debug_function(struct ndpi_detection_module_struct *ndpi_str, 967 ndpi_debug_function_ptr ndpi_debug_printf); 968 u_int16_t ndpi_get_api_version(void); 969 const char *ndpi_get_gcrypt_version(void); 970 971 /* https://github.com/corelight/community-id-spec */ 972 int ndpi_flowv4_flow_hash(u_int8_t l4_proto, u_int32_t src_ip, u_int32_t dst_ip, u_int16_t src_port, u_int16_t dst_port, 973 u_int8_t icmp_type, u_int8_t icmp_code, u_char *hash_buf, u_int8_t hash_buf_len); 974 int ndpi_flowv6_flow_hash(u_int8_t l4_proto, struct ndpi_in6_addr *src_ip, struct ndpi_in6_addr *dst_ip, 975 u_int16_t src_port, u_int16_t dst_port, u_int8_t icmp_type, u_int8_t icmp_code, 976 u_char *hash_buf, u_int8_t hash_buf_len); 977 u_int8_t ndpi_extra_dissection_possible(struct ndpi_detection_module_struct *ndpi_struct, 978 struct ndpi_flow_struct *flow); 979 u_int8_t ndpi_is_safe_ssl_cipher(u_int32_t cipher); 980 const char* ndpi_cipher2str(u_int32_t cipher); 981 const char* ndpi_tunnel2str(ndpi_packet_tunnel tt); 982 u_int16_t ndpi_guess_host_protocol_id(struct ndpi_detection_module_struct *ndpi_struct, 983 struct ndpi_flow_struct *flow); 984 int ndpi_has_human_readeable_string(struct ndpi_detection_module_struct *ndpi_struct, 985 char *buffer, u_int buffer_size, 986 u_int8_t min_string_match_len, /* Will return 0 if no string > min_string_match_len have been found */ 987 char *outbuf, u_int outbuf_len); 988 /* Return a flow info string (summarized). Does only work for DNS/HTTP/TLS/QUIC. */ 989 const char* ndpi_get_flow_info(struct ndpi_flow_struct const * const flow, 990 ndpi_protocol const * const l7_protocol); 991 char* ndpi_ssl_version2str(struct ndpi_flow_struct *flow, 992 u_int16_t version, u_int8_t *unknown_tls_version); 993 int ndpi_netbios_name_interpret(u_char *in, u_int in_len, u_char *out, u_int out_len); 994 void ndpi_patchIPv6Address(char *str); 995 void ndpi_user_pwd_payload_copy(u_int8_t *dest, u_int dest_len, u_int offset, 996 const u_int8_t *src, u_int src_len); 997 u_char* ndpi_base64_decode(const u_char *src, size_t len, size_t *out_len); 998 char* ndpi_base64_encode(unsigned char const* bytes_to_encode, size_t in_len); /* NOTE: caller MUST free the returned pointer */ 999 void ndpi_string_sha1_hash(const uint8_t *message, size_t len, u_char *hash /* 20-bytes */); 1000 1001 int ndpi_load_ipv4_ptree(struct ndpi_detection_module_struct *ndpi_str, 1002 const char *path, u_int16_t protocol_id); 1003 int ndpi_dpi2json(struct ndpi_detection_module_struct *ndpi_struct, 1004 struct ndpi_flow_struct *flow, 1005 ndpi_protocol l7_protocol, 1006 ndpi_serializer *serializer); 1007 int ndpi_flow2json(struct ndpi_detection_module_struct *ndpi_struct, 1008 struct ndpi_flow_struct *flow, 1009 u_int8_t ip_version, 1010 u_int8_t l4_protocol, u_int16_t vlan_id, 1011 u_int32_t src_v4, u_int32_t dst_v4, 1012 struct ndpi_in6_addr *src_v6, struct ndpi_in6_addr *dst_v6, 1013 u_int16_t src_port, u_int16_t dst_port, 1014 ndpi_protocol l7_protocol, 1015 ndpi_serializer *serializer); 1016 1017 void ndpi_md5(const u_char *data, size_t data_len, u_char hash[16]); 1018 u_int32_t ndpi_quick_hash(unsigned char *str, u_int str_len); 1019 1020 const char* ndpi_http_method2str(ndpi_http_method m); 1021 ndpi_http_method ndpi_http_str2method(const char* method, u_int16_t method_len); 1022 1023 /* Utility functions to fill prefix (used by the patricia tree) */ 1024 int ndpi_fill_prefix_v4(ndpi_prefix_t *p, const struct in_addr *a, int b, int mb); 1025 int ndpi_fill_prefix_v6(ndpi_prefix_t *prefix, const struct in6_addr *addr, int bits, int maxbits); 1026 int ndpi_fill_prefix_mac(ndpi_prefix_t *prefix, u_int8_t *mac, int bits, int maxbits); 1027 1028 /* Patricia tree API (radix tree supporting IPv4/IPv6/MAC) */ 1029 ndpi_patricia_tree_t *ndpi_patricia_new(u_int16_t maxbits); 1030 ndpi_patricia_tree_t *ndpi_patricia_clone (const ndpi_patricia_tree_t * const from); 1031 void ndpi_patricia_destroy(ndpi_patricia_tree_t *patricia, ndpi_void_fn_t func); 1032 1033 ndpi_patricia_node_t *ndpi_patricia_search_exact(ndpi_patricia_tree_t *patricia, ndpi_prefix_t *prefix); 1034 ndpi_patricia_node_t *ndpi_patricia_search_best(ndpi_patricia_tree_t *patricia, ndpi_prefix_t *prefix); 1035 ndpi_patricia_node_t *ndpi_patricia_lookup(ndpi_patricia_tree_t *patricia, ndpi_prefix_t *prefix); 1036 size_t ndpi_patricia_walk_tree_inorder(ndpi_patricia_tree_t *patricia, ndpi_void_fn3_t func, void *data); 1037 size_t ndpi_patricia_walk_inorder(ndpi_patricia_node_t *node, ndpi_void_fn3_t func, void *data); 1038 void ndpi_patricia_remove(ndpi_patricia_tree_t *patricia, ndpi_patricia_node_t *node); 1039 1040 void ndpi_patricia_set_node_u64(ndpi_patricia_node_t *node, u_int64_t value); 1041 u_int64_t ndpi_patricia_get_node_u64(ndpi_patricia_node_t *node); 1042 void ndpi_patricia_set_node_data(ndpi_patricia_node_t *node, void *data); 1043 void *ndpi_patricia_get_node_data(ndpi_patricia_node_t *node); 1044 ndpi_prefix_t *ndpi_patricia_get_node_prefix(ndpi_patricia_node_t *node); 1045 u_int16_t ndpi_patricia_get_node_bits(ndpi_patricia_node_t *node); 1046 u_int16_t ndpi_patricia_get_maxbits(ndpi_patricia_tree_t *tree); 1047 1048 /* ptree (trie) API - a wrapper on top of Patricia that seamlessly handle IPv4 and IPv6 */ 1049 ndpi_ptree_t* ndpi_ptree_create(void); 1050 int ndpi_ptree_insert(ndpi_ptree_t *tree, const ndpi_ip_addr_t *addr, u_int8_t bits, u_int64_t user_data); 1051 int ndpi_ptree_match_addr(ndpi_ptree_t *tree, const ndpi_ip_addr_t *addr, u_int64_t *user_data); 1052 void ndpi_ptree_destroy(ndpi_ptree_t *tree); 1053 1054 /* General purpose utilities */ 1055 u_int64_t ndpi_htonll(u_int64_t v); 1056 u_int64_t ndpi_ntohll(u_int64_t v); 1057 u_int8_t ndpi_is_valid_protoId(u_int16_t protoId); 1058 u_int8_t ndpi_is_encrypted_proto(struct ndpi_detection_module_struct *ndpi_str, ndpi_protocol proto); 1059 1060 /* DGA */ 1061 int ndpi_check_dga_name(struct ndpi_detection_module_struct *ndpi_str, 1062 struct ndpi_flow_struct *flow, 1063 char *name, u_int8_t is_hostname); 1064 1065 /* Serializer (supports JSON, TLV, CSV) */ 1066 1067 /** 1068 * Initialize a serializer handle (allocated by the caller). 1069 * @param serializer The serializer handle 1070 * @param fmt The serialization format (ndpi_serialization_format_json, ndpi_serialization_format_tlv, ndpi_serialization_format_csv) 1071 * @return 0 on success, a negative number otherwise 1072 */ 1073 int ndpi_init_serializer(ndpi_serializer *serializer, ndpi_serialization_format fmt); 1074 1075 /** 1076 * Initialize a serializer handle. Same as ndpi_init_serializer, but with some low-level settings. 1077 * @param serializer The serializer handle 1078 * @param fmt The serialization format (ndpi_serialization_format_json, ndpi_serialization_format_tlv, ndpi_serialization_format_csv) 1079 * @param buffer_size The initial internal buffer_size 1080 * @return 0 on success, a negative number otherwise 1081 */ 1082 int ndpi_init_serializer_ll(ndpi_serializer *serializer, ndpi_serialization_format fmt, u_int32_t buffer_size); 1083 1084 /** 1085 * Release all allocated data structure. 1086 * @param serializer The serializer handle 1087 */ 1088 void ndpi_term_serializer(ndpi_serializer *serializer); 1089 1090 /** 1091 * Reset the serializer (cleanup the internal buffer to start a new serialization) 1092 * @param serializer The serializer handle 1093 */ 1094 void ndpi_reset_serializer(ndpi_serializer *serializer); 1095 1096 /** 1097 * Serialize a 32-bit unsigned int key and a 32-bit unsigned int value 1098 * @param serializer The serializer handle 1099 * @param key The field name or ID 1100 * @param value The field value 1101 * @return 0 on success, a negative number otherwise 1102 */ 1103 int ndpi_serialize_uint32_uint32(ndpi_serializer *serializer, u_int32_t key, u_int32_t value); 1104 1105 /** 1106 * Serialize a 32-bit unsigned int key and a 64-bit unsigned int value 1107 * @param serializer The serializer handle 1108 * @param key The field name or ID 1109 * @param value The field value 1110 * @return 0 on success, a negative number otherwise 1111 */ 1112 int ndpi_serialize_uint32_uint64(ndpi_serializer *serializer, u_int32_t key, u_int64_t value); 1113 1114 /** 1115 * Serialize a 32-bit unsigned int key and a 32-bit signed int value 1116 * @param serializer The serializer handle 1117 * @param key The field name or ID 1118 * @param value The field value 1119 * @return 0 on success, a negative number otherwise 1120 */ 1121 int ndpi_serialize_uint32_int32(ndpi_serializer *serializer, u_int32_t key, int32_t value); 1122 1123 /** 1124 * Serialize a 32-bit unsigned int key and a 64-bit signed int value 1125 * @param serializer The serializer handle 1126 * @param key The field name or ID 1127 * @param value The field value 1128 * @return 0 on success, a negative number otherwise 1129 */ 1130 int ndpi_serialize_uint32_int64(ndpi_serializer *serializer, u_int32_t key, int64_t value); 1131 1132 /** 1133 * Serialize a 32-bit unsigned int key and a float value 1134 * @param serializer The serializer handle 1135 * @param key The field name or ID 1136 * @param value The field value 1137 * @param format The float value format 1138 * @return 0 on success, a negative number otherwise 1139 */ 1140 int ndpi_serialize_uint32_float(ndpi_serializer *serializer, u_int32_t key, float value, const char *format /* e.f. "%.2f" */); 1141 1142 /** 1143 * Serialize a 32-bit unsigned int key and a string value 1144 * @param serializer The serializer handle 1145 * @param key The field name or ID 1146 * @param value The field value 1147 * @return 0 on success, a negative number otherwise 1148 */ 1149 int ndpi_serialize_uint32_string(ndpi_serializer *serializer, u_int32_t key, const char *value); 1150 1151 /** 1152 * Serialize a 32-bit unsigned int key and a boolean value 1153 * @param serializer The serializer handle 1154 * @param key The field name or ID 1155 * @param value The field value 1156 * @return 0 on success, a negative number otherwise 1157 */ 1158 int ndpi_serialize_uint32_boolean(ndpi_serializer *serializer, u_int32_t key, u_int8_t value); 1159 1160 /** 1161 * Serialize an unterminated string key and a 32-bit signed int value 1162 * @param serializer The serializer handle 1163 * @param key The field name or ID 1164 * @param klen The key length 1165 * @param value The field value 1166 * @return 0 on success, a negative number otherwise 1167 */ 1168 int ndpi_serialize_binary_int32(ndpi_serializer *_serializer, const char *key, u_int16_t klen, int32_t value); 1169 1170 /** 1171 * Serialize a string key and a 32-bit signed int value 1172 * @param serializer The serializer handle 1173 * @param key The field name or ID 1174 * @param value The field value 1175 * @return 0 on success, a negative number otherwise 1176 */ 1177 int ndpi_serialize_string_int32(ndpi_serializer *serializer, const char *key, int32_t value); 1178 1179 /** 1180 * Serialize an unterminated string key and a 64-bit signed int value 1181 * @param serializer The serializer handle 1182 * @param key The field name or ID 1183 * @param klen The key length 1184 * @param value The field value 1185 * @return 0 on success, a negative number otherwise 1186 */ 1187 int ndpi_serialize_binary_int64(ndpi_serializer *_serializer, const char *key, u_int16_t klen, int64_t value); 1188 1189 /** 1190 * Serialize a string key and a 64-bit signed int value 1191 * @param serializer The serializer handle 1192 * @param key The field name or ID 1193 * @param value The field value 1194 * @return 0 on success, a negative number otherwise 1195 */ 1196 int ndpi_serialize_string_int64(ndpi_serializer *serializer, const char *key, int64_t value); 1197 1198 /** 1199 * Serialize an unterminated string key and a 32-bit unsigned int value 1200 * @param serializer The serializer handle 1201 * @param key The field name or ID 1202 * @param klen The key length 1203 * @param value The field value 1204 * @return 0 on success, a negative number otherwise 1205 */ 1206 int ndpi_serialize_binary_uint32(ndpi_serializer *_serializer, const char *key, u_int16_t klen, u_int32_t value); 1207 1208 /** 1209 * Serialize a string key and a 32-bit unsigned int value 1210 * @param serializer The serializer handle 1211 * @param key The field name or ID 1212 * @param value The field value 1213 * @return 0 on success, a negative number otherwise 1214 */ 1215 int ndpi_serialize_string_uint32(ndpi_serializer *serializer, const char *key, u_int32_t value); 1216 1217 /** 1218 * Serialize a string key and a float value 1219 * @param serializer The serializer handle 1220 * @param key The field name or ID 1221 * @param value The field value 1222 * @param format The float format 1223 * @return 0 on success, a negative number otherwise 1224 */ 1225 int ndpi_serialize_string_uint32_format(ndpi_serializer *serializer, const char *key, u_int32_t value, const char *format); 1226 1227 /** 1228 * Serialize an unterminated string key and a 64-bit unsigned int value 1229 * @param serializer The serializer handle 1230 * @param key The field name or ID 1231 * @param klen The key length 1232 * @param value The field value 1233 * @return 0 on success, a negative number otherwise 1234 */ 1235 int ndpi_serialize_binary_uint64(ndpi_serializer *_serializer, const char *key, u_int16_t klen, u_int64_t value); 1236 1237 /** 1238 * Serialize a string key and a 64-bit unsigned int value 1239 * @param serializer The serializer handle 1240 * @param key The field name or ID 1241 * @param value The field value 1242 * @return 0 on success, a negative number otherwise 1243 */ 1244 int ndpi_serialize_string_uint64(ndpi_serializer *serializer, const char *key, u_int64_t value); 1245 1246 /** 1247 * Serialize an unterminated string key and an unterminated string value 1248 * @param serializer The serializer handle 1249 * @param key The field name or ID 1250 * @param klen The key length 1251 * @param value The field value 1252 * @param vlen The value length 1253 * @return 0 on success, a negative number otherwise 1254 */ 1255 int ndpi_serialize_binary_binary(ndpi_serializer *_serializer, const char *key, u_int16_t klen, const char *_value, u_int16_t vlen); 1256 1257 /** 1258 * Serialize a string key and a string value 1259 * @param serializer The serializer handle 1260 * @param key The field name or ID 1261 * @param value The field value 1262 * @return 0 on success, a negative number otherwise 1263 */ 1264 int ndpi_serialize_string_string(ndpi_serializer *serializer, const char *key, const char *value); 1265 1266 /** 1267 * Serialize a string key and an unterminated string value 1268 * @param serializer The serializer handle 1269 * @param key The field name or ID 1270 * @param value The field value 1271 * @param vlen The value length 1272 * @return 0 on success, a negative number otherwise 1273 */ 1274 int ndpi_serialize_string_binary(ndpi_serializer *serializer, const char *key, const char *_value, u_int16_t vlen); 1275 1276 /** 1277 * Serialize a string key and a raw value (this is a string which is added to the JSON without any quote or escaping) 1278 * @param serializer The serializer handle 1279 * @param key The field name or ID 1280 * @param value The field value 1281 * @param vlen The value length 1282 * @return 0 on success, a negative number otherwise 1283 */ 1284 int ndpi_serialize_string_raw(ndpi_serializer *_serializer, const char *key, const char *_value, u_int16_t vlen); 1285 1286 /** 1287 * Serialize an unterminated string key and a float value 1288 * @param serializer The serializer handle 1289 * @param key The field name or ID 1290 * @param klen The key length 1291 * @param value The field value 1292 * @param format The float format 1293 * @return 0 on success, a negative number otherwise 1294 */ 1295 int ndpi_serialize_binary_float(ndpi_serializer *_serializer, const char *key, u_int16_t klen, float value, const char *format /* e.f. "%.2f" */); 1296 1297 /** 1298 * Serialize a string key and a a float value 1299 * @param serializer The serializer handle 1300 * @param key The field name or ID 1301 * @param value The field value 1302 * @param format The float format 1303 * @return 0 on success, a negative number otherwise 1304 */ 1305 int ndpi_serialize_string_float(ndpi_serializer *serializer, const char *key, float value, const char *format /* e.f. "%.2f" */); 1306 1307 /** 1308 * Serialize an unterminated string key and a boolean value (JSON/CSV only, not supported by TLV) 1309 * @param serializer The serializer handle 1310 * @param key The field name or ID 1311 * @param klen The key length 1312 * @param value The field value 1313 * @return 0 on success, a negative number otherwise 1314 */ 1315 int ndpi_serialize_binary_boolean(ndpi_serializer *_serializer, const char *key, u_int16_t klen, u_int8_t value); 1316 1317 /** 1318 * Serialize a string key and a boolean value (JSON/CSV only, not supported by TLV) 1319 * @param serializer The serializer handle 1320 * @param key The field name or ID 1321 * @param value The field value 1322 * @return 0 on success, a negative number otherwise 1323 */ 1324 int ndpi_serialize_string_boolean(ndpi_serializer *serializer, const char *key, u_int8_t value); 1325 1326 /** 1327 * Serialize a raw record in an array (this is a low-level function and its use is not recommended) 1328 * @param serializer The serializer handle 1329 * @param record The record value 1330 * @param record_len The record length 1331 * @return 0 on success, a negative number otherwise 1332 */ 1333 int ndpi_serialize_raw_record(ndpi_serializer *_serializer, u_char *record, u_int32_t record_len); 1334 1335 /** 1336 * Serialize an End-Of-Record (the current object becomes is terminated and added to an array, 1337 * and a new object is created where the next items will be added) 1338 * @param serializer The serializer handle 1339 * @return 0 on success, a negative number otherwise 1340 */ 1341 int ndpi_serialize_end_of_record(ndpi_serializer *serializer); 1342 1343 /** 1344 * Serialize the start of a list with an unterminated string key, where the next serialized items 1345 * will be added (note: keys for the new items are ignored) 1346 * @param serializer The serializer handle 1347 * @param key The field name or ID 1348 * @param klen The key length 1349 * @return 0 on success, a negative number otherwise 1350 */ 1351 int ndpi_serialize_start_of_list_binary(ndpi_serializer *_serializer, const char *key, u_int16_t klen); 1352 1353 /** 1354 * Serialize the start of a list, where the next serialized items will be added (note: keys for 1355 * the new items are ignored) 1356 * @param serializer The serializer handle 1357 * @param key The field name or ID 1358 * @param value The field value 1359 * @return 0 on success, a negative number otherwise 1360 */ 1361 int ndpi_serialize_start_of_list(ndpi_serializer *serializer, const char *key); 1362 1363 /** 1364 * Serialize the end of a list 1365 * @param serializer The serializer handle 1366 * @return 0 on success, a negative number otherwise 1367 */ 1368 int ndpi_serialize_end_of_list(ndpi_serializer *serializer); 1369 1370 /** 1371 * Serialize the start of a block with an unterminated string key 1372 * @param serializer The serializer handle 1373 * @param key The field name or ID 1374 * @param klen The key length 1375 * @return 0 on success, a negative number otherwise 1376 */ 1377 int ndpi_serialize_start_of_block_binary(ndpi_serializer *_serializer, const char *key, u_int16_t klen); 1378 1379 /** 1380 * Serialize the start of a block with a string key 1381 * @param serializer The serializer handle 1382 * @param key The field name or ID 1383 * @return 0 on success, a negative number otherwise 1384 */ 1385 int ndpi_serialize_start_of_block(ndpi_serializer *serializer, const char *key); 1386 1387 /** 1388 * Serialize the end of a block 1389 * @param serializer The serializer handle 1390 * @param key The field name or ID 1391 * @param value The field value 1392 * @return 0 on success, a negative number otherwise 1393 */ 1394 int ndpi_serialize_end_of_block(ndpi_serializer *serializer); 1395 1396 /** 1397 * Return the serialized buffer 1398 * @param serializer The serializer handle 1399 * @param buffer_len The buffer length (out) 1400 * @return The buffer 1401 */ 1402 char* ndpi_serializer_get_buffer(ndpi_serializer *serializer, u_int32_t *buffer_len); 1403 1404 /** 1405 * Return the current serialized buffer length 1406 * @param serializer The serializer handle 1407 * @return The buffer length 1408 */ 1409 u_int32_t ndpi_serializer_get_buffer_len(ndpi_serializer *serializer); 1410 1411 /** 1412 * Return the real internal buffer size (containing the serialized buffer) 1413 * @param serializer The serializer handle 1414 * @return The internal buffer size 1415 */ 1416 u_int32_t ndpi_serializer_get_internal_buffer_size(ndpi_serializer *serializer); 1417 1418 /** 1419 * Change the serializer buffer length 1420 * @param serializer The serializer handle 1421 * @param l The new buffer length 1422 * @return 0 on success, a negative number otherwise 1423 */ 1424 int ndpi_serializer_set_buffer_len(ndpi_serializer *serializer, u_int32_t l); 1425 1426 /** 1427 * Return the configured serialization format 1428 * @param serializer The serializer handle 1429 * @return The serialization format 1430 */ 1431 ndpi_serialization_format ndpi_serializer_get_format(ndpi_serializer *serializer); 1432 1433 /** 1434 * Set the CSV separator 1435 * @param serializer The serializer handle 1436 * @param separator The separator 1437 */ 1438 void ndpi_serializer_set_csv_separator(ndpi_serializer *serializer, char separator); 1439 1440 /** 1441 * Return the header automatically built from keys (CSV only) 1442 * @param serializer The serializer handle 1443 * @param buffer_len The buffer length (out) 1444 * @return The header 1445 */ 1446 char* ndpi_serializer_get_header(ndpi_serializer *serializer, u_int32_t *buffer_len); 1447 1448 /** 1449 * Create a snapshot of the internal buffer for later rollback (ndpi_serializer_rollback_snapshot) 1450 * @param serializer The serializer handle 1451 */ 1452 void ndpi_serializer_create_snapshot(ndpi_serializer *serializer); 1453 1454 /** 1455 * Rollback to the latest snapshot 1456 * @param serializer The serializer handle 1457 */ 1458 void ndpi_serializer_rollback_snapshot(ndpi_serializer *serializer); 1459 1460 /* Deserializer (supports TLV only) */ 1461 1462 int ndpi_init_deserializer(ndpi_deserializer *deserializer, 1463 ndpi_serializer *serializer); 1464 int ndpi_init_deserializer_buf(ndpi_deserializer *deserializer, 1465 u_int8_t *serialized_buffer, 1466 u_int32_t serialized_buffer_len); 1467 1468 ndpi_serialization_format ndpi_deserialize_get_format(ndpi_deserializer *_deserializer); 1469 ndpi_serialization_type ndpi_deserialize_get_item_type(ndpi_deserializer *deserializer, ndpi_serialization_type *key_type); 1470 int ndpi_deserialize_next(ndpi_deserializer *deserializer); 1471 1472 int ndpi_deserialize_key_uint32(ndpi_deserializer *deserializer, u_int32_t *key); 1473 int ndpi_deserialize_key_string(ndpi_deserializer *deserializer, ndpi_string *key); 1474 1475 int ndpi_deserialize_value_uint32(ndpi_deserializer *deserializer, u_int32_t *value); 1476 int ndpi_deserialize_value_uint64(ndpi_deserializer *deserializer, u_int64_t *value); 1477 int ndpi_deserialize_value_int32(ndpi_deserializer *deserializer, int32_t *value); 1478 int ndpi_deserialize_value_int64(ndpi_deserializer *deserializer, int64_t *value); 1479 int ndpi_deserialize_value_float(ndpi_deserializer *deserializer, float *value); 1480 int ndpi_deserialize_value_string(ndpi_deserializer *deserializer, ndpi_string *value); 1481 1482 int ndpi_deserialize_clone_item(ndpi_deserializer *deserializer, ndpi_serializer *serializer); 1483 int ndpi_deserialize_clone_all(ndpi_deserializer *deserializer, ndpi_serializer *serializer); 1484 1485 /* Data analysis */ 1486 struct ndpi_analyze_struct* ndpi_alloc_data_analysis(u_int16_t _max_series_len); 1487 void ndpi_init_data_analysis(struct ndpi_analyze_struct *s, u_int16_t _max_series_len); 1488 void ndpi_free_data_analysis(struct ndpi_analyze_struct *d, u_int8_t free_pointer); 1489 void ndpi_reset_data_analysis(struct ndpi_analyze_struct *d); 1490 void ndpi_data_add_value(struct ndpi_analyze_struct *s, const u_int32_t value); 1491 1492 /* Sliding-window only */ 1493 float ndpi_data_window_average(struct ndpi_analyze_struct *s); 1494 float ndpi_data_window_variance(struct ndpi_analyze_struct *s); 1495 float ndpi_data_window_stddev(struct ndpi_analyze_struct *s); 1496 1497 /* All data */ 1498 float ndpi_data_average(struct ndpi_analyze_struct *s); 1499 float ndpi_data_entropy(struct ndpi_analyze_struct *s); 1500 float ndpi_data_variance(struct ndpi_analyze_struct *s); 1501 float ndpi_data_stddev(struct ndpi_analyze_struct *s); 1502 u_int32_t ndpi_data_last(struct ndpi_analyze_struct *s); 1503 u_int32_t ndpi_data_min(struct ndpi_analyze_struct *s); 1504 u_int32_t ndpi_data_max(struct ndpi_analyze_struct *s); 1505 float ndpi_data_ratio(u_int32_t sent, u_int32_t rcvd); 1506 1507 /* ******************************* */ 1508 1509 int ndpi_alloc_rsi(struct ndpi_rsi_struct *s, u_int16_t num_learning_values); 1510 void ndpi_free_rsi(struct ndpi_rsi_struct *s); 1511 float ndpi_rsi_add_value(struct ndpi_rsi_struct *s, const u_int32_t value); 1512 1513 /* ******************************* */ 1514 1515 int ndpi_hw_init(struct ndpi_hw_struct *hw, u_int16_t num_periods, u_int8_t additive_seeasonal, 1516 double alpha, double beta, double gamma, float significance); 1517 void ndpi_hw_free(struct ndpi_hw_struct *hw); 1518 int ndpi_hw_add_value(struct ndpi_hw_struct *hw, const u_int64_t value, double *forecast, double *confidence_band); 1519 1520 /* ******************************* */ 1521 1522 int ndpi_ses_init(struct ndpi_ses_struct *ses, double alpha, float significance); 1523 int ndpi_ses_add_value(struct ndpi_ses_struct *ses, const u_int64_t _value, double *forecast, double *confidence_band); 1524 1525 /* ******************************* */ 1526 1527 int ndpi_des_init(struct ndpi_des_struct *des, double alpha, double beta, float significance); 1528 int ndpi_des_add_value(struct ndpi_des_struct *des, const u_int64_t _value, double *forecast, double *confidence_band); 1529 1530 /* ******************************* */ 1531 1532 int ndpi_jitter_init(struct ndpi_jitter_struct *hw, u_int16_t num_periods); 1533 void ndpi_jitter_free(struct ndpi_jitter_struct *hw); 1534 float ndpi_jitter_add_value(struct ndpi_jitter_struct *s, const float value); 1535 1536 /* ******************************* */ 1537 1538 const char* ndpi_data_ratio2str(float ratio); 1539 1540 void ndpi_data_print_window_values(struct ndpi_analyze_struct *s); /* debug */ 1541 1542 ndpi_risk_enum ndpi_validate_url(char *url); 1543 1544 u_int8_t ndpi_is_protocol_detected(struct ndpi_detection_module_struct *ndpi_str, 1545 ndpi_protocol proto); 1546 void ndpi_serialize_risk(ndpi_serializer *serializer, struct ndpi_flow_struct *flow); 1547 1548 const char* ndpi_risk2str(ndpi_risk_enum risk); 1549 const char* ndpi_severity2str(ndpi_risk_severity s); 1550 ndpi_risk_info* ndpi_risk2severity(ndpi_risk_enum risk); 1551 u_int16_t ndpi_risk2score(ndpi_risk risk, 1552 u_int16_t *client_score, u_int16_t *server_score); 1553 1554 /* ******************************* */ 1555 1556 /* HyperLogLog cardinality estimator */ 1557 1558 /* Memory lifecycle */ 1559 int ndpi_hll_init(struct ndpi_hll *hll, u_int8_t bits); 1560 void ndpi_hll_destroy(struct ndpi_hll *hll); 1561 void ndpi_hll_reset(struct ndpi_hll *hll); 1562 1563 /* Add values */ 1564 void ndpi_hll_add(struct ndpi_hll *hll, const char *data, size_t data_len); 1565 void ndpi_hll_add_number(struct ndpi_hll *hll, u_int32_t value) ; 1566 1567 /* Get cardinality estimation */ 1568 double ndpi_hll_count(struct ndpi_hll *hll); 1569 1570 /* ******************************* */ 1571 1572 int ndpi_init_bin(struct ndpi_bin *b, enum ndpi_bin_family f, u_int8_t num_bins); 1573 void ndpi_free_bin(struct ndpi_bin *b); 1574 struct ndpi_bin* ndpi_clone_bin(struct ndpi_bin *b); 1575 void ndpi_inc_bin(struct ndpi_bin *b, u_int8_t slot_id, u_int32_t val); 1576 void ndpi_set_bin(struct ndpi_bin *b, u_int8_t slot_id, u_int32_t value); 1577 u_int32_t ndpi_get_bin_value(struct ndpi_bin *b, u_int8_t slot_id); 1578 void ndpi_reset_bin(struct ndpi_bin *b); 1579 void ndpi_normalize_bin(struct ndpi_bin *b); 1580 char* ndpi_print_bin(struct ndpi_bin *b, u_int8_t normalize_first, char *out_buf, u_int out_buf_len); 1581 float ndpi_bin_similarity(struct ndpi_bin *b1, struct ndpi_bin *b2, u_int8_t normalize_first); 1582 int ndpi_cluster_bins(struct ndpi_bin *bins, u_int16_t num_bins, 1583 u_int8_t num_clusters, u_int16_t *cluster_ids, 1584 struct ndpi_bin *centroids); 1585 1586 /* ******************************* */ 1587 1588 u_int32_t ndpi_quick_16_byte_hash(u_int8_t *in_16_bytes_long); 1589 1590 /* ******************************* */ 1591 1592 ndpi_str_hash* ndpi_hash_alloc(u_int32_t max_num_entries); 1593 void ndpi_hash_free(ndpi_str_hash *h); 1594 int ndpi_hash_find_entry(ndpi_str_hash *h, char *key, u_int key_len, u_int8_t *value); 1595 int ndpi_hash_add_entry(ndpi_str_hash *h, char *key, u_int8_t key_len, u_int8_t value); 1596 1597 /* ******************************* */ 1598 1599 int ndpi_load_geoip(struct ndpi_detection_module_struct *ndpi_str, 1600 const char *ip_city_data, const char *ip_as_data); 1601 void ndpi_free_geoip(struct ndpi_detection_module_struct *ndpi_str); 1602 int ndpi_get_geoip_asn(struct ndpi_detection_module_struct *ndpi_str, 1603 char *ip, u_int32_t *asn); 1604 int ndpi_get_geoip_country_continent(struct ndpi_detection_module_struct *ndpi_str, char *ip, 1605 char *country_code, u_int8_t country_code_len, 1606 char *continent, u_int8_t continent_len); 1607 1608 /* ******************************* */ 1609 1610 char* ndpi_get_flow_name(struct ndpi_flow_struct *flow); 1611 1612 /* ******************************* */ 1613 1614#ifdef __cplusplus 1615} 1616#endif 1617 1618#endif /* __NDPI_API_H__ */ 1619