1 /* $Id$ */ 2 /* 3 ** Copyright (C) 2014-2021 Cisco and/or its affiliates. All rights reserved. 4 * ** Copyright (C) 2005-2013 Sourcefire, Inc. 5 * ** AUTHOR: Steven Sturges 6 * ** 7 * ** This program is free software; you can redistribute it and/or modify 8 * ** it under the terms of the GNU General Public License Version 2 as 9 * ** published by the Free Software Foundation. You may not use, modify or 10 * ** distribute this program under any other version of the GNU General 11 * ** Public License. 12 * ** 13 * ** This program is distributed in the hope that it will be useful, 14 * ** but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * ** GNU General Public License for more details. 17 * ** 18 * ** You should have received a copy of the GNU General Public License 19 * ** along with this program; if not, write to the Free Software 20 * ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 * */ 22 23 /* stream_api.h 24 * 25 * Purpose: Definition of the StreamAPI. To be used as a common interface 26 * for TCP (and later UDP & ICMP) Stream access for other 27 * preprocessors and detection plugins. 28 * 29 * Arguments: 30 * 31 * Effect: 32 * 33 * Comments: 34 * 35 * Any comments? 36 * 37 */ 38 39 #ifndef STREAM_API_H_ 40 #define STREAM_API_H_ 41 42 #ifdef HAVE_CONFIG_H 43 #include "config.h" 44 #endif 45 46 #include <sys/types.h> 47 48 #include "ipv6_port.h" 49 #include "preprocids.h" /* IDs are used when setting preproc specific data */ 50 #include "bitop.h" 51 #include "decode.h" 52 #include "sfPolicy.h" 53 #include "session_api.h" 54 55 typedef enum { 56 STREAM_FLPOLICY_NONE, 57 STREAM_FLPOLICY_FOOTPRINT, /* size-based footprint flush */ 58 STREAM_FLPOLICY_LOGICAL, /* queued bytes-based flush */ 59 STREAM_FLPOLICY_RESPONSE, /* flush when we see response */ 60 STREAM_FLPOLICY_SLIDING_WINDOW, /* flush on sliding window */ 61 #if 0 62 STREAM_FLPOLICY_CONSUMED, /* purge consumed bytes */ 63 #endif 64 STREAM_FLPOLICY_IGNORE, /* ignore this traffic */ 65 STREAM_FLPOLICY_PROTOCOL, /* protocol aware flushing (PAF) */ 66 #ifdef NORMALIZER 67 STREAM_FLPOLICY_FOOTPRINT_IPS, /* protocol agnostic ips */ 68 STREAM_FLPOLICY_PROTOCOL_IPS, /* protocol aware ips */ 69 #endif 70 STREAM_FLPOLICY_FOOTPRINT_NOACK, /* protocol aware ips */ 71 STREAM_FLPOLICY_PROTOCOL_NOACK, /* protocol aware ips */ 72 #ifdef NORMALIZER 73 STREAM_FLPOLICY_FOOTPRINT_IPS_FTP, /* protocol agnostic ips for FTP*/ 74 #endif 75 76 STREAM_FLPOLICY_DISABLED, /* reassembly disabled for this traffic */ 77 78 STREAM_FLPOLICY_MAX 79 } FlushPolicy; 80 81 typedef enum _PreprocessorFlags{ 82 PP_FTPTELNET_FTPS = 0x00000001, 83 PP_HTTPINSPECT_PAF_FLUSH_POST_HDR = 0x00000002, 84 }PreprocessorFlags; 85 86 typedef enum { 87 PAF_TYPE_SERVICE, 88 PAF_TYPE_PORT 89 }PafType; 90 91 #define STREAM_FLPOLICY_SET_ABSOLUTE 0x01 92 #define STREAM_FLPOLICY_SET_APPEND 0x02 93 94 #define STREAM_API_VERSION5 6 95 96 typedef void (*LogExtraData)(void *ssnptr, void *config, LogFunction *funcs, uint32_t max_count, uint32_t xtradata_mask, uint32_t id, uint32_t sec); 97 98 typedef int (*PacketIterator)( DAQ_PktHdr_t *, 99 uint8_t *, /* pkt pointer */ 100 void * /* user-defined data pointer */ 101 ); 102 103 typedef int (*StreamSegmentIterator)( DAQ_PktHdr_t *, 104 uint8_t *, /* pkt pointer */ 105 uint8_t *, /* payload pointer */ 106 uint32_t, /* sequence number */ 107 void * /* user-defined data pointer */ 108 ); 109 110 111 /* for protocol aware flushing (PAF): */ 112 typedef enum { 113 PAF_ABORT, /* non-paf operation */ 114 PAF_START, /* internal use only */ 115 PAF_SEARCH, /* searching for next flush point */ 116 PAF_FLUSH, /* flush at given offset */ 117 PAF_LIMIT, /* if paf_max is reached, flush up to given offset*/ 118 PAF_SKIP, /* skip ahead to given offset */ 119 PAF_PERFORMED_LMT_FLUSH, /* previously performed PAF_LIMIT */ 120 PAF_DISCARD_START, /*start of the discard point */ 121 PAF_DISCARD_END, /*end of the discard point */ 122 PAF_PSEUDO_FLUSH_SEARCH, /* payload can be pseudo flushed before flushing */ 123 PAF_PSEUDO_FLUSH_SKIP, /* HTTP chunked payload can be pseudo flushed */ 124 PAF_IGNORE, /* Used for HTTP2.0*/ 125 } PAF_Status; 126 127 typedef PAF_Status (*PAF_Callback)( /* return your scan state */ 128 void* session, /* session pointer */ 129 void** user, /* arbitrary user data hook */ 130 const uint8_t* data, /* in order segment data as it arrives */ 131 uint32_t len, /* length of data */ 132 uint64_t *flags, /* packet flags indicating direction of data */ 133 uint32_t* fp, /* flush point (offset) relative to data */ 134 uint32_t * fp_eoh /* flush point (offset) at end-of-header */ 135 ); 136 137 typedef void (*PAF_Free_Callback)( 138 void* user /* arbitrary user data hook */ 139 ); 140 141 #if defined(FEAT_OPEN_APPID) 142 typedef struct s_HEADER_LOCATION { 143 const uint8_t *start; 144 unsigned len; 145 } HEADER_LOCATION; 146 147 typedef struct _HttpParsedHeaders 148 { 149 HEADER_LOCATION host, url, method, userAgent, referer, via, responseCode, server, xWorkingWith, contentType; 150 } HttpParsedHeaders; 151 152 typedef void (*Http_Processor_Callback)( 153 Packet *p, 154 HttpParsedHeaders *headers 155 ); 156 typedef enum { 157 APP_PROTOID_SERVICE, 158 APP_PROTOID_CLIENT, 159 APP_PROTOID_PAYLOAD, 160 APP_PROTOID_MISC, 161 APP_PROTOID_MAX 162 } AppProtoIdIndex; 163 #endif /* defined(FEAT_OPEN_APPID) */ 164 165 typedef unsigned int ServiceEventType; 166 167 typedef void (*ServiceEventNotifierFunc)(void *ssnptr, ServiceEventType eventType, void *eventData); 168 169 typedef void (*Stream_Callback)(Packet *); 170 171 typedef void (*FTP_Processor_Flush_Callback)(Packet *p); 172 173 struct _ExpectNode; 174 typedef struct _stream_api 175 { 176 int version; 177 178 /* 179 * Drop on Inline Alerts for Midstream pickups 180 * 181 * Parameters 182 *, 183 * Returns 184 * 0 if not alerting 185 * !0 if alerting 186 */ 187 int (*alert_inline_midstream_drops)(void); 188 189 /* Flushes the stream on an alert 190 * Side that is flushed is the same as the packet. 191 * 192 * Parameters 193 * Packet 194 */ 195 int (*alert_flush_stream)(Packet *); 196 197 /* Flushes the stream on arrival of packet 198 * Side that is flushed is the same side of the packet. 199 * 200 * Parameters 201 * Packet 202 */ 203 int (*request_flush_stream)(Packet *); 204 205 /* Flushes the stream on arrival of another packet 206 * Side that is flushed is the opposite of the packet. 207 * 208 * Parameters 209 * Packet 210 */ 211 int (*response_flush_stream)(Packet *); 212 213 /* Calls user-provided callback function for each packet of 214 * a reassembled stream. If the callback function returns non-zero, 215 * iteration ends. 216 * 217 * Parameters 218 * Packet 219 * Packet Iterator Function (called for each packet in the stream) 220 * user data (may be NULL) 221 * 222 * Returns 223 * number of packets 224 */ 225 int (*traverse_reassembled)(Packet *, PacketIterator, void *userdata); 226 227 /* Calls user-provided callback function for each segment of 228 * a reassembled stream. If the callback function returns non-zero, 229 * iteration ends. 230 * 231 * Parameters 232 * Packet 233 * StreamSegmentIterator Function (called for each packet in the stream) 234 * user data (may be NULL) 235 * 236 * Returns 237 * number of packets 238 */ 239 int (*traverse_stream_segments)(Packet *, StreamSegmentIterator, void *userdata); 240 241 /* Add session alert 242 * 243 * Parameters 244 * Session Ptr 245 * gen ID 246 * sig ID 247 * 248 * Returns 249 * 0 success 250 * -1 failure (max alerts reached) 251 * 252 */ 253 int (*add_session_alert)(void *, Packet *p, uint32_t, uint32_t); 254 255 /* Check session alert 256 * 257 * Parameters 258 * Session Ptr 259 * Packet 260 * gen ID 261 * sig ID 262 * 263 * Returns 264 * 0 if not previously alerted 265 * !0 if previously alerted 266 */ 267 int (*check_session_alerted)(void *, Packet *p, uint32_t, uint32_t); 268 269 /* Set Extra Data Logging 270 * 271 * Parameters 272 * Session Ptr 273 * Packet 274 * gen ID 275 * sig ID 276 * Returns 277 * 0 success 278 * -1 failure ( no alerts ) 279 * 280 */ 281 int (*update_session_alert)(void *, Packet *p, uint32_t, uint32_t, uint32_t, uint32_t); 282 283 /* Set reassembly flush policy/direction for given session 284 * 285 * Parameters 286 * Session Ptr 287 * Flush Policy 288 * Direction(s) 289 * Flags 290 * 291 * Returns 292 * direction(s) of reassembly for session 293 */ 294 /* XXX Do not attempt to set flush policy to PROTOCOL or PROTOCOL_IPS. */ 295 char (*set_reassembly)(void *, uint8_t, char, char); 296 297 /* Set direction of session 298 * 299 * Parameters: 300 * Session Ptr 301 * New Direction 302 * IP 303 * Port 304 */ 305 void (*update_direction)(void *, char, sfaddr_t*, uint16_t ); 306 307 /* Get reassembly direction for given session 308 * 309 * Parameters 310 * Session Ptr 311 * 312 * Returns 313 * direction(s) of reassembly for session 314 */ 315 char (*get_reassembly_direction)(void *); 316 317 /* Get reassembly flush_policy for given session 318 * 319 * Parameters 320 * Session Ptr 321 * Direction 322 * 323 * Returns 324 * flush policy for specified direction 325 */ 326 char (*get_reassembly_flush_policy)(void *, char); 327 328 /* Get true/false as to whether stream data is in 329 * sequence or packets are missing 330 * 331 * Parameters 332 * Session Ptr 333 * Direction 334 * 335 * Returns 336 * true/false 337 */ 338 char (*is_stream_sequenced)(void *, char); 339 340 /* Get whether there are missing packets before, after or 341 * before and after reassembled buffer 342 * 343 * Parameters 344 * Session Ptr 345 * Direction 346 * 347 * Returns 348 * SSN_MISSING_BOTH if missing before and after 349 * SSN_MISSING_BEFORE if missing before 350 * SSN_MISSING_AFTER if missing after 351 * SSN_MISSING_NONE if none missing 352 */ 353 int (*missing_in_reassembled)(void *, char); 354 355 /* Get true/false as to whether packets were missed on 356 * the stream 357 * 358 * Parameters 359 * Session Ptr 360 * Direction 361 * 362 * Returns 363 * true/false 364 */ 365 char (*missed_packets)(void *, char); 366 367 /* Drop retransmitted packet arriving on session. 368 * 369 * Parameters 370 * Packet 371 */ 372 void (*drop_packet)(Packet *); 373 374 /* Get the current flush point 375 * 376 * Arguments 377 * void * - session pointer 378 * char - direction 379 * 380 * Returns 381 * Current flush point for session 382 */ 383 uint32_t (*get_flush_point)(void *, char); 384 385 /* Set the next flush point 386 * 387 * Arguments 388 * void * - session pointer 389 * char - direction 390 * uint32_t - flush point size 391 */ 392 void (*set_flush_point)(void *, char, uint32_t); 393 394 // register for stateful scanning of in-order payload to determine flush points 395 // autoEnable allows PAF regardless of s5 ports config 396 uint8_t (*register_paf_port)( struct _SnortConfig *sc, tSfPolicyId, uint16_t server_port, bool toServer, 397 PAF_Callback, bool autoEnable); 398 399 // get any paf user data stored for this session 400 void** (*get_paf_user_data)(void* ssnptr, bool toServer, uint8_t id); 401 402 bool (*is_paf_active)(void* ssn, bool toServer); 403 bool (*activate_paf)(void* ssn, int dir, int16_t service, uint8_t type); 404 405 /** Set flag to force sessions to be created on SYN packets. 406 * This function can only be used with independent bits 407 * acquired from get_preprocessor_status_bit. If this is called 408 * during parsing a preprocessor configuration, make sure to 409 * set the parsing argument to 1. 410 */ 411 void (*set_tcp_syn_session_status)(struct _SnortConfig *sc, uint16_t status, tSfPolicyId policyId, int parsing); 412 413 /** Unset flag that forces sessions to be created on SYN 414 * packets. This function can only be used with independent 415 * bits acquired from get_preprocessor_status_bit. If this is 416 * called during parsing a preprocessor configuration, make 417 * sure to set the parsing argument to 1. 418 */ 419 void (*unset_tcp_syn_session_status)(struct _SnortConfig *sc, uint16_t status, tSfPolicyId policyId, int parsing); 420 421 //Register callbacks for extra data logging 422 uint32_t (*reg_xtra_data_cb)(LogFunction ); 423 424 //Register Extra Data Log Function 425 void (*reg_xtra_data_log)(LogExtraData, void *); 426 427 //Get the Extra data map 428 uint32_t (*get_xtra_data_map)(LogFunction **); 429 430 // register for stateful scanning of in-order payload to determine flush points 431 // autoEnable allows PAF regardless of s5 ports config 432 uint8_t (*register_paf_service)( 433 struct _SnortConfig *sc, tSfPolicyId, uint16_t service, bool toServer, 434 PAF_Callback, bool autoEnable); 435 436 void (*set_extra_data)(void*, Packet *, uint32_t); 437 void (*clear_extra_data)(void*, Packet *, uint32_t); 438 439 // These methods may move to Session: 440 // 441 /* Set port to either ignore, inspect or maintain session state. 442 * If this is called during parsing a preprocessor configuration, make 443 * sure to set the parsing argument to 1. 444 */ 445 void (*set_port_filter_status)(struct _SnortConfig *sc, IpProto protocol, uint16_t port, uint16_t status, 446 tSfPolicyId policyId, int parsing); 447 448 /* Unset port to maintain session state. This function can only 449 * be used with independent bits acquired from 450 * get_preprocessor_status_bit. If this is called during 451 * parsing a preprocessor configuration, make sure to set the 452 * parsing argument to 1. 453 */ 454 void (*unset_port_filter_status)(struct _SnortConfig *sc, IpProto protocol, uint16_t port, uint16_t status, 455 tSfPolicyId policyId, int parsing); 456 457 458 /* Set service to either ignore, inspect or maintain session state. 459 * If this is called during parsing a preprocessor configuration, make 460 * sure to set the parsing argument to 1. 461 */ 462 void (*set_service_filter_status)( struct _SnortConfig *sc, int service, int status, 463 tSfPolicyId policyId, int parsing ); 464 465 /* Register specified port for reassembly on specified network. If network is NULL the 466 * port is register for reassembly on the default stream network policy 467 */ 468 void (*register_reassembly_port)( char *, uint16_t, int ); 469 470 /* Unregister specified port for reassembly on specified network. If network is NULL the 471 * port is unregistered for reassembly on the default stream network policy 472 */ 473 void (*unregister_reassembly_port)( char *, uint16_t, int ); 474 475 /* Time out the specified session. 476 * 477 * Parameters 478 * Session Ptr 479 */ 480 void (*expire_session)(void *); 481 void (*force_delete_session)(void *); 482 483 /* register returns a non-zero id for use with set; zero is error */ 484 unsigned (*register_event_handler)(Stream_Callback); 485 bool (*set_event_handler)(void* ssnptr, unsigned id, Stream_Event); 486 void (*set_reset_policy)(void* ssn, int dir, uint16_t policy, uint16_t mss); 487 void (*set_session_decrypted)(void *ssn, bool enable); 488 bool (*is_session_decrypted)(void *ssn); 489 490 /* Turn off inspection for potential session. 491 * Adds session identifiers to a hash table. 492 * TCP only. 493 * 494 * Parameters 495 * Control Channel Packet 496 * IP addr #1 497 * Port #1 498 * IP addr #2 499 * Port #2 500 * Protocol 501 * ID, 502 * Preprocessor ID calling this function, 503 * Preprocessor specific data, 504 * Preprocessor data free function. If NULL, then static buffer is assumed. 505 * Preprocessor event handler callback ID (used when calling set_event_handler) 506 * Preprocessor event on which to callback (only used when cbId is not NULL ) 507 * 508 * Returns 509 * 0 on success 510 * -1 on failure 511 */ 512 int (*set_application_protocol_id_expected_preassign_callback)(const Packet *, sfaddr_t*, uint16_t, 513 sfaddr_t*, uint16_t, uint8_t, int16_t, uint32_t, void*, void (*)(void*), unsigned, Stream_Event, 514 struct _ExpectNode**); 515 516 // print and reset normalization statistics 517 void (*print_normalization_stats)(void); 518 void (*reset_normalization_stats)(void); 519 520 #if defined(FEAT_OPEN_APPID) 521 /* set detected service, client, payload and misc Applicaiton Id. 522 * 523 * Parameters 524 * Session Ptr 525 * Snort Protocol Id for service application 526 * Snort Protocol Id for client application 527 * Snort Protocol Id for payload application 528 * Snort Protocol Id for misc application 529 */ 530 void (*set_application_id)(void* ssnptr, int16_t serviceAppid, int16_t clientAppid, int16_t payloadAppId, int16_t miscAppid); 531 532 /* get detected service, client, payload and misc Applicaiton Id. 533 * 534 * Parameters 535 * Session Ptr 536 * Snort Protocol Id for service application 537 * Snort Protocol Id for client application 538 * Snort Protocol Id for payload application 539 * Snort Protocol Id for misc application 540 */ 541 void (*get_application_id)(void* ssnptr, int16_t *serviceAppid, int16_t *clientAppid, int16_t *payloadAppId, int16_t *miscAppid); 542 543 544 /* Register callback function for processing HTTP headers extracted by HTTP preprocessor. 545 * 546 * Parameters 547 * Callback function pointer 548 */ 549 int (*register_http_header_callback)(Http_Processor_Callback); 550 #endif /* defined(FEAT_OPEN_APPID) */ 551 552 /* function to publish events 553 * 554 * Parameters 555 * preprocId - preprocess identifier 556 * ssnptr - sesssion pointer 557 * eventType - type of event enumerated in ServiceEventType 558 * eventData - void data pointer. Structure must be agreed between publisher and subscriber. 559 */ 560 bool (*service_event_publish)(unsigned int preprocId, void *ssnptr, ServiceEventType eventType, void *eventData); 561 562 /* function for subcribing to events. 563 * 564 * Parameters 565 * preprocId - preprocess identifier 566 * eventType - type of event enumerated in ServiceEventType 567 * Callback function pointer 568 */ 569 bool (*service_event_subscribe)(unsigned int preprocId, ServiceEventType eventType, ServiceEventNotifierFunc cb); 570 571 /* function to register for customized free function 572 * 573 * Parameters 574 * id - registered paf identifier 575 * Callback function pointer 576 */ 577 void (*register_paf_free)(uint8_t id, PAF_Free_Callback); 578 579 /* function to return the wire packet 580 * 581 * Parameters 582 * None 583 */ 584 Packet *(*get_wire_packet)(void); 585 586 /* function which returns the forward dir or reverse dir to h2_paf 587 * 588 * Parameter 589 * None 590 */ 591 uint8_t (*get_flush_policy_dir)(void); 592 593 /* function returns if its a http/2 session 594 * 595 * Parameters 596 * Session Pointer 597 */ 598 bool (*is_session_http2)(void *ssn); 599 600 /* function sets http/2 session flag 601 * 602 * Parameters 603 * Session Pointer 604 */ 605 void (*set_session_http2)(void *ssn); 606 607 bool (*is_show_rebuilt_packets_enabled)(); 608 /* function returns if its a http/2 session Upgrade 609 * 610 * Parameters 611 * Session Pointer 612 */ 613 bool (*is_session_http2_upg)(void *ssn); 614 615 /* function sets http/2 session Upgrade flag 616 * 617 * Parameters 618 * Session Pointer 619 */ 620 void (*set_session_http2_upg)(void *ssn); 621 622 /* Gets the proto_flags for a session 623 * 624 * Parameters 625 * ssnptr - sesssion pointer 626 */ 627 uint32_t (*get_preproc_flags)(void *ssnptr); 628 629 /* Register the FTP Flush callback 630 * 631 * Parameters 632 * ssnptr - sesssion pointer 633 */ 634 int (*register_ftp_flush_cb)(FTP_Processor_Flush_Callback); 635 636 /* set the ftp file position 637 * 638 * parameters 639 * ssnptr -session pointer 640 * flage -flush flage 641 */ 642 void (*set_ftp_file_position)(void *ssnptr, bool flush); 643 644 #ifdef HAVE_DAQ_DECRYPTED_SSL 645 /* Simulate ACK in peer Streamtracker 646 * 647 * Parameters 648 * ssnptr - sesssion pointer 649 * dir - direction to be ACKed in( 0:C to S, 1:S to C ) 650 * len - Number of bytes to be ACKed 651 */ 652 int (*simulate_tcp_akc_in_peer_stream_tracker)(void *ssnptr, uint8_t dir, uint32_t len); 653 #endif 654 } StreamAPI; 655 /* To be set by Stream */ 656 extern StreamAPI *stream_api; 657 658 #endif /* STREAM_API_H_ */ 659 660