|
...
|
...
|
@@ -210,33 +210,62 @@ struct cl_scan_options {
|
|
210
|
210
|
struct cl_engine;
|
|
211
|
211
|
struct cl_settings;
|
|
212
|
212
|
|
|
|
213
|
+/* ----------------------------------------------------------------------------
|
|
|
214
|
+ * Enable global libclamav features.
|
|
|
215
|
+ */
|
|
|
216
|
+
|
|
|
217
|
+/**
|
|
|
218
|
+ * @brief Enable debug messages
|
|
|
219
|
+ */
|
|
|
220
|
+extern void cl_debug(void);
|
|
|
221
|
+
|
|
|
222
|
+/**
|
|
|
223
|
+ * @brief Set libclamav to always create section hashes for PE files.
|
|
|
224
|
+ *
|
|
|
225
|
+ * Section hashes are used in .mdb signature.
|
|
|
226
|
+ */
|
|
|
227
|
+extern void cl_always_gen_section_hash(void);
|
|
|
228
|
+
|
|
|
229
|
+/* ----------------------------------------------------------------------------
|
|
|
230
|
+ * Scan engine functions.
|
|
|
231
|
+ */
|
|
|
232
|
+
|
|
213
|
233
|
/**
|
|
214
|
|
- * @brief This function initializes the openssl crypto system
|
|
|
234
|
+ * @brief This function initializes the openssl crypto system.
|
|
215
|
235
|
*
|
|
216
|
236
|
* Called by cl_init() and does not need to be cleaned up as de-init
|
|
217
|
237
|
* is handled automatically by openssl 1.0.2.h and 1.1.0
|
|
218
|
238
|
*
|
|
219
|
239
|
* @return Always returns 0
|
|
220
|
|
- *
|
|
221
|
|
- */
|
|
|
240
|
+ */
|
|
222
|
241
|
int cl_initialize_crypto(void);
|
|
223
|
242
|
|
|
224
|
243
|
/**
|
|
225
|
|
- * @brief This is a deprecated function that used to clean up ssl crypto inits
|
|
226
|
|
- *
|
|
227
|
|
- * Call to EVP_cleanup() has been removed since cleanup is now handled by
|
|
228
|
|
- * auto-deinit as of openssl 1.0.2h and 1.1.0
|
|
|
244
|
+ * @brief This is a deprecated function that used to clean up ssl crypto inits.
|
|
229
|
245
|
*
|
|
|
246
|
+ * Call to EVP_cleanup() has been removed since cleanup is now handled by
|
|
|
247
|
+ * auto-deinit as of openssl 1.0.2h and 1.1.0
|
|
230
|
248
|
*/
|
|
231
|
249
|
void cl_cleanup_crypto(void);
|
|
232
|
250
|
|
|
233
|
251
|
#define CL_INIT_DEFAULT 0x0
|
|
|
252
|
+/**
|
|
|
253
|
+ * @brief Initialize the ClamAV library.
|
|
|
254
|
+ *
|
|
|
255
|
+ * @param initoptions Unused.
|
|
|
256
|
+ * @return cl_error_t CL_SUCCESS if everything initalized correctly.
|
|
|
257
|
+ */
|
|
234
|
258
|
extern int cl_init(unsigned int initoptions);
|
|
235
|
259
|
|
|
|
260
|
+/**
|
|
|
261
|
+ * @brief Allocate a new scanning engine and initialize default settings.
|
|
|
262
|
+ *
|
|
|
263
|
+ * The engine should be freed with `cl_engine_free()`.
|
|
|
264
|
+ *
|
|
|
265
|
+ * @return struct cl_engine* Pointer to the scanning engine.
|
|
|
266
|
+ */
|
|
236
|
267
|
extern struct cl_engine *cl_engine_new(void);
|
|
237
|
268
|
|
|
238
|
|
-extern void cl_always_gen_section_hash(void);
|
|
239
|
|
-
|
|
240
|
269
|
enum cl_engine_field {
|
|
241
|
270
|
CL_ENGINE_MAX_SCANSIZE, /* uint64_t */
|
|
242
|
271
|
CL_ENGINE_MAX_FILESIZE, /* uint64_t */
|
|
...
|
...
|
@@ -301,193 +330,573 @@ typedef struct cli_stats_sections {
|
|
301
|
301
|
struct cli_section_hash *sections;
|
|
302
|
302
|
} stats_section_t;
|
|
303
|
303
|
|
|
|
304
|
+/**
|
|
|
305
|
+ * @brief Set a numerical engine option.
|
|
|
306
|
+ *
|
|
|
307
|
+ * @param engine An initialized scan engine.
|
|
|
308
|
+ * @param cl_engine_field A CL_ENGINE option.
|
|
|
309
|
+ * @param num The new engine option value.
|
|
|
310
|
+ * @return cl_error_t CL_SUCCESS if successfully set.
|
|
|
311
|
+ * @return cl_error_t CL_EARG if the field number was incorrect.
|
|
|
312
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
313
|
+ */
|
|
304
|
314
|
extern int cl_engine_set_num(struct cl_engine *engine, enum cl_engine_field field, long long num);
|
|
305
|
315
|
|
|
|
316
|
+/**
|
|
|
317
|
+ * @brief Get a numerical engine option.
|
|
|
318
|
+ *
|
|
|
319
|
+ * @param engine An initialized scan engine.
|
|
|
320
|
+ * @param cl_engine_field A CL_ENGINE option.
|
|
|
321
|
+ * @param err (optional) A cl_error_t status code.
|
|
|
322
|
+ * @return long long The numerical option value.
|
|
|
323
|
+ */
|
|
306
|
324
|
extern long long cl_engine_get_num(const struct cl_engine *engine, enum cl_engine_field field, int *err);
|
|
307
|
325
|
|
|
|
326
|
+/**
|
|
|
327
|
+ * @brief Set a string engine option.
|
|
|
328
|
+ *
|
|
|
329
|
+ * @param engine An initialized scan engine.
|
|
|
330
|
+ * @param cl_engine_field A CL_ENGINE option.
|
|
|
331
|
+ * @param str The new engine option value.
|
|
|
332
|
+ * @return cl_error_t CL_SUCCESS if successfully set.
|
|
|
333
|
+ * @return cl_error_t CL_EARG if the field number was incorrect.
|
|
|
334
|
+ * @return cl_error_t CL_EMEM if a memory allocation error occurred.
|
|
|
335
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
336
|
+ */
|
|
308
|
337
|
extern int cl_engine_set_str(struct cl_engine *engine, enum cl_engine_field field, const char *str);
|
|
309
|
338
|
|
|
|
339
|
+/**
|
|
|
340
|
+ * @brief Get a string engine option.
|
|
|
341
|
+ *
|
|
|
342
|
+ * @param engine An initialized scan engine.
|
|
|
343
|
+ * @param cl_engine_field A CL_ENGINE option.
|
|
|
344
|
+ * @param err (optional) A cl_error_t status code.
|
|
|
345
|
+ * @return const char * The string option value.
|
|
|
346
|
+ */
|
|
310
|
347
|
extern const char *cl_engine_get_str(const struct cl_engine *engine, enum cl_engine_field field, int *err);
|
|
311
|
348
|
|
|
|
349
|
+/**
|
|
|
350
|
+ * @brief Copy the settings from an existing scan engine.
|
|
|
351
|
+ *
|
|
|
352
|
+ * The cl_settings pointer is allocated and must be freed with cl_engine_settings_free().
|
|
|
353
|
+ *
|
|
|
354
|
+ * @param engine An configured scan engine.
|
|
|
355
|
+ * @return struct cl_settings* The settings.
|
|
|
356
|
+ */
|
|
312
|
357
|
extern struct cl_settings *cl_engine_settings_copy(const struct cl_engine *engine);
|
|
313
|
358
|
|
|
|
359
|
+/**
|
|
|
360
|
+ * @brief Apply settings from a settings structure to a scan engine.
|
|
|
361
|
+ *
|
|
|
362
|
+ * @param engine A scan engine.
|
|
|
363
|
+ * @param settings The settings.
|
|
|
364
|
+ * @return cl_error_t CL_SUCCESS if successful.
|
|
|
365
|
+ * @return cl_error_t CL_EMEM if a memory allocation error occurred.
|
|
|
366
|
+ */
|
|
314
|
367
|
extern int cl_engine_settings_apply(struct cl_engine *engine, const struct cl_settings *settings);
|
|
315
|
368
|
|
|
|
369
|
+/**
|
|
|
370
|
+ * @brief Free a settings struct pointer.
|
|
|
371
|
+ *
|
|
|
372
|
+ * @param settings The settings struct pointer.
|
|
|
373
|
+ * @return cl_error_t CL_SUCCESS if successful.
|
|
|
374
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
375
|
+ */
|
|
316
|
376
|
extern int cl_engine_settings_free(struct cl_settings *settings);
|
|
317
|
377
|
|
|
|
378
|
+/**
|
|
|
379
|
+ * @brief Prepare the scanning engine.
|
|
|
380
|
+ *
|
|
|
381
|
+ * Called this after all required databases have been loaded and settings have
|
|
|
382
|
+ * been applied.
|
|
|
383
|
+ *
|
|
|
384
|
+ * @param engine A scan engine.
|
|
|
385
|
+ * @return cl_error_t CL_SUCCESS if successful.
|
|
|
386
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
387
|
+ */
|
|
318
|
388
|
extern int cl_engine_compile(struct cl_engine *engine);
|
|
319
|
389
|
|
|
|
390
|
+/**
|
|
|
391
|
+ * @brief Add a reference count to the engine.
|
|
|
392
|
+ *
|
|
|
393
|
+ * Thread safety mechanism so that the engine is not free'd by another thread.
|
|
|
394
|
+ *
|
|
|
395
|
+ * The engine is initialized with refcount = 1, so this only needs to be called
|
|
|
396
|
+ * for additional scanning threads.
|
|
|
397
|
+ *
|
|
|
398
|
+ * @param engine A scan engine.
|
|
|
399
|
+ * @return cl_error_t CL_SUCCESS if successful.
|
|
|
400
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
401
|
+ */
|
|
320
|
402
|
extern int cl_engine_addref(struct cl_engine *engine);
|
|
321
|
403
|
|
|
|
404
|
+/**
|
|
|
405
|
+ * @brief Free an engine.
|
|
|
406
|
+ *
|
|
|
407
|
+ * Will lower the reference count on an engine. If the reference count hits
|
|
|
408
|
+ * zero, the engine will be freed.
|
|
|
409
|
+ *
|
|
|
410
|
+ * @param engine A scan engine.
|
|
|
411
|
+ * @return cl_error_t CL_SUCCESS if successful.
|
|
|
412
|
+ * @return cl_error_t CL_ENULLARG null arguments were provided.
|
|
|
413
|
+ */
|
|
322
|
414
|
extern int cl_engine_free(struct cl_engine *engine);
|
|
323
|
415
|
|
|
324
|
|
-extern void cli_cache_disable(void);
|
|
325
|
|
-
|
|
326
|
|
-extern int cli_cache_enable(struct cl_engine *engine);
|
|
327
|
|
-
|
|
328
|
|
-/* CALLBACKS */
|
|
329
|
|
-
|
|
330
|
|
-/* I certainly wish I could declare the callback protos stable and
|
|
331
|
|
- move on to better things. But real life crossed my way enough times
|
|
332
|
|
- already and what looked perfect had to evolve somehow.
|
|
333
|
|
- So all I can say is I'll try my best not to break these things in the long run.
|
|
334
|
|
- But I just can't guarantee that won't happen (again). */
|
|
|
416
|
+/* ----------------------------------------------------------------------------
|
|
|
417
|
+ * Callback function type definitions.
|
|
|
418
|
+ */
|
|
335
|
419
|
|
|
|
420
|
+/**
|
|
|
421
|
+ * @brief Pre-cache callback.
|
|
|
422
|
+ *
|
|
|
423
|
+ * Called for each processed file (both the entry level - AKA 'outer' - file and
|
|
|
424
|
+ * inner files - those generated when processing archive and container files), before
|
|
|
425
|
+ * the actual scanning takes place.
|
|
|
426
|
+ *
|
|
|
427
|
+ * @param fd File descriptor which is about to be scanned.
|
|
|
428
|
+ * @param type File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
|
|
|
429
|
+ * @param context Opaque application provided data.
|
|
|
430
|
+ * @return CL_CLEAN = File is scanned.
|
|
|
431
|
+ * @return CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.
|
|
|
432
|
+ * @return CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected.
|
|
|
433
|
+ */
|
|
336
|
434
|
typedef cl_error_t (*clcb_pre_cache)(int fd, const char *type, void *context);
|
|
337
|
|
-/* PRE-CACHE
|
|
338
|
|
- Called for each processed file (both the entry level - AKA 'outer' - file and
|
|
339
|
|
- inner files - those generated when processing archive and container files), before
|
|
340
|
|
- the actual scanning takes place.
|
|
341
|
|
-
|
|
342
|
|
-Input:
|
|
343
|
|
-fd = File descriptor which is about to be scanned
|
|
344
|
|
-type = File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE")
|
|
345
|
|
-context = Opaque application provided data
|
|
346
|
|
-
|
|
347
|
|
-Output:
|
|
348
|
|
-CL_CLEAN = File is scanned
|
|
349
|
|
-CL_BREAK = Whitelisted by callback - file is skipped and marked as clean
|
|
350
|
|
-CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected
|
|
351
|
|
-*/
|
|
|
435
|
+/**
|
|
|
436
|
+ * @brief Set a custom pre-cache callback function.
|
|
|
437
|
+ *
|
|
|
438
|
+ * @param engine The initialized scanning engine.
|
|
|
439
|
+ * @param callback The callback function pointer.
|
|
|
440
|
+ */
|
|
352
|
441
|
extern void cl_engine_set_clcb_pre_cache(struct cl_engine *engine, clcb_pre_cache callback);
|
|
353
|
442
|
|
|
|
443
|
+/**
|
|
|
444
|
+ * @brief Pre-scan callback.
|
|
|
445
|
+ *
|
|
|
446
|
+ * Called for each NEW file (inner and outer) before the scanning takes place. This is
|
|
|
447
|
+ * roughly the the same as clcb_before_cache, but it is affected by clean file caching.
|
|
|
448
|
+ * This means that it won't be called if a clean cached file (inner or outer) is
|
|
|
449
|
+ * scanned a second time.
|
|
|
450
|
+ *
|
|
|
451
|
+ * @param fd File descriptor which is about to be scanned.
|
|
|
452
|
+ * @param type File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
|
|
|
453
|
+ * @param context Opaque application provided data.
|
|
|
454
|
+ * @return CL_CLEAN = File is scanned.
|
|
|
455
|
+ * @return CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.
|
|
|
456
|
+ * @return CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected.
|
|
|
457
|
+ */
|
|
354
|
458
|
typedef cl_error_t (*clcb_pre_scan)(int fd, const char *type, void *context);
|
|
355
|
|
-/* PRE-SCAN
|
|
356
|
|
- Called for each NEW file (inner and outer) before the scanning takes place. This is
|
|
357
|
|
- roughly the the same as clcb_before_cache, but it is affected by clean file caching.
|
|
358
|
|
- This means that it won't be called if a clean cached file (inner or outer) is
|
|
359
|
|
- scanned a second time.
|
|
360
|
|
-
|
|
361
|
|
-Input:
|
|
362
|
|
-fd = File descriptor which is about to be scanned
|
|
363
|
|
-type = File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE")
|
|
364
|
|
-context = Opaque application provided data
|
|
365
|
|
-
|
|
366
|
|
-Output:
|
|
367
|
|
-CL_CLEAN = File is scanned
|
|
368
|
|
-CL_BREAK = Whitelisted by callback - file is skipped and marked as clean
|
|
369
|
|
-CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected
|
|
370
|
|
-*/
|
|
|
459
|
+/**
|
|
|
460
|
+ * @brief Set a custom pre-scan callback function.
|
|
|
461
|
+ *
|
|
|
462
|
+ * @param engine The initialized scanning engine.
|
|
|
463
|
+ * @param callback The callback function pointer.
|
|
|
464
|
+ */
|
|
371
|
465
|
extern void cl_engine_set_clcb_pre_scan(struct cl_engine *engine, clcb_pre_scan callback);
|
|
372
|
466
|
|
|
|
467
|
+/**
|
|
|
468
|
+ * @brief Post-scan callback.
|
|
|
469
|
+ *
|
|
|
470
|
+ * Called for each processed file (inner and outer), after the scanning is complete.
|
|
|
471
|
+ * In all-match mode, the virname will be one of the matches, but there is no
|
|
|
472
|
+ * guarantee in which order the matches will occur, thus the final virname may
|
|
|
473
|
+ * be any one of the matches.
|
|
|
474
|
+ *
|
|
|
475
|
+ * @param fd File descriptor which was scanned.
|
|
|
476
|
+ * @param result The scan result for the file.
|
|
|
477
|
+ * @param virname A signature name if there was one or more matches.
|
|
|
478
|
+ * @param context Opaque application provided data.
|
|
|
479
|
+ * @return Scan result is not overridden.
|
|
|
480
|
+ * @return CL_BREAK = Whitelisted by callback - scan result is set to CL_CLEAN.
|
|
|
481
|
+ * @return Blacklisted by callback - scan result is set to CL_VIRUS.
|
|
|
482
|
+ */
|
|
373
|
483
|
typedef cl_error_t (*clcb_post_scan)(int fd, int result, const char *virname, void *context);
|
|
374
|
|
-/* POST-SCAN
|
|
375
|
|
- Called for each processed file (inner and outer), after the scanning is complete.
|
|
376
|
|
-
|
|
377
|
|
-Input:
|
|
378
|
|
-fd = File descriptor which is was scanned
|
|
379
|
|
-result = The scan result for the file
|
|
380
|
|
-virname = Virus name if infected
|
|
381
|
|
-context = Opaque application provided data
|
|
382
|
|
-
|
|
383
|
|
-Output:
|
|
384
|
|
-CL_CLEAN = Scan result is not overridden
|
|
385
|
|
-CL_BREAK = Whitelisted by callback - scan result is set to CL_CLEAN
|
|
386
|
|
-CL_VIRUS = Blacklisted by callback - scan result is set to CL_VIRUS
|
|
387
|
|
-*/
|
|
|
484
|
+/**
|
|
|
485
|
+ * @brief Set a custom post-scan callback function.
|
|
|
486
|
+ *
|
|
|
487
|
+ * @param engine The initialized scanning engine.
|
|
|
488
|
+ * @param callback The callback function pointer.
|
|
|
489
|
+ */
|
|
388
|
490
|
extern void cl_engine_set_clcb_post_scan(struct cl_engine *engine, clcb_post_scan callback);
|
|
389
|
491
|
|
|
|
492
|
+/**
|
|
|
493
|
+ * @brief Post-scan callback.
|
|
|
494
|
+ *
|
|
|
495
|
+ * Called for each signature match.
|
|
|
496
|
+ * If all-match is enabled, clcb_virus_found() may be called multiple times per
|
|
|
497
|
+ * scan.
|
|
|
498
|
+ *
|
|
|
499
|
+ * In addition, clcb_virus_found() does not have a return value and thus.
|
|
|
500
|
+ * can not be used to whitelist the match.
|
|
|
501
|
+ *
|
|
|
502
|
+ * @param fd File descriptor which was scanned.
|
|
|
503
|
+ * @param virname Virus name.
|
|
|
504
|
+ * @param context Opaque application provided data.
|
|
|
505
|
+ */
|
|
390
|
506
|
typedef void (*clcb_virus_found)(int fd, const char *virname, void *context);
|
|
391
|
|
-/* VIRUS FOUND
|
|
392
|
|
- Called for each virus found.
|
|
393
|
|
-
|
|
394
|
|
-Input:
|
|
395
|
|
-fd = File descriptor which is was scanned
|
|
396
|
|
-virname = Virus name
|
|
397
|
|
-context = Opaque application provided data
|
|
398
|
|
-
|
|
399
|
|
-Output:
|
|
400
|
|
-none
|
|
401
|
|
-*/
|
|
|
507
|
+/**
|
|
|
508
|
+ * @brief Set a custom virus-found callback function.
|
|
|
509
|
+ *
|
|
|
510
|
+ * @param engine The initialized scanning engine.
|
|
|
511
|
+ * @param callback The callback function pointer.
|
|
|
512
|
+ */
|
|
402
|
513
|
extern void cl_engine_set_clcb_virus_found(struct cl_engine *engine, clcb_virus_found callback);
|
|
403
|
514
|
|
|
|
515
|
+/**
|
|
|
516
|
+ * @brief Signature-load callback.
|
|
|
517
|
+ *
|
|
|
518
|
+ * May be used to ignore signatures at database load time.
|
|
|
519
|
+ *
|
|
|
520
|
+ * WARNING: Some signatures (notably ldb, cbc) can be dependent upon other signatures.
|
|
|
521
|
+ * Failure to preserve dependency chains will result in database loading failure.
|
|
|
522
|
+ * It is the implementor's responsibility to guarantee consistency.
|
|
|
523
|
+ *
|
|
|
524
|
+ * @param type The signature type (e.g. "db", "ndb", "mdb", etc.)
|
|
|
525
|
+ * @param name Signature name.
|
|
|
526
|
+ * @param custom The signature is official (custom == 0) or custom (custom != 0)
|
|
|
527
|
+ * @param context Opaque application provided data
|
|
|
528
|
+ * @return 0 to load the current signature.
|
|
|
529
|
+ * @return Non-0 to skip the current signature.
|
|
|
530
|
+ */
|
|
404
|
531
|
typedef int (*clcb_sigload)(const char *type, const char *name, unsigned int custom, void *context);
|
|
405
|
|
-/* SIGNATURE LOAD
|
|
406
|
|
-Input:
|
|
407
|
|
-type = The signature type (e.g. "db", "ndb", "mdb", etc.)
|
|
408
|
|
-name = The virus name
|
|
409
|
|
-custom = The signature is official (custom == 0) or custom (custom != 0)
|
|
410
|
|
-context = Opaque application provided data
|
|
411
|
|
-
|
|
412
|
|
-Output:
|
|
413
|
|
-0 = Load the current signature
|
|
414
|
|
-Non 0 = Skip the current signature
|
|
415
|
|
-
|
|
416
|
|
-WARNING: Some signatures (notably ldb, cbc) can be dependent upon other signatures.
|
|
417
|
|
- Failure to preserve dependency chains will result in database loading failure.
|
|
418
|
|
- It is the implementor's responsibility to guarantee consistency.
|
|
419
|
|
-*/
|
|
|
532
|
+/**
|
|
|
533
|
+ * @brief Set a custom signature-load callback function.
|
|
|
534
|
+ *
|
|
|
535
|
+ * @param engine The initialized scanning engine.
|
|
|
536
|
+ * @param callback The callback function pointer.
|
|
|
537
|
+ * @param context Opaque application provided data.
|
|
|
538
|
+ */
|
|
420
|
539
|
extern void cl_engine_set_clcb_sigload(struct cl_engine *engine, clcb_sigload callback, void *context);
|
|
421
|
540
|
|
|
422
|
|
-/* LibClamAV messages callback
|
|
|
541
|
+enum cl_msg {
|
|
|
542
|
+ /* leave room for more message levels in the future */
|
|
|
543
|
+ CL_MSG_INFO_VERBOSE = 32, /* verbose */
|
|
|
544
|
+ CL_MSG_WARN = 64, /* LibClamAV WARNING: */
|
|
|
545
|
+ CL_MSG_ERROR = 128/* LibClamAV ERROR: */
|
|
|
546
|
+};
|
|
|
547
|
+
|
|
|
548
|
+/**
|
|
|
549
|
+ * @brief Logging message callback for info, warning, and error messages.
|
|
|
550
|
+ *
|
|
423
|
551
|
* The specified callback will be called instead of logging to stderr.
|
|
424
|
552
|
* Messages of lower severity than specified are logged as usual.
|
|
425
|
553
|
*
|
|
|
554
|
+ * Callback may be used to silence logging by assigning a do-nothing function.
|
|
|
555
|
+ * Does not affect debug log messages.
|
|
|
556
|
+ *
|
|
426
|
557
|
* Just like with cl_debug() this must be called before going multithreaded.
|
|
427
|
558
|
* Callable before cl_init, if you want to log messages from cl_init() itself.
|
|
428
|
559
|
*
|
|
429
|
|
- * You can use context of cl_scandesc_callback to convey more information to the callback (such as the filename!)
|
|
|
560
|
+ * You can use context of cl_scandesc_callback to convey more information to
|
|
|
561
|
+ * the callback (such as the filename!).
|
|
|
562
|
+ *
|
|
430
|
563
|
* Note: setting a 2nd callbacks overwrites previous, multiple callbacks are not
|
|
431
|
|
- * supported
|
|
|
564
|
+ * supported.
|
|
|
565
|
+ *
|
|
|
566
|
+ * @param severity Message severity (CL_MSG_INFO_VERBOSE, CL_MSG_WARN, or CL_MSG_ERROR).
|
|
|
567
|
+ * @param fullmsg The log message including the "LibClamAV <severity>: " prefix.
|
|
|
568
|
+ * @param msg The log message.
|
|
|
569
|
+ * @param context Opaque application provided data.
|
|
432
|
570
|
*/
|
|
433
|
|
-enum cl_msg {
|
|
434
|
|
- /* leave room for more message levels in the future */
|
|
435
|
|
- CL_MSG_INFO_VERBOSE = 32, /* verbose */
|
|
436
|
|
- CL_MSG_WARN = 64, /* LibClamAV WARNING: */
|
|
437
|
|
- CL_MSG_ERROR = 128/* LibClamAV ERROR: */
|
|
438
|
|
-};
|
|
439
|
571
|
typedef void (*clcb_msg)(enum cl_msg severity, const char *fullmsg, const char *msg, void *context);
|
|
|
572
|
+/**
|
|
|
573
|
+ * @brief Set a custom logging message callback function for all of libclamav.
|
|
|
574
|
+ *
|
|
|
575
|
+ * @param callback The callback function pointer.
|
|
|
576
|
+ */
|
|
440
|
577
|
extern void cl_set_clcb_msg(clcb_msg callback);
|
|
441
|
578
|
|
|
442
|
|
-/* LibClamAV hash stats callback */
|
|
|
579
|
+/**
|
|
|
580
|
+ * @brief LibClamAV hash stats callback.
|
|
|
581
|
+ *
|
|
|
582
|
+ * Callback that provides the hash of a scanned sample if a signature alerted.
|
|
|
583
|
+ * Provides a mechanism to record detection statistics.
|
|
|
584
|
+ *
|
|
|
585
|
+ * @param fd File descriptor if available, else -1.
|
|
|
586
|
+ * @param size Sample size
|
|
|
587
|
+ * @param md5 Sample md5 hash
|
|
|
588
|
+ * @param virname Signature name that the sample matched against
|
|
|
589
|
+ * @param context Opaque application provided data
|
|
|
590
|
+ */
|
|
443
|
591
|
typedef void (*clcb_hash)(int fd, unsigned long long size, const unsigned char *md5, const char *virname, void *context);
|
|
|
592
|
+/**
|
|
|
593
|
+ * @brief Set a custom hash stats callback function.
|
|
|
594
|
+ *
|
|
|
595
|
+ * @param engine The initialized scanning engine.
|
|
|
596
|
+ * @param callback The callback function pointer.
|
|
|
597
|
+ */
|
|
444
|
598
|
extern void cl_engine_set_clcb_hash(struct cl_engine *engine, clcb_hash callback);
|
|
445
|
599
|
|
|
446
|
|
-/* Archive member metadata callback. Return CL_VIRUS to blacklist, CL_CLEAN to
|
|
447
|
|
- * continue scanning */
|
|
|
600
|
+/**
|
|
|
601
|
+ * @brief Archive meta matching callback function.
|
|
|
602
|
+ *
|
|
|
603
|
+ * May be used to blacklist archive/container samples based on archive metadata.
|
|
|
604
|
+ * Function is invoked multiple times per archive. Typically once per contained file.
|
|
|
605
|
+ *
|
|
|
606
|
+ * Note: Used by the --archive-verbose clamscan option. Overriding this will alter
|
|
|
607
|
+ * the output from --archive-verbose.
|
|
|
608
|
+ *
|
|
|
609
|
+ * @param container_type String name of type (CL_TYPE).
|
|
|
610
|
+ * @param fsize_container Sample size
|
|
|
611
|
+ * @param filename Filename associated with the data in archive.
|
|
|
612
|
+ * @param fsize_real Size of file after decompression (according to the archive).
|
|
|
613
|
+ * @param is_encrypted Boolean non-zero if the contained file is encrypted.
|
|
|
614
|
+ * @param filepos_container File index in container.
|
|
|
615
|
+ * @param context Opaque application provided data.
|
|
|
616
|
+ * @return CL_VIRUS to blacklist
|
|
|
617
|
+ * @return CL_CLEAN to continue scanning
|
|
|
618
|
+ */
|
|
448
|
619
|
typedef cl_error_t (*clcb_meta)(const char* container_type, unsigned long fsize_container, const char *filename,
|
|
449
|
620
|
unsigned long fsize_real, int is_encrypted, unsigned int filepos_container, void *context);
|
|
|
621
|
+/**
|
|
|
622
|
+ * @brief Set a custom archive metadata matching callback function.
|
|
|
623
|
+ *
|
|
|
624
|
+ * @param engine The initialized scanning engine.
|
|
|
625
|
+ * @param callback The callback function pointer.
|
|
|
626
|
+ */
|
|
450
|
627
|
extern void cl_engine_set_clcb_meta(struct cl_engine *engine, clcb_meta callback);
|
|
451
|
628
|
|
|
452
|
|
-/* File properties callback */
|
|
|
629
|
+/**
|
|
|
630
|
+ * @brief File properties callback function.
|
|
|
631
|
+ *
|
|
|
632
|
+ * Invoked after a scan the CL_SCAN_GENERAL_COLLECT_METADATA general scan option
|
|
|
633
|
+ * is enabled and libclamav was built with json support.
|
|
|
634
|
+ *
|
|
|
635
|
+ * @param j_propstr File properties/metadata in a JSON encoded string.
|
|
|
636
|
+ * @param rc The cl_error_t return code from the scan.
|
|
|
637
|
+ * @param cbdata Opaque application provided data.
|
|
|
638
|
+ */
|
|
453
|
639
|
typedef int (*clcb_file_props)(const char *j_propstr, int rc, void *cbdata);
|
|
|
640
|
+/**
|
|
|
641
|
+ * @brief Set a custom file properties callback function.
|
|
|
642
|
+ *
|
|
|
643
|
+ * @param engine The initialized scanning engine.
|
|
|
644
|
+ * @param callback The callback function pointer.
|
|
|
645
|
+ */
|
|
454
|
646
|
extern void cl_engine_set_clcb_file_props(struct cl_engine *engine, clcb_file_props callback);
|
|
455
|
647
|
|
|
456
|
|
-/* Statistics/intelligence gathering callbacks */
|
|
|
648
|
+/* ----------------------------------------------------------------------------
|
|
|
649
|
+ * Statistics/telemetry gathering callbacks.
|
|
|
650
|
+ *
|
|
|
651
|
+ * The statistics callback functions may be used to implement a telemetry
|
|
|
652
|
+ * gathering feature.
|
|
|
653
|
+ *
|
|
|
654
|
+ * The structure definition for `cbdata` is entirely up to the caller, as are
|
|
|
655
|
+ * the implementations of each of the callback functions defined below.
|
|
|
656
|
+ */
|
|
|
657
|
+
|
|
|
658
|
+/**
|
|
|
659
|
+ * @brief Set a pointer the caller-defined cbdata structure.
|
|
|
660
|
+ *
|
|
|
661
|
+ * The data must persist at least until `clcb_stats_submit()` is called, or
|
|
|
662
|
+ * `clcb_stats_flush()` is called (optional).
|
|
|
663
|
+ *
|
|
|
664
|
+ * @param engine The scanning engine.
|
|
|
665
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
666
|
+ */
|
|
457
|
667
|
extern void cl_engine_set_stats_set_cbdata(struct cl_engine *engine, void *cbdata);
|
|
458
|
668
|
|
|
|
669
|
+/**
|
|
|
670
|
+ * @brief Add sample metadata to the statistics for a sample that matched on a signature.
|
|
|
671
|
+ *
|
|
|
672
|
+ * @param virname Name of the signature that matched.
|
|
|
673
|
+ * @param md5 Sample hash.
|
|
|
674
|
+ * @param size Sample size.
|
|
|
675
|
+ * @param sections PE section data, if applicable.
|
|
|
676
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
677
|
+ */
|
|
459
|
678
|
typedef void (*clcb_stats_add_sample)(const char *virname, const unsigned char *md5, size_t size, stats_section_t *sections, void *cbdata);
|
|
|
679
|
+/**
|
|
|
680
|
+ * @brief Set a custom callback function to add sample metadata to a statistics report.
|
|
|
681
|
+ *
|
|
|
682
|
+ * @param engine The initialized scanning engine.
|
|
|
683
|
+ * @param callback The callback function pointer.
|
|
|
684
|
+ */
|
|
460
|
685
|
extern void cl_engine_set_clcb_stats_add_sample(struct cl_engine *engine, clcb_stats_add_sample callback);
|
|
461
|
686
|
|
|
|
687
|
+/**
|
|
|
688
|
+ * @brief Remove a specific sample from the statistics report.
|
|
|
689
|
+ *
|
|
|
690
|
+ * @param virname Name of the signature that matched.
|
|
|
691
|
+ * @param md5 Sample hash.
|
|
|
692
|
+ * @param size Sample size.
|
|
|
693
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
694
|
+ */
|
|
462
|
695
|
typedef void (*clcb_stats_remove_sample)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
|
|
|
696
|
+/**
|
|
|
697
|
+ * @brief Set a custom callback function to remove sample metadata from a statistics report.
|
|
|
698
|
+ *
|
|
|
699
|
+ * @param engine The initialized scanning engine.
|
|
|
700
|
+ * @param callback The callback function pointer.
|
|
|
701
|
+ */
|
|
463
|
702
|
extern void cl_engine_set_clcb_stats_remove_sample(struct cl_engine *engine, clcb_stats_remove_sample callback);
|
|
464
|
703
|
|
|
|
704
|
+/**
|
|
|
705
|
+ * @brief Decrement the hit count listed in the statistics report for a specific sample.
|
|
|
706
|
+ *
|
|
|
707
|
+ * @param virname Name of the signature that matched.
|
|
|
708
|
+ * @param md5 Sample hash.
|
|
|
709
|
+ * @param size Sample size.
|
|
|
710
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
711
|
+ */
|
|
465
|
712
|
typedef void (*clcb_stats_decrement_count)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
|
|
|
713
|
+/**
|
|
|
714
|
+ * @brief Set a custom callback function to decrement the hit count listed in the statistics report for a specific sample.
|
|
|
715
|
+ *
|
|
|
716
|
+ * This function may remove the sample from the report if the hit count is decremented to 0.
|
|
|
717
|
+ *
|
|
|
718
|
+ * @param engine The initialized scanning engine.
|
|
|
719
|
+ * @param callback The callback function pointer.
|
|
|
720
|
+ */
|
|
466
|
721
|
extern void cl_engine_set_clcb_stats_decrement_count(struct cl_engine *engine, clcb_stats_decrement_count callback);
|
|
467
|
722
|
|
|
|
723
|
+/**
|
|
|
724
|
+ * @brief Function to submit a statistics report.
|
|
|
725
|
+ *
|
|
|
726
|
+ * @param engine The initialized scanning engine.
|
|
|
727
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
728
|
+ */
|
|
468
|
729
|
typedef void (*clcb_stats_submit)(struct cl_engine *engine, void *cbdata);
|
|
|
730
|
+/**
|
|
|
731
|
+ * @brief Set a custom callback function to submit the statistics report.
|
|
|
732
|
+ *
|
|
|
733
|
+ * @param engine The initialized scanning engine.
|
|
|
734
|
+ * @param callback The callback function pointer.
|
|
|
735
|
+ */
|
|
469
|
736
|
extern void cl_engine_set_clcb_stats_submit(struct cl_engine *engine, clcb_stats_submit callback);
|
|
470
|
737
|
|
|
|
738
|
+/**
|
|
|
739
|
+ * @brief Function to flush/free the statistics report data.
|
|
|
740
|
+ *
|
|
|
741
|
+ * @param engine The initialized scanning engine.
|
|
|
742
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
743
|
+ */
|
|
471
|
744
|
typedef void (*clcb_stats_flush)(struct cl_engine *engine, void *cbdata);
|
|
|
745
|
+/**
|
|
|
746
|
+ * @brief Set a custom callback function to flush/free the statistics report data.
|
|
|
747
|
+ *
|
|
|
748
|
+ * @param engine The initialized scanning engine.
|
|
|
749
|
+ * @param callback The callback function pointer.
|
|
|
750
|
+ */
|
|
472
|
751
|
extern void cl_engine_set_clcb_stats_flush(struct cl_engine *engine, clcb_stats_flush callback);
|
|
473
|
752
|
|
|
|
753
|
+/**
|
|
|
754
|
+ * @brief Function to get the number of samples listed in the statistics report.
|
|
|
755
|
+ *
|
|
|
756
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
757
|
+ */
|
|
474
|
758
|
typedef size_t (*clcb_stats_get_num)(void *cbdata);
|
|
|
759
|
+/**
|
|
|
760
|
+ * @brief Set a custom callback function to get the number of samples listed in the statistics report.
|
|
|
761
|
+ *
|
|
|
762
|
+ * @param engine The initialized scanning engine.
|
|
|
763
|
+ * @param callback The callback function pointer.
|
|
|
764
|
+ */
|
|
475
|
765
|
extern void cl_engine_set_clcb_stats_get_num(struct cl_engine *engine, clcb_stats_get_num callback);
|
|
476
|
766
|
|
|
|
767
|
+/**
|
|
|
768
|
+ * @brief Function to get the size of memory used to store the statistics report.
|
|
|
769
|
+ *
|
|
|
770
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
771
|
+ */
|
|
477
|
772
|
typedef size_t (*clcb_stats_get_size)(void *cbdata);
|
|
|
773
|
+/**
|
|
|
774
|
+ * @brief Set a custom callback function to get the size of memory used to store the statistics report.
|
|
|
775
|
+ *
|
|
|
776
|
+ * @param engine The initialized scanning engine.
|
|
|
777
|
+ * @param callback The callback function pointer.
|
|
|
778
|
+ */
|
|
478
|
779
|
extern void cl_engine_set_clcb_stats_get_size(struct cl_engine *engine, clcb_stats_get_size callback);
|
|
479
|
780
|
|
|
|
781
|
+/**
|
|
|
782
|
+ * @brief Function to get the machine's unique host ID.
|
|
|
783
|
+ *
|
|
|
784
|
+ * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
|
|
|
785
|
+ */
|
|
480
|
786
|
typedef char * (*clcb_stats_get_hostid)(void *cbdata);
|
|
|
787
|
+/**
|
|
|
788
|
+ * @brief Set a custom callback function to get the machine's unique host ID.
|
|
|
789
|
+ *
|
|
|
790
|
+ * @param engine The initialized scanning engine.
|
|
|
791
|
+ * @param callback The callback function pointer.
|
|
|
792
|
+ */
|
|
481
|
793
|
extern void cl_engine_set_clcb_stats_get_hostid(struct cl_engine *engine, clcb_stats_get_hostid callback);
|
|
482
|
794
|
|
|
|
795
|
+/**
|
|
|
796
|
+ * @brief Function enables the built-in statistics reporting feature.
|
|
|
797
|
+ *
|
|
|
798
|
+ * @param engine The initialized scanning engine.
|
|
|
799
|
+ */
|
|
483
|
800
|
extern void cl_engine_stats_enable(struct cl_engine *engine);
|
|
484
|
801
|
|
|
485
|
|
-struct cl_stat {
|
|
486
|
|
- char *dir;
|
|
487
|
|
- STATBUF *stattab;
|
|
488
|
|
- char **statdname;
|
|
489
|
|
- unsigned int entries;
|
|
490
|
|
-};
|
|
|
802
|
+/* ----------------------------------------------------------------------------
|
|
|
803
|
+ * File scanning.
|
|
|
804
|
+ */
|
|
|
805
|
+
|
|
|
806
|
+/**
|
|
|
807
|
+ * @brief Scan a file, given a file descriptor.
|
|
|
808
|
+ *
|
|
|
809
|
+ * @param desc File descriptor of an open file. The caller must provide this or the map.
|
|
|
810
|
+ * @param filename (optional) Filepath of the open file descriptor or file map.
|
|
|
811
|
+ * @param[out] virname Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.
|
|
|
812
|
+ * @param[out] scanned The number of bytes scanned.
|
|
|
813
|
+ * @param engine The scanning engine.
|
|
|
814
|
+ * @param scanoptions Scanning options.
|
|
|
815
|
+ * @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.
|
|
|
816
|
+ */
|
|
|
817
|
+extern int cl_scandesc(int desc, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions);
|
|
|
818
|
+
|
|
|
819
|
+/**
|
|
|
820
|
+ * @brief Scan a file, given a file descriptor.
|
|
|
821
|
+ *
|
|
|
822
|
+ * This callback variant allows the caller to provide a context structure that caller provided callback functions can interpret.
|
|
|
823
|
+ *
|
|
|
824
|
+ * @param desc File descriptor of an open file. The caller must provide this or the map.
|
|
|
825
|
+ * @param filename (optional) Filepath of the open file descriptor or file map.
|
|
|
826
|
+ * @param[out] virname Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.
|
|
|
827
|
+ * @param[out] scanned The number of bytes scanned.
|
|
|
828
|
+ * @param engine The scanning engine.
|
|
|
829
|
+ * @param scanoptions Scanning options.
|
|
|
830
|
+ * @param[in/out] context An opaque context structure allowing the caller to record details about the sample being scanned.
|
|
|
831
|
+ * @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.
|
|
|
832
|
+ */
|
|
|
833
|
+extern int cl_scandesc_callback(int desc, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions, void *context);
|
|
|
834
|
+
|
|
|
835
|
+/**
|
|
|
836
|
+ * @brief Scan a file, given a filename.
|
|
|
837
|
+ *
|
|
|
838
|
+ * @param filename Filepath of the file to be scanned.
|
|
|
839
|
+ * @param[out] virname Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.
|
|
|
840
|
+ * @param[out] scanned The number of bytes scanned.
|
|
|
841
|
+ * @param engine The scanning engine.
|
|
|
842
|
+ * @param scanoptions Scanning options.
|
|
|
843
|
+ * @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.
|
|
|
844
|
+ */
|
|
|
845
|
+extern int cl_scanfile(const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions);
|
|
|
846
|
+
|
|
|
847
|
+/**
|
|
|
848
|
+ * @brief Scan a file, given a filename.
|
|
|
849
|
+ *
|
|
|
850
|
+ * This callback variant allows the caller to provide a context structure that caller provided callback functions can interpret.
|
|
|
851
|
+ *
|
|
|
852
|
+ * @param filename Filepath of the file to be scanned.
|
|
|
853
|
+ * @param[out] virname Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.
|
|
|
854
|
+ * @param[out] scanned The number of bytes scanned.
|
|
|
855
|
+ * @param engine The scanning engine.
|
|
|
856
|
+ * @param scanoptions Scanning options.
|
|
|
857
|
+ * @param[in/out] context An opaque context structure allowing the caller to record details about the sample being scanned.
|
|
|
858
|
+ * @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.
|
|
|
859
|
+ */
|
|
|
860
|
+extern int cl_scanfile_callback(const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions, void *context);
|
|
|
861
|
+
|
|
|
862
|
+/* ----------------------------------------------------------------------------
|
|
|
863
|
+ * Database handling.
|
|
|
864
|
+ */
|
|
|
865
|
+extern int cl_load(const char *path, struct cl_engine *engine, unsigned int *signo, unsigned int dboptions);
|
|
|
866
|
+extern const char *cl_retdbdir(void);
|
|
|
867
|
+
|
|
|
868
|
+/* ----------------------------------------------------------------------------
|
|
|
869
|
+ * CVD / database functions
|
|
|
870
|
+ */
|
|
491
|
871
|
|
|
492
|
872
|
struct cl_cvd { /* field no. */
|
|
493
|
873
|
char *time; /* 2 */
|
|
...
|
...
|
@@ -501,332 +910,526 @@ struct cl_cvd { /* field no. */
|
|
501
|
501
|
unsigned int stime; /* 9 */
|
|
502
|
502
|
};
|
|
503
|
503
|
|
|
504
|
|
-/* file scanning */
|
|
505
|
|
-extern int cl_scandesc(int desc, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions);
|
|
506
|
|
-extern int cl_scandesc_callback(int desc, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions, void *context);
|
|
507
|
|
-
|
|
508
|
|
-extern int cl_scanfile(const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions);
|
|
509
|
|
-extern int cl_scanfile_callback(const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options* scanoptions, void *context);
|
|
510
|
|
-
|
|
511
|
|
-/* database handling */
|
|
512
|
|
-extern int cl_load(const char *path, struct cl_engine *engine, unsigned int *signo, unsigned int dboptions);
|
|
513
|
|
-extern const char *cl_retdbdir(void);
|
|
514
|
|
-
|
|
515
|
|
-/* engine handling */
|
|
516
|
|
-
|
|
517
|
|
-/* CVD */
|
|
|
504
|
+/**
|
|
|
505
|
+ * @brief Read the CVD header data from a file.
|
|
|
506
|
+ *
|
|
|
507
|
+ * The returned pointer must be free'd with cl_cvdfree().
|
|
|
508
|
+ *
|
|
|
509
|
+ * @param file Filepath of CVD file.
|
|
|
510
|
+ * @return struct cl_cvd* Pointer to an allocated CVD header data structure.
|
|
|
511
|
+ */
|
|
518
|
512
|
extern struct cl_cvd *cl_cvdhead(const char *file);
|
|
|
513
|
+
|
|
|
514
|
+/**
|
|
|
515
|
+ * @brief Parse the CVD header.
|
|
|
516
|
+ *
|
|
|
517
|
+ * Buffer length is not an argument, and the check must be done
|
|
|
518
|
+ * by the caller cl_cvdhead().
|
|
|
519
|
+ *
|
|
|
520
|
+ * The returned pointer must be free'd with cl_cvdfree().
|
|
|
521
|
+ *
|
|
|
522
|
+ * @param head Pointer to the header data buffer.
|
|
|
523
|
+ * @return struct cl_cvd* Pointer to an allocated CVD header data structure.
|
|
|
524
|
+ */
|
|
519
|
525
|
extern struct cl_cvd *cl_cvdparse(const char *head);
|
|
|
526
|
+
|
|
|
527
|
+/**
|
|
|
528
|
+ * @brief Verify a CVD file by loading and unloading it.
|
|
|
529
|
+ *
|
|
|
530
|
+ * @param file Filepath of CVD file.
|
|
|
531
|
+ * @return cl_error_t CL_SUCCESS if success, else a CL_E* error code.
|
|
|
532
|
+ */
|
|
520
|
533
|
extern int cl_cvdverify(const char *file);
|
|
|
534
|
+
|
|
|
535
|
+/**
|
|
|
536
|
+ * @brief Free a CVD header struct.
|
|
|
537
|
+ *
|
|
|
538
|
+ * @param cvd Pointer to a CVD header struct.
|
|
|
539
|
+ */
|
|
521
|
540
|
extern void cl_cvdfree(struct cl_cvd *cvd);
|
|
522
|
541
|
|
|
523
|
|
-/* db dir stat functions */
|
|
|
542
|
+/* ----------------------------------------------------------------------------
|
|
|
543
|
+ * DB directory stat functions.
|
|
|
544
|
+ * Use these functions to watch for database changes.
|
|
|
545
|
+ */
|
|
|
546
|
+
|
|
|
547
|
+struct cl_stat {
|
|
|
548
|
+ char *dir;
|
|
|
549
|
+ STATBUF *stattab;
|
|
|
550
|
+ char **statdname;
|
|
|
551
|
+ unsigned int entries;
|
|
|
552
|
+};
|
|
|
553
|
+
|
|
|
554
|
+/**
|
|
|
555
|
+ * @brief Initialize a directory to be watched for database changes.
|
|
|
556
|
+ *
|
|
|
557
|
+ * The dbstat out variable is allocated and must be freed using cl_statfree().
|
|
|
558
|
+ *
|
|
|
559
|
+ * @param dirname Pathname of the database directory.
|
|
|
560
|
+ * @param[out] dbstat dbstat handle.
|
|
|
561
|
+ * @return cl_error_t CL_SUCCESS if successfully initialized.
|
|
|
562
|
+ */
|
|
524
|
563
|
extern int cl_statinidir(const char *dirname, struct cl_stat *dbstat);
|
|
|
564
|
+
|
|
|
565
|
+/**
|
|
|
566
|
+ * @brief Check the database directory for changes.
|
|
|
567
|
+ *
|
|
|
568
|
+ * @param dbstat dbstat handle.
|
|
|
569
|
+ * @return int 0 No change.
|
|
|
570
|
+ * @return int 1 Some change occured.
|
|
|
571
|
+ */
|
|
525
|
572
|
extern int cl_statchkdir(const struct cl_stat *dbstat);
|
|
|
573
|
+
|
|
|
574
|
+/**
|
|
|
575
|
+ * @brief Free the dbstat handle.
|
|
|
576
|
+ *
|
|
|
577
|
+ * @param dbstat dbstat handle.
|
|
|
578
|
+ * @return cl_error_t CL_SUCCESS
|
|
|
579
|
+ * @return cl_error_t CL_ENULLARG
|
|
|
580
|
+ */
|
|
526
|
581
|
extern int cl_statfree(struct cl_stat *dbstat);
|
|
527
|
582
|
|
|
528
|
|
-/* count signatures */
|
|
|
583
|
+/**
|
|
|
584
|
+ * @brief Count the number of signatures in a database file or directory.
|
|
|
585
|
+ *
|
|
|
586
|
+ * @param path Path of the database file or directory.
|
|
|
587
|
+ * @param countoptions A bitflag field. May be CL_COUNTSIGS_OFFICIAL, CL_COUNTSIGS_UNOFFICIAL, or CL_COUNTSIGS_ALL.
|
|
|
588
|
+ * @param[out] sigs The number of sigs.
|
|
|
589
|
+ * @return cl_error_t CL_SUCCESS if success, else a CL_E* error type.
|
|
|
590
|
+ */
|
|
529
|
591
|
extern int cl_countsigs(const char *path, unsigned int countoptions, unsigned int *sigs);
|
|
530
|
592
|
|
|
531
|
|
-/* enable debug messages */
|
|
532
|
|
-extern void cl_debug(void);
|
|
|
593
|
+/* ----------------------------------------------------------------------------
|
|
|
594
|
+ * Software versions.
|
|
|
595
|
+ */
|
|
533
|
596
|
|
|
534
|
|
-/* software versions */
|
|
|
597
|
+/**
|
|
|
598
|
+ * @brief Get the Functionality Level (FLEVEL).
|
|
|
599
|
+ *
|
|
|
600
|
+ * @return unsigned int The FLEVEL.
|
|
|
601
|
+ */
|
|
535
|
602
|
extern unsigned int cl_retflevel(void);
|
|
|
603
|
+
|
|
|
604
|
+/**
|
|
|
605
|
+ * @brief Get the ClamAV version string.
|
|
|
606
|
+ *
|
|
|
607
|
+ * E.g. clamav-0.100.0-beta
|
|
|
608
|
+ *
|
|
|
609
|
+ * @return const char* The version string.
|
|
|
610
|
+ */
|
|
536
|
611
|
extern const char *cl_retver(void);
|
|
537
|
612
|
|
|
538
|
|
-/* others */
|
|
|
613
|
+/* ----------------------------------------------------------------------------
|
|
|
614
|
+ * Others.
|
|
|
615
|
+ */
|
|
539
|
616
|
extern const char *cl_strerror(int clerror);
|
|
540
|
617
|
|
|
541
|
|
-/* custom data scanning */
|
|
|
618
|
+/* ----------------------------------------------------------------------------
|
|
|
619
|
+ * Custom data scanning.
|
|
|
620
|
+ */
|
|
542
|
621
|
struct cl_fmap;
|
|
543
|
622
|
typedef struct cl_fmap cl_fmap_t;
|
|
544
|
623
|
|
|
545
|
|
-/* handle - the handle passed to cl_fmap_open_handle, its meaning is up to the
|
|
546
|
|
- * callback's implementation
|
|
547
|
|
- * buf, count, offset - read 'count' bytes starting at 'offset' into the buffer 'buf'
|
|
548
|
|
- * Thread safety: it is guaranteed that only one callback is executing for a specific handle at
|
|
549
|
|
- * any time, but there might be multiple callbacks executing for different
|
|
550
|
|
- * handle at the same time.
|
|
|
624
|
+/**
|
|
|
625
|
+ * @brief Read callback function type.
|
|
|
626
|
+ *
|
|
|
627
|
+ * A callback function pointer type for reading data from a cl_fmap_t that uses
|
|
|
628
|
+ * reads data from a handle interface.
|
|
|
629
|
+ *
|
|
|
630
|
+ * Read 'count' bytes starting at 'offset' into the buffer 'buf'
|
|
|
631
|
+ *
|
|
|
632
|
+ * Thread safety: It is guaranteed that only one callback is executing for a
|
|
|
633
|
+ * specific handle at any time, but there might be multiple callbacks executing
|
|
|
634
|
+ * for different handle at the same time.
|
|
|
635
|
+ *
|
|
|
636
|
+ * @param handle The handle passed to cl_fmap_open_handle, its meaning is up
|
|
|
637
|
+ * to the callback's implementation
|
|
|
638
|
+ * @param buf A buffer to read data into, must be at least offset + count
|
|
|
639
|
+ * bytes in size.
|
|
|
640
|
+ * @param count The number of bytes to read.
|
|
|
641
|
+ * @param offset The the offset into buf to read the data to. If successful,
|
|
|
642
|
+ * the number of bytes actually read is returned. Upon reading
|
|
|
643
|
+ * end-of-file, zero is returned. Otherwise, a -1 is returned
|
|
|
644
|
+ * and the global variable errno is set to indicate the error.
|
|
551
|
645
|
*/
|
|
552
|
646
|
typedef off_t (*clcb_pread)(void* handle, void *buf, size_t count, off_t offset);
|
|
553
|
647
|
|
|
554
|
|
-/* Open a map for scanning custom data accessed by a handle and pread (lseek +
|
|
|
648
|
+/**
|
|
|
649
|
+ * @brief Open a map given a handle.
|
|
|
650
|
+ *
|
|
|
651
|
+ * Open a map for scanning custom data accessed by a handle and pread (lseek +
|
|
555
|
652
|
* read)-like interface. For example a WIN32 HANDLE.
|
|
556
|
653
|
* By default fmap will use aging to discard old data, unless you tell it not
|
|
557
|
654
|
* to.
|
|
|
655
|
+ *
|
|
558
|
656
|
* The handle will be passed to the callback each time.
|
|
|
657
|
+ *
|
|
|
658
|
+ * @param handle A handle that may be accessed using lseek + read.
|
|
|
659
|
+ * @param offset Initial offset to start scanning.
|
|
|
660
|
+ * @param len Length of the data from the start (not the offset).
|
|
|
661
|
+ * @param use_aging Set to a non-zero value to enable aging.
|
|
|
662
|
+ * @param pread_cb A callback function to read data from the handle.
|
|
|
663
|
+ * @return cl_fmap_t* A map representing the handle interface.
|
|
559
|
664
|
*/
|
|
560
|
665
|
extern cl_fmap_t *cl_fmap_open_handle(void* handle, size_t offset, size_t len,
|
|
561
|
666
|
clcb_pread, int use_aging);
|
|
562
|
667
|
|
|
563
|
|
-/* Open a map for scanning custom data, where the data is already in memory,
|
|
|
668
|
+/**
|
|
|
669
|
+ * @brief Open a map given a buffer.
|
|
|
670
|
+ *
|
|
|
671
|
+ * Open a map for scanning custom data, where the data is already in memory,
|
|
564
|
672
|
* either in the form of a buffer, a memory mapped file, etc.
|
|
565
|
673
|
* Note that the memory [start, start+len) must be the _entire_ file,
|
|
566
|
674
|
* you can't give it parts of a file and expect detection to work.
|
|
|
675
|
+ *
|
|
|
676
|
+ * @param start Pointer to a buffer of data.
|
|
|
677
|
+ * @param len Length in bytes of the data.
|
|
|
678
|
+ * @return cl_fmap_t* A map representing the buffer.
|
|
567
|
679
|
*/
|
|
568
|
680
|
extern cl_fmap_t *cl_fmap_open_memory(const void *start, size_t len);
|
|
569
|
681
|
|
|
570
|
|
-/* Releases resources associated with the map, you should release any resources
|
|
571
|
|
- * you hold only after (handles, maps) calling this function */
|
|
|
682
|
+/**
|
|
|
683
|
+ * @brief Releases resources associated with the map.
|
|
|
684
|
+ *
|
|
|
685
|
+ * You should release any resources you hold only after (handles, maps) calling
|
|
|
686
|
+ * this function.
|
|
|
687
|
+ *
|
|
|
688
|
+ * @param map Map to be closed.
|
|
|
689
|
+ */
|
|
572
|
690
|
extern void cl_fmap_close(cl_fmap_t*);
|
|
573
|
691
|
|
|
574
|
|
-/* Scan custom data */
|
|
|
692
|
+/**
|
|
|
693
|
+ * @brief Scan custom data.
|
|
|
694
|
+ *
|
|
|
695
|
+ * @param map Buffer to be scanned, in form of a cl_fmap_t.
|
|
|
696
|
+ * @param filename Name of data origin. Does not need to be an actual
|
|
|
697
|
+ * file on disk. May be NULL if a name is not available.
|
|
|
698
|
+ * @param[out] virname Pointer to receive the signature match name name if a
|
|
|
699
|
+ * signature matched.
|
|
|
700
|
+ * @param[out] scanned Number of bytes scanned.
|
|
|
701
|
+ * @param engine The scanning engine.
|
|
|
702
|
+ * @param scanoptions The scanning options struct.
|
|
|
703
|
+ * @param context An application-defined context struct, opaque to
|
|
|
704
|
+ * libclamav. May be used within your callback functions.
|
|
|
705
|
+ * @return cl_error_t CL_CLEAN if no signature matched. CL_VIRUS if a
|
|
|
706
|
+ * signature matched. Another CL_E* error code if an
|
|
|
707
|
+ * error occured.
|
|
|
708
|
+ */
|
|
575
|
709
|
extern int cl_scanmap_callback(cl_fmap_t *map, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options *scanoptions, void *context);
|
|
576
|
710
|
|
|
577
|
|
-/* Crypto/hashing functions */
|
|
|
711
|
+/* ----------------------------------------------------------------------------
|
|
|
712
|
+ * Crypto/hashing functions
|
|
|
713
|
+ */
|
|
578
|
714
|
#define MD5_HASH_SIZE 16
|
|
579
|
715
|
#define SHA1_HASH_SIZE 20
|
|
580
|
716
|
#define SHA256_HASH_SIZE 32
|
|
581
|
717
|
#define SHA384_HASH_SIZE 48
|
|
582
|
718
|
#define SHA512_HASH_SIZE 64
|
|
583
|
719
|
|
|
584
|
|
-/** Generate a hash of data.
|
|
585
|
|
- @param[in] alg The hashing algorithm to use
|
|
586
|
|
- @param[in] buf The data to be hashed
|
|
587
|
|
- @param[in] len The length of the to-be-hashed data
|
|
588
|
|
- @param[out] obuf An optional buffer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
589
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is.
|
|
590
|
|
- @return A pointer to the generated hash or obuf if obuf is not NULL.
|
|
|
720
|
+/**
|
|
|
721
|
+ * @brief Generate a hash of data.
|
|
|
722
|
+ *
|
|
|
723
|
+ * @param alg The hashing algorithm to use.
|
|
|
724
|
+ * @param buf The data to be hashed.
|
|
|
725
|
+ * @param len The length of the to-be-hashed data.
|
|
|
726
|
+ * @param[out] obuf (optional) A buffer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
|
727
|
+ * @param[out] olen (optional) A pointer that stores how long the generated hash is.
|
|
|
728
|
+ * @return A pointer to the generated hash or obuf if obuf is not NULL.
|
|
591
|
729
|
*/
|
|
592
|
730
|
unsigned char *cl_hash_data(const char *alg, const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
|
|
593
|
731
|
|
|
594
|
|
-/** Generate a hash of a file.
|
|
595
|
|
- @param[in] ctx A pointer to the OpenSSL EVP_MD_CTX object
|
|
596
|
|
- @param[in] fd The file descriptor
|
|
597
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is
|
|
598
|
|
- @return A pointer to a dynamically-created buffer that holds the generated hash
|
|
|
732
|
+/**
|
|
|
733
|
+ * @brief Generate a hash of a file.
|
|
|
734
|
+ *
|
|
|
735
|
+ * @param ctx A pointer to the OpenSSL EVP_MD_CTX object.
|
|
|
736
|
+ * @param fd The file descriptor.
|
|
|
737
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
738
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
599
|
739
|
*/
|
|
600
|
740
|
unsigned char *cl_hash_file_fd_ctx(EVP_MD_CTX *ctx, int fd, unsigned int *olen);
|
|
601
|
741
|
|
|
602
|
|
-/** Generate a hash of a file.
|
|
603
|
|
- @param[in] fd The file descriptor
|
|
604
|
|
- @param[in] alg The hashing algorithm to use
|
|
605
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is
|
|
606
|
|
- @return A pointer to a dynamically-created buffer that holds the generated hash
|
|
|
742
|
+/**
|
|
|
743
|
+ * @brief Generate a hash of a file.
|
|
|
744
|
+ *
|
|
|
745
|
+ * @param fd The file descriptor.
|
|
|
746
|
+ * @param alg The hashing algorithm to use.
|
|
|
747
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
748
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
607
|
749
|
*/
|
|
608
|
750
|
unsigned char *cl_hash_file_fd(int fd, const char *alg, unsigned int *olen);
|
|
609
|
751
|
|
|
610
|
|
-/** Generate a hash of a file.
|
|
611
|
|
- @param[in] fp A pointer to a FILE object
|
|
612
|
|
- @param[in] alg The hashing algorithm to use
|
|
613
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is
|
|
614
|
|
- @return A pointer to a dynamically-created buffer that holds the generated hash
|
|
|
752
|
+/**
|
|
|
753
|
+ * @brief Generate a hash of a file.
|
|
|
754
|
+ *
|
|
|
755
|
+ * @param fp A pointer to a FILE object.
|
|
|
756
|
+ * @param alg The hashing algorithm to use.
|
|
|
757
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
758
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
615
|
759
|
*/
|
|
616
|
760
|
unsigned char *cl_hash_file_fp(FILE *fp, const char *alg, unsigned int *olen);
|
|
617
|
761
|
|
|
618
|
|
-/** Generate a sha256 hash of data
|
|
619
|
|
- @param[in] buf The data to hash
|
|
620
|
|
- @param[in] len The length of the to-be-hashed data
|
|
621
|
|
- @param[out] obuf An optional pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
622
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is.
|
|
623
|
|
- @return A pointer to the buffer that holds the generated hash
|
|
|
762
|
+/**
|
|
|
763
|
+ * @brief Generate a sha256 hash of data.
|
|
|
764
|
+ *
|
|
|
765
|
+ * @param buf The data to hash.
|
|
|
766
|
+ * @param len The length of the to-be-hashed data.
|
|
|
767
|
+ * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
|
768
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
769
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
624
|
770
|
*/
|
|
625
|
771
|
unsigned char *cl_sha256(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
|
|
626
|
772
|
|
|
627
|
|
-/** Generate a sha384 hash of data
|
|
628
|
|
- @param[in] buf The data to hash
|
|
629
|
|
- @param[in] len The length of the to-be-hashed data
|
|
630
|
|
- @param[out] obuf An optional pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
631
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is.
|
|
632
|
|
- @return A pointer to the buffer that holds the generated hash
|
|
|
773
|
+/**
|
|
|
774
|
+ * @brief Generate a sha384 hash of data.
|
|
|
775
|
+ *
|
|
|
776
|
+ * @param buf The data to hash.
|
|
|
777
|
+ * @param len The length of the to-be-hashed data.
|
|
|
778
|
+ * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
|
779
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
780
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
633
|
781
|
*/
|
|
634
|
782
|
unsigned char *cl_sha384(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
|
|
635
|
783
|
|
|
636
|
|
-/** Generate a sha512 hash of data
|
|
637
|
|
- @param[in] buf The data to hash
|
|
638
|
|
- @param[in] len The length of the to-be-hashed data
|
|
639
|
|
- @param[out] obuf An optional pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
640
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is.
|
|
641
|
|
- @return A pointer to the buffer that holds the generated hash
|
|
|
784
|
+/**
|
|
|
785
|
+ * @brief Generate a sha512 hash of data.
|
|
|
786
|
+ *
|
|
|
787
|
+ * @param buf The data to hash.
|
|
|
788
|
+ * @param len The length of the to-be-hashed data.
|
|
|
789
|
+ * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
|
790
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
791
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
642
|
792
|
*/
|
|
643
|
793
|
unsigned char *cl_sha512(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
|
|
644
|
794
|
|
|
645
|
|
-/** Generate a sha1 hash of data
|
|
646
|
|
- @param[in] buf The data to hash
|
|
647
|
|
- @param[in] len The length of the to-be-hashed data
|
|
648
|
|
- @param[out] obuf An optional pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
649
|
|
- @param[out] olen An optional pointer that stores how long the generated hash is.
|
|
650
|
|
- @return A pointer to the buffer that holds the generated hash or obuf if obuf is not NULL
|
|
|
795
|
+/**
|
|
|
796
|
+ * @brief Generate a sha1 hash of data.
|
|
|
797
|
+ *
|
|
|
798
|
+ * @param buf The data to hash.
|
|
|
799
|
+ * @param len The length of the to-be-hashed data.
|
|
|
800
|
+ * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
|
|
|
801
|
+ * @param[out] olen (optional) The length of the generated hash.
|
|
|
802
|
+ * @return A pointer to a malloc'd buffer that holds the generated hash.
|
|
651
|
803
|
*/
|
|
652
|
804
|
unsigned char *cl_sha1(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
|
|
653
|
805
|
|
|
654
|
|
-/** Verify validity of signed data
|
|
655
|
|
- @param[in] pkey The public key of the keypair that signed the data
|
|
656
|
|
- @param[in] alg The algorithm used to hash the data
|
|
657
|
|
- @param[in] sig The signature block
|
|
658
|
|
- @param[in] siglen The length of the signature
|
|
659
|
|
- @param[in] data The data that was signed
|
|
660
|
|
- @param[in] datalen The length of the data
|
|
661
|
|
- @param[in] decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
662
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
806
|
+/**
|
|
|
807
|
+ * @brief Verify validity of signed data.
|
|
|
808
|
+ *
|
|
|
809
|
+ * @param pkey The public key of the keypair that signed the data.
|
|
|
810
|
+ * @param alg The algorithm used to hash the data.
|
|
|
811
|
+ * @param sig The signature block.
|
|
|
812
|
+ * @param siglen The length of the signature.
|
|
|
813
|
+ * @param data The data that was signed.
|
|
|
814
|
+ * @param datalen The length of the data.
|
|
|
815
|
+ * @param decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
|
816
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
663
|
817
|
*/
|
|
664
|
818
|
int cl_verify_signature(EVP_PKEY *pkey, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *data, size_t datalen, int decode);
|
|
665
|
819
|
|
|
666
|
|
-/** Verify validity of signed data
|
|
667
|
|
- @param[in] pkey The public key of the keypair that signed the data
|
|
668
|
|
- @param[in] alg The algorithm used to hash the data
|
|
669
|
|
- @param[in] sig The signature block
|
|
670
|
|
- @param[in] siglen The length of the signature
|
|
671
|
|
- @param[in] digest The hash of the signed data
|
|
672
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
820
|
+/**
|
|
|
821
|
+ * @brief Verify validity of signed data.
|
|
|
822
|
+ *
|
|
|
823
|
+ * @param pkey The public key of the keypair that signed the data.
|
|
|
824
|
+ * @param alg The algorithm used to hash the data.
|
|
|
825
|
+ * @param sig The signature block.
|
|
|
826
|
+ * @param siglen The length of the signature.
|
|
|
827
|
+ * @param digest The hash of the signed data.
|
|
|
828
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
673
|
829
|
*/
|
|
674
|
830
|
int cl_verify_signature_hash(EVP_PKEY *pkey, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *digest);
|
|
675
|
831
|
|
|
676
|
|
-/** Verify validity of signed data
|
|
677
|
|
- @param[in] pkey The public key of the keypair that signed the data
|
|
678
|
|
- @param[in] alg The algorithm used to hash the data
|
|
679
|
|
- @param[in] sig The signature block
|
|
680
|
|
- @param[in] siglen The length of the signature
|
|
681
|
|
- @param[in] fd The file descriptor
|
|
682
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
832
|
+/**
|
|
|
833
|
+ * @brief Verify validity of signed data.
|
|
|
834
|
+ *
|
|
|
835
|
+ * @param pkey The public key of the keypair that signed the data.
|
|
|
836
|
+ * @param alg The algorithm used to hash the data.
|
|
|
837
|
+ * @param sig The signature block.
|
|
|
838
|
+ * @param siglen The length of the signature.
|
|
|
839
|
+ * @param fd The file descriptor.
|
|
|
840
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
683
|
841
|
*/
|
|
684
|
842
|
int cl_verify_signature_fd(EVP_PKEY *pkey, const char *alg, unsigned char *sig, unsigned int siglen, int fd);
|
|
685
|
843
|
|
|
686
|
|
-/** Verify validity of signed data
|
|
687
|
|
- @param[in] x509path The path to the public key of the keypair that signed the data
|
|
688
|
|
- @param[in] alg The algorithm used to hash the data
|
|
689
|
|
- @param[in] sig The signature block
|
|
690
|
|
- @param[in] siglen The length of the signature
|
|
691
|
|
- @param[in] digest The hash of the signed data
|
|
692
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
844
|
+/**
|
|
|
845
|
+ * @brief Verify validity of signed data.
|
|
|
846
|
+ *
|
|
|
847
|
+ * @param x509path The path to the public key of the keypair that signed the data.
|
|
|
848
|
+ * @param alg The algorithm used to hash the data.
|
|
|
849
|
+ * @param sig The signature block.
|
|
|
850
|
+ * @param siglen The length of the signature.
|
|
|
851
|
+ * @param digest The hash of the signed data.
|
|
|
852
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
693
|
853
|
*/
|
|
694
|
854
|
int cl_verify_signature_hash_x509_keyfile(char *x509path, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *digest);
|
|
695
|
855
|
|
|
696
|
|
-/** Verify validity of signed data
|
|
697
|
|
- @param[in] x509path The path to the public key of the keypair that signed the data
|
|
698
|
|
- @param[in] alg The algorithm used to hash the data
|
|
699
|
|
- @param[in] sig The signature block
|
|
700
|
|
- @param[in] siglen The length of the signature
|
|
701
|
|
- @param[in] fd The file descriptor
|
|
702
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
856
|
+/**
|
|
|
857
|
+ * @brief Verify validity of signed data.
|
|
|
858
|
+ *
|
|
|
859
|
+ * @param x509path The path to the public key of the keypair that signed the data.
|
|
|
860
|
+ * @param alg The algorithm used to hash the data.
|
|
|
861
|
+ * @param sig The signature block.
|
|
|
862
|
+ * @param siglen The length of the signature.
|
|
|
863
|
+ * @param fd The file descriptor.
|
|
|
864
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
703
|
865
|
*/
|
|
704
|
866
|
int cl_verify_signature_fd_x509_keyfile(char *x509path, const char *alg, unsigned char *sig, unsigned int siglen, int fd);
|
|
705
|
867
|
|
|
706
|
|
-/** Verify validity of signed data
|
|
707
|
|
- @param[in] x509path The path to the public key of the keypair that signed the data
|
|
708
|
|
- @param[in] alg The algorithm used to hash the data
|
|
709
|
|
- @param[in] sig The signature block
|
|
710
|
|
- @param[in] siglen The length of the signature
|
|
711
|
|
- @param[in] data The data that was signed
|
|
712
|
|
- @param[in] datalen The length of the data
|
|
713
|
|
- @param[in] decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
714
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
868
|
+/**
|
|
|
869
|
+ * @brief Verify validity of signed data.
|
|
|
870
|
+ *
|
|
|
871
|
+ * @param x509path The path to the public key of the keypair that signed the data.
|
|
|
872
|
+ * @param alg The algorithm used to hash the data.
|
|
|
873
|
+ * @param sig The signature block.
|
|
|
874
|
+ * @param siglen The length of the signature.
|
|
|
875
|
+ * @param data The data that was signed.
|
|
|
876
|
+ * @param datalen The length of the data.
|
|
|
877
|
+ * @param decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
|
878
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
715
|
879
|
*/
|
|
716
|
880
|
int cl_verify_signature_x509_keyfile(char *x509path, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *data, size_t datalen, int decode);
|
|
717
|
881
|
|
|
718
|
|
-/** Verify validity of signed data
|
|
719
|
|
- @param[in] x509 The X509 object of the public key of the keypair that signed the data
|
|
720
|
|
- @param[in] alg The algorithm used to hash the data
|
|
721
|
|
- @param[in] sig The signature block
|
|
722
|
|
- @param[in] siglen The length of the signature
|
|
723
|
|
- @param[in] digest The hash of the signed data
|
|
724
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
882
|
+/**
|
|
|
883
|
+ * @brief Verify validity of signed data
|
|
|
884
|
+ *
|
|
|
885
|
+ * @param x509 The X509 object of the public key of the keypair that signed the data.
|
|
|
886
|
+ * @param alg The algorithm used to hash the data.
|
|
|
887
|
+ * @param sig The signature block.
|
|
|
888
|
+ * @param siglen The length of the signature.
|
|
|
889
|
+ * @param digest The hash of the signed data.
|
|
|
890
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
725
|
891
|
*/
|
|
726
|
892
|
int cl_verify_signature_hash_x509(X509 *x509, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *digest);
|
|
727
|
893
|
|
|
728
|
|
-/** Verify validity of signed data
|
|
729
|
|
- @param[in] x509 The X509 object of the public key of the keypair that signed the data
|
|
730
|
|
- @param[in] alg The algorithm used to hash the data
|
|
731
|
|
- @param[in] sig The signature block
|
|
732
|
|
- @param[in] siglen The length of the signature
|
|
733
|
|
- @param[in] fd The file descriptor
|
|
734
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
894
|
+/**
|
|
|
895
|
+ * @brief Verify validity of signed data.
|
|
|
896
|
+ *
|
|
|
897
|
+ * @param x509 The X509 object of the public key of the keypair that signed the data.
|
|
|
898
|
+ * @param alg The algorithm used to hash the data.
|
|
|
899
|
+ * @param sig The signature block.
|
|
|
900
|
+ * @param siglen The length of the signature.
|
|
|
901
|
+ * @param fd The file descriptor.
|
|
|
902
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
735
|
903
|
*/
|
|
736
|
904
|
int cl_verify_signature_fd_x509(X509 *x509, const char *alg, unsigned char *sig, unsigned int siglen, int fd);
|
|
737
|
905
|
|
|
738
|
|
-/** Verify validity of signed data
|
|
739
|
|
- @param[in] x509 The X509 object of the public key of the keypair that signed the data
|
|
740
|
|
- @param[in] alg The algorithm used to hash the data
|
|
741
|
|
- @param[in] sig The signature block
|
|
742
|
|
- @param[in] siglen The length of the signature
|
|
743
|
|
- @param[in] data The data that was signed
|
|
744
|
|
- @param[in] datalen The length of the data
|
|
745
|
|
- @param[in] decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
746
|
|
- @return 0 for success, -1 for error or invalid signature
|
|
|
906
|
+/**
|
|
|
907
|
+ * @brief Verify validity of signed data.
|
|
|
908
|
+ *
|
|
|
909
|
+ * @param x509 The X509 object of the public key of the keypair that signed the data.
|
|
|
910
|
+ * @param alg The algorithm used to hash the data.
|
|
|
911
|
+ * @param sig The signature block.
|
|
|
912
|
+ * @param siglen The length of the signature.
|
|
|
913
|
+ * @param data The data that was signed.
|
|
|
914
|
+ * @param datalen The length of the data.
|
|
|
915
|
+ * @param decode Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
|
|
|
916
|
+ * @return 0 for success, -1 for error or invalid signature.
|
|
747
|
917
|
*/
|
|
748
|
918
|
int cl_verify_signature_x509(X509 *x509, const char *alg, unsigned char *sig, unsigned int siglen, unsigned char *data, size_t datalen, int decode);
|
|
749
|
919
|
|
|
750
|
|
-/** Get an X509 object from memory
|
|
751
|
|
- * @param[in] data A pointer to a spot in memory that contains the PEM X509 cert
|
|
752
|
|
- * @param[in] len The length of the data
|
|
753
|
|
- * @return a pointer to the X509 object on success, NULL on error
|
|
|
920
|
+/**
|
|
|
921
|
+ * @brief Get an X509 object from memory.
|
|
|
922
|
+ *
|
|
|
923
|
+ * @param data A pointer to a spot in memory that contains the PEM X509 cert.
|
|
|
924
|
+ * @param len The length of the data.
|
|
|
925
|
+ * @return A pointer to the X509 object on success, NULL on error.
|
|
754
|
926
|
*/
|
|
755
|
927
|
X509 *cl_get_x509_from_mem(void *data, unsigned int len);
|
|
756
|
928
|
|
|
757
|
|
-/** Validate an X509 certificate chain, with the chain being located in a directory
|
|
758
|
|
- @param[in] tsdir The path to the trust store directory
|
|
759
|
|
- @param[in] certpath The path to the X509 certificate to be validated.
|
|
760
|
|
- @return 0 for success, -1 for error or invalid certificate.
|
|
|
929
|
+/**
|
|
|
930
|
+ * @brief Validate an X509 certificate chain, with the chain being located in a directory.
|
|
|
931
|
+ *
|
|
|
932
|
+ * @param tsdir The path to the trust store directory.
|
|
|
933
|
+ * @param certpath The path to the X509 certificate to be validated.
|
|
|
934
|
+ * @return 0 for success, -1 for error or invalid certificate.
|
|
761
|
935
|
*/
|
|
762
|
936
|
int cl_validate_certificate_chain_ts_dir(char *tsdir, char *certpath);
|
|
763
|
937
|
|
|
764
|
|
-/** Validate an X509 certificate chain with support for a CRL
|
|
765
|
|
- @param[in] authorities A NULL-terminated array of strings that hold the path of the CA's X509 certificate
|
|
766
|
|
- @param[in] crlpath An optional path to the CRL file. NULL if no CRL.
|
|
767
|
|
- @param[in] certpath The path to the X509 certificate to be validated.
|
|
768
|
|
- @return 0 for success, -1 for error or invalid certificate.
|
|
|
938
|
+/**
|
|
|
939
|
+ * @brief Validate an X509 certificate chain with support for a CRL.
|
|
|
940
|
+ *
|
|
|
941
|
+ * @param authorities A NULL-terminated array of strings that hold the path of the CA's X509 certificate.
|
|
|
942
|
+ * @param crlpath (optional) A path to the CRL file. NULL if no CRL.
|
|
|
943
|
+ * @param certpath The path to the X509 certificate to be validated.
|
|
|
944
|
+ * @return 0 for success, -1 for error or invalid certificate.
|
|
769
|
945
|
*/
|
|
770
|
946
|
int cl_validate_certificate_chain(char **authorities, char *crlpath, char *certpath);
|
|
771
|
947
|
|
|
772
|
|
-/** Load an X509 certificate from a file
|
|
773
|
|
- @param[in] certpath The path to the X509 certificate
|
|
|
948
|
+/**
|
|
|
949
|
+ * @brief Load an X509 certificate from a file.
|
|
|
950
|
+ *
|
|
|
951
|
+ * @param certpath The path to the X509 certificate.
|
|
774
|
952
|
*/
|
|
775
|
953
|
X509 *cl_load_cert(const char *certpath);
|
|
776
|
954
|
|
|
777
|
|
-/** Parse an ASN1_TIME object
|
|
778
|
|
- @param[in] timeobj The ASN1_TIME object
|
|
779
|
|
- @return A pointer to a (struct tm). Adjusted for time zone and daylight savings time.
|
|
|
955
|
+/**
|
|
|
956
|
+ * @brief Parse an ASN1_TIME object.
|
|
|
957
|
+ *
|
|
|
958
|
+ * @param timeobj The ASN1_TIME object.
|
|
|
959
|
+ * @return A pointer to a (struct tm). Adjusted for time zone and daylight savings time.
|
|
780
|
960
|
*/
|
|
781
|
961
|
struct tm *cl_ASN1_GetTimeT(ASN1_TIME *timeobj);
|
|
782
|
962
|
|
|
783
|
|
-/** Load a CRL file into an X509_CRL object
|
|
784
|
|
- @param[in] file The path to the CRL
|
|
785
|
|
- @return A pointer to an X509_CRL object or NULL on error.
|
|
|
963
|
+/**
|
|
|
964
|
+ * @brief Load a CRL file into an X509_CRL object.
|
|
|
965
|
+ *
|
|
|
966
|
+ * @param file The path to the CRL.
|
|
|
967
|
+ * @return A pointer to an X509_CRL object or NULL on error.
|
|
786
|
968
|
*/
|
|
787
|
969
|
X509_CRL *cl_load_crl(const char *timeobj);
|
|
788
|
970
|
|
|
789
|
|
-/** Sign data with a key stored on disk
|
|
790
|
|
- @param[in] keypath The path to the RSA private key
|
|
791
|
|
- @param[in] alg The hash/signature algorithm to use
|
|
792
|
|
- @param[in] hash The hash to sign
|
|
793
|
|
- @param[out] olen A pointer that stores the size of the signature
|
|
794
|
|
- @param[in] Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
795
|
|
- @return The generated signature
|
|
|
971
|
+/**
|
|
|
972
|
+ * @brief Sign data with a key stored on disk.
|
|
|
973
|
+ *
|
|
|
974
|
+ * @param keypath The path to the RSA private key.
|
|
|
975
|
+ * @param alg The hash/signature algorithm to use.
|
|
|
976
|
+ * @param hash The hash to sign.
|
|
|
977
|
+ * @param[out] olen A pointer that stores the size of the signature.
|
|
|
978
|
+ * @param Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
979
|
+ * @return The generated signature.
|
|
796
|
980
|
*/
|
|
797
|
981
|
unsigned char *cl_sign_data_keyfile(char *keypath, const char *alg, unsigned char *hash, unsigned int *olen, int encode);
|
|
798
|
982
|
|
|
799
|
|
-/** Sign data with an RSA private key object
|
|
800
|
|
- @param[in] pkey The RSA private key object
|
|
801
|
|
- @param[in] alg The hash/signature algorithm to use
|
|
802
|
|
- @param[in] hash The hash to sign
|
|
803
|
|
- @param[out] olen A pointer that stores the size of the signature
|
|
804
|
|
- @param[in] Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
805
|
|
- @return The generated signature
|
|
|
983
|
+/**
|
|
|
984
|
+ * @brief Sign data with an RSA private key object.
|
|
|
985
|
+ *
|
|
|
986
|
+ * @param pkey The RSA private key object.
|
|
|
987
|
+ * @param alg The hash/signature algorithm to use.
|
|
|
988
|
+ * @param hash The hash to sign.
|
|
|
989
|
+ * @param[out] olen A pointer that stores the size of the signature.
|
|
|
990
|
+ * @param Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
991
|
+ * @return The generated signature.
|
|
806
|
992
|
*/
|
|
807
|
993
|
unsigned char *cl_sign_data(EVP_PKEY *pkey, const char *alg, unsigned char *hash, unsigned int *olen, int encode);
|
|
808
|
994
|
|
|
809
|
|
-/** Sign a file with an RSA private key object
|
|
810
|
|
- @param[in] fd The file descriptor
|
|
811
|
|
- @param[in] pkey The RSA private key object
|
|
812
|
|
- @param[in] alg The hash/signature algorithm to use
|
|
813
|
|
- @param[out] olen A pointer that stores the size of the signature
|
|
814
|
|
- @param[in] encode Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
995
|
+/**
|
|
|
996
|
+ * @brief Sign a file with an RSA private key object.
|
|
|
997
|
+ *
|
|
|
998
|
+ * @param fd The file descriptor.
|
|
|
999
|
+ * @param pkey The RSA private key object.
|
|
|
1000
|
+ * @param alg The hash/signature algorithm to use.
|
|
|
1001
|
+ * @param[out] olen A pointer that stores the size of the signature.
|
|
|
1002
|
+ * @param encode Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
1003
|
+ * @return The generated signature.
|
|
815
|
1004
|
*/
|
|
816
|
1005
|
unsigned char *cl_sign_file_fd(int fd, EVP_PKEY *pkey, const char *alg, unsigned int *olen, int encode);
|
|
817
|
1006
|
|
|
818
|
|
-/** Sign a file with an RSA private key object
|
|
819
|
|
- @param[in] fp A pointer to a FILE object
|
|
820
|
|
- @param[in] pkey The RSA private key object
|
|
821
|
|
- @param[in] alg The hash/signature algorithm to use
|
|
822
|
|
- @param[out] olen A pointer that stores the size of the signature
|
|
823
|
|
- @param[in] encode Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
1007
|
+/**
|
|
|
1008
|
+ * @brief Sign a file with an RSA private key object.
|
|
|
1009
|
+ *
|
|
|
1010
|
+ * @param fp A pointer to a FILE object.
|
|
|
1011
|
+ * @param pkey The RSA private key object.
|
|
|
1012
|
+ * @param alg The hash/signature algorithm to use.
|
|
|
1013
|
+ * @param[out] olen A pointer that stores the size of the signature.
|
|
|
1014
|
+ * @param encode Whether or not to base64-encode the signature. 1 for yes, 0 for no.
|
|
|
1015
|
+ * @return The generated signature.
|
|
824
|
1016
|
*/
|
|
825
|
1017
|
unsigned char *cl_sign_file_fp(FILE *fp, EVP_PKEY *pkey, const char *alg, unsigned int *olen, int encode);
|
|
826
|
1018
|
|
|
827
|
|
-/** Get the Private Key stored on disk
|
|
828
|
|
- * @param[in] keypath The path on disk where the private key is stored
|
|
829
|
|
- * @return A pointer to the EVP_PKEY object that contains the private key in memory
|
|
|
1019
|
+/**
|
|
|
1020
|
+ * @brief Get the Private Key stored on disk.
|
|
|
1021
|
+ *
|
|
|
1022
|
+ * @param keypath The path on disk where the private key is stored.
|
|
|
1023
|
+ * @return A pointer to the EVP_PKEY object that contains the private key in memory.
|
|
830
|
1024
|
*/
|
|
831
|
1025
|
EVP_PKEY *cl_get_pkey_file(char *keypath);
|
|
832
|
1026
|
|
|
...
|
...
|
@@ -834,10 +1437,9 @@ void *cl_hash_init(const char *alg);
|
|
834
|
834
|
int cl_update_hash(void *ctx, const void *data, size_t sz);
|
|
835
|
835
|
int cl_finish_hash(void *ctx, void *buf);
|
|
836
|
836
|
void cl_hash_destroy(void *ctx);
|
|
837
|
|
-/* End of crypto/hashing functions */
|
|
838
|
837
|
|
|
839
|
838
|
#ifdef __cplusplus
|
|
840
|
839
|
}
|
|
841
|
840
|
#endif
|
|
842
|
|
-
|
|
|
841
|
+
|
|
843
|
842
|
#endif /* __CLAMAV_H */
|
Micah Snyder (micasnyd) authored on 2018/11/17 04:02:15