/* * Copyright (C) 2010 Sourcefire, Inc. * Authors: aCaB * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License version 2.1 as published by the Free Software Foundation. * * This library 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 * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 * USA */ #ifndef _CLSCANAPI_H #define _CLSCANAPI_H /************************************************************************************** CLAMAPI interface ***************************************************************************************/ /* CLAMAPI calling convention. Please do not touch */ #ifndef CALL_CONVENTION #define CALL_CONVENTION __cdecl #endif #ifndef CLAMAPI #define CLAMAPI #endif /* CLAMAPI - return codes */ /* Always check for the return value of CLAMAPI's * Possible values are: * - return_value == CLAMAPI_SUCCESS: API succeded * - return_value != CLAMAPI_SUCCESS: API failed (call Scan_GetErrorMsg(return_value) to retrieve the error message) */ #define CLAMAPI_SUCCESS 0 /* CLAMAPI LIMITS */ /* List of limits configurable via Scan_SetLimit and readable via Scan_GetLimit (see below) */ enum CLAM_LIMIT_TYPE { CLAM_LIMIT_FILESIZE, CLAM_LIMIT_SCANSIZE, CLAM_LIMIT_RECURSION }; /* CLAMAPI SCAN OPTIONS */ /* List of options settable via Scan_SetOption and retrievable via Scan_GetOption (see below) * All the options have a corresponding unsigned int value (0 = option disabled / non 0 = option enabled) */ enum CLAM_SCAN_OPTIONS { CLAM_OPTION_SCAN_ARCHIVE, /* Enable/disable scanning of archive files (zip, arj, rar, cab, etc.) */ CLAM_OPTION_SCAN_MAIL, /* Enable/disable scanning of archive mail files (mbox, eml) */ CLAM_OPTION_SCAN_OLE2, /* Enable/disable scanning of OLE2 files (mostly msi and doc) */ CLAM_OPTION_SCAN_HTML, /* Enable/disable scanning of html files */ CLAM_OPTION_SCAN_PE, /* Enable/disable scanning of archive PE (aka windows) executables */ CLAM_OPTION_SCAN_ALGORITHMIC, /* Enable/disable scanning for certain viruses and exploits */ CLAM_OPTION_SCAN_ELF, /* Enable/disable scanning of archive ELF (aka linux) executables */ /* FIXME: is this needed */ CLAM_OPTION_SCAN_PDF, /* Enable/disable scanning of Adobe PDF files */ CLAM_OPTION_SCAN_SWF /* Enable/disable scanning of Adobe Flash files */ }; /* NOTE: by default (i.e. before calling Scan_SetOption) ALL the options are ENABLED! */ /* CLAMAPI SCAN PHASES */ /* Define the scan phase to which the returned results refer to */ typedef enum _CLAM_SCAN_PHASE { SCAN_PHASE_INITIAL, /* Right before ClamAV starts scanning the entry (outer) file - in scan callback mode only */ SCAN_PHASE_PRESCAN, /* Right before ClamAV starts scanning the current file - in scan callback mode only */ SCAN_PHASE_POSTSCAN, /* After ClamAV has scanned the current file - in scan callback mode only */ SCAN_PHASE_FINAL /* After ClamAV has scanned the entry (outer) file (callback) and upon returning from ScanObject */ } CLAM_SCAN_PHASE; /* CLAMAPI SCAN RESULT VALUES */ /* Value returned by ScanObject */ #define CLAM_CLEAN 0 #define CLAM_INFECTED 1 /* CLAMAPI RESULT DEFINITIONS */ /* The CLAM_SCAN_INFO structure is used: * - to return scan results * - to pass progress data and results to the scan callback */ typedef struct _CLAM_SCAN_INFO { /** The size of this structure: to be set to sizeof(CLAM_SCAN_INFO) **/ /* Presence: ALWAYS */ int cbSize; /** A single field that can store information regarding packers, installers, compound objects etc **/ int flags; /** The phase to which the results refer to **/ /* Presence: ALWAYS */ CLAM_SCAN_PHASE scanPhase; /** Error condition **/ /* Possible values: CLAMAPI_SUCCESS if no error; call Scan_GetErrorMsg(errorCode) * to retrieve the error message */ /* Presence: ALWAYS */ int errorCode; /** The type of threat (e.g. "Adware", "Trojan", etc.) **/ /* For clean files this is set to NULL */ /* Presence: SCAN_PHASE_POSTSCAN, SCAN_PHASE_FINAL */ const wchar_t *pThreatType; /** The name of threat (i.e. virus name) **/ /* For clean files this is set to NULL */ /* Presence: SCAN_PHASE_POSTSCAN, SCAN_PHASE_FINAL */ const wchar_t *pThreatName; /** The handle of the file being processed **/ /* Note #1: the handle MUST BE CLOSED by the caller, at any point * Note #2: the has FILE_ATTRIBUTE_TEMPORARY and FILE_FLAG_DELETE_ON_CLOSE attributes * Note #3: the file pointer is guaranteed to be set at the begin of * the file and its position needs not to be reset */ /* Presence: SCAN_PHASE_PRESCAN, SCAN_PHASE_POSTSCAN */ HANDLE object; /** An unique identifier for the file being processed **/ /* Provided for mapping purposes (type HANDLE for legacy reasons) */ /* Presence: SCAN_PHASE_PRESCAN, SCAN_PHASE_POSTSCAN */ HANDLE objectId; /** The path of inner file relative to file being scanned **/ /* This applies only to archive for which internal names can be retrieved and is NULL otherwise */ /* Presence: ALWAYS */ const wchar_t *pInnerObjectPath; /** File type **/ /* Presence; SCAN_PHASE_PRESCAN */ _int64 filetype[2]; } CLAM_SCAN_INFO, *PCLAM_SCAN_INFO; /* NOTE: all the objects within the above structure are guaranteed to be available and * valid until the callback returns (SCAN_PHASE_PRESCAN and SCAN_PHASE_POSTSCAN) or * Scan_DeleteScanInfo is called (SCAN_PHASE_FINAL) */ /* List of CLAM_SCAN_INFO items */ /* Typical use: If no callback is registered and an archive file is scanned, this list corresponds to each infected file found */ typedef struct _CLAM_SCAN_INFO_LIST { /* Number of CLAM_SCAN_INFO structures present */ int cbCount; /* Pointer to first CLAM_SCAN_INFO structure */ PCLAM_SCAN_INFO pInfoList; } CLAM_SCAN_INFO_LIST, *PCLAM_SCAN_INFO_LIST; /************************************************************************************** CLAMAPI scan callback ***************************************************************************************/ /* SCAN CALLBACK ACTIONS */ /* The following actions can be requested by the scan callback */ typedef enum _CLAM_ACTION { CLAM_ACTION_CONTINUE, /* Keep on scanning */ CLAM_ACTION_SKIP, /* Skip the current file */ CLAM_ACTION_ABORT /* Early terminate the scan process */ } CLAM_ACTION; /* * Callback that can be registered to be invoked by the scan engine on each inner file. * Parameters: * INPUT @param pObjectInfo : all relevant information of the file being scanned * OUTPUT @param scanAction : action to be taken as determined by callback * INPUT @param context : any context to be passed to scan callback */ typedef void (CALL_CONVENTION *CLAM_SCAN_CALLBACK)(const CLAM_SCAN_INFO *pObjectInfo, CLAM_ACTION *scanAction, void *context); /************************************************************************************** CLAMAPI functions ***************************************************************************************/ #ifdef __cplusplus extern "C" { #endif // In future this can be extended to C++ style interface // CCLAMScanner refers to Scanner instance #define CClamAVScanner void /* * MANDATORY SUPPORT * Load scan engine defs * Parameters: * INPUT @param pEnginesFolder : path where defs are located * INPUT @param pTempRoot : path in which temporary files must be created * INPUT @param pLicenseKey : license key blob * INPUT @param bLoadMinDefs : load minimal defs */ int CLAMAPI Scan_Initialize(const wchar_t *pEnginesFolder, const wchar_t *pTempRoot, const wchar_t *pLicenseKey, BOOL bLoadMinDefs); /* * MANDATORY SUPPORT * Unload scan engine defs, which were loaded using Scan_Initialize * Parameters: None */ int CLAMAPI Scan_Uninitialize(); /* * MANDATORY SUPPORT * Create scan engine instance. * The engine instances should have the ability to be shared across threads * If synchronization is not done internally, it should be identified as such * OUTPUT @param ppScanner : location to hold opaque object */ int CLAMAPI Scan_CreateInstance(CClamAVScanner **ppScanner); /* * MANDATORY SUPPORT * Destroy scan engine instance. * INPUT @param pScanner : opaque object */ int CLAMAPI Scan_DestroyInstance(CClamAVScanner *pScanner); /* * MANDATORY SUPPORT * Set callback that is invoked when file is being scanned * For archive, installers, compound files the callback should be invoked for each file. Each file can cause the callback to be invoked more than once. * INPUT @param pScanner : opaque object * INPUT @param pfnCallback : callback function * INPUT @param pContext : context to be passed to callback function */ int CLAMAPI Scan_SetScanCallback(CClamAVScanner *pScanner, CLAM_SCAN_CALLBACK pfnCallback, void *pContext); /* * MANDATORY SUPPORT * Scan object using path * INPUT @param pScanner : opaque object * INPUT @param pObjectPath : path to object * OUTPUT @param pScanStatus : indicates status of scan (CLAM_CLEAN or CLAM_INFECTED) * OUTPUT @param pInfoList : list containing additional information about file that was scanned (ONLY valid in *pScanStatus == CLAM_INFECTED) */ int CLAMAPI Scan_ScanObject(CClamAVScanner *pScanner, const wchar_t *pObjectPath, int *pScanStatus, PCLAM_SCAN_INFO_LIST *pInfoList); /* * MANDATORY SUPPORT * Scan object using object handle * INPUT @param pScanner : opaque object * INPUT @param object : handle to object * OUTPUT @param pScanStatus : indicates status of scan * OUTPUT @param pInfoList : list containing additional information about file that was scanned (ONLY valid in *pScanStatus == CLAM_INFECTED) */ int CLAMAPI Scan_ScanObjectByHandle(CClamAVScanner *pScanner, HANDLE object, int *pScanStatus, PCLAM_SCAN_INFO_LIST *pInfoList); /* * Returns the outer file type as an _int64[2] for the given HANDLE * Scan is not performed and no callback is invoked * INPUT @param hFile : file handle whose type is to be determined * OUTPUT @param filetype : result array (_int64[2]) */ int CLAMAPI Scan_GetFileType(HANDLE hFile, _int64 *filetype); /* * Checks if any meaningful signature is loaded * Returns 0 (false), 1 (true) or -1 (error) * OUTPUT @param official : set to the number of official signatures loaded, unless NULL * OUTPUT @param custom : set to the number of custom signatures loaded, unless NULL */ int CLAMAPI Scan_HaveSigs(unsigned int *official, unsigned int *custom); /* * MANDATORY SUPPORT * Destroy memory allocated when malicious objects are found during scan * INPUT @param pScanner : opaque object * INPUT/OUTPUT @param pInfoList : list to be freed */ int CLAMAPI Scan_DeleteScanInfo(CClamAVScanner *pScanner, PCLAM_SCAN_INFO_LIST pInfoList); /* * Get integer based scanning options * ex: License Expiration Time, Count of DB signatures, Last updated time for DB, Major, Minor version of scan library * INPUT @param option : limit type * OUTPUT @param value : limit size in bytes */ int CLAMAPI Scan_GetLimit(int option, unsigned int *value); /* * Set integer based scanning options * ex: scan Archives, scan packed samples, scan e-mail databases, scan installers * INPUT @param option : limit type * INPUT @param value : limit size in bytes */ int CLAMAPI Scan_SetLimit(int option, unsigned int value); /* * Get integer based scanning options * ex: License Expiration Time, Count of DB signatures, Last updated time for DB, Major, Minor version of scan library * INPUT @param scanner : opaque object * INPUT @param option : option enum * INPUT @param value : location to store value * INPUT @param inputLength : size of input buffer * OUTPUT @param outLength : mimimum size require to store data */ int CLAMAPI Scan_GetOption(CClamAVScanner *pScanner, int option, void *value, unsigned long inputLength, unsigned long *outLength); /* * Set integer based scanning options * ex: scan Archives, scan packed samples, scan e-mail databases, scan installers * INPUT @param pScanner : opaque object * INPUT @param option : option enum * INPUT @param value : location to store value * INPUT @param inputLength : size of input value */ int CLAMAPI Scan_SetOption(CClamAVScanner *pScanner, int option, void *value, unsigned long inputLength); /* * Convert a ClamAV error code into a string * INPUT @param errorCode * NOTE: the returned string is not to be freed! */ CLAMAPI const wchar_t * Scan_GetErrorMsg(int errorCode); /* * Reload the virus database * INPUT @param bLoadMinDefs : full or minimal defininition selector */ CLAMAPI void Scan_ReloadDatabase(BOOL bLoadMinDefs); #ifdef __cplusplus }; /* extern "C" */ #endif #endif /* _CLSCANAPI_H */