1 /* 2 * 3 ** @file yafcore.h 4 ** YAF core I/O routines 5 ** 6 ** ------------------------------------------------------------------------ 7 ** Copyright (C) 2006-2015 Carnegie Mellon University. All Rights Reserved. 8 ** ------------------------------------------------------------------------ 9 ** Authors: Brian Trammell 10 ** ------------------------------------------------------------------------ 11 ** Use of the YAF system and related source code is subject to the terms 12 ** of the following licenses: 13 ** 14 ** GNU Public License (GPL) Rights pursuant to Version 2, June 1991 15 ** Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013 16 ** 17 ** NO WARRANTY 18 ** 19 ** ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER 20 ** PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY 21 ** PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN 22 ** "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY 23 ** KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT 24 ** LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE, 25 ** MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE 26 ** OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT, 27 ** SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY 28 ** TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF 29 ** WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES. 30 ** LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF 31 ** CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON 32 ** CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE 33 ** DELIVERABLES UNDER THIS LICENSE. 34 ** 35 ** Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie 36 ** Mellon University, its trustees, officers, employees, and agents from 37 ** all claims or demands made against them (and any related losses, 38 ** expenses, or attorney's fees) arising out of, or relating to Licensee's 39 ** and/or its sub licensees' negligent use or willful misuse of or 40 ** negligent conduct or willful misconduct regarding the Software, 41 ** facilities, or other rights or assistance granted by Carnegie Mellon 42 ** University under this License, including, but not limited to, any 43 ** claims of product liability, personal injury, death, damage to 44 ** property, or violation of any laws or regulations. 45 ** 46 ** Carnegie Mellon University Software Engineering Institute authored 47 ** documents are sponsored by the U.S. Department of Defense under 48 ** Contract FA8721-05-C-0003. Carnegie Mellon University retains 49 ** copyrights in all material produced under this contract. The U.S. 50 ** Government retains a non-exclusive, royalty-free license to publish or 51 ** reproduce these documents, or allow others to do so, for U.S. 52 ** Government purposes only pursuant to the copyright license under the 53 ** contract clause at 252.227.7013. 54 ** 55 ** ------------------------------------------------------------------------ 56 */ 57 58 /** 59 * @mainpage YAF Core Library 60 * 61 * @section Introduction 62 * 63 * The YAF Core Library (libyaf) provides YAF file and stream I/O primitives 64 * for reading and writing YAF bidirectional flow data in IPFIX files and via 65 * the IPFIX protocol. It also provides packet decode, fragment reassembly, 66 * and flow generation routines for YAF. 67 * 68 * yafcore.h provides the YAF I/O interface. The packet decode interface is 69 * defined in decode.h. The fragment reassembly interface is defined in 70 * yafrag.h, and the flow generator interface is defined in yaftab.h. 71 * 72 * picq.h defines a generic pickable queue used in fragment reassembly and 73 * flow generation. 74 * 75 * @section Building 76 * 77 * The YAF Core Library is automatically built and installed as part of the 78 * YAF installation process. 79 * 80 * @section Copyright 81 * YAF is copyright 2006-2015 Carnegie Mellon University, and is released 82 * under the GNU General Public License. See the COPYING file in the 83 * distribution for details. 84 * 85 * YAF was developed at the CERT Network Situational Awareness Group by 86 * Brian Trammell and the CERT Network Situational Awareness Group Engineering 87 * Team. 88 * 89 */ 90 91 /** 92 * @file 93 * 94 * YAF Core Library. Defines API for reading and writing YAF files, and the 95 * yfFlow_t data structures. 96 */ 97 98 #ifndef _YAF_CORE_H_ 99 #define _YAF_CORE_H_ 100 101 #include <yaf/autoinc.h> 102 #include <fixbuf/public.h> 103 #include <stdlib.h> 104 #include <math.h> 105 /** 106 * This is the CERT Private Enterprise Number (PEN) assigned by 107 * IANA, used to define our enterprise data elements to extend 108 * IPFIX RFC 5103 data model 109 */ 110 #define CERT_PEN 6871 111 112 /** 113 * GError domain for YAF errors. All YAF errors belong to this domain. 114 * In addition, YAF core library routines can return libfixbuf errors if 115 * reading or writing fails. 116 */ 117 #define YAF_ERROR_DOMAIN (g_quark_from_string("certYAFError")) 118 /** A YAF file header was malformed. The file is probably not a YAF file. */ 119 #define YAF_ERROR_HEADER 1 120 /** Illegal argument error. */ 121 #define YAF_ERROR_ARGUMENT 2 122 /** General I/O error */ 123 #define YAF_ERROR_IO 3 124 /** YAF could not accept IPFIX input due to missing fields. */ 125 #define YAF_ERROR_IPFIX 4 126 /** Requested feature is not available */ 127 #define YAF_ERROR_IMPL 5 128 /** Internal error occured (aka a bug)*/ 129 #define YAF_ERROR_INTERNAL 6 130 /** Hard program limit reached */ 131 #define YAF_ERROR_LIMIT 7 132 /** End of file */ 133 #define YAF_ERROR_EOF 8 134 /** Internal alignment error */ 135 #define YAF_ERROR_ALIGNMENT 9 136 /** Packet payload processing error */ 137 #define YAF_ERROR_PACKET_PAYLOAD 10 138 139 140 141 /** 142 * Pseudo end reason for flows still active during collection. 143 * Not valid on disk. 144 */ 145 #define YAF_FLOW_ACTIVE 0 146 /** Flow ended due to idle timeout. */ 147 #define YAF_END_IDLE 1 148 /** Flow ended due to active timeout. */ 149 #define YAF_END_ACTIVE 2 150 /** Flow ended due to FIN or RST close. */ 151 #define YAF_END_CLOSED 3 152 /** Flow ended due to YAF shutdown. */ 153 #define YAF_END_FORCED 4 154 /** Flow flushed due to YAF resource exhaustion. */ 155 #define YAF_END_RESOURCE 5 156 /** Flow flushed due to udp-uniflow on all or selected ports.*/ 157 #define YAF_END_UDPFORCE 0x1F 158 /** Flow has same size packets in this direction */ 159 #define YAF_SAME_SIZE 0x01 160 /** Flow was processed out of sequence */ 161 #define YAF_OUT_OF_SEQUENCE 0x02 162 /** Flow had MP_CAPABLE TCP Option */ 163 #define YAF_MP_CAPABLE 0x04 164 /** Flow contained packets that were fragmented */ 165 #define YAF_FRAGMENTS 0x08 166 /** Flow contains partial fragments */ 167 #define YAF_PARTIAL_FRAGS 0x10 168 /** Flow has fragments that have reached active timeout */ 169 #define YAF_FRAG_ACTIVE 0x03 170 /** Flow has fragments that have reached passive timeout */ 171 #define YAF_FRAG_PASSIVE 0x04 172 /** Flow reason mask */ 173 #define YAF_END_MASK 0x7F 174 175 /** SiLK mode flow reason flag - flow was created after active termination */ 176 #define YAF_ENDF_ISCONT 0x80 177 178 /** IP protocol identifier for ICMP */ 179 #define YAF_IP_ICMP 1 180 /** IP protocol identifier for TCP */ 181 #define YAF_IP_TCP 6 182 /** IP protocol identifier for UDP */ 183 #define YAF_IP_UDP 17 184 185 /** This is the size of the packet to store away for use primarily in 186 passive OS fingerprinting, this value is only used if application 187 labeling is enabled */ 188 #define YFP_IPTCPHEADER_SIZE 128 189 /** length of Ethernet MAC Address */ 190 #define ETHERNET_MAC_ADDR_LENGTH 6 191 /** maximum number of hooks (plugins) allowed at one time */ 192 #define YAF_MAX_HOOKS 4 193 194 /** this is the maximum amount of data that the plugins may export in sum total 195 */ 196 #define YAF_HOOKS_MAX_EXPORT 1500 197 /** Maximum Number of Packet Boundaries to keep around per payload */ 198 #define YAF_MAX_PKT_BOUNDARY 25 199 /** Maximum length of PCAP output file - 5MB */ 200 #define YAF_PCAP_MAX 5000000 201 /** Maximum number of labels we're going to keep around */ 202 #define YAF_MAX_MPLS_LABELS 3 203 204 /** 205 * A YAF flow key. 206 * Contains a flow's five-tuple; used at runtime in the flow table. 207 */ 208 typedef struct yfFlowKey_st { 209 /** Source transport port */ 210 uint16_t sp; 211 /** Destination transport port. Contains type and code for ICMP */ 212 uint16_t dp; 213 /** IP protocol */ 214 uint8_t proto; 215 /** IP Version */ 216 uint8_t version; 217 /** VLAN Tag - only fwd */ 218 uint16_t vlanId; 219 /** Type of Service/Traffic Class */ 220 uint8_t tos; 221 /** for DAG cards need to record the interface, may only be seeing 222 unidirectional flows on each interface, and want to record what 223 direction that is happening on */ 224 #if YAF_ENABLE_DAG_SEPARATE_INTERFACES || YAF_ENABLE_SEPARATE_INTERFACES 225 uint8_t netIf; 226 #endif 227 /** IP address two-tuple union */ 228 union { 229 struct { 230 /** Source IPv4 address */ 231 uint32_t sip; 232 /** Destination IPv4 address */ 233 uint32_t dip; 234 } v4; 235 struct { 236 /** Source IPv6 address */ 237 uint8_t sip[16]; 238 /** Destination IPv6 address */ 239 uint8_t dip[16]; 240 } v6; 241 } addr; 242 } yfFlowKey_t; 243 244 /** 245 * yaf flow statistics 246 */ 247 typedef struct yfFlowStats_st { 248 /** to calculate inter-packet delay */ 249 uint64_t iaarray[10]; 250 /** to calculate distribution of packet payload size */ 251 uint16_t pktsize[10]; 252 /** total amount of payload data */ 253 uint64_t payoct; 254 /** used to calculate interarrival time */ 255 uint64_t ltime; 256 /** Number of urgent packets */ 257 uint32_t tcpurgct; 258 /** Number of packets with 60 bytes or less of data */ 259 uint32_t smallpktct; 260 /** total number of non empty pkts */ 261 uint32_t nonemptypktct; 262 /** total number of packets with 225 bytes or more */ 263 uint32_t largepktct; 264 /** average interarrival time in milliseconds */ 265 uint32_t aitime; 266 /** payload length of first non-empty pkt */ 267 uint16_t firstpktsize; 268 /** largest pkt size */ 269 uint16_t maxpktsize; 270 } yfFlowStats_t; 271 272 /** 273 * A YAF uniflow value. Contains directional packet header fields and counters; 274 * two of these are used to build a biflow. 275 */ 276 typedef struct yfFlowVal_st { 277 /** Octet count */ 278 uint64_t oct; 279 /** Packet count */ 280 uint64_t pkt; 281 # if YAF_ENABLE_PAYLOAD 282 /** Payload length */ 283 uint32_t paylen; 284 /** Captured payload buffer */ 285 uint8_t *payload; 286 /** Offsets into the payload on packet boundaries */ 287 size_t *paybounds; 288 # endif 289 /** Initial TCP sequence number */ 290 uint32_t isn; 291 /** Last TCP sequence number */ 292 uint32_t lsn; 293 /** First Packet Size - to determine whether to turn on fixed size flag*/ 294 uint16_t first_pkt_size; 295 /** flowAttributes */ 296 uint16_t attributes; 297 /** Initial TCP flags */ 298 uint8_t iflags; 299 /** Union of remaining TCP flags */ 300 uint8_t uflags; 301 /** packets with payload - don't care if this wraps. */ 302 uint8_t appkt; 303 /** VLAN TAG (also in key, but want to record both sides) */ 304 uint16_t vlan; 305 # if YAF_ENABLE_SEPARATE_INTERFACES 306 uint8_t netIf; 307 # endif 308 # if YAF_ENABLE_ENTROPY 309 /** Entropy value */ 310 uint8_t entropy; 311 /** Entropy padding */ 312 uint8_t entpad[7]; 313 # endif 314 # if YAF_ENABLE_P0F 315 /** passive OS finger printing OS Name */ 316 const char *osname; 317 /** passive OS finger printing OS version */ 318 const char *osver; 319 /** required for libp0f */ 320 uint8_t fuzzyMatch; 321 /** required for libp0f */ 322 uint8_t fuzzyPad[7]; 323 /** p0f OS FingerPrint */ 324 char *osFingerPrint; 325 # endif 326 # if YAF_ENABLE_FPEXPORT 327 /** length of firstPacket Handshake header */ 328 uint32_t firstPacketLen; 329 /** length of secondPacket Handshake header */ 330 uint32_t secondPacketLen; 331 /** TCP Handshake header from first TCP packet */ 332 uint8_t *firstPacket; 333 /** TCP Handshake header from second TCP packet */ 334 uint8_t *secondPacket; 335 # endif 336 /** yaf flow statistics */ 337 yfFlowStats_t *stats; 338 } yfFlowVal_t; 339 340 #if YAF_MPLS 341 typedef struct yfMPLSNode_st { 342 /** Flow Key Hash Tables */ 343 GHashTable *tab; 344 /** TOP 3 MPLS Labels */ 345 uint32_t mpls_label[YAF_MAX_MPLS_LABELS]; 346 /** number of mpls nodes hash table */ 347 int tab_count; 348 } yfMPLSNode_t; 349 #endif 350 351 typedef struct yfMPTCPFlow_st { 352 /** initial data seq no. */ 353 uint64_t idsn; 354 /** receiver token */ 355 uint32_t token; 356 /** max segment size */ 357 uint16_t mss; 358 /** addr id */ 359 uint8_t addrid; 360 /** hash_flags */ 361 uint8_t flags; 362 } yfMPTCPFlow_t; 363 364 365 /** 366 * A YAF flow. Joins a flow key with forward and reverse flow values in time. 367 * 368 * @note if you edit the layout of this structure, you must make a 369 * corresponding edit of the yfFlowIPv4_t structure in yaftab.c 370 */ 371 typedef struct yfFlow_st { 372 /** Flow start time in epoch milliseconds */ 373 uint64_t stime; 374 /** Flow end time in epoch milliseconds */ 375 uint64_t etime; 376 #ifdef YAF_ENABLE_HOOKS 377 /** 378 * Hook flow context array. Used by extensions to store per-flow state. 379 * An array of ptr's - one per hook. 380 */ 381 void *hfctx[YAF_MAX_HOOKS]; 382 #endif 383 /* 384 * Reverse flow delta start time in milliseconds. Equivalent to initial 385 * packet round-trip time; useful for decomposing biflows into uniflows. 386 */ 387 int32_t rdtime; 388 #if YAF_ENABLE_APPLABEL 389 /** Application label for this flow */ 390 uint16_t appLabel; 391 #endif 392 #if YAF_ENABLE_NDPI 393 uint16_t ndpi_master; 394 uint16_t ndpi_sub; 395 #endif 396 /** Flow termination reason (YAF_END_ macros, per IPFIX standard) */ 397 uint8_t reason; 398 /** Keep track of number of pcap files for this flow */ 399 uint8_t pcap_serial; 400 /** src Mac Address */ 401 uint8_t sourceMacAddr[ETHERNET_MAC_ADDR_LENGTH]; 402 /** destination Mac Address */ 403 uint8_t destinationMacAddr[ETHERNET_MAC_ADDR_LENGTH]; 404 /** Pcap File "ID" so we know when to make entries in metadata file */ 405 uint8_t pcap_file_no; 406 /** non empty packet directions, 1, or 0 **/ 407 uint8_t pktdir; 408 /** reverse ToS (fwd in flowKey) */ 409 uint8_t rtos; 410 /** Pcap File Ptr */ 411 pcap_dumper_t *pcap; 412 #if YAF_MPLS 413 /** MPLS Node that contains this flow */ 414 yfMPLSNode_t *mpls; 415 #endif 416 /** MPTCP Flow */ 417 yfMPTCPFlow_t mptcp; 418 /** Forward value */ 419 yfFlowVal_t val; 420 /** Reverse value */ 421 yfFlowVal_t rval; 422 /** Flow key */ 423 yfFlowKey_t key; 424 } yfFlow_t; 425 426 /** 427 * yfAlignmentCheck 428 * 429 * This is a purely internal diagnostic function. It checks the alignment 430 * of the internal data structures that are used with fixbuf and causes 431 * the program to abort if there is an alignment issue. 432 * 433 */ 434 void yfAlignmentCheck(void); 435 436 437 /** 438 * Prepare a static flow buffer for use with yaf_flow_read(). Call this before 439 * the first yaf_flow_read() call; subsequent reads do not need initialization. 440 * This is used to prepare storage for payload information. 441 * 442 * @param flow a yfFlow_t to initialize 443 */ 444 445 void yfFlowPrepare( 446 yfFlow_t *flow); 447 448 /** 449 * Clean up after a static flow buffer prepared by yfFlowPrepare. 450 * This is used to free storage for payload information. 451 * 452 * @param flow a yfFlow_t to free 453 */ 454 455 void yfFlowCleanup( 456 yfFlow_t *flow); 457 458 /** 459 * Get an IPFIX message buffer for writing YAF flows to a named file. 460 * Sets the observation domain of the buffer to the given value. 461 * 462 * @param path Name of the file to write to, or - for stdout. 463 * @param domain observation domain 464 * @param export_meta Export Template/IE Metadata 465 * @param err an error description, set on failure. 466 * @return fBuf_t a new writer, or a reused writer, for writing on the 467 * given open file. NULL on failure. 468 */ 469 470 fBuf_t *yfWriterForFile( 471 const char *path, 472 uint32_t domain, 473 gboolean export_meta, 474 GError **err); 475 476 /** 477 * Get an IPFIX message buffer for writing YAF flows to an open file pointer. 478 * Sets the observation domain of the buffer to the given value. Note that this 479 * is intended for use with Airframe MIO based applications; non-MIO 480 * applications writing YAF IPFIX files should use yfWriterForFile instead. 481 * 482 * @param fp File pointer to open file to write to. 483 * @param domain observation domain 484 * @param export_meta Export Template/IE Metadata 485 * @param err an error description, set on failure. 486 * @return fBuf_t a new writer, or a reused writer, for writing on the 487 * given open file. NULL on failure. 488 */ 489 490 fBuf_t *yfWriterForFP( 491 FILE *fp, 492 uint32_t domain, 493 gboolean export_meta, 494 GError **err); 495 496 /** 497 * Get an IPFIX message buffer for writing YAF flows to a socket. 498 * 499 * @param spec fixbuf connection specifier for remote end of socket. 500 * @param domain observation domain 501 * @param export_meta Export Template/IE Metadata 502 * @param err an error description, set on failure. 503 * @return a new writer for export to the given address. 504 */ 505 506 fBuf_t *yfWriterForSpec( 507 fbConnSpec_t *spec, 508 uint32_t domain, 509 gboolean export_meta, 510 GError **err); 511 512 513 #ifdef HAVE_SPREAD 514 /** 515 * Get an IPFIX message buffer for writing YAF flows to Spread. 516 * If Groupby feature is used it will call yfInitExporterSpreadSession 517 * to set up templates per group, otherwise it calls yfInitExporterSession. 518 * 519 * @param params fixbuf Spread parameters 520 * @param domain observation domain 521 * @param spreadGroupIndex an array of groups matched to IE values 522 * @param export_meta Export Template/IE Metadata 523 * @param err an error description, set on failure. 524 * @return a new writer for export to the given address 525 */ 526 527 fBuf_t *yfWriterForSpread( 528 fbSpreadParams_t *params, 529 uint32_t domain, 530 uint16_t *spreadGroupIndex, 531 gboolean export_meta, 532 GError **err); 533 534 #endif /* HAVE_SPREAD */ 535 536 /** 537 * A wrapper that calls both yfWriteStatsFlow and yfWriteDataFlow with 538 * appropriate condition checking. 539 * 540 * @param yfContext Context pointer for the yaf state, used to get the 541 * fbuf pointer. 542 * @param pcap_drop Number of packets dropped reported by libpcap 543 * @param timer Pointer to yafstats GTimer 544 * @param err an error description; required. 545 * @return TRUE on success, FALSE otherwise. 546 * 547 */ 548 gboolean yfWriteOptionsDataFlows( 549 void *yfContext, 550 uint32_t pcap_drop, 551 GTimer *timer, 552 GError **err); 553 554 /** 555 * Write a statistics options data record to an IPFIX Message buffer. To turn 556 * off stats output - use --nostats. Sets the internal template to the stats 557 * option template, builds the record, and sends it - then sets the internal 558 * template back to the full flow record. 559 * 560 * @param yfContext Context pointer for the yaf state, used to get the 561 * fbuf pointer. 562 * @param pcap_drop Number of packets dropped reported by libpcap 563 * @param timer Pointer to yafstats GTimer 564 * @param err an error description; required. 565 * @return TRUE on success, FALSE otherwise. 566 * 567 */ 568 gboolean yfWriteStatsFlow( 569 void *yfContext, 570 uint32_t pcap_drop, 571 GTimer *timer, 572 GError **err); 573 574 /** 575 * Write a tombstone options data record to an IPFIX Message buffer. Sets the 576 * internal template to the tombstone option template, builds the record, and 577 * sends it - then sets the internal template back to the full flow record. 578 * 579 * @param yfContext Context pointer for the yaf state, used to get the 580 * fbuf pointer. 581 * @param err an error description; required. 582 * @return TRUE on success, FALSE otherwise. 583 * 584 */ 585 gboolean yfWriteTombstoneFlow( 586 void *yfContext, 587 GError **err); 588 589 /** 590 * Write a single flow to an IPFIX message buffer. The buffer must have been 591 * returned by yfWriterForFP() or yfWriterForSpec(). 592 * 593 * @param yfContext Context pointer for the yaf state, used to get the 594 * fbuf pointer, a buffer to write the message to, returned 595 * from yfWriterForFP() or yfWriterForSpec() 596 * @param flow pointer to yfFlow_t to write to file or stream. 597 * @param err an error description; required. 598 * @return TRUE on success, FALSE otherwise. 599 */ 600 601 gboolean yfWriteFlow( 602 void *yfContext, 603 yfFlow_t *flow, 604 GError **err); 605 606 /** 607 * Close the connection underlying an IPFIX message buffer created by 608 * yfWriterForFP() or yfWriterForSpec(). If flush is TRUE, forces any message 609 * in progress to be emitted before close; use FALSE if closing the buffer in 610 * response to a write error. Does not free the buffer. 611 * 612 * @param fbuf buffer to close. 613 * @param flush TRUE to flush buffer before closing. 614 * @param err an error description, set on failure. 615 * @return TRUE on success, FALSE otherwise. 616 */ 617 618 gboolean yfWriterClose( 619 fBuf_t *fbuf, 620 gboolean flush, 621 GError **err); 622 623 /** 624 * FIXME doc 625 */ 626 627 void yfWriterExportPayload( 628 int max_payload); 629 630 /** 631 * FIXME doc 632 */ 633 634 void yfWriterExportMappedV6( 635 gboolean map_mode); 636 637 /** 638 * Get an IPFIX message buffer for reading YAF flows from an open file pointer. 639 * Reuses an existing buffer if supplied. 640 * 641 * @param fbuf IPFIX message buffer to reuse; must have been returned by a 642 * prior call to yfReaderForFP(). Pass NULL to create a new buffer. 643 * @param fp File pointer to open file to read from. 644 * @param err an error description, set on failure. 645 * @return a new reader, or a reused reader, for reading the 646 * given open file. NULL on failure. 647 */ 648 649 fBuf_t *yfReaderForFP( 650 fBuf_t *fbuf, 651 FILE *fp, 652 GError **err); 653 654 /** 655 * Get an IPFIX connection listener for collecting YAF flows via IPFIX from 656 * the network. 657 * 658 * @param spec fixbuf connection specifier for local end of socket. 659 * @param appinit Application context initialization function, 660 * for creating application-specific collector contexts. 661 * Pass NULL for no appinit function. 662 * @param appfree Application context cleanup function. 663 * Pass NULL for no appfree function. 664 * @param err an error description, set on failure. 665 * @return a new listener, initialized for reading YAF flows, for use 666 * with fbListenerWait(). Buffers returned from this call can 667 * then be used with yfReadFlow() and yfReadFlowExtended(). 668 */ 669 670 fbListener_t *yfListenerForSpec( 671 fbConnSpec_t *spec, 672 fbListenerAppInit_fn appinit, 673 fbListenerAppFree_fn appfree, 674 GError **err); 675 676 /** 677 * Read a single flow from an IPFIX message buffer. The buffer must have been 678 * returned by yfReaderForFP(), or by fbListenerWait() called on a listener 679 * created by yfListenerForSpec(). 680 * 681 * @param fbuf Buffer to read message from, returned by yfReaderForFP() 682 * or from a YAF listener. 683 * @param flow pointer to yfFlow_t structure to fill from file or stream. 684 * @param err an error description; required. 685 * @return TRUE on success, FALSE otherwise. If false, check error against 686 * FB_ERROR_EOF to determine if the message reader is at end of 687 * file or stream, or against FB_ERROR_EOM to see if the listener 688 * should be waited upon. 689 */ 690 691 gboolean yfReadFlow( 692 fBuf_t *fbuf, 693 yfFlow_t *flow, 694 GError **err); 695 696 /** 697 * Read a single flow from an IPFIX message buffer. The buffer must have been 698 * returned by yfReaderForFP(), or by fbListenerWait() called on a listener 699 * created by yfListenerForSpec(). This function does not necessarily require 700 * its input to have been written by yfWriteFlow(); it supports additional flow 701 * timestamp and counter IEs that may be exported by other IPFIX exporting 702 * processes. 703 * 704 * @param fbuf Buffer to read message from, returned by yfReaderForFP() 705 * or from a YAF listener. 706 * @param flow pointer to yfFlow_t structure to fill from file or stream. 707 * @param err an error description; required. 708 * @return TRUE on success, FALSE otherwise. If false, check error against 709 * FB_ERROR_EOF to determine if the message reader is at end of 710 * file or stream, or against FB_ERROR_EOM to see if the listener 711 * should be waited upon. 712 */ 713 714 gboolean yfReadFlowExtended( 715 fBuf_t *fbuf, 716 yfFlow_t *flow, 717 GError **err); 718 719 /** 720 * Print a YAF flow to a GString. 721 * 722 * @param rstr string to append text representation of flow to. 723 * @param flow flow to print. 724 */ 725 726 void yfPrintString( 727 GString *rstr, 728 yfFlow_t *flow); 729 730 /** 731 * Print a YAF flow to a GString in pipe-delimited (tabular) format. 732 * 733 * @param rstr string to append text representation of flow to. 734 * @param flow flow to print. 735 * @param yaft_mac Add mac addresses to tabular format. 736 */ 737 738 void yfPrintDelimitedString( 739 GString *rstr, 740 yfFlow_t *flow, 741 gboolean yaft_mac); 742 743 /** 744 * Print a YAF flow to a file. 745 * 746 * @param out file to print to. 747 * @param flow flow to print. 748 * @param err an error descriptor. 749 * @return TRUE on success, FALSE otherwise. 750 */ 751 752 gboolean yfPrint( 753 FILE *out, 754 yfFlow_t *flow, 755 GError **err); 756 757 /** 758 * Print a YAF flow to a file in pipe-delimited (tabular) format. 759 * 760 * @param out file to print to. 761 * @param flow flow to print. 762 * @param yaft_mac print mac addresses in tabular format 763 * @param err an error descriptor. 764 * @return TRUE on success, FALSE otherwise. 765 */ 766 767 gboolean yfPrintDelimited( 768 FILE *out, 769 yfFlow_t *flow, 770 gboolean yaft_mac, 771 GError **err); 772 773 /** 774 * Print column headers for the pipe-delimited (tabular) format. 775 * 776 * @param out file to print to. 777 * @param yaft_mac print mac address column headers if enabled 778 * @param err an error descriptor. 779 * @return TRUE on success, FALSE otherwise. 780 */ 781 782 void yfPrintColumnHeaders( 783 FILE *out, 784 gboolean yaft_mac, 785 GError **err); 786 787 #if YAF_ENABLE_HOOKS 788 /** 789 * Add all DPI info elements to info model 790 * 791 * 792 */ 793 fbInfoModel_t *yfDPIInfoModel(); 794 #endif 795 796 797 798 #endif 799