Browse code

libclamav / clamav.h documentation updated both to clean up existing documentation and to add new documentation.

Micah Snyder (micasnyd) authored on 2018/11/17 04:02:15
Showing 3 changed files
... ...
@@ -20,6 +20,14 @@ we've cooked up over the past 6 months.
20 20
   before, although our `libclamunrar_iface` supporting library has changed from
21 21
   LGPL to the BSD 3-Clause license.
22 22
 - Libclamav API changes:
23
+  - The following scanning functions now require a filename argument.
24
+    This will enable ClamAV to report more details warning and error
25
+    information in the future, and will also allow for more sensible temp
26
+    file names. The filename argument may be `NULL` if a filename is not
27
+    available.
28
+    - `cl_scandesc`
29
+    - `cl_scandesc_callback`
30
+    - `cl_scanmap_callback`
23 31
   - Scanning options have been converted from a single flag bit-field into
24 32
     a structure of multiple categorized flag bit-fields. This change enabled
25 33
     us to add new scanning options requested by the community. In addition,
... ...
@@ -44,6 +44,7 @@ int main(int argc, char **argv)
44 44
 	unsigned int sigs = 0;
45 45
 	long double mb;
46 46
 	const char *virname;
47
+    const char *filename;
47 48
 	struct cl_engine *engine;
48 49
     struct cl_scan_options options;
49 50
 
... ...
@@ -52,6 +53,8 @@ int main(int argc, char **argv)
52 52
 	return 2;
53 53
     }
54 54
 
55
+    filename = argv[1];
56
+
55 57
     if((fd = open(argv[1], O_RDONLY)) == -1) {
56 58
 	printf("Can't open file %s\n", argv[1]);
57 59
 	return 2;
... ...
@@ -90,7 +93,7 @@ int main(int argc, char **argv)
90 90
     options.parse |= ~0; /* enable all parsers */
91 91
     options.general |= CL_SCAN_GENERAL_HEURISTICS; /* enable heuristic alert options */
92 92
 
93
-    if((ret = cl_scandesc(fd, &virname, &size, engine, &options)) == CL_VIRUS) {
93
+    if((ret = cl_scandesc(fd, filename, &virname, &size, engine, &options)) == CL_VIRUS) {
94 94
 	printf("Virus detected: %s\n", virname);
95 95
     } else {
96 96
 	if(ret == CL_CLEAN) {
... ...
@@ -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
+ *