aixiao/denyhosts
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity
master
denyhosts/clamav/libclamav/clamav.h

1630 lines
63 KiB
C
Raw Permalink Blame History

/*
* Copyright (C) 2013-2022 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
#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 */
/* c4w error codes */
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 /* 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
/* 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. */
/* 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
/* 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 /* Enables hash output in sha-collect builds - for internal use only */
#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
// 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 This is a deprecated function that used to clean up ssl crypto inits.
*
* 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 initalized correctly.
*/
extern cl_error_t cl_init(unsigned int initoptions);
/**
* @brief Allocate a new scanning engine and initialize default settings.
*
* The engine should 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_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 */
};
enum bytecode_security {
CL_BYTECODE_TRUST_ALL = 0, /* 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);
/* ----------------------------------------------------------------------------
* Callback function type definitions.
*/
/**
* @brief Pre-cache callback.
*
* 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.
*
* 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);
/*
* Attributes of each layer in scan.
*/
#define LAYER_ATTRIBUTES_NONE 0x0
#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. I.e. had to decrypt some previous layer. */
/**
* @brief File inspection callback.
*
* DISCLAIMER: This interface is to be considered unstable while we continue to evaluate it.
* We may change this interface in the future.
*
* 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.
*
* 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.
*
* Called for each NEW file (inner and outer) before the scanning takes place. This is
* roughly the 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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
* @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 unsigned char *md5, const char *virname, void *context);
/**
* @brief Set a custom hash stats 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_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);
/* ----------------------------------------------------------------------------
* 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.
*
* @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.
* @param engine The scanning engine.
* @param scanoptions Scanning options.
* @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured 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.
*
* 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.
* @param engine The scanning engine.
* @param scanoptions Scanning options.
* @param[in,out] context An opaque context structure allowing the caller to record details about the sample being scanned.
* @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured 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 filename.
*
* @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.
* @param engine The scanning engine.
* @param scanoptions Scanning options.
* @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured 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.
*
* 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.
* @param engine The scanning engine.
* @param scanoptions Scanning options.
* @param[in,out] context An opaque context structure allowing the caller to record details about the sample being scanned.
* @return cl_error_t CL_CLEAN, CL_VIRUS, or an error code if an error occured 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);
/* ----------------------------------------------------------------------------
* 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.
*
* @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 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.
*
* 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 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);
/* ----------------------------------------------------------------------------
* 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 occured.
*/
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);
/* ----------------------------------------------------------------------------
* Custom data scanning.
*/
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 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.
*
* @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 Releases resources associated with the map.
*
* You should 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 *);
/**
* @brief Scan custom data.
*
* @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.
* @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 occured.
*/
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);
/* ----------------------------------------------------------------------------
* Crypto/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
/**
* @brief Generate a hash of data.
*
* @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.
* @param[out] olen (optional) A pointer that stores how long the generated hash is.
* @return A pointer to the generated hash or obuf if obuf is not NULL.
*/
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.
*
* @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.
*/
unsigned char *cl_hash_file_fd_ctx(EVP_MD_CTX *ctx, int fd, unsigned int *olen);
/**
* @brief Generate a hash of a file.
*
* @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.
*/
unsigned char *cl_hash_file_fd(int fd, const char *alg, unsigned int *olen);
/**
* @brief Generate a hash of a file.
*
* @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.
*/
unsigned char *cl_hash_file_fp(FILE *fp, const char *alg, unsigned int *olen);
/**
* @brief Generate a sha256 hash of data.
*
* @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.
*/
unsigned char *cl_sha256(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
/**
* @brief Generate a sha384 hash of data.
*
* @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.
*/
unsigned char *cl_sha384(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
/**
* @brief Generate a sha512 hash of data.
*
* @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.
*/
unsigned char *cl_sha512(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
/**
* @brief Generate a sha1 hash of data.
*
* @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.
*/
unsigned char *cl_sha1(const void *buf, size_t len, unsigned char *obuf, unsigned int *olen);
/**
* @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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
EVP_PKEY *cl_get_pkey_file(char *keypath);
void *cl_hash_init(const char *alg);
int cl_update_hash(void *ctx, const void *data, size_t sz);
int cl_finish_hash(void *ctx, void *buf);
void cl_hash_destroy(void *ctx);
#ifdef __cplusplus
}
#endif
#endif /* __CLAMAV_H */
Reference in New Issue View Git Blame Copy Permalink