1 /*
2 ** Copyright (C) 2014-2021 Cisco and/or its affiliates. All rights reserved.
3 * ** Copyright (C) 2012-2013 Sourcefire, Inc.
4 * ** AUTHOR: Hui Cao
5 * **
6 * ** This program is free software; you can redistribute it and/or modify
7 * ** it under the terms of the GNU General Public License Version 2 as
8 * ** published by the Free Software Foundation. You may not use, modify or
9 * ** distribute this program under any other version of the GNU General
10 * ** Public License.
11 * **
12 * ** This program is distributed in the hope that it will be useful,
13 * ** but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * ** GNU General Public License for more details.
16 * **
17 * ** You should have received a copy of the GNU General Public License
18 * ** along with this program; if not, write to the Free Software
19 * ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 * */
21
22 /* file_api.h
23 *
24 * Purpose: Definition of the FileAPI. To be used as a common interface
25 * for file process access for other preprocessors and detection
26 * plugins.
27 *
28 * Author(s): Hui Cao <hcao@sourcefire.com>
29 *
30 * NOTES
31 * 5.25.12 - Initial Source Code. Hcao
32 */
33
34 #ifndef FILE_API_H_
35 #define FILE_API_H_
36
37 #ifdef HAVE_CONFIG_H
38 #include <config.h>
39 #endif
40
41 #include <sys/types.h>
42 #include "sfPolicy.h"
43
44 #define ENABLE_FILE_TYPE_IDENTIFICATION 0x1
45 #define ENABLE_FILE_SIGNATURE_SHA256 0x2
46 #define ENABLE_FILE_CAPTURE 0x4
47 #define FILE_ALL_ON 0xFFFFFFFF
48 #define FILE_ALL_OFF 0x00000000
49 #define MAX_FILE 1024
50 #define MAX_EMAIL 1024
51 #define MAX_UNICODE_FILE_NAME 1024
52
53 #define FILE_RESUME_BLOCK 0x01
54 #define FILE_RESUME_LOG 0x02
55
56 /*
57 * Generator id. Define here the same as the official register
58 * in generators.h
59 */
60 #define GENERATOR_FILE_TYPE 146
61 #define GENERATOR_FILE_SIGNATURE 147
62
63 #define FILE_SIGNATURE_SHA256 1
64 #define FILE_SIGNATURE_SHA256_STR "(file) malware detected"
65
66 #define UTF_16_BE_BOM "\xFE\xFF"
67 #define UTF_16_LE_BOM "\xFF\xFE"
68
69 #define UTF_16_BE_BOM_LEN 2
70 #define UTF_16_LE_BOM_LEN 2
71
72 typedef enum _File_Verdict
73 {
74 FILE_VERDICT_UNKNOWN = 0,
75 FILE_VERDICT_LOG,
76 FILE_VERDICT_STOP,
77 FILE_VERDICT_BLOCK,
78 FILE_VERDICT_REJECT,
79 FILE_VERDICT_PENDING,
80 FILE_VERDICT_STOP_CAPTURE,
81 FILE_VERDICT_MAX
82 } File_Verdict;
83
84 typedef enum _FilePosition
85 {
86 SNORT_FILE_POSITION_UNKNOWN,
87 SNORT_FILE_START,
88 SNORT_FILE_MIDDLE,
89 SNORT_FILE_END,
90 SNORT_FILE_FULL
91 } FilePosition;
92
93 typedef enum _FileCaptureState
94 {
95 FILE_CAPTURE_SUCCESS = 0,
96 FILE_CAPTURE_MIN, /*smaller than file capture min*/
97 FILE_CAPTURE_MAX, /*larger than file capture max*/
98 FILE_CAPTURE_MEMCAP, /*memcap reached, no more file buffer*/
99 FILE_CAPTURE_FAIL /*Other file capture failures*/
100 } FileCaptureState;
101
102 typedef enum _FileSigState
103 {
104 FILE_SIG_PROCESSING = 0,
105 FILE_SIG_DEPTH_FAIL, /*larger than file signature depth*/
106 FILE_SIG_FLUSH,
107 FILE_SIG_DONE
108 } FileSigState;
109
110 typedef enum _FileProcessType
111 {
112 SNORT_FILE_TYPE_ID,
113 SNORT_FILE_SHA256,
114 SNORT_FILE_CAPTURE
115 } FileProcessType;
116
117 typedef enum _FileCharEncoding
118 {
119 SNORT_CHAR_ENCODING_ASCII = 0,
120 SNORT_CHAR_ENCODING_UTF_16LE,
121 SNORT_CHAR_ENCODING_UTF_16BE,
122 }FileCharEncoding;
123
124 typedef struct _FileState
125 {
126 FileCaptureState capture_state;
127 FileSigState sig_state;
128 } FileState;
129
130 typedef struct _FileCacheStatus
131 {
132 uint64_t prunes; /* number of file entries pruned due to memcap*/
133 uint64_t segment_mem_in_use; /* memory used currently */
134 uint64_t segment_mem_in_use_max; /* Maximal memory usage */
135 } FileCacheStatus;
136
137 struct s_MAIL_LogState;
138 struct _DecodeConfig;
139 struct s_MAIL_LogConfig;
140 struct _MimeDataPafInfo;
141 struct _MimeState;
142
143 struct _FileCaptureInfo;
144 typedef struct _FileCaptureInfo FileCaptureInfo;
145 struct _SnortConfig;
146 struct _FileContext;
147 struct _FileCache;
148
149 struct _MemPool;
150
151 typedef struct _FileSession
152 {
153 struct _FileContext *current_context;
154 struct _FileContext *main_context;
155 struct _FileContext *pending_context;
156 uint32_t max_file_id;
157 struct _FileCache *file_cache;
158 uint64_t file_id;
159
160 } FileSession;
161
162 #define FILE_API_VERSION 5
163
164 #define DEFAULT_FILE_ID 0
165
166 typedef uint32_t (*File_policy_callback_func) (void* ssnptr, int16_t app_id, bool upload);
167 typedef File_Verdict (*File_type_callback_func) (void* p, void* ssnptr,
168 uint32_t file_type_id, bool upload, uint32_t file_id);
169 typedef File_Verdict (*File_signature_callback_func) (void* p, void* ssnptr,
170 uint8_t* file_sig, uint64_t file_size, FileState *state, bool upload,
171 uint32_t file_id, bool partial_file);
172 typedef void (*Log_file_action_func) (void* ssnptr, int action);
173
174 typedef int (*File_process_func)( void* p, uint8_t* file_data, int data_size, FilePosition position,
175 bool upload, bool suspend_block_verdict, bool do_flush);
176 typedef int (*Get_file_name_func) (void* ssnptr, uint8_t **file_name, uint32_t *name_len);
177 typedef uint64_t (*Get_file_size_func) (void* ssnptr);
178 typedef bool (*Get_file_direction_func) (void* ssnptr);
179 typedef uint8_t *(*Get_file_sig_sha256_func) (void* ssnptr);
180
181 typedef void (*Set_file_name_func) (void* ssnptr, uint8_t *, uint32_t, bool);
182 typedef void (*Set_file_direction_func) (void* ssnptr, bool);
183
184 typedef int64_t (*Get_file_depth_func) (struct _SnortConfig *snort_conf, bool next);
185 typedef bool (*Is_file_signature_enabled_func) (void);
186
187 typedef void (*Set_file_policy_func)(File_policy_callback_func);
188 typedef void (*Enable_file_type_func)(struct _SnortConfig* sc, File_type_callback_func);
189 typedef void (*Enable_file_signature_func)(struct _SnortConfig* sc, File_signature_callback_func);
190 typedef void (*Enable_file_capture_func)(struct _SnortConfig* sc, File_signature_callback_func);
191 typedef void (*Set_file_action_log_func)(Log_file_action_func);
192 typedef void (*Install_file_service_func)(void);
193
194 typedef int (*Set_log_buffers_func)(struct s_MAIL_LogState **log_state, struct s_MAIL_LogConfig *conf, void *mempool,
195 void* scbPtr, uint32_t preproc_id);
196 typedef void (*Update_mime_mempool_func)(void*, int, int);
197 typedef void (*Update_log_mempool_func)(void*, int, int);
198 typedef void (*Display_mime_mempool_func)(void *memory_pool, struct _DecodeConfig *decode_conf_old, struct _DecodeConfig *decode_conf_new);
199 typedef void (*Display_log_mempool_func)(void *memory_pool, unsigned memcap_old, unsigned memcap_new);
200 typedef void (*Display_decode_depth_func)(struct _DecodeConfig *decode_conf_old, struct _DecodeConfig *decode_conf_new);
201 typedef void* (*Init_mime_mempool_func)(int max_mime_mem, int max_depth, void *mempool, const char *preproc_name);
202 typedef void* (*Init_log_mempool_func)(uint32_t email_hdrs_log_depth, uint32_t memcap, void *mempool, const char *preproc_name);
203
204 typedef int (*File_resume_block_add_file_func)(void *pkt, uint32_t file_sig,
205 uint32_t timeout, File_Verdict verdict, uint32_t file_type_id, uint8_t *signature,
206 uint16_t cli_port, uint16_t srv_port, bool create_pinhole, bool direction);
207 typedef File_Verdict (*File_resume_block_check_func)(void *pkt, uint32_t file_sig);
208 typedef uint32_t (*Str_to_hash_func)(uint8_t *str, int length );
209 typedef void (*File_signature_lookup_func)(void* p, bool is_retransmit);
210 typedef void (*Set_mime_decode_config_defaults_func)(struct _DecodeConfig *decode_conf);
211 typedef void (*Set_mime_log_config_defaults_func)(struct s_MAIL_LogConfig *log_config);
212 typedef int (*Parse_mime_decode_args_func)(struct _DecodeConfig *decode_conf, char *arg, const char *preproc_name, char **saveptr);
213 typedef const uint8_t * (*Process_mime_data_func)(void *packet, const uint8_t *start, const uint8_t *end,
214 struct _MimeState *mime_ssn, bool upload, bool paf_enabled, char *protocol, uint32_t preproc_id);
215 typedef void (*Free_mime_session_func)(struct _MimeState *mime_ssn);
216 typedef bool (*Is_decoding_enabled_func)(struct _DecodeConfig *decode_conf);
217 typedef bool (*Check_decoding_conf_func)(struct _DecodeConfig *configNext, struct _DecodeConfig *config, const char *preproc_name);
218 typedef bool (*Is_mime_log_enabled_func)(struct s_MAIL_LogConfig *log_config);
219 typedef void (*Finalize_mime_position_func)(void *ssnptr, void *decode_state, FilePosition *position);
220 typedef File_Verdict (*Get_file_verdict_func)(void *ssnptr);
221 typedef void (*Render_block_verdict_func)(void *ctx, void *p);
222 typedef FileCaptureState (*Reserve_file_func)(void *ssnptr, FileCaptureInfo **file_mem);
223 typedef void* (*Get_file_func)(FileCaptureInfo *file_mem, uint8_t **buff, int *size);
224 typedef void (*Release_file_func)(FileCaptureInfo *data);
225 typedef size_t (*File_capture_size_func)(FileCaptureInfo *file_mem);
226
227 typedef bool (*Is_file_service_enabled)(void);
228 typedef bool (*Check_paf_abort_func)(void* ssn);
229 typedef void (*Update_file_name_func) (struct s_MAIL_LogState *log_state);
230 typedef FilePosition (*GetFilePosition)(void *pkt);
231 typedef void (*Reset_mime_paf_state_func)(struct _MimeDataPafInfo *data_info);
232 /* Process data boundary and flush each file based on boundary*/
233 typedef bool (*Process_mime_paf_data_func)(struct _MimeDataPafInfo *data_info, uint8_t data);
234 typedef bool (*Check_data_end_func)(void *end_state, uint8_t data);
235 typedef uint32_t (*Get_file_type_id)(void *);
236 typedef uint32_t (*Get_new_file_instance)(void *);
237
238 /*Context based file process functions*/
239 typedef struct _FileContext* (*Create_file_context_func)(void *ssnptr);
240 typedef void (*Init_file_context_func)(void *ssnptr, bool upload, struct _FileContext *ctx);
241 typedef struct _FileContext* (*Get_file_context_func)(void *ssnptr);
242 typedef bool (*Set_file_context_func)(void *ssnptr, struct _FileContext *ctx);
243 typedef int (*Process_file_func)( struct _FileContext *ctx, void *p,
244 uint8_t *file_data, int data_size, FilePosition position,
245 bool suspend_block_verdict);
246 typedef void *(*File_cache_update_entry_func) (struct _FileCache *fileCache, void* p, uint64_t file_id,
247 uint8_t *file_name, uint32_t file_name_size, uint64_t file_size, bool reset, bool no_update_size);
248 typedef int (*File_segment_process_func)( struct _FileCache *fileCache, void* p, uint64_t file_id,
249 uint64_t file_size, const uint8_t* file_data, int data_size, uint64_t offset,
250 bool upload);
251 typedef struct _FileCache * (*File_cache_create_func)(uint64_t memcap, uint32_t cleanup_files);
252 typedef void (*File_cache_free_func)(struct _FileCache *fileCache);
253 typedef FileCacheStatus * (*File_cache_status_func)(struct _FileCache *fileCache);
254 typedef int64_t (*Get_max_file_capture_size)(void *ssn);
255 typedef bool (*File_config_malware_check)(void *ssn, uint16_t app_id);
256 typedef FileCharEncoding (*Get_character_encoding)(uint8_t *, uint32_t);
257 typedef bool (*File_cache_mem_adjust_func)(struct _FileCache *fileCache, uint8_t *pWork);
258 typedef void (*File_cache_mem_set_func)(struct _FileCache *fileCache, uint64_t memcap);
259 typedef void (*File_event_log_dump_func)( struct _FileCache *fileCache, void* p, uint64_t file_id);
260 typedef void (*File_signature_reset)(void *ssnptr);
261 typedef void (*Set_file_partial_func)(void *p, FilePosition position, bool upload, bool is_partial);
262 typedef char* (*File_get_filetype_func) (void *ssnptr);
263
264 typedef struct _file_api
265 {
266 int version;
267
268 /* Check if file type id is enabled.
269 *
270 * Arguments: None
271 *
272 * Returns:
273 * (bool) true file processing is enabled
274 * (bool) false file processing is disabled
275 */
276 Is_file_service_enabled is_file_service_enabled;
277
278 /* File process function, called by preprocessors that provides file data
279 *
280 * Arguments:
281 * void* p: packet pointer
282 * uint8_t* file_data: file data
283 * int data_size: file data size
284 * FilePosition: file position
285 * bool upload: upload or not
286 * Returns:
287 * 1: continue processing/log/block this file
288 * 0: ignore this file (no further processing needed)
289 */
290 File_process_func file_process;
291
292 /*-----File property functions--------*/
293
294 /* Get file name and the length of file name
295 * Note: this is updated after file processing. It will be available
296 * for file event logging, but might not be available during file type
297 * callback or file signature callback, because those callbacks are called
298 * during file processing.
299 *
300 * Arguments:
301 * void* ssnptr: session pointer
302 * uint8_t **file_name: address for file name to be saved
303 * uint32_t *name_len: address to save file name length
304 * Returns
305 * 1: file name available,
306 * 0: file name is unavailable
307 */
308 Get_file_name_func get_file_name;
309
310 /* Get file size
311 * Note: this is updated after file processing. It will be available
312 * for file event logging, but might not be available during file type
313 * callback or file signature callback, because those callbacks are called
314 * during file processing.
315 *
316 * Arguments:
317 * void* ssnptr: session pointer
318 *
319 * Returns
320 * uint64_t: file size
321 * Note: 0 means file size is unavailable
322 */
323 Get_file_size_func get_file_size;
324
325 /* Get number of bytes processed
326 *
327 * Arguments:
328 * void* ssnptr: session pointer
329 *
330 * Returns
331 * uint64_t: processed file data size
332 */
333 Get_file_size_func get_file_processed_size;
334
335 /* Get file direction
336 *
337 * Arguments:
338 * void* ssnptr: session pointer
339 *
340 * Returns
341 * 1: upload
342 * 0: download
343 */
344 Get_file_direction_func get_file_direction;
345
346 /* Get file signature sha256
347 *
348 * Arguments:
349 * void* ssnptr: session pointer
350 *
351 * Returns
352 * char *: pointer to sha256
353 * NULL: sha256 is not available
354 */
355 Get_file_sig_sha256_func get_sig_sha256;
356
357 /* Set file name and the length of file name
358 *
359 * Arguments:
360 * void* ssnptr: session pointer
361 * uint8_t *file_name: file name to be saved
362 * uint32_t name_len: file name length
363 * bool save_in_context: true if file name is saved in context
364 * instead of session
365 * Returns
366 * None
367 */
368 Set_file_name_func set_file_name;
369
370 /* Get file direction
371 *
372 * Arguments:
373 * void* ssnptr: session pointer
374 * bool:
375 * 1 - upload
376 * 0 - download
377 * Returns
378 * None
379 */
380 Set_file_direction_func set_file_direction;
381
382 /*----------File call backs--------------*/
383
384 /* Set file policy callback. This callback is called in the beginning
385 * of session. This callback will decide whether to do file type ID,
386 * file signature, or file capture
387 *
388 * Arguments:
389 * File_policy_callback_func
390 * Returns
391 * None
392 */
393 Set_file_policy_func set_file_policy_callback;
394
395 /* Enable file type ID and set file type callback.
396 * File type callback is called when file type is identified. Callback
397 * will return a verdict based on file type
398 *
399 * Arguments:
400 * File_type_callback_func
401 * Returns
402 * None
403 */
404 Enable_file_type_func enable_file_type;
405
406 /* Enable file signature and set file signature callback.
407 * File signature callback is called when file signature is calculated.
408 * Callback will return a verdict based on file signature.
409 * SHA256 is calculated after file transfer is finished.
410 *
411 * Arguments:
412 * File_signature_callback_func
413 * Returns
414 * None
415 */
416 Enable_file_signature_func enable_file_signature;
417
418 /* Enable file capture and set file signature callback.
419 * File signature callback is called when file signature is calculated.
420 * Callback will return a verdict based on file signature.
421 * SHA256 is calculated after file transfer is finished.
422 *
423 * Note: file signature and file capture will use the same callback, but
424 * enabled separately.
425 *
426 * Arguments:
427 * File_signature_callback_func
428 * Returns
429 * None
430 */
431 Enable_file_signature_func enable_file_capture;
432
433 /* Set file action log callback.
434 * File action log callback is called when file resume is detected.
435 * It allows file events to be generated for a resumed file download
436 *
437 * Arguments:
438 * Log_file_action_func
439 * Returns
440 * None
441 */
442 Set_file_action_log_func set_file_action_log_callback;
443
444 /* Install file service.
445 * This must be called in band with packets.
446 * It makes the functions set in the other enable calls active.
447 *
448 * Arguments:
449 * None
450 * Returns
451 * None
452 */
453 Install_file_service_func install_file_service;
454
455 /*--------------File configurations-------------*/
456
457 /* Get file depth required for all file processings enabled
458 *
459 * Arguments:
460 * None
461 *
462 * Returns:
463 * int64_t: file depth in bytes
464 */
465 Get_file_depth_func get_max_file_depth;
466
467 /* Is file signature enabled
468 *
469 * Arguments:
470 * None
471 *
472 * Returns:
473 * bool: true if file_signature_enabled is set
474 */
475 Is_file_signature_enabled_func is_file_signature_enabled;
476
477
478 /*--------------Common functions used for MIME processing-------------*/
479 Set_log_buffers_func set_log_buffers;
480 Update_mime_mempool_func update_mime_mempool;
481 Update_log_mempool_func update_log_mempool;
482 Display_mime_mempool_func displayMimeMempool;
483 Display_log_mempool_func displayLogMempool;
484 Display_decode_depth_func displayDecodeDepth;
485 Init_mime_mempool_func init_mime_mempool;
486 Init_log_mempool_func init_log_mempool;
487 Set_mime_decode_config_defaults_func set_mime_decode_config_defauts;
488 Set_mime_log_config_defaults_func set_mime_log_config_defauts;
489 Parse_mime_decode_args_func parse_mime_decode_args;
490 Process_mime_data_func process_mime_data;
491 Free_mime_session_func free_mime_session;
492 Is_decoding_enabled_func is_decoding_enabled;
493 Check_decoding_conf_func check_decoding_conf;
494 Is_mime_log_enabled_func is_mime_log_enabled;
495 Finalize_mime_position_func finalize_mime_position;
496 Reset_mime_paf_state_func reset_mime_paf_state;
497 Process_mime_paf_data_func process_mime_paf_data;
498 Check_data_end_func check_data_end;
499 Check_paf_abort_func check_paf_abort;
500
501 /*--------------Other helper functions-------------*/
502 File_resume_block_add_file_func file_resume_block_add_file;
503 File_resume_block_check_func file_resume_block_check;
504 Str_to_hash_func str_to_hash;
505 File_signature_lookup_func file_signature_lookup;
506 Get_file_verdict_func get_file_verdict;
507 Render_block_verdict_func render_block_verdict;
508 /*
509 * Preserve the file in memory until it is released
510 * This function must be called in packet processing thread
511 * Arguments:
512 * void *ssnptr: session pointer
513 * void **file_mem: the pointer to store the memory block
514 * that stores file and its metadata.
515 * It will set NULL if no memory or fail to store
516 *
517 * Returns:
518 * FileCaptureState:
519 * FILE_CAPTURE_SUCCESS = 0,
520 * FILE_CAPTURE_MIN,
521 * FILE_CAPTURE_MAX,
522 * FILE_CAPTURE_MEMCAP,
523 * FILE_CAPTURE_FAIL
524 */
525 Reserve_file_func reserve_file;
526
527 /*
528 * Get the file that is reserved in memory. To get a full file,
529 * this function must be called iteratively until NULL is returned
530 * This function can be called in out of band thread
531 *
532 * Arguments:
533 * void *file_mem: the memory block working on
534 * uint8_t **buff: address to store buffer address
535 * int *size: address to store size of file
536 *
537 * Returns:
538 * the next memory block
539 * If NULL: no memory or fail to get file
540 */
541 Get_file_func read_file;
542
543 /*
544 * Get the file size captured in the file buffer
545 * This function can be called in out of band thread
546 *
547 * Arguments:
548 * void *file_mem: the first memory block of file buffer
549 *
550 * Returns:
551 * the size of file
552 * If 0: no memory or fail to read file
553 */
554 File_capture_size_func get_file_capture_size;
555
556 /*
557 * Release the file that is reserved in memory.
558 * This function can be called in out of band thread.
559 *
560 * Arguments:
561 * void *data: the memory block that stores file and its metadata
562 *
563 * Returns:
564 * None
565 */
566 Release_file_func release_file;
567
568 /* Return the file rule id associated with a session.
569 *
570 * Arguments:
571 * void *ssnptr: session pointer
572 *
573 * Returns:
574 * (u32) file-rule id on session; FILE_TYPE_UNKNOWN otherwise.
575 */
576 Get_file_type_id get_file_type_id;
577
578 /* Create a file context to use
579 *
580 * Arguments:
581 * void* ssnptr: session pointer
582 * Returns:
583 * FileContext *: file context created.
584 */
585 Create_file_context_func create_file_context;
586
587 /* Intialize a file context
588 *
589 * Arguments:
590 * void* ssnptr: session pointer
591 * Returns:
592 * FileContext *: file context.
593 */
594 Init_file_context_func init_file_context;
595
596 /* Set file context to be the current
597 *
598 * Arguments:
599 * void* ssnptr: session pointer
600 * FileContext *: file context that will be current
601 * Returns:
602 * True: changed successfully
603 * False: fail to change
604 */
605 Set_file_context_func set_current_file_context;
606
607 /* Get current file context
608 *
609 * Arguments:
610 * void* ssnptr: session pointer
611 * Returns:
612 * FileContext *: current file context
613 */
614 Get_file_context_func get_current_file_context;
615
616 /* Get main file context that used by preprocessors
617 *
618 * Arguments:
619 * void* ssnptr: session pointer
620 * Returns:
621 * FileContext *: main file context
622 */
623 Get_file_context_func get_main_file_context;
624
625 /* Process file function, called by preprocessors that provides file data
626 *
627 * Arguments:
628 * void* ctx: file context that will be processed
629 * void* p: packet pointer
630 * uint8_t* file_data: file data
631 * int data_size: file data size
632 * FilePosition: file position
633 * bool suspend_block_verdict: used for smb to allow file pass
634 * Returns:
635 * 1: continue processing/log/block this file
636 * 0: ignore this file (no further processing needed)
637 */
638 Process_file_func process_file;
639
640 /* Create the file cache that store file segments and properties.
641 *
642 * Arguments:
643 * uint64_t: total memory available for file cache, including file contexts
644 * uint32_t: maximal number of files pruned when memcap is reached
645 * Returns:
646 * struct _FileCache *: file cache pointer
647 */
648 File_cache_create_func file_cache_create;
649
650 /* Free the file cache that store file segments and properties.
651 *
652 * Arguments:
653 * struct _FileCache *: file cache pointer
654 * Returns:
655 * None
656 */
657 File_cache_free_func file_cache_free;
658
659 /* Get the status of file cache for troubleshooting.
660 *
661 * Arguments:
662 * struct _FileCache *: file cache pointer
663 * Returns:
664 * FileCacheStatus *: status of file cache
665 */
666 File_cache_status_func file_cache_status;
667
668 /* Get a new file entry in the file cache, if already exists, update file name
669 *
670 * Arguments:
671 * struct _FileCache *: file cache that stores file segments
672 * void* : packet pointer
673 * uint64_t: file id that is unique
674 * uint8_t *: file name
675 * uint32_t: file name size
676 * Returns:
677 * None
678 */
679 File_cache_update_entry_func file_cache_update_entry;
680
681 /* Process file segment, when file segment is in order, file data will be
682 * processed; otherwise it is stored.
683 *
684 * Arguments:
685 * struct _FileCache *: file cache that stores file segments
686 * void* : packet pointer
687 * uint64_t: file id that is unique
688 * uint64_t: total file size,
689 * const uint8_t*: file data
690 * int: file data size
691 * uint64_t: file data offset in the file
692 * bool: true for upload, false for download
693 * Returns:
694 * 1: continue processing/log/block this file
695 * 0: ignore this file (no further processing needed)
696 */
697 File_segment_process_func file_segment_process;
698
699 /* Return a unique file instance number
700 *
701 * Arguments:
702 * void *ssnptr: session pointer
703 * Returns:
704 * (u32) a unique file instance id.
705 */
706 Get_new_file_instance get_new_file_instance;
707
708 GetFilePosition get_file_position;
709
710 Get_max_file_capture_size get_max_file_capture_size;
711 File_config_malware_check file_config_malware_check;
712 /* Return the character encoding of a buffer
713 * Arguments:
714 * uint8 *: input buffer
715 * uint32 : input buffer length
716 * Returns:
717 * FileCharEncoding
718 SNORT_CHAR_ENCODING_ASCII = 0,
719 SNORT_CHAR_ENCODING_UTF_16LE,
720 SNORT_CHAR_ENCODING_UTF_16BE
721 */
722 Get_character_encoding get_character_encoding;
723
724 File_cache_mem_adjust_func file_cache_shrink_to_memcap;
725 File_cache_mem_set_func file_cache_set_memcap;
726 File_signature_reset file_signature_reset;
727 /* Return a char string that indicates the file type
728 * Arguments:
729 * void * ssnptr: session pointer
730 * Returns:
731 * File Type name
732 */
733 File_get_filetype_func file_get_filetype;
734
735 /* Logging a file event */
736 File_event_log_dump_func file_event_log_dump;
737 Set_file_partial_func set_file_partial;
738
739 } FileAPI;
740
741 /* To be set by Stream */
742 extern FileAPI *file_api;
743
initFilePosition(FilePosition * position,uint64_t processed_size)744 static inline void initFilePosition(FilePosition *position,
745 uint64_t processed_size)
746 {
747 *position = SNORT_FILE_START;
748 if (processed_size)
749 *position = SNORT_FILE_MIDDLE;
750 }
updateFilePosition(FilePosition * position,uint64_t processed_size)751 static inline void updateFilePosition(FilePosition *position,
752 uint64_t processed_size)
753 {
754 if ((*position == SNORT_FILE_END) || (*position == SNORT_FILE_FULL))
755 *position = SNORT_FILE_START;
756 else if (processed_size)
757 *position = SNORT_FILE_MIDDLE;
758 }
finalFilePosition(FilePosition * position)759 static inline void finalFilePosition(FilePosition *position)
760 {
761 if (*position == SNORT_FILE_START)
762 *position = SNORT_FILE_FULL;
763 else if (*position != SNORT_FILE_FULL)
764 *position = SNORT_FILE_END;
765 }
766
isFileStart(FilePosition position)767 static inline bool isFileStart(FilePosition position)
768 {
769 return ((position == SNORT_FILE_START) || (position == SNORT_FILE_FULL));
770 }
771
isFileEnd(FilePosition position)772 static inline bool isFileEnd(FilePosition position)
773 {
774 return ((position == SNORT_FILE_END) || (position == SNORT_FILE_FULL));
775 }
776 #endif /* FILE_API_H_ */
777
778