clamav/libclamav/clamav.h

/*
 *  Copyright (C) 2013-2025 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
 *  Copyright (C) 2007-2013 Sourcefire, Inc.
 *
 *  Authors: Tomasz Kojm
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2 as
 *  published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 *  MA 02110-1301, USA.
 */

#ifndef __CLAMAV_H
#define __CLAMAV_H

#ifdef _WIN32
#ifndef OWN_WINSOCK
#include <winsock2.h>
#endif
#endif

#include <openssl/ssl.h>
#include <openssl/err.h>

/* Certain OSs already use 64bit variables in their stat struct */
#if (!defined(__FreeBSD__) && !defined(__APPLE__))
#define STAT64_OK 1
#else
#define STAT64_OK 0
#endif

#if defined(HAVE_STAT64) && STAT64_OK

#include <unistd.h>

#define STATBUF struct stat64
#define CLAMSTAT stat64
#define LSTAT lstat64
#define FSTAT fstat64
#define safe_open(a, b) open(a, b | O_LARGEFILE)

#else

#define STATBUF struct stat
#define CLAMSTAT stat
#define LSTAT lstat
#define FSTAT fstat
/* Nothing is safe in windows, not even open, safe_open defined under /win32 */
#ifndef _WIN32
#define safe_open open
#endif

#endif

/* Apple does not define __pid_t */
#ifdef __APPLE__
typedef pid_t __pid_t;
#endif

#define UNUSEDPARAM(x) (void)(x)

#include <sys/types.h>
#include <sys/stat.h>
#include <stdbool.h>

#include "clamav-types.h"
#include "clamav-version.h"

#ifdef __cplusplus
extern "C" {
#endif

#define CL_COUNT_PRECISION 4096

/* return codes */
typedef enum cl_error_t {
    /* libclamav specific */
    CL_CLEAN   = 0,
    CL_SUCCESS = 0,
    CL_VIRUS,
    CL_ENULLARG,
    CL_EARG,
    CL_EMALFDB,
    CL_ECVD,
    CL_EVERIFY,
    CL_EUNPACK,

    /* I/O and memory errors */
    CL_EOPEN,
    CL_ECREAT,
    CL_EUNLINK,
    CL_ESTAT,
    CL_EREAD,
    CL_ESEEK,
    CL_EWRITE,
    CL_EDUP,
    CL_EACCES,
    CL_ETMPFILE,
    CL_ETMPDIR,
    CL_EMAP,
    CL_EMEM,
    CL_ETIMEOUT,

    /* internal (not reported outside libclamav) */
    CL_BREAK,
    CL_EMAXREC,
    CL_EMAXSIZE,
    CL_EMAXFILES,
    CL_EFORMAT,
    CL_EPARSE,
    CL_EBYTECODE,          /** may be reported in testmode */
    CL_EBYTECODE_TESTFAIL, /** may be reported in testmode */
    CL_ELOCK,
    CL_EBUSY,
    CL_ESTATE,

    CL_VERIFIED, /** The binary has been deemed trusted */
    CL_ERROR,    /** Unspecified / generic error */

    /* no error codes below this line please */
    CL_ELAST_ERROR
} cl_error_t;

/* db options */
// clang-format off
#define CL_DB_PHISHING          0x2
#define CL_DB_PHISHING_URLS     0x8
#define CL_DB_PUA               0x10
#define CL_DB_CVDNOTMP          0x20    /** @deprecated obsolete */
#define CL_DB_OFFICIAL          0x40    /** internal */
#define CL_DB_PUA_MODE          0x80
#define CL_DB_PUA_INCLUDE       0x100
#define CL_DB_PUA_EXCLUDE       0x200
#define CL_DB_COMPILED          0x400   /** internal */
#define CL_DB_DIRECTORY         0x800   /** internal */
#define CL_DB_OFFICIAL_ONLY     0x1000
#define CL_DB_BYTECODE          0x2000
#define CL_DB_SIGNED            0x4000  /** internal */
#define CL_DB_BYTECODE_UNSIGNED 0x8000  /** Caution: You should never run bytecode signatures from untrusted sources.
                                         *           Doing so may result in arbitrary code execution. */
#define CL_DB_UNSIGNED          0x10000 /** internal */
#define CL_DB_BYTECODE_STATS    0x20000
#define CL_DB_ENHANCED          0x40000
#define CL_DB_PCRE_STATS        0x80000
#define CL_DB_YARA_EXCLUDE      0x100000
#define CL_DB_YARA_ONLY         0x200000
#define CL_DB_FIPS_LIMITS       0x400000 /** Disable MD5 and SHA1 methods for trusting files and verifying certificates.
                                          *  Means: 1. CVD must be signed with external `.sign` file.
                                          *         2. Disables support for `.fp` signatures. */

/* recommended db settings */
#define CL_DB_STDOPT (CL_DB_PHISHING | CL_DB_PHISHING_URLS | CL_DB_BYTECODE)

/*** scan options ***/
struct cl_scan_options {
    uint32_t general;
    uint32_t parse;
    uint32_t heuristic;
    uint32_t mail;
    uint32_t dev;
};

/* general */
#define CL_SCAN_GENERAL_ALLMATCHES                  0x1  /** scan in all-match mode */
#define CL_SCAN_GENERAL_COLLECT_METADATA            0x2  /** collect metadata (--gen-json) */
#define CL_SCAN_GENERAL_HEURISTICS                  0x4  /** option to enable heuristic alerts */
#define CL_SCAN_GENERAL_HEURISTIC_PRECEDENCE        0x8  /** allow heuristic match to take precedence */
#define CL_SCAN_GENERAL_UNPRIVILEGED                0x10 /** scanner will not have read access to files */
#define CL_SCAN_GENERAL_STORE_HTML_URIS             0x20 /** when collect-metadata enabled: store uris found in html <a and <form tags */
#define CL_SCAN_GENERAL_STORE_PDF_URIS              0x40 /** when collect-metadata enabled: store uris found in pdf /URI tags */
#define CL_SCAN_GENERAL_STORE_EXTRA_HASHES          0x80 /** when collect-metadata enabled: calculate and store each type of supported file hash */

/* parsing capabilities options */
#define CL_SCAN_PARSE_ARCHIVE                       0x1
#define CL_SCAN_PARSE_ELF                           0x2
#define CL_SCAN_PARSE_PDF                           0x4
#define CL_SCAN_PARSE_SWF                           0x8
#define CL_SCAN_PARSE_HWP3                          0x10
#define CL_SCAN_PARSE_XMLDOCS                       0x20
#define CL_SCAN_PARSE_MAIL                          0x40
#define CL_SCAN_PARSE_OLE2                          0x80
#define CL_SCAN_PARSE_HTML                          0x100
#define CL_SCAN_PARSE_PE                            0x200
#define CL_SCAN_PARSE_ONENOTE                       0x400
#define CL_SCAN_PARSE_IMAGE                         0x800  /** option to enable/disable parsing images (graphics) */
#define CL_SCAN_PARSE_IMAGE_FUZZY_HASH              0x1000 /** option to enable/disable image fuzzy hash calculation. */

/* heuristic alerting options */
#define CL_SCAN_HEURISTIC_BROKEN                    0x2    /** alert on broken PE and broken ELF files */
#define CL_SCAN_HEURISTIC_EXCEEDS_MAX               0x4    /** alert when files exceed scan limits (filesize, max scansize, or max recursion depth) */
#define CL_SCAN_HEURISTIC_PHISHING_SSL_MISMATCH     0x8    /** alert on SSL mismatches */
#define CL_SCAN_HEURISTIC_PHISHING_CLOAK            0x10   /** alert on cloaked URLs in emails */
#define CL_SCAN_HEURISTIC_MACROS                    0x20   /** alert on OLE2 files containing macros */
#define CL_SCAN_HEURISTIC_ENCRYPTED_ARCHIVE         0x40   /** alert if archive is encrypted (rar, zip, etc) */
#define CL_SCAN_HEURISTIC_ENCRYPTED_DOC             0x80   /** alert if a document is encrypted (pdf, docx, etc) */
#define CL_SCAN_HEURISTIC_PARTITION_INTXN           0x100  /** alert if partition table size doesn't make sense */
#define CL_SCAN_HEURISTIC_STRUCTURED                0x200  /** data loss prevention options, i.e. alert when detecting personal information */
#define CL_SCAN_HEURISTIC_STRUCTURED_SSN_NORMAL     0x400  /** alert when detecting social security numbers */
#define CL_SCAN_HEURISTIC_STRUCTURED_SSN_STRIPPED   0x800  /** alert when detecting stripped social security numbers */
#define CL_SCAN_HEURISTIC_STRUCTURED_CC             0x1000 /** alert when detecting credit card numbers */
#define CL_SCAN_HEURISTIC_BROKEN_MEDIA              0x2000 /** alert if a file does not match the identified file format, works with JPEG, TIFF, GIF, PNG */

/* mail scanning options */
#define CL_SCAN_MAIL_PARTIAL_MESSAGE                0x1

/* dev options */
#define CL_SCAN_DEV_COLLECT_SHA                     0x1 /** @deprecated (functionality removed) */
#define CL_SCAN_DEV_COLLECT_PERFORMANCE_INFO        0x2 /** collect performance timings */

/* cl_countsigs options */
#define CL_COUNTSIGS_OFFICIAL                       0x1
#define CL_COUNTSIGS_UNOFFICIAL                     0x2
#define CL_COUNTSIGS_ALL                            (CL_COUNTSIGS_OFFICIAL | CL_COUNTSIGS_UNOFFICIAL)

/* For the new engine_options bit field in the engine */
#define ENGINE_OPTIONS_NONE             0x0
#define ENGINE_OPTIONS_DISABLE_CACHE    0x1
#define ENGINE_OPTIONS_FORCE_TO_DISK    0x2
#define ENGINE_OPTIONS_DISABLE_PE_STATS 0x4
#define ENGINE_OPTIONS_DISABLE_PE_CERTS 0x8
#define ENGINE_OPTIONS_PE_DUMPCERTS     0x10
#define ENGINE_OPTIONS_TMPDIR_RECURSION 0x20
#define ENGINE_OPTIONS_FIPS_LIMITS      0x40
// clang-format on

struct cl_engine;
struct cl_settings;

/* ----------------------------------------------------------------------------
 * Enable global libclamav features.
 */

/**
 * @brief Enable debug messages
 */
extern void cl_debug(void);

/**
 * @brief Set libclamav to always create section hashes for PE files.
 *
 * Section hashes are used in .mdb signature.
 */
extern void cl_always_gen_section_hash(void);

/* ----------------------------------------------------------------------------
 * Scan engine functions.
 */

/**
 * @brief This function initializes the openssl crypto system.
 *
 * Called by cl_init() and does not need to be cleaned up as de-init
 * is handled automatically by openssl 1.0.2.h and 1.1.0
 *
 * @return Always returns 0
 */
int cl_initialize_crypto(void);

/**
 * @brief Clean up ssl crypto inits.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 *             Call to EVP_cleanup() has been removed since cleanup is now handled by
 *             auto-deinit as of openssl 1.0.2h and 1.1.0.
 */
void cl_cleanup_crypto(void);

#define CL_INIT_DEFAULT 0x0
/**
 * @brief Initialize the ClamAV library.
 *
 * @param initoptions   Unused.
 * @return cl_error_t   CL_SUCCESS if everything initialized correctly.
 */
extern cl_error_t cl_init(unsigned int initoptions);

/**
 * @brief Allocate a new scanning engine and initialize default settings.
 *
 * The engine must be freed with `cl_engine_free()`.
 *
 * @return struct cl_engine* Pointer to the scanning engine.
 */
extern struct cl_engine *cl_engine_new(void);

enum cl_engine_field {
    CL_ENGINE_MAX_SCANSIZE,        /** uint64_t */
    CL_ENGINE_MAX_FILESIZE,        /** uint64_t */
    CL_ENGINE_MAX_RECURSION,       /** uint32_t */
    CL_ENGINE_MAX_FILES,           /** uint32_t */
    CL_ENGINE_MIN_CC_COUNT,        /** uint32_t */
    CL_ENGINE_MIN_SSN_COUNT,       /** uint32_t */
    CL_ENGINE_PUA_CATEGORIES,      /** (char *) */
    CL_ENGINE_DB_OPTIONS,          /** uint32_t */
    CL_ENGINE_DB_VERSION,          /** uint32_t */
    CL_ENGINE_DB_TIME,             /** time_t */
    CL_ENGINE_AC_ONLY,             /** uint32_t */
    CL_ENGINE_AC_MINDEPTH,         /** uint32_t */
    CL_ENGINE_AC_MAXDEPTH,         /** uint32_t */
    CL_ENGINE_TMPDIR,              /** (char *) */
    CL_ENGINE_KEEPTMP,             /** uint32_t */
    CL_ENGINE_BYTECODE_SECURITY,   /** uint32_t */
    CL_ENGINE_BYTECODE_TIMEOUT,    /** uint32_t */
    CL_ENGINE_BYTECODE_MODE,       /** uint32_t */
    CL_ENGINE_MAX_EMBEDDEDPE,      /** uint64_t */
    CL_ENGINE_MAX_HTMLNORMALIZE,   /** uint64_t */
    CL_ENGINE_MAX_HTMLNOTAGS,      /** uint64_t */
    CL_ENGINE_MAX_SCRIPTNORMALIZE, /** uint64_t */
    CL_ENGINE_MAX_ZIPTYPERCG,      /** uint64_t */
    CL_ENGINE_FORCETODISK,         /** uint32_t */
    CL_ENGINE_CACHE_SIZE,          /** uint32_t */
    CL_ENGINE_DISABLE_CACHE,       /** uint32_t */
    CL_ENGINE_DISABLE_PE_STATS,    /** uint32_t */
    CL_ENGINE_STATS_TIMEOUT,       /** uint32_t */
    CL_ENGINE_MAX_PARTITIONS,      /** uint32_t */
    CL_ENGINE_MAX_ICONSPE,         /** uint32_t */
    CL_ENGINE_MAX_RECHWP3,         /** uint32_t */
    CL_ENGINE_MAX_SCANTIME,        /** uint32_t */
    CL_ENGINE_PCRE_MATCH_LIMIT,    /** uint64_t */
    CL_ENGINE_PCRE_RECMATCH_LIMIT, /** uint64_t */
    CL_ENGINE_PCRE_MAX_FILESIZE,   /** uint64_t */
    CL_ENGINE_DISABLE_PE_CERTS,    /** uint32_t */
    CL_ENGINE_PE_DUMPCERTS,        /** uint32_t */
    CL_ENGINE_CVDCERTSDIR,         /** (char *) */
    CL_ENGINE_TMPDIR_RECURSION,    /** uint32_t */
    CL_ENGINE_FIPS_LIMITS,         /** uint32_t */
};

enum bytecode_security {
    CL_BYTECODE_TRUST_ALL = 0, /** @deprecated obsolete */
    CL_BYTECODE_TRUST_SIGNED,  /** default */
    CL_BYTECODE_TRUST_NOTHING  /** paranoid setting */
};

enum bytecode_mode {
    CL_BYTECODE_MODE_AUTO = 0,    /** JIT if possible, fallback to interpreter */
    CL_BYTECODE_MODE_JIT,         /** force JIT */
    CL_BYTECODE_MODE_INTERPRETER, /** force interpreter */
    CL_BYTECODE_MODE_TEST,        /** both JIT and interpreter, compare results, all failures are fatal */
    CL_BYTECODE_MODE_OFF          /** for query only, not settable */
};

struct cli_section_hash {
    unsigned char md5[16];
    size_t len;
};

typedef struct cli_stats_sections {
    size_t nsections;
    struct cli_section_hash *sections;
} stats_section_t;

/**
 * @brief Set a numerical engine option.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine            An initialized scan engine.
 * @param cl_engine_field   A CL_ENGINE option.
 * @param num               The new engine option value.
 * @return cl_error_t       CL_SUCCESS if successfully set.
 * @return cl_error_t       CL_EARG if the field number was incorrect.
 * @return cl_error_t       CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_set_num(struct cl_engine *engine, enum cl_engine_field field, long long num);

/**
 * @brief Get a numerical engine option.
 *
 * @param engine            An initialized scan engine.
 * @param cl_engine_field   A CL_ENGINE option.
 * @param err               (optional) A cl_error_t status code.
 * @return long long        The numerical option value.
 */
extern long long cl_engine_get_num(const struct cl_engine *engine, enum cl_engine_field field, int *err);

/**
 * @brief Set a string engine option.
 *
 * If the string option has already been set, the existing string will be free'd
 * and the new string will replace it.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine            An initialized scan engine.
 * @param cl_engine_field   A CL_ENGINE option.
 * @param str               The new engine option value.
 * @return cl_error_t       CL_SUCCESS if successfully set.
 * @return cl_error_t       CL_EARG if the field number was incorrect.
 * @return cl_error_t       CL_EMEM if a memory allocation error occurred.
 * @return cl_error_t       CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_set_str(struct cl_engine *engine, enum cl_engine_field field, const char *str);

/**
 * @brief Get a string engine option.
 *
 * @param engine            An initialized scan engine.
 * @param cl_engine_field   A CL_ENGINE option.
 * @param err               (optional) A cl_error_t status code.
 * @return const char *     The string option value.
 */
extern const char *cl_engine_get_str(const struct cl_engine *engine, enum cl_engine_field field, int *err);

/**
 * @brief Copy the settings from an existing scan engine.
 *
 * The cl_settings pointer is allocated and must be freed with cl_engine_settings_free().
 *
 * @param engine                An configured scan engine.
 * @return struct cl_settings*  The settings.
 */
extern struct cl_settings *cl_engine_settings_copy(const struct cl_engine *engine);

/**
 * @brief Apply settings from a settings structure to a scan engine.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine        A scan engine.
 * @param settings      The settings.
 * @return cl_error_t   CL_SUCCESS if successful.
 * @return cl_error_t   CL_EMEM if a memory allocation error occurred.
 */
extern cl_error_t cl_engine_settings_apply(struct cl_engine *engine, const struct cl_settings *settings);

/**
 * @brief Free a settings struct pointer.
 *
 * @param settings      The settings struct pointer.
 * @return cl_error_t   CL_SUCCESS if successful.
 * @return cl_error_t   CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_settings_free(struct cl_settings *settings);

/**
 * @brief Prepare the scanning engine.
 *
 * Call this after all required databases have been loaded and settings have
 * been applied.
 *
 * @param engine        A scan engine.
 * @return cl_error_t   CL_SUCCESS if successful.
 * @return cl_error_t   CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_compile(struct cl_engine *engine);

/**
 * @brief Add a reference count to the engine.
 *
 * Thread safety mechanism so that the engine is not free'd by another thread.
 *
 * The engine is initialized with refcount = 1, so this only needs to be called
 * for additional scanning threads.
 *
 * @param engine        A scan engine.
 * @return cl_error_t   CL_SUCCESS if successful.
 * @return cl_error_t   CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_addref(struct cl_engine *engine);

/**
 * @brief Free an engine.
 *
 * Will lower the reference count on an engine. If the reference count hits
 * zero, the engine will be freed.
 *
 * @param engine        A scan engine.
 * @return cl_error_t   CL_SUCCESS if successful.
 * @return cl_error_t   CL_ENULLARG null arguments were provided.
 */
extern cl_error_t cl_engine_free(struct cl_engine *engine);

/* ----------------------------------------------------------------------------
 * ClamAV File Map Abstraction Public API.
 */
struct cl_fmap;
typedef struct cl_fmap cl_fmap_t;

/**
 * @brief Read callback function type.
 *
 * A callback function pointer type for reading data from a cl_fmap_t that uses
 * reads data from a handle interface.
 *
 * Read 'count' bytes starting at 'offset' into the buffer 'buf'
 *
 * Thread safety: It is guaranteed that only one callback is executing for a
 * specific handle at any time, but there might be multiple callbacks executing
 * for different handle at the same time.
 *
 * @param handle    The handle passed to cl_fmap_open_handle, its meaning is up
 *                  to the callback's implementation
 * @param buf       A buffer to read data into, must be at least offset + count
 *                  bytes in size.
 * @param count     The number of bytes to read.
 * @param offset    The offset into buf to read the data to. If successful,
 *                  the number of bytes actually read is returned. Upon reading
 *                  end-of-file, zero is returned. Otherwise, a -1 is returned
 *                  and the global variable errno is set to indicate the error.
 */
typedef off_t (*clcb_pread)(void *handle, void *buf, size_t count, off_t offset);

/**
 * @brief Open a map given a handle.
 *
 * Open a map for scanning custom data accessed by a handle and pread (lseek +
 * read)-like interface. For example a file descriptor or a WIN32 HANDLE.
 * By default fmap will use aging to discard old data, unless you tell it not
 * to.
 *
 * The handle will be passed to the callback each time.
 *
 * TIP: Check the size limits before calling this function so you don't map a
 * file that is larger than the maximum size the engine is configured to scan.
 *
 * Note that the offset and len is for the start through the end of an _entire_
 * file, which may be contained within another larger file.
 * You can't give it parts of a file and expect detection to work.
 *
 * @param handle        A handle that may be accessed using lseek + read.
 * @param offset        Initial offset to start scanning.
 * @param len           Length of the data from the start (not the offset).
 * @param pread_cb      A callback function to read data from the handle.
 * @param use_aging     Set to a non-zero value to enable aging.
 * @return cl_fmap_t*   A map representing the handle interface.
 */
extern cl_fmap_t *cl_fmap_open_handle(
    void *handle,
    size_t offset,
    size_t len,
    clcb_pread pread_cb,
    int use_aging);

/**
 * @brief Open a map given a buffer.
 *
 * Open a map for scanning custom data, where the data is already in memory,
 * either in the form of a buffer, a memory mapped file, etc.
 *
 * Note that the memory [start, start+len) must be the _entire_ file,
 * you can't give it parts of a file and expect detection to work.
 *
 * @param start         Pointer to a buffer of data.
 * @param len           Length in bytes of the data.
 * @return cl_fmap_t*   A map representing the buffer.
 */
extern cl_fmap_t *cl_fmap_open_memory(const void *start, size_t len);

/**
 * @brief Set the utf8 name of a file map. E.g. "invoice.exe"
 *
 * The name is used for debugging and logging purposes.
 * In a future release, the file extension may help determine refine file type
 * detection. E.g. ".js" may indicate that something previously identified as
 * a text file is more specifically a JavaScript file.
 * That is - at this time setting the name will have no impact on detection,
 * but it may in the future.
 *
 * @param map           The file map to modify.
 * @param name          The new name for the file map.
 * @return cl_error_t   CL_SUCCESS if the name was set successfully.
 */
extern cl_error_t cl_fmap_set_name(cl_fmap_t *map, const char *name);

/**
 * @brief Get the utf8 name of a file map.
 *
 * The name is used for debugging and logging purposes.
 *
 * @param map           The file map to query.
 * @param[out] name_out Pointer to a variable to receive the name of the file map.
 * @return const char*  The name of the file map, or NULL if not set.
 */
extern cl_error_t cl_fmap_get_name(cl_fmap_t *map, const char **name_out);

/**
 * @brief Set the utf8 path of a file map. E.g. "/tmp/invoice.exe"
 *
 * This is used to set the actual file path of the mapped map.
 * The path may be used for debugging or logging purposes.
 *
 * You might want to set the path if you opened the map with `cl_fmap_open_handle()`.
 *
 * @param map           The file map to modify.
 * @param path          The new path for the file map.
 * @return cl_error_t   CL_SUCCESS if the path was set successfully.
 */
extern cl_error_t cl_fmap_set_path(cl_fmap_t *map, const char *path);

/**
 * @brief Get the utf8 path of a file map.
 *
 * The path is used for debugging and logging purposes.
 *
 * This may be NULL even if there is a file descriptor associated with the map.
 * There is no guarantee that the path was set by whomever created the map.
 * For example, if the map was created from a file descriptor that was provided
 * to clamd by clamonacc or clamdscan using fd-passing, then the path may not be
 * known.
 *
 * This of course will be NULL if the map was created from a memory buffer.
 *
 * If you need a temp file for each file extracted, you can use ClamAV's
 * force-to-disk feature. Note: There is no option to force-to-memory.
 * Many of the parser modules will create temporary files no matter what.
 *
 * If the fmap represents a temp file created during the scan, then unless you
 * use CL_ENGINE_KEEPTMP, it will be deleted when the scan is done with this
 * layer.
 *
 * @param map             The file map to query.
 * @param[out] path_out   Pointer to a variable to receive the path of the file map.
 * @param[out] offset_out (optional) Pointer to a variable to receive the offset of the current layer within the given file.
 * @param[out] len_out    (optional) Pointer to a variable to receive the length of the current layer within the given file.
 * @return cl_error_t     CL_SUCCESS if the path was successfully retrieved.
 *                        CL_EACCES if the map does not have a file descriptor.
 *                        CL_ENULLARG if null arguments were provided.
 */
extern cl_error_t cl_fmap_get_path(cl_fmap_t *map, const char **path_out, size_t *offset_out, size_t *len_out);

/**
 * @brief Get the file descriptor of a file map.
 *
 * The file descriptor is used to access the file represented by the file map.
 * If the file map was created from a file descriptor, this will return that
 * descriptor. Otherwise, it will return -1.
 *
 * If you need a temp file for each file extracted, you can use ClamAV's
 * force-to-disk feature. Note: There is no option to force-to-memory.
 * Many of the parser modules will create temporary files no matter what.
 *
 * Don't close this file descriptor. Don't dup it either.
 *
 * @param map             The file map to query.
 * @param[out] fd_out     Pointer to a variable to receive the file descriptor.
 * @param[out] offset_out (optional) Pointer to a variable to receive the offset of the current layer within the given file.
 * @param[out] len_out    (optional) Pointer to a variable to receive the length of the current layer within the given file.
 * @return cl_error_t     CL_SUCCESS if the file descriptor was successfully retrieved.
 *                        CL_EACCES if the map does not have a file descriptor.
 *                        CL_ENULLARG if null arguments were provided.
 */
extern cl_error_t cl_fmap_get_fd(const cl_fmap_t *map, int *fd_out, size_t *offset_out, size_t *len_out);

/**
 * @brief Get the file size of the current layer from a file map.
 *
 * This function retrieves the size of the file represented by the file map.
 * If the file map was created from a handle, it will use the pread callback
 * to determine the size.
 *
 * @param map           The file map to query.
 * @param[out] size_out Pointer to a variable to receive the size of the file.
 * @return cl_error_t   CL_SUCCESS if the file size was successfully retrieved.
 */
extern cl_error_t cl_fmap_get_size(const cl_fmap_t *map, size_t *size_out);

/**
 * @brief Set the file hash for a file map.
 *
 * This function sets the hash of the file represented by the file map.
 * If a hash of the requested type has already been calculated, it will be
 * overwritten with the new value.
 *
 * @param map           The file map to modify.
 * @param hash_alg      The hash algorithm to use (e.g., "md5", "sha1", "sha2-256").
 * @param hash          The hash value to set.
 * @return cl_error_t   CL_SUCCESS if the hash was successfully set.
 */
extern cl_error_t cl_fmap_set_hash(const cl_fmap_t *map, const char *hash_alg, char hash);

/**
 * @brief Check if we already calculated a file hash of a specific type.
 *
 * This function checks if the file represented by the file map has a hash
 * of the requested type already calculated.
 *
 * @param map                A file map.
 * @param hash_alg           The hash algorithm to check (e.g., "md5", "sha1", "sha2-256").
 * @param[out] have_hash_out Pointer to a boolean that will be set to true if the hash exists, false otherwise.
 * @return cl_error_t        CL_SUCCESS if the check was successful.
 */
extern cl_error_t cl_fmap_have_hash(const cl_fmap_t *map, const char *hash_alg, bool *have_hash_out);

/**
 * @brief Indicate that we will need a file hash of a specific type later.
 *
 * This function indicates that we will need the file hash of the requested
 * type in the future. The next time a hash is calculated, (e.g. when you run
 * `cl_fmap_get_hash()`, it will also calculate the requested hash type.
 *
 * This is an optimization to avoid iterating over the file contents multiple times
 * which might happen if you call `cl_fmap_get_hash()` without calling this first.
 *
 * @param map           A file map.
 * @param hash_alg      The hash algorithm to indicate (e.g., "md5", "sha1", "sha2-256").
 * @return cl_error_t   CL_SUCCESS if the indication was successful.
 */
extern cl_error_t cl_fmap_will_need_hash_later(const cl_fmap_t *map, const char *hash_alg);

/**
 * @brief Get the file hash from a file map.
 *
 * This function retrieves the hash of the file represented by the file map.
 * If a hash of the requested type has NOT already been calculated then it will
 * be calculated when you call this function, and stored for future use.
 *
 * You are responsible for freeing the hash string when you're done with it.
 *
 * @param map           A file map.
 * @param hash_alg      The hash algorithm to use (e.g., "md5", "sha1", "sha2-256").
 * @param[out] hash_out Malloced string containing the hash value.
 * @return cl_error_t   CL_SUCCESS if the hash was successfully retrieved.
 */
extern cl_error_t cl_fmap_get_hash(const cl_fmap_t *map, const char *hash_alg, char **hash_out);

/**
 * @brief Get the file contents from a file map.
 *
 * This function will get you a pointer to the contents of the file represented
 * by the file map. This is read-only and is not malloced.
 * If you want a copy to keep, you must copy it yourself.
 *
 * Use the offset and length parameters to specify the range of the file you
 * want to retrieve. If you don't need the whole file, don't ask for the whole file.
 *
 * @param map               A file map.
 * @param offset            The offset in the file from which to access.
 * @param len               The length of the data to read.
 *                          If 0, then the rest of the file will be provided.
 * @param[out] data_out     A valid pointer to data file contents. Will be NULL if failed.
 * @param[out] data_len_out The length of the file contents. May be less than requested if the end of file is reached.
 * @return cl_error_t       CL_SUCCESS if the contents were successfully retrieved.
 */
extern cl_error_t cl_fmap_get_data(
    const cl_fmap_t *map,
    size_t offset,
    size_t len,
    const uint8_t **data_out,
    size_t *data_len_out);

/**
 * @brief Releases resources associated with the map.
 *
 * You must release any resources you hold only after (handles, maps) calling
 * this function.
 *
 * @param map           Map to be closed.
 */
extern void cl_fmap_close(cl_fmap_t *);

/* ----------------------------------------------------------------------------
 * ClamAV Recursive Scan Layer Public API.
 */
struct cl_scan_layer;
typedef struct cl_scan_layer cl_scan_layer_t;

/**
 * @brief Get the file map associated with a scan layer.
 *
 * @param layer                 The scan layer to query.
 * @param[out] fmap_out         Pointer to a variable to receive the file map.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_fmap(
    cl_scan_layer_t *layer,
    cl_fmap_t **fmap_out);

/**
 * @brief Get the parent layer of a scan layer.
 *
 * You may use this in a loop/recursively to walk the scan layers.
 * Also consider using `cl_scan_layer_get_recursion_level()` to determine the
 * depth of the current layer.
 *
 * @param layer                 The scan layer to query.
 * @param[out] parent_layer_out Pointer to a variable to receive the parent layer.
 *                              Will be NULL if the layer has no parent.
 *                              For example, the root layer has no parent.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_parent_layer(
    cl_scan_layer_t *layer,
    cl_scan_layer_t **parent_layer_out);

/**
 * @brief Get the file type of a scan layer.
 *
 * The file type as clamav currently believes it to be.
 * It may change later in the scan, so consider using `clcb_file_type_correction`
 * callback to access the file again if it is re-typed.
 *
 * @param layer                 The scan layer to query.
 * @param[out] type_out         Pointer to a variable to receive the file type.
 *                              This is a static reference and must not be freed.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_type(
    cl_scan_layer_t *layer,
    const char **type_out);

/**
 * @brief Get the recursion level of a scan layer.
 *
 * @param layer                    The scan layer to query.
 * @param[out] recursion_level_out Pointer to a variable to receive the recursion level.
 * @return cl_error_t              CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_recursion_level(
    cl_scan_layer_t *layer,
    uint32_t *recursion_level_out);

/**
 * @brief Get the object ID of a scan layer.
 *
 * Object ID is a unique identifier for the scan layer. It counts up from 0, although the callback interface
 * may skip some IDs if the scan layer is processed immediately rather than being handled as distinct file type.
 * For example, HTML may be normalized several ways and they're each given an Object ID, but we immediately
 * pattern match them and do not handle them as distinct file types that were contained within the HTML.
 *
 * @param layer                 The scan layer to query.
 * @param[out] object_id_out    Pointer to a variable to receive the object ID.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_object_id(
    cl_scan_layer_t *layer,
    uint64_t *object_id_out);

/**
 * @brief Get the last detected alert name from a scan layer.
 *
 * Do not free the alert name, and make a copy if you need one.
 *
 * @param layer                 The scan layer to query.
 * @param[out] alert_name_out   Pointer to a variable to receive the alert name.
 *                              If the layer has no alerts, this will be set to NULL.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_last_alert(
    cl_scan_layer_t *layer,
    const char **alert_name_out);

/*
 * Attributes of each layer in scan.
 */
#define LAYER_ATTRIBUTES_NONE 0x0       /**< No attributes set. */
#define LAYER_ATTRIBUTES_NORMALIZED 0x1 /**< This layer was modified to make matching more generic, reliable. */
#define LAYER_ATTRIBUTES_DECRYPTED 0x2  /**< Decryption was used to extract this layer. \
                                         *   E.g. ClamAV was able to decrypt an encrypted file entry in the parent layer. */
#define LAYER_ATTRIBUTES_RETYPED 0x4    /**< This layer is a re-scan of the parent layer but as a new type (e.g. using HandlerType). */
#define LAYER_ATTRIBUTES_EMBEDDED 0x8   /**< This layer was found within the parent layer using FTM signatures \
                                         *   (e.g. like ZIP entries found within an executable). */

/**
 * @brief Get the attributes of a scan layer.
 *
 * @param layer                 The scan layer to query.
 * @param[out] attributes_out    Pointer to a variable to receive the layer attributes.
 * @return cl_error_t           CL_SUCCESS if successful.
 */
extern cl_error_t cl_scan_layer_get_attributes(
    cl_scan_layer_t *layer,
    uint32_t *attributes_out);

/* ----------------------------------------------------------------------------
 * Callback function type definitions.
 */

typedef enum scan_callback {
    /** Pre-hash
     *
     * Occurs just after basic file-type detection and before any hashes have been calculated either for the cache or
     * the gen-json metadata.
     * If you want any hashes other than SHA2-256, the most efficient option is to run the
     * `cl_fmap_will_need_hash_later()` function in this callback for each and then run the `cl_fmap_get_hash()`
     * function afterwards (now or later) to gather the hashes.
     *
     * Using this callback will appear in-order for ClamAV's depth-first approach.
     */
    CL_SCAN_CALLBACK_PRE_HASH,

    /** Pre-scan
     *
     * Occurs before parser modules run and before pattern matching.
     *
     * Using this callback will appear in-order for ClamAV's depth-first approach.
     */
    CL_SCAN_CALLBACK_PRE_SCAN,

    /** Post-scan
     *
     * Occurs after pattern matching and after running parser modules (i.e. scan complete for this layer).
     * This callback is useful for post-processing the results of the scan, but is the most likely of the callbacks to
     * be skipped if something goes critically wrong or the hash for the layer appeared in the clean-cache.
     *
     * Using this callback will appear in REVERSE-order for ClamAV's depth-first approach.
     */
    CL_SCAN_CALLBACK_POST_SCAN,

    /** Alert
     *
     * Occurs each time an alert (detection) would be triggered during a scan.
     * In all-match mode, you may receive multiple alerts for the same file, and even the same layer, corresponding with
     * each signature that matched.
     */
    CL_SCAN_CALLBACK_ALERT,

    /** File type
     *
     * Occurs each time the file type determination is refined.
     * This may happen more than once per LAYER!
     *
     * Outside of using this callback, The most accurate time to check the file type would be:
     * - For each layer: Use `cl_scan_layer_get_type()` in the `CL_SCAN_CALLBACK_POST_SCAN` callback.
     * - For just the top layer: Use the `file_type_out` parameter provided by the `cl_scan*ex()` functions.
     */
    CL_SCAN_CALLBACK_FILE_TYPE
} cl_scan_callback_t;

/**
 * @brief Callback interface to get access to the current layer using the scan-
 * layer abstraction. This grants access to file content and attributes as well
 * as those of each ancestor layers (if any).
 *
 * Called for each processed file including both the top level file (i.e. the
 * zeroeth layer) and all contained files (recursively).
 *
 * @param layer          Scan layer (abstraction) for the current layer being scanned.
 *                       Use the `cl_scan_layer_*` functions to access layer data and metadata.
 *                       You may want to use `cl_scan_layer_get_fmap()` to get the file map for the current layer.
 *                       You may also use it to access ancestor layers using `cl_scan_layer_get_parent_layer()`.
 *
 * @param context        The application context pointer passed in to the `cl_scan*()` function.
 *
 * @return CL_BREAK
 *
 *         Scan aborted by callback (the rest of the scan is skipped).
 *         This does not mark the file as clean or infected, it just skips the rest of the scan.
 *
 * @return CL_SUCCESS / CL_CLEAN
 *
 *         File scan will continue.
 *
 *         For CL_SCAN_CALLBACK_ALERT: Means you want to ignore this specific alert and keep scanning.
 *         This is different than CL_VERIFIED because it does not affect prior or future alerts.
 *         Return CL_VERIFIED instead if you want to remove prior alerts for this layer and skip
 *         the rest of the scan for this layer.
 *
 * @return CL_VIRUS
 *
 *         This will mark the file as infected. A new alert will be added.
 *
 *         For CL_SCAN_CALLBACK_ALERT: Means you agree with the alert (no extra alert needed).
 *                                     Remember that CL_SUCCESS means you want to ignore the alert.
 *
 * @return CL_VERIFIED
 *
 *         Layer explicitly trusted by the callback and previous alerts removed FOR THIS layer.
 *         You might want to do this if you trust the hash or verified a digital signature.
 *         The rest of the scan will be skipped FOR THIS layer.
 *         For contained files, this does NOT mean that the parent or adjacent layers are trusted.
 */
typedef cl_error_t (*clcb_scan)(cl_scan_layer_t *layer, void *context);
/**
 * @brief Set a callback function using the clcb_scan callback type.
 *
 * Select the callback location using the `cl_scan_callback_t` enum.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 * @param location  The location of the callback.
 */
extern void cl_engine_set_scan_callback(struct cl_engine *engine, clcb_scan callback, cl_scan_callback_t location);

/**
 * @brief Pre-cache callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_PRE_HASH` with `cl_engine_set_scan_callback()` instead.
 *
 * Called for each processed file (both the entry level - AKA 'outer' - file and
 * inner files - those generated when processing archive and container files), before
 * the actual scanning takes place.
 *
 * @param fd        File descriptor which is about to be scanned.
 * @param type      File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
 * @param context   Opaque application provided data.
 * @return          CL_CLEAN = File is scanned.
 * @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.
 * @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected.
 */
typedef cl_error_t (*clcb_pre_cache)(int fd, const char *type, void *context);
/**
 * @brief Set a custom pre-cache callback function.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_PRE_HASH` with `cl_engine_set_scan_callback()` instead.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_pre_cache(struct cl_engine *engine, clcb_pre_cache callback);

/**
 * @brief File inspection callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.
 *
 * You can use the `cl_fmap_*` functions to access the file map, file name, file size, file contents,
 * and those of each ancestor layers (if any).
 *
 * Called for each NEW file (inner and outer).
 * Provides capability to record embedded file information during a scan.
 *
 * @param fd                  Current file descriptor which is about to be scanned.
 * @param type                Current file type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
 * @param ancestors           An array of ancestors filenames of size `recursion_level`. filenames may be NULL.
 * @param parent_file_size    Parent file size.
 * @param file_name           Current file name, or NULL if the file does not have a name or ClamAV failed to record the name.
 * @param file_size           Current file size.
 * @param file_buffer         Current file buffer pointer.
 * @param recursion_level     Recursion level / depth of the current file.
 * @param layer_attributes    See LAYER_ATTRIBUTES_* flags.
 * @param context             Opaque application provided data.
 * @return                    CL_CLEAN = File is scanned.
 * @return                    CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.
 * @return                    CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected.
 */
typedef cl_error_t (*clcb_file_inspection)(
    int fd,
    const char *type,
    const char **ancestors,
    size_t parent_file_size,
    const char *file_name,
    size_t file_size,
    const char *file_buffer,
    uint32_t recursion_level,
    uint32_t layer_attributes,
    void *context);
/**
 * @brief Set a custom file inspection callback function.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.
 *
 * DISCLAIMER: This interface is to be considered unstable while we continue to evaluate it.
 * We may change this interface in the future.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_file_inspection(struct cl_engine *engine, clcb_file_inspection callback);

/**
 * @brief Pre-scan callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 *
 * Called for each NEW file (inner and outer) before the scanning takes place. This is
 * roughly the same as clcb_before_cache, but it is affected by clean file caching.
 * This means that it won't be called if a clean cached file (inner or outer) is
 * scanned a second time.
 *
 * @param fd        File descriptor which is about to be scanned.
 * @param type      File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
 * @param context   Opaque application provided data.
 * @return          CL_CLEAN = File is scanned.
 * @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.
 * @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected.
 */
typedef cl_error_t (*clcb_pre_scan)(int fd, const char *type, void *context);
/**
 * @brief Set a custom pre-scan callback function.
 * Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_pre_scan(struct cl_engine *engine, clcb_pre_scan callback);

/**
 * @brief Post-scan callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.
 *
 * Called for each processed file (inner and outer), after the scanning is complete.
 * In all-match mode, the virname will be one of the matches, but there is no
 * guarantee in which order the matches will occur, thus the final virname may
 * be any one of the matches.
 *
 * @param fd        File descriptor which was scanned.
 * @param result    The scan result for the file.
 * @param virname   A signature name if there was one or more matches.
 * @param context   Opaque application provided data.
 * @return          Scan result is not overridden.
 * @return          CL_BREAK = Allowed by callback - scan result is set to CL_CLEAN.
 * @return          Blocked by callback - scan result is set to CL_VIRUS.
 */
typedef cl_error_t (*clcb_post_scan)(int fd, int result, const char *virname, void *context);
/**
 * @brief Set a custom post-scan callback function.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_post_scan(struct cl_engine *engine, clcb_post_scan callback);

/**
 * @brief Virus-found callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_ALERT` with `cl_engine_set_scan_callback()` instead.
 *
 * Called for each signature match.
 * If all-match is enabled, clcb_virus_found() may be called multiple times per
 * scan.
 *
 * In addition, clcb_virus_found() does not have a return value and thus.
 * can not be used to ignore the match.
 *
 * @param fd        File descriptor which was scanned.
 * @param virname   Virus name.
 * @param context   Opaque application provided data.
 */
typedef void (*clcb_virus_found)(int fd, const char *virname, void *context);
/**
 * @brief Set a custom virus-found callback function.
 * Use `CL_SCAN_CALLBACK_ALERT` with `cl_engine_set_scan_callback()` instead.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_virus_found(struct cl_engine *engine, clcb_virus_found callback);

/**
 * @brief Signature-load callback.
 *
 * May be used to ignore signatures at database load time.
 *
 * WARNING: Some signatures (notably ldb, cbc) can be dependent upon other signatures.
 *          Failure to preserve dependency chains will result in database loading failure.
 *          It is the implementor's responsibility to guarantee consistency.
 *
 * @param type      The signature type (e.g. "db", "ndb", "mdb", etc.)
 * @param name      Signature name.
 * @param custom    The signature is official (custom == 0) or custom (custom != 0)
 * @param context   Opaque application provided data
 * @return          0 to load the current signature.
 * @return          Non-0 to skip the current signature.
 */
typedef int (*clcb_sigload)(const char *type, const char *name, unsigned int custom, void *context);
/**
 * @brief Set a custom signature-load callback function.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 * @param context   Opaque application provided data.
 */
extern void cl_engine_set_clcb_sigload(struct cl_engine *engine, clcb_sigload callback, void *context);

enum cl_msg {
    /* leave room for more message levels in the future */
    CL_MSG_INFO_VERBOSE = 32, /* verbose */
    CL_MSG_WARN         = 64, /* LibClamAV WARNING: */
    CL_MSG_ERROR        = 128 /* LibClamAV ERROR: */
};

/**
 * @brief Progress callback for sig-load, engine-compile, and engine-free.
 *
 * Progress is complete when total_items == now_completed.
 *
 * Note: The callback should return CL_SUCCESS. We reserve the right to have it
 *       cancel the operation in the future if you return something else...
 *       ... but for now, the return value will be ignored.
 *
 * @param total_items   Total number of items
 * @param now_completed Number of items completed
 * @param context       Opaque application provided data
 * @return cl_error_t   reserved for future use
 */
typedef cl_error_t (*clcb_progress)(size_t total_items, size_t now_completed, void *context);

/**
 * @brief Set a progress callback function to be called incrementally during a
 * database load.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine
 * @param callback  The callback function pointer
 * @param context   Opaque application provided data
 */
extern void cl_engine_set_clcb_sigload_progress(struct cl_engine *engine, clcb_progress callback, void *context);

/**
 * @brief Set a progress callback function to be called incrementally during an
 * engine compile.
 *
 * Disclaimer: the number of items for this is a rough estimate of the items that
 * tend to take longest to compile and doesn't represent an accurate number of
 * things compiled.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine
 * @param callback  The callback function pointer
 * @param context   Opaque application provided data
 */
extern void cl_engine_set_clcb_engine_compile_progress(struct cl_engine *engine, clcb_progress callback, void *context);

/**
 * @brief Set a progress callback function to be called incrementally during an
 * engine free (if the engine is in fact freed).
 *
 * Disclaimer: the number of items for this is a rough estimate of the items that
 * tend to take longest to free and doesn't represent an accurate number of
 * things freed.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine
 * @param callback  The callback function pointer
 * @param context   Opaque application provided data
 */
extern void cl_engine_set_clcb_engine_free_progress(struct cl_engine *engine, clcb_progress callback, void *context);

/**
 * @brief Logging message callback for info, warning, and error messages.
 *
 * The specified callback will be called instead of logging to stderr.
 * Messages of lower severity than specified are logged as usual.
 *
 * Callback may be used to silence logging by assigning a do-nothing function.
 * Does not affect debug log messages.
 *
 * Just like with cl_debug() this must be called before going multithreaded.
 * Callable before cl_init, if you want to log messages from cl_init() itself.
 *
 * You can use context of cl_scandesc_callback to convey more information to
 * the callback (such as the filename!).
 *
 * Note: setting a 2nd callbacks overwrites previous, multiple callbacks are not
 * supported.
 *
 * @param severity  Message severity (CL_MSG_INFO_VERBOSE, CL_MSG_WARN, or CL_MSG_ERROR).
 * @param fullmsg   The log message including the "LibClamAV <severity>: " prefix.
 * @param msg       The log message.
 * @param context   Opaque application provided data.
 */
typedef void (*clcb_msg)(enum cl_msg severity, const char *fullmsg, const char *msg, void *context);
/**
 * @brief Set a custom logging message callback function for all of libclamav.
 *
 * @param callback  The callback function pointer.
 */
extern void cl_set_clcb_msg(clcb_msg callback);

/**
 * @brief LibClamAV hash stats callback.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_ALERT` with `cl_engine_set_scan_callback()` instead.
 * Then use the `cl_scan_layer_get_fmap()` and `cl_fmap_get_hash()` functions.
 *
 * Callback that provides the hash of a scanned sample if a signature alerted.
 * Provides a mechanism to record detection statistics.
 *
 * @param fd        File descriptor if available, else -1.
 * @param size      Sample size
 * @param md5       Sample md5 hash (string)
 * @param virname   Signature name that the sample matched against
 * @param context   Opaque application provided data
 */
typedef void (*clcb_hash)(int fd, unsigned long long size, const char *md5, const char *virname, void *context);
/**
 * @brief Set a custom hash stats callback function.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `CL_SCAN_CALLBACK_ALERT` with `cl_engine_set_scan_callback()` instead.
 * Then use the `cl_scan_layer_get_fmap()` and `cl_fmap_get_hash()` functions.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_hash(struct cl_engine *engine, clcb_hash callback);

/**
 * @brief Archive meta matching callback function.
 *
 * May be used to block archive/container samples based on archive metadata.
 * Function is invoked multiple times per archive. Typically once per contained file.
 *
 * Note: Used by the --archive-verbose clamscan option. Overriding this will alter
 * the output from --archive-verbose.
 *
 * @param container_type    String name of type (CL_TYPE).
 * @param fsize_container   Sample size
 * @param filename          Filename associated with the data in archive.
 * @param fsize_real        Size of file after decompression (according to the archive).
 * @param is_encrypted      Boolean non-zero if the contained file is encrypted.
 * @param filepos_container File index in container.
 * @param context           Opaque application provided data.
 * @return                  CL_VIRUS to block (alert on)
 * @return                  CL_CLEAN to continue scanning
 */
typedef cl_error_t (*clcb_meta)(
    const char *container_type,
    unsigned long fsize_container,
    const char *filename,
    unsigned long fsize_real,
    int is_encrypted,
    unsigned int filepos_container,
    void *context);
/**
 * @brief Set a custom archive metadata matching callback function.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_meta(struct cl_engine *engine, clcb_meta callback);

/**
 * @brief File properties callback function.
 *
 * Invoked after a scan the CL_SCAN_GENERAL_COLLECT_METADATA general scan option
 * is enabled and libclamav was built with json support.
 *
 * @param j_propstr File properties/metadata in a JSON encoded string.
 * @param rc        The cl_error_t return code from the scan.
 * @param cbdata    Opaque application provided data.
 */
typedef int (*clcb_file_props)(const char *j_propstr, int rc, void *cbdata);
/**
 * @brief Set a custom file properties callback function.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_file_props(struct cl_engine *engine, clcb_file_props callback);

/**
 * @brief generic data callback function.
 *
 * Callback handler prototype for callbacks passing back data and application context.
 *
 * @param data      A pointer to some data. Should be treated as read-only and may be freed after callback.
 * @param data_len  The length of data.
 * @param cbdata    Opaque application provided data.
 */
typedef int (*clcb_generic_data)(const unsigned char *const data, const size_t data_len, void *cbdata);

/**
 * @brief Set a custom VBA macro callback function.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_vba(struct cl_engine *engine, clcb_generic_data callback);

/* ----------------------------------------------------------------------------
 * Statistics/telemetry gathering callbacks.
 *
 * The statistics callback functions may be used to implement a telemetry
 * gathering feature.
 *
 * The structure definition for `cbdata` is entirely up to the caller, as are
 * the implementations of each of the callback functions defined below.
 */

/**
 * @brief Set a pointer the caller-defined cbdata structure.
 *
 * The data must persist at least until `clcb_stats_submit()` is called, or
 * `clcb_stats_flush()` is called (optional).
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine The scanning engine.
 * @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
 */
extern void cl_engine_set_stats_set_cbdata(struct cl_engine *engine, void *cbdata);

/**
 * @brief Add sample metadata to the statistics for a sample that matched on a signature.
 *
 * @param virname   Name of the signature that matched.
 * @param md5       Sample hash.
 * @param size      Sample size.
 * @param sections  PE section data, if applicable.
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef void (*clcb_stats_add_sample)(
    const char *virname,
    const unsigned char *md5,
    size_t size,
    stats_section_t *sections,
    void *cbdata);
/**
 * @brief Set a custom callback function to add sample metadata to a statistics report.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_add_sample(struct cl_engine *engine, clcb_stats_add_sample callback);

/**
 * @brief Remove a specific sample from the statistics report.
 *
 * @param virname   Name of the signature that matched.
 * @param md5       Sample hash.
 * @param size      Sample size.
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef void (*clcb_stats_remove_sample)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
/**
 * @brief Set a custom callback function to remove sample metadata from a statistics report.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_remove_sample(struct cl_engine *engine, clcb_stats_remove_sample callback);

/**
 * @brief Decrement the hit count listed in the statistics report for a specific sample.
 *
 * @param virname   Name of the signature that matched.
 * @param md5       Sample hash.
 * @param size      Sample size.
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef void (*clcb_stats_decrement_count)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
/**
 * @brief Set a custom callback function to decrement the hit count listed in the statistics report for a specific sample.
 *
 * This function may remove the sample from the report if the hit count is decremented to 0.
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_decrement_count(struct cl_engine *engine, clcb_stats_decrement_count callback);

/**
 * @brief Function to submit a statistics report.
 *
 * @param engine    The initialized scanning engine.
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef void (*clcb_stats_submit)(struct cl_engine *engine, void *cbdata);
/**
 * @brief Set a custom callback function to submit the statistics report.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_submit(struct cl_engine *engine, clcb_stats_submit callback);

/**
 * @brief Function to flush/free the statistics report data.
 *
 * @param engine    The initialized scanning engine.
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef void (*clcb_stats_flush)(struct cl_engine *engine, void *cbdata);
/**
 * @brief Set a custom callback function to flush/free the statistics report data.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_flush(struct cl_engine *engine, clcb_stats_flush callback);

/**
 * @brief Function to get the number of samples listed in the statistics report.
 *
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef size_t (*clcb_stats_get_num)(void *cbdata);
/**
 * @brief Set a custom callback function to get the number of samples listed in the statistics report.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_get_num(struct cl_engine *engine, clcb_stats_get_num callback);

/**
 * @brief Function to get the size of memory used to store the statistics report.
 *
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef size_t (*clcb_stats_get_size)(void *cbdata);
/**
 * @brief Set a custom callback function to get the size of memory used to store the statistics report.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_get_size(struct cl_engine *engine, clcb_stats_get_size callback);

/**
 * @brief Function to get the machine's unique host ID.
 *
 * @param cbdata    The statistics data. Probably a pointer to a malloc'd struct.
 */
typedef char *(*clcb_stats_get_hostid)(void *cbdata);
/**
 * @brief Set a custom callback function to get the machine's unique host ID.
 *
 * Caution: changing options for an engine that is in-use is not thread-safe!
 *
 * @param engine    The initialized scanning engine.
 * @param callback  The callback function pointer.
 */
extern void cl_engine_set_clcb_stats_get_hostid(struct cl_engine *engine, clcb_stats_get_hostid callback);

/**
 * @brief Function enables the built-in statistics reporting feature.
 *
 * @param engine    The initialized scanning engine.
 */
extern void cl_engine_stats_enable(struct cl_engine *engine);

/* ----------------------------------------------------------------------------
 * File scanning.
 */

/**
 * @brief Scan a file, given a file descriptor.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use `cl_scandesc_ex()` instead.
 *
 * @param desc            File descriptor of an open file. The caller must provide this or the map.
 * @param filename        (optional) Filepath of the open file descriptor or file map.
 * @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.
 * @param[out] scanned    The number of bytes scanned / CL_COUNT_PRECISION.
 * @param engine          The scanning engine.
 * @param scanoptions     Scanning options.
 * @return cl_error_t     CL_CLEAN, CL_VIRUS, or an error code if an error occurred during the scan.
 */
extern cl_error_t cl_scandesc(
    int desc,
    const char *filename,
    const char **virname,
    unsigned long int *scanned,
    const struct cl_engine *engine,
    struct cl_scan_options *scanoptions);

/**
 * @brief Scan a file, given a file descriptor.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use `cl_scandesc_ex()` instead.
 *
 * This callback variant allows the caller to provide a context structure that
 * caller provided callback functions can interpret.
 *
 * @param desc            File descriptor of an open file. The caller must provide this or the map.
 * @param filename        (optional) Filepath of the open file descriptor or file map.
 * @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.
 * @param[out] scanned    The number of bytes scanned / CL_COUNT_PRECISION.
 * @param engine          The scanning engine.
 * @param scanoptions     Scanning options.
 * @param[in,out] context (Optional) An application-defined context struct, opaque to libclamav.
 *                        May be used within your callback functions.
 * @return cl_error_t     CL_CLEAN, CL_VIRUS, or an error code if an error occurred during the scan.
 */
extern cl_error_t 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);

/**
 * @brief Scan a file, given a file descriptor.
 *
 * This callback variant allows the caller to provide a context structure that
 * caller provided callback functions can interpret.
 *
 * This extended version of cl_scanmap_callback allows the caller to provide
 * additional hints to the scanning engine, such as a file hash and file type.
 *
 * This variant also upgrades the `scanned` output parameter to a 64-bit integer.
 *
 * @param desc               File descriptor of an open file. The caller must provide this or the map.
 * @param filename           (optional) Filepath of the open file descriptor or file map.
 * @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.
 * @param[out] scanned       The (exact) number of bytes scanned.
 * @param engine             The scanning engine.
 * @param scanoptions        Scanning options.
 * @param[in,out] context    (Optional) An application-defined context struct, opaque to libclamav.
 *                           May be used within your callback functions.
 * @param hash_hint          (Optional) A NULL terminated string of the file hash so that
 *                           libclamav does not need to calculate it.
 * @param[out] hash_out      (Optional) A NULL terminated string of the file hash.
 *                           The caller is responsible for freeing the string.
 * @param hash_alg           The hashing algorithm used for either `hash_hint` or `hash_out`.
 *                           Supported algorithms are "md5", "sha1", "sha2-256".
 *                           If not specified, the default is "sha2-256".
 * @param file_type_hint     (Optional) A NULL terminated string of the file type hint.
 *                           E.g. "pe", "elf", "zip", etc.
 *                           You may also use ClamAV type names such as "CL_TYPE_PE".
 *                           ClamAV will ignore the hint if it is not familiar with the specified type.
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @param[out] file_type_out (Optional) A NULL terminated string of the file type
 *                           of the top layer as determined by ClamAV.
 *                           Will take the form of the standard ClamAV file type format. E.g. "CL_TYPE_PE".
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @return cl_error_t        CL_CLEAN if no signature matched.
 *                           CL_VIRUS if a signature matched.
 *                           Another CL_E* error code if an error occurred.
 */
extern cl_error_t cl_scandesc_ex(
    int desc,
    const char *filename,
    const char **virname,
    uint64_t *scanned,
    const struct cl_engine *engine,
    struct cl_scan_options *scanoptions,
    void *context,
    const char *hash_hint,
    char **hash_out,
    const char *hash_alg,
    const char *file_type_hint,
    char **file_type_out);

/**
 * @brief Scan a file, given a filename.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use `cl_scanfile_ex()` instead.
 *
 * @param filename        Filepath of the file to be scanned.
 * @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.
 * @param[out] scanned    The number of bytes scanned / CL_COUNT_PRECISION.
 * @param engine          The scanning engine.
 * @param scanoptions     Scanning options.
 * @return cl_error_t     CL_CLEAN, CL_VIRUS, or an error code if an error occurred during the scan.
 */
extern cl_error_t cl_scanfile(
    const char *filename,
    const char **virname,
    unsigned long int *scanned,
    const struct cl_engine *engine,
    struct cl_scan_options *scanoptions);

/**
 * @brief Scan a file, given a filename.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use `cl_scanfile_ex()` instead.
 *
 * This callback variant allows the caller to provide a context structure that
 * caller provided callback functions can interpret.
 *
 * @param filename        Filepath of the file to be scanned.
 * @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.
 * @param[out] scanned    The number of bytes scanned / CL_COUNT_PRECISION.
 * @param engine          The scanning engine.
 * @param scanoptions     Scanning options.
 * @param[in,out] context (Optional) An application-defined context struct, opaque to libclamav.
 *                        May be used within your callback functions.
 * @return cl_error_t     CL_CLEAN, CL_VIRUS, or an error code if an error occurred during the scan.
 */
extern cl_error_t 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);

/**
 * @brief Scan a file, given a filename.
 *
 * This callback variant allows the caller to provide a context structure that
 * caller provided callback functions can interpret.
 *
 * This extended version of cl_scanmap_callback allows the caller to provide
 * additional hints to the scanning engine, such as a file hash and file type.
 *
 * This variant also upgrades the `scanned` output parameter to a 64-bit integer.
 *
 * @param filename           Filepath of the file to be scanned.
 * @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.
 * @param[out] scanned       The exact number of bytes scanned.
 * @param engine             The scanning engine.
 * @param scanoptions        Scanning options.
 * @param[in,out] context    (Optional) An application-defined context struct, opaque to libclamav.
 *                           May be used within your callback functions.
 * @param hash_hint          (Optional) A NULL terminated string of the file hash so that
 *                           libclamav does not need to calculate it.
 * @param[out] hash_out      (Optional) A NULL terminated string of the file hash.
 *                           The caller is responsible for freeing the string.
 * @param hash_alg           The hashing algorithm used for either `hash_hint` or `hash_out`.
 *                           Supported algorithms are "md5", "sha1", "sha2-256".
 *                           If not specified, the default is "sha2-256".
 * @param file_type_hint     (Optional) A NULL terminated string of the file type hint.
 *                           E.g. "pe", "elf", "zip", etc.
 *                           You may also use ClamAV type names such as "CL_TYPE_PE".
 *                           ClamAV will ignore the hint if it is not familiar with the specified type.
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @param[out] file_type_out (Optional) A NULL terminated string of the file type
 *                           of the top layer as determined by ClamAV.
 *                           Will take the form of the standard ClamAV file type format. E.g. "CL_TYPE_PE".
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @return cl_error_t        CL_CLEAN if no signature matched.
 *                           CL_VIRUS if a signature matched.
 *                           Another CL_E* error code if an error occurred.
 */
extern cl_error_t cl_scanfile_ex(
    const char *filename,
    const char **virname,
    uint64_t *scanned,
    const struct cl_engine *engine,
    struct cl_scan_options *scanoptions,
    void *context,
    const char *hash_hint,
    char **hash_out,
    const char *hash_alg,
    const char *file_type_hint,
    char **file_type_out);

/**
 * @brief Scan custom data, given a fmap.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use `cl_scanmap_ex()` instead.
 *
 * Fmaps are an abstraction representing a file or memory buffer.
 *
 * Create one using:
 * - `cl_fmap_open_handle()` for a file handle, or
 * - `cl_fmap_open_memory()` for a memory buffer.
 *
 * After the scan, you can also get the file hash with `cl_fmap_get_file_hash()`.
 *
 * @param map           Buffer to be scanned, in form of a cl_fmap_t.
 * @param filename      Name of data origin. Does not need to be an actual
 *                      file on disk. May be NULL if a name is not available.
 * @param[out] virname  Pointer to receive the signature match name name if a
 *                      signature matched.
 * @param[out] scanned  Number of bytes scanned / CL_COUNT_PRECISION.
 * @param engine        The scanning engine.
 * @param scanoptions   The scanning options struct.
 * @param context       An application-defined context struct, opaque to
 *                      libclamav. May be used within your callback functions.
 * @return cl_error_t   CL_CLEAN if no signature matched. CL_VIRUS if a
 *                      signature matched. Another CL_E* error code if an
 *                      error occurred.
 */
extern cl_error_t 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);

/**
 * @brief Scan custom data, given a map.
 *
 * Fmaps are an abstraction representing a file or memory buffer.
 *
 * Create one using:
 * - `cl_fmap_open_handle()` for a file handle, or
 * - `cl_fmap_open_memory()` for a memory buffer.
 *
 * After the scan, you can also get the file hash with `cl_fmap_get_file_hash()`.
 *
 * This extended version of cl_scanmap_callback allows the caller to provide
 * additional hints to the scanning engine, such as a file hash and file type.
 *
 * This variant also upgrades the `scanned` output parameter to a 64-bit integer.
 *
 * @param map                Buffer to be scanned, in form of a cl_fmap_t.
 * @param filename           Name of data origin. Does not need to be an actual
 *                           file on disk. May be NULL if a name is not available.
 * @param[out] virname       Pointer to receive the signature match name name if a
 *                           signature matched.
 * @param[out] scanned       The exact number of bytes scanned.
 * @param engine             The scanning engine.
 * @param scanoptions        The scanning options struct.
 * @param[in,out] context    (Optional) An application-defined context struct, opaque to libclamav.
 *                           May be used within your callback functions.
 * @param hash_hint          (Optional) A NULL terminated string of the file hash so that
 *                           libclamav does not need to calculate it.
 * @param[out] hash_out      (Optional) A NULL terminated string of the file hash.
 *                           The caller is responsible for freeing the string.
 * @param hash_alg           The hashing algorithm used for either `hash_hint` or `hash_out`.
 *                           Supported algorithms are "md5", "sha1", "sha2-256".
 *                           If not specified, the default is "sha2-256".
 * @param file_type_hint     (Optional) A NULL terminated string of the file type hint.
 *                           E.g. "pe", "elf", "zip", etc.
 *                           You may also use ClamAV type names such as "CL_TYPE_PE".
 *                           ClamAV will ignore the hint if it is not familiar with the specified type.
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @param[out] file_type_out (Optional) A NULL terminated string of the file type
 *                           of the top layer as determined by ClamAV.
 *                           Will take the form of the standard ClamAV file type format. E.g. "CL_TYPE_PE".
 *                           See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
 * @return cl_error_t        CL_CLEAN if no signature matched.
 *                           CL_VIRUS if a signature matched.
 *                           Another CL_E* error code if an error occurred.
 */
extern cl_error_t cl_scanmap_ex(
    cl_fmap_t *map,
    const char *filename,
    const char **virname,
    uint64_t *scanned,
    const struct cl_engine *engine,
    struct cl_scan_options *scanoptions,
    void *context,
    const char *hash_hint,
    char **hash_out,
    const char *hash_alg,
    const char *file_type_hint,
    char **file_type_out);

/* ----------------------------------------------------------------------------
 * Database handling.
 */

/**
 * @brief Load the signature databases found at the path.
 *
 * @param path          May be a file or directory.
 * @param engine        The engine to load the signatures into
 * @param[out] signo    The number of signatures loaded
 * @param dboptions     Database load bitflag field. See the CL_DB_* defines, above.
 * @return cl_error_t
 */
extern cl_error_t cl_load(const char *path, struct cl_engine *engine, unsigned int *signo, unsigned int dboptions);

/**
 * @brief Get the default database directory path.
 *
 * @return const char*
 */
extern const char *cl_retdbdir(void);

/* ----------------------------------------------------------------------------
 * CVD / database functions
 */

struct cl_cvd {           /* field no. */
    char *time;           /* 2 */
    unsigned int version; /* 3 */
    unsigned int sigs;    /* 4 */
    unsigned int fl;      /* 5 */
                          /* padding */
    char *md5;            /* 6 */
    char *dsig;           /* 7 */
    char *builder;        /* 8 */
    unsigned int stime;   /* 9 */
};

/**
 * @brief Read the CVD header data from a file.
 *
 * The returned pointer must be free'd with cl_cvdfree().
 *
 * @param file              Filepath of CVD file.
 * @return struct cl_cvd*   Pointer to an allocated CVD header data structure.
 */
extern struct cl_cvd *cl_cvdhead(const char *file);

/**
 * @brief Parse the CVD header.
 *
 * Buffer length is not an argument, and the check must be done
 * by the caller cl_cvdhead().
 *
 * The returned pointer must be free'd with cl_cvdfree().
 *
 * @param head              Pointer to the header data buffer.
 * @return struct cl_cvd*   Pointer to an allocated CVD header data structure.
 */
extern struct cl_cvd *cl_cvdparse(const char *head);

/**
 * @brief Verify a CVD file by loading and unloading it.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use cl_cvdverify_ex() instead.
 *
 * @param file          Filepath of CVD file.
 * @return cl_error_t   CL_SUCCESS if success, else a CL_E* error code.
 */
extern cl_error_t cl_cvdverify(const char *file);

/**
 * @brief Verify a CVD file by loading and unloading it.
 *
 * May also verify the CVD digital signature.
 *
 * @param file              Filepath of CVD file.
 * @param certs_directory   Directory containing CA certificates required to verify the CVD digital signature.
 * @param dboptions         Bitmask of flags to modify behavior.
 *                          Set CL_DB_FIPS_LIMITS to require the CVD to be signed with a FIPS-compliant external '.sign' file.
 *                          Set CL_DB_UNSIGNED to disable verification of CVD digital signatures. Allow load testing unsigned CVD files.
 * @return cl_error_t       CL_SUCCESS if success, else a CL_E* error code.
 */
extern cl_error_t cl_cvdverify_ex(const char *file, const char *certs_directory, uint32_t dboptions);

/**
 * @brief Free a CVD header struct.
 *
 * @param cvd   Pointer to a CVD header struct.
 */
extern void cl_cvdfree(struct cl_cvd *cvd);

/**
 * @brief Unpack a CVD file.
 *
 * @deprecated This function is deprecated and will be removed in a future release. Use cl_cvdunpack_ex() instead.
 *
 * Will verify the CVD is correctly signed unless the `dont_verify` parameter is true.
 *
 * This function is deprecated. Use cl_cvdunpack_ex() instead.
 *
 * @param file          Filepath of CVD file.
 * @param dir           Destination directory.
 * @param dont_verify   If true, don't verify the CVD.
 * @return cl_error_t   CL_SUCCESS if success, else a CL_E* error code.
 */
extern cl_error_t cl_cvdunpack(const char *file, const char *dir, bool dont_verify);

/**
 * @brief Unpack a CVD file.
 *
 * Will verify the CVD is correctly signed unless the `dont_verify` parameter is true.
 *
 * @param file              Filepath of CVD file.
 * @param dir               Destination directory.
 * @param certs_directory   Path where ClamAV public certs are located, needed to verify external digital signatures.
 * @param dboptions         Bitmask of flags to modify behavior.
 *                          Set CL_DB_FIPS_LIMITS to require the CVD to be signed with a FIPS-compliant external '.sign' file.
 *                          Set CL_DB_UNSIGNED to disable verification of CVD digital signatures. Allow load testing unsigned CVD files.
 * @return cl_error_t       CL_SUCCESS if success, else a CL_E* error code.
 */
cl_error_t cl_cvdunpack_ex(const char *file, const char *dir, const char *certs_directory, uint32_t dboptions);

/**
 * @brief Retrieve the age of CVD disk data.
 *
 * Will retrieve the age of the youngest file in a database directory,
 * or the age of a single CVD (or CLD) file.
 *
 * @param path          Filepath of CVD directory or file.
 * @param age_seconds   Age of the directory or file.
 * @return cl_error_t   CL_SUCCESS if success, else a CL_E* error code.
 */
extern cl_error_t cl_cvdgetage(const char *path, time_t *age_seconds);

/* ----------------------------------------------------------------------------
 * DB directory stat functions.
 * Use these functions to watch for database changes.
 */

struct cl_stat {
    char *dir;
    STATBUF *stattab;
    char **statdname;
    unsigned int entries;
};

/**
 * @brief Initialize a directory to be watched for database changes.
 *
 * The dbstat out variable is allocated and must be freed using cl_statfree().
 *
 * @param dirname       Pathname of the database directory.
 * @param[out] dbstat   dbstat handle.
 * @return cl_error_t   CL_SUCCESS if successfully initialized.
 */
extern cl_error_t cl_statinidir(const char *dirname, struct cl_stat *dbstat);

/**
 * @brief Check the database directory for changes.
 *
 * @param dbstat dbstat handle.
 * @return int   0 No change.
 * @return int   1 Some change occurred.
 */
extern int cl_statchkdir(const struct cl_stat *dbstat);

/**
 * @brief Free the dbstat handle.
 *
 * @param dbstat        dbstat handle.
 * @return cl_error_t   CL_SUCCESS
 * @return cl_error_t   CL_ENULLARG
 */
extern cl_error_t cl_statfree(struct cl_stat *dbstat);

/**
 * @brief Count the number of signatures in a database file or directory.
 *
 * @param path          Path of the database file or directory.
 * @param countoptions  A bitflag field. May be CL_COUNTSIGS_OFFICIAL, CL_COUNTSIGS_UNOFFICIAL, or CL_COUNTSIGS_ALL.
 * @param[out] sigs     The number of sigs.
 * @return cl_error_t   CL_SUCCESS if success, else a CL_E* error type.
 */
extern cl_error_t cl_countsigs(const char *path, unsigned int countoptions, unsigned int *sigs);

/* ----------------------------------------------------------------------------
 * Software versions.
 */

/**
 * @brief Get the Functionality Level (FLEVEL).
 *
 * @return unsigned int The FLEVEL.
 */
extern unsigned int cl_retflevel(void);

/**
 * @brief Get the ClamAV version string.
 *
 * E.g. clamav-0.100.0-beta
 *
 * @return const char* The version string.
 */
extern const char *cl_retver(void);

/* ----------------------------------------------------------------------------
 * Others.
 */
extern const char *cl_strerror(cl_error_t clerror);

/* ----------------------------------------------------------------------------
 * Hashing functions.
 */
#define MD5_HASH_SIZE 16
#define SHA1_HASH_SIZE 20
#define SHA256_HASH_SIZE 32
#define SHA384_HASH_SIZE 48
#define SHA512_HASH_SIZE 64

#define CL_HASH_FLAG_NONE 0x00        /* None */
#define CL_HASH_FLAG_ALLOCATE 0x01    /* Use CL_HASH_FLAG_ALLOCATE to dynamically allocate the output buffer.                 \
                                       * If this flag is set, the function will allocate a buffer for the hash and return it. \
                                       * The caller is responsible for freeing the buffer using free().                       \
                                       * If this flag is not set, the caller must provide a buffer to store the hash. */
#define CL_HASH_FLAG_FIPS_BYPASS 0x02 /* Use CL_HASH_FLAG_FIPS_BYPASS to bypass FIPS restrictions on which algorithms can be \
                                       * used. This is useful if you want to use algorithms that are not FIPS-approved.      \
                                       * For example, you might want to use this flag if you want to use "md5" or "sha1".    \
                                       * You should only do this when the hash is used for non-cryptographic purposes.       \
                                       * Note: If OpenSSL's FIPS provider is not available, this flag has no effect. */

/**
 * @brief Generate a hash of data.
 *
 * @param alg               The hashing algorithm to use.
 *                          Suggested "alg" names include "md5", "sha1", "sha2-256", "sha2-384", and "sha2-512".
 *                          But the underlying hashing library is OpenSSL and you might be able to use
 *                          other algorithms supported by OpenSSL's EVP_get_digestbyname() function.
 *                          Note: For the `cl_scan*` functions (above) the supported algorithms are
 *                                presently limited to "md5", "sha1", "sha2-256".
 * @param data              The data to be hashed.
 * @param data_len          The length of the to-be-hashed data.
 * @param[inout] hash       A buffer to store the generated hash.
 *                          Set flags to CL_HASH_FLAG_ALLOCATE to dynamically allocate buffer.
 * @param[inout] hash_len   If providing a buffer, set this to the size of the buffer.
 *                          If allocating, this is purely an output parameter and need not be initialized.
 * @param flags             Flags to modify the behavior of the hashing function.
 *                          Use CL_HASH_FLAG_ALLOCATE to dynamically allocate the output buffer.
 *                          Use CL_HASH_FLAG_FIPS_BYPASS to bypass FIPS restrictions on which algorithms can be used.
 *
 * @return cl_error_t       CL_SUCCESS if the hash was generated successfully.
 *                          CL_E* error code if an error occurred.
 */
extern cl_error_t cl_hash_data_ex(
    const char *alg,
    const uint8_t *data,
    size_t data_len,
    uint8_t **hash,
    size_t *hash_len,
    uint32_t flags);

struct cl_hash_ctx;
typedef struct cl_hash_ctx cl_hash_ctx_t;

/**
 * @brief Initialize a hash context.
 *
 * @param alg               The hash algorithm to use.
 * @param flags             Flags to modify the behavior of the hashing function.
 *                          Use CL_HASH_FLAG_FIPS_BYPASS to bypass FIPS restrictions on which algorithms can be used.
 * @return cl_error_t       CL_SUCCESS if the hash context was successfully initialized.
 */
extern cl_error_t cl_hash_init_ex(
    const char *alg,
    uint32_t flags,
    cl_hash_ctx_t **ctx_out);

/**
 * @brief Update a hash context with new data.
 *
 * @param ctx               The hash context.
 * @param data              The data to hash.
 * @param length            The size of the data.
 * @return cl_error_t       CL_SUCCESS if the data was successfully added to the hash context.
 *                          CL_E* error code if an error occurred.
 */
extern cl_error_t cl_update_hash_ex(
    cl_hash_ctx_t *ctx,
    const uint8_t *data,
    size_t length);

/**
 * @brief Finalize a hash context and get the resulting hash.
 *
 * @param ctx               The hash context.
 * @param[inout] hash       A buffer to store the generated hash.
 *                          Set flags to CL_HASH_FLAG_ALLOCATE to dynamically allocate buffer.
 * @param[inout] hash_len   If providing a buffer, set this to the size of the buffer.
 *                          If allocating, this is purely an output parameter and need not be initialized.
 * @param flags             Flags to modify the behavior of the hashing function.
 *                          Use CL_HASH_FLAG_ALLOCATE to dynamically allocate the output buffer.
 *
 * @return cl_error_t       CL_SUCCESS if the hash was successfully finalized.
 *                          CL_E* error code if an error occurred.
 */
extern cl_error_t cl_finish_hash_ex(
    cl_hash_ctx_t *ctx,
    uint8_t **hash,
    size_t *hash_len,
    uint32_t flags);

/**
 * @brief Destroy a hash context.
 *
 * @param ctx   The hash context.
 */
extern void cl_hash_destroy_ex(cl_hash_ctx_t *ctx);

/**
 * @brief Generate a hash of a file.
 *
 * @param alg               The hashing algorithm to use.
 * @param fd                The file descriptor.
 * @param offset            The offset in the file to start hashing from.
 * @param length            The length of the data to hash. If 0, the entire file will be hashed.
 * @param[inout] hash       A buffer to store the generated hash.
 *                          Set flags to CL_HASH_FLAG_ALLOCATE to dynamically allocate buffer.
 * @param[inout] hash_len   A pointer that stores how long the generated hash is.
 * @param flags             Flags to modify the behavior of the hashing function.
 *                          Use CL_HASH_FLAG_ALLOCATE to dynamically allocate the output buffer.
 *                          Use CL_HASH_FLAG_FIPS_BYPASS to bypass FIPS restrictions on which algorithms can be used.
 *
 * @return cl_error_t       CL_SUCCESS if the hash was generated successfully.
 */
extern cl_error_t cl_hash_file_fd_ex(
    const char *alg,
    int fd,
    size_t offset,
    size_t length,
    uint8_t **hash,
    size_t *hash_len,
    uint32_t flags);

/**
 * @brief Generate a hash of data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_data_ex()` instead.
 *
 * Note: This function intentionally bypasses FIPS restrictions on which algorithms can be used.
 * Do not use this function for cryptographic purposes or for false positive hash checks.
 *
 * @param alg       The hashing algorithm to use.
 * @param buf       The data to be hashed.
 * @param len       The length of the to-be-hashed data.
 * @param[out] obuf (optional) A buffer to store the generated hash. Use NULL to dynamically allocate buffer.
 *                  If providing, use the *_HASH_SIZE macros above to determine the required buffer size.
 * @param[out] olen (optional) A pointer that stores how long the generated hash is.
 *                  This is purely an output parameter and need not be initialized.
 * @return          A pointer to the generated hash or obuf if obuf is not NULL.
 */
extern unsigned char *cl_hash_data(const char *alg, const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);

/**
 * @brief Generate a hash of a file given a file descriptor.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Note: there is no `cl_hash_file_fd_ctx_ex()` function. Use `cl_hash_file_fd_ex()` instead.
 *
 * @param ctx       A pointer to the OpenSSL EVP_MD_CTX object.
 * @param fd        The file descriptor.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_hash_file_fd_ctx(EVP_MD_CTX *ctx, int fd, unsigned int *olen);

/**
 * @brief Generate a hash of a file given a file descriptor.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_file_fd_ex()` instead.
 *
 * Note: This function intentionally bypasses FIPS restrictions on which algorithms can be used.
 * Do not use this function for cryptographic purposes or for false positive hash checks.
 *
 * @param fd        The file descriptor.
 * @param alg       The hashing algorithm to use.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_hash_file_fd(int fd, const char *alg, unsigned int *olen);

/**
 * @brief Generate a hash of a file given a FILE pointer.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Note: There is no `cl_hash_file_fp_ex()` function. Use `cl_hash_file_fd_ex()` instead.
 *
 * Note: This function intentionally bypasses FIPS restrictions on which algorithms can be used.
 * Do not use this function for cryptographic purposes or for false positive hash checks.
 *
 * @param fp        A pointer to a FILE object.
 * @param alg       The hashing algorithm to use.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_hash_file_fp(FILE *fp, const char *alg, unsigned int *olen);

/**
 * @brief Generate a sha2-256 hash of data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_data_ex()` instead.
 *
 * @param buf       The data to hash.
 * @param len       The length of the to-be-hashed data.
 * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_sha256(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);

/**
 * @brief Generate a sha2-384 hash of data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_data_ex()` instead.
 *
 * @param buf       The data to hash.
 * @param len       The length of the to-be-hashed data.
 * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_sha384(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);

/**
 * @brief Generate a sha2-512 hash of data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_data_ex()` instead.
 *
 * @param buf       The data to hash.
 * @param len       The length of the to-be-hashed data.
 * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_sha512(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);

/**
 * @brief Generate a sha1 hash of data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_data_ex()` instead.
 *
 * Note: This function intentionally bypasses FIPS restrictions on which algorithms can be used.
 * Do not use this function for cryptographic purposes or for false positive hash checks.
 *
 * @param buf       The data to hash.
 * @param len       The length of the to-be-hashed data.
 * @param[out] obuf (optional) A pointer to store the generated hash. Use NULL to dynamically allocate buffer.
 * @param[out] olen (optional) The length of the generated hash.
 * @return          A pointer to a malloc'd buffer that holds the generated hash.
 */
extern unsigned char *cl_sha1(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);

/**
 * @brief Initialize a hash context.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_init_ex()` instead.
 *
 * Note: This function intentionally bypasses FIPS restrictions on which algorithms can be used.
 * Do not use this function for cryptographic purposes or for false positive hash checks.
 *
 * @param alg       The hash algorithm to use.
 * @return void*
 */
extern void *cl_hash_init(const char *alg);

/**
 * @brief Update a hash context with new data.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_update_hash_ex()` instead.
 *
 * @param ctx       The hash context.
 * @param data      The data to hash.
 * @param sz        The size of the data.
 * @return int      0 on success, -1 on error.
 */
extern int cl_update_hash(void *ctx, const void *data, size_t sz);

/**
 * @brief Finalize a hash context and get the resulting hash.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_finish_hash_ex()` instead.
 *
 * @param ctx       The hash context.
 * @param buf       A buffer to store the resulting hash. Must be large enough to hold the hash.
 * @return int      0 on success, -1 on error.
 */
extern int cl_finish_hash(void *ctx, void *buf);

/**
 * @brief Destroy a hash context.
 *
 * @deprecated This function is deprecated and will be removed in a future release.
 * Use `cl_hash_destroy_ex()` instead.
 *
 * @param ctx   The hash context.
 */
extern void cl_hash_destroy(void *ctx);

/* -------------------------------------------------------------------------------
 * Signing and verification functions.
 */

/**
 * @brief Verify validity of signed data.
 *
 * @param pkey      The public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param data      The data that was signed.
 * @param datalen   The length of the data.
 * @param decode    Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature(
    EVP_PKEY *pkey,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    unsigned char *data,
    size_t datalen,
    int decode);

/**
 * @brief Verify validity of signed data.
 *
 * @param pkey      The public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param digest    The hash of the signed data.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_hash(
    EVP_PKEY *pkey,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    unsigned char *digest);

/**
 * @brief Verify validity of signed data.
 *
 * @param pkey      The public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param fd        The file descriptor.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_fd(
    EVP_PKEY *pkey,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    int fd);

/**
 * @brief Verify validity of signed data.
 *
 * @param x509path  The path to the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param digest    The hash of the signed data.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_hash_x509_keyfile(
    char *x509path,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    unsigned char *digest);

/**
 * @brief Verify validity of signed data.
 *
 * @param x509path  The path to the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param fd        The file descriptor.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_fd_x509_keyfile(
    char *x509path,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    int fd);

/**
 * @brief Verify validity of signed data.
 *
 * @param x509path  The path to the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param data      The data that was signed.
 * @param datalen   The length of the data.
 * @param decode    Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern 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);

/**
 * @brief Verify validity of signed data
 *
 * @param x509      The X509 object of the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param digest    The hash of the signed data.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_hash_x509(
    X509 *x509,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    unsigned char *digest);

/**
 * @brief Verify validity of signed data.
 *
 * @param x509      The X509 object of the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param fd        The file descriptor.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_fd_x509(X509 *x509, const char *alg, unsigned char *sig, unsigned int siglen, int fd);

/**
 * @brief Verify validity of signed data.
 *
 * @param x509      The X509 object of the public key of the keypair that signed the data.
 * @param alg       The algorithm used to hash the data.
 * @param sig       The signature block.
 * @param siglen    The length of the signature.
 * @param data      The data that was signed.
 * @param datalen   The length of the data.
 * @param decode    Whether or not to base64-decode the signature prior to verification. 1 for yes, 0 for no.
 * @return          0 for success, -1 for error or invalid signature.
 */
extern int cl_verify_signature_x509(
    X509 *x509,
    const char *alg,
    unsigned char *sig,
    unsigned int siglen,
    unsigned char *data,
    size_t datalen,
    int decode);

/**
 * @brief Get an X509 object from memory.
 *
 * @param data      A pointer to a spot in memory that contains the PEM X509 cert.
 * @param len       The length of the data.
 * @return          A pointer to the X509 object on success, NULL on error.
 */
extern X509 *cl_get_x509_from_mem(void *data, unsigned int len);

/**
 * @brief Validate an X509 certificate chain, with the chain being located in a directory.
 *
 * @param tsdir     The path to the trust store directory.
 * @param certpath  The path to the X509 certificate to be validated.
 * @return          0 for success, -1 for error or invalid certificate.
 */
extern int cl_validate_certificate_chain_ts_dir(char *tsdir, char *certpath);

/**
 * @brief Validate an X509 certificate chain with support for a CRL.
 *
 * @param authorities   A NULL-terminated array of strings that hold the path of the CA's X509 certificate.
 * @param crlpath       (optional) A path to the CRL file. NULL if no CRL.
 * @param certpath      The path to the X509 certificate to be validated.
 * @return              0 for success, -1 for error or invalid certificate.
 */
extern int cl_validate_certificate_chain(char **authorities, char *crlpath, char *certpath);

/**
 * @brief Load an X509 certificate from a file.
 *
 * @param certpath  The path to the X509 certificate.
 */
extern X509 *cl_load_cert(const char *certpath);

/**
 * @brief Parse an ASN1_TIME object.
 *
 * @param timeobj   The ASN1_TIME object.
 * @return          A pointer to a (struct tm). Adjusted for time zone and daylight savings time.
 */
extern struct tm *cl_ASN1_GetTimeT(ASN1_TIME *timeobj);

/**
 * @brief Load a CRL file into an X509_CRL object.
 *
 * @param file  The path to the CRL.
 * @return      A pointer to an X509_CRL object or NULL on error.
 */
extern X509_CRL *cl_load_crl(const char *timeobj);

/**
 * @brief Sign data with a key stored on disk.
 *
 * @param keypath   The path to the RSA private key.
 * @param alg       The hash/signature algorithm to use.
 * @param hash      The hash to sign.
 * @param[out] olen A pointer that stores the size of the signature.
 * @param           Whether or not to base64-encode the signature. 1 for yes, 0 for no.
 * @return          The generated signature.
 */
extern unsigned char *cl_sign_data_keyfile(
    char *keypath,
    const char *alg,
    unsigned char *hash,
    unsigned int *olen,
    int encode);

/**
 * @brief Sign data with an RSA private key object.
 *
 * @param pkey      The RSA private key object.
 * @param alg       The hash/signature algorithm to use.
 * @param hash      The hash to sign.
 * @param[out] olen A pointer that stores the size of the signature.
 * @param           Whether or not to base64-encode the signature. 1 for yes, 0 for no.
 * @return          The generated signature.
 */
extern unsigned char *cl_sign_data(EVP_PKEY *pkey, const char *alg, unsigned char *hash, unsigned int *olen, int encode);

/**
 * @brief Sign a file with an RSA private key object.
 *
 * @param fd        The file descriptor.
 * @param pkey      The RSA private key object.
 * @param alg       The hash/signature algorithm to use.
 * @param[out] olen A pointer that stores the size of the signature.
 * @param encode    Whether or not to base64-encode the signature. 1 for yes, 0 for no.
 * @return          The generated signature.
 */
extern unsigned char *cl_sign_file_fd(int fd, EVP_PKEY *pkey, const char *alg, unsigned int *olen, int encode);

/**
 * @brief Sign a file with an RSA private key object.
 *
 * @param fp        A pointer to a FILE object.
 * @param pkey      The RSA private key object.
 * @param alg       The hash/signature algorithm to use.
 * @param[out] olen A pointer that stores the size of the signature.
 * @param encode    Whether or not to base64-encode the signature. 1 for yes, 0 for no.
 * @return          The generated signature.
 */
extern unsigned char *cl_sign_file_fp(FILE *fp, EVP_PKEY *pkey, const char *alg, unsigned int *olen, int encode);

/**
 * @brief Get the Private Key stored on disk.
 *
 * @param keypath   The path on disk where the private key is stored.
 * @return          A pointer to the EVP_PKEY object that contains the private key in memory.
 */
extern EVP_PKEY *cl_get_pkey_file(char *keypath);

#ifdef __cplusplus
}
#endif

#endif /* __CLAMAV_H */