Contents
1 About this supplement..............................................................................................................3
2 SAVI configuration options.......................................................................................................4
2.1 Introduction.................................................................................................................4
2.2 Using SAVI configuration options...............................................................................4
2.3 SAVI configuration option data types..........................................................................5
2.4 SAVI group configuration options...............................................................................6
2.5 Current SAVI configuration options.............................................................................7
3 SAVI return values..................................................................................................................20
4 SAVI storage IDs....................................................................................................................27
5 Data types..............................................................................................................................32
6 Technical support....................................................................................................................33
7 Legal notices..........................................................................................................................34
2
1 About this supplementThis supplement documents the SAV Interface Developer Toolkit. It contains the followinginformation:
■ An overview and list of the SAVI (SAV Interface) configuration options.
■ A list of SAVI return codes.
■ A list of storage IDs.
For full information about implementing SAVI, see the SAV Interface Developer Toolkit usermanual, which is included in the SAVI Developer Toolkit and is also available on the OEMIntegration Resources webpage of the Sophos website.
3
supplement
2 SAVI configuration options
2.1 IntroductionThis section contains a brief overview of SAVI configuration, along with a list of the current SAVIconfiguration options.
SAVI configuration options control:
■ The file types handled by SAVI
■ The behavior of SAVI as it scans files
They are also used for other general configuration purposes.
Full information about how to use the member functions of the SAVI interfaces and enumeratorsis available in the SAV Interface Developer Toolkit user manual.
Note: The list of virus engine configuration options grows as more features and support for newfile types are added to SAVI.
2.2 Using SAVI configuration options
2.2.1 SAVI configuration options - general information■ Each SAVI configuration option has a unique name that is used to control the value of the
associated SAVI feature (e.g. to turn on or off the handling of ZIP archives). SAVI configurationoption names are case insensitive and don't contain spaces.
Names are passed to SAVI as an LPCOLESTR data type. Depending on the platform, this eithermaps to a pointer to a wide character string (16 bit, Unicode), or a char/multibyte string (8 bit). Inthe event of a mismatch in character encoding between SAVI and the client application, the clientmust carry out any necessary conversions.
■ Each SAVI configuration option also has a unique type, one of the SOPHOS_TYPE_... codeslisted in the header file savitype.h, under "Configuration option types". Currently-usedconfiguration option types are listed in SAVI configuration option data types (page 5).
Values are passed in and out of SAVI as strings. This enables a number of different data typesto be passed through a single API. Client applications must, where appropriate, convert numericvalues to and from strings using appropriate conventions for the configuration option type. Aswith SAVI option names, the value string is an LPCOLESTR data type, and can therefore pointto 8 or 16 bit data.
When changing a SAVI configuration option, both the name and the type must be passed throughthe SAVI API.
4
SAV Interface Developer Toolkit
2.2.2 Local and Global Options
Most SAVI configuration options apply just to the SAVI object receiving the call to SetConfigValue.However, there is a set of options which are shared by all SAVI objects running in a process. Ifone of these options is changed then it will affect all SAVI objects, not just the one being called.These options all relate to aspects of SAVI which are also shared between the SAVI objectsrunning in a process, in particular the threat data.
The global SAVI options are IdeDir, VirusDataDir, VirusDataName, AllowPartialVirusData andthe entire set of ProductXxx options.
If, for example, the virus data directory is changed, this will flag that virus data needs to be reloadedfrom the new location. This reload will happen automatically on the next call to e.g. SweepFile,even if that is made on a different SAVI object to the one which called SetConfigValue.
A similar issue can occur if one of these options is changed followed a little later by a call toSetConfigDefaults. Depending on the timing of calls to SweepFile, this can result in multiple datareloads.
It should also be noted that, as a shared resource, care may be needed when changing theseoptions on multiple SAVI object and/or threads. The majority of supported SAVI platforms havebuilt-in thread synchronisation which will prevent conflicts here, but the designer of the clientapplication needs to be aware of possible interactions between threads when using these options.
2.2.3 Listing and changing SAVI settings■ To ask a running SAVI object to list the names and types of configuration options it supports,
use GetConfigEnumerator() to get a pointer to an enumerator interface. Then use theenumerator interface to obtain the list of configuration options supported.
■ To configure engine settings to their default values, use the SetConfigDefaults() function ofthe ISavi2 or ISavi3 interfaces.
■ To read and change the values of individual configuration options, use the SetConfigValue()and GetConfigValue() functions of the ISavi2 or ISavi3 interfaces.
For a full description of these functions, see the SAV Interface Developer Toolkit user manual.
2.3 SAVI configuration option data typesSAVI configuration option data types are listed under "Configuration option types" in the headerfile savitype.h, but not all of them are currently in use. The following is a list of currently-useddata types.
Unsigned 16-bit value. Passed to and from SAVI asa string representing the decimal value of theconfiguration option.
SOPHOS_TYPE_U16
Unsigned 32-bit value. Passed to and from SAVI asa string representing the decimal value of the
SOPHOS_TYPE_U32
configuration option. Many on/off settings are
5
supplement
configured as SOPHOS_TYPE_U32, and arecontrolled by being set to 1 or 0 respectively.
A numeric value that may be 0, 1 or 2. Passed to andfrom SAVI as a string representing the value of the
SOPHOS_TYPE_OPTION_GROUP
configuration option. See SAVI group configurationoptions (page 6) for more information.
This setting type represents a string, and so can bepassed to and from SAVI directly, without needingany translation.
Note: When calling SetConfigValue() for a settingof this type, SAVI takes a copy of the string, so theclient may safely free the string buffer after the call.
SOPHOS_TYPE_STRING
2.4 SAVI group configuration options
2.4.1 Overview
Many configuration options have similar characteristics and can therefore be grouped, for example,into those that handle similar types of files. Group configuration options enable you to switch allthe individual options in a group on or off with a single call to SetConfigValue().
This simplifies client code, which would otherwise have to make numerous calls toSetConfigValue(). It also means new configuration options that fall into a particular group areautomatically controlled by the group configuration option, so you do not necessarily need toupdate SAVI client code to deal with new configuration options.
2.4.2 Currently defined groups
The following is a list of the currently defined group configuration options.
Any option that is part of a group is also included inthis group.
GrpSuper
All archive and compressed archive file formats (e.g.ZIP, UUE, etc).
GrpArchiveUnpack
File formats that contain an executable stub thatautomatically decompresses the body of the file.
GrpSelfExtract
Executable files.GrpExecutable
File formats commonly in use on the internet.GrpInternet
Office suite file formats from Microsfoft and othersupported vendors.
GrpMSOffice
6
SAV Interface Developer Toolkit
File formats that do not fall into any of the abovecategories.
GrpMisc
Enables or disables disinfection of all files for whichdisinfection is supported.
GrpDisinfect
All “clean” file formats.GrpClean
Compression formats commonly used in HTTP andsupported by web browsers.
GrpWebArchive
HTML encoding schemes commonly used in webpages.
GrpWebEncoding
2.4.3 Using SAVI group configuration options
Group configuration options take one of three values:
■ 0 represents off.
■ 1 represents on.
■ 2 (or greater) represents invalid.
invalid is not an error state. If passed into SAVI using SetConfigValue() it simply means none ofthe configuration options in the group will be altered.
SAVI also returns invalid if GetConfigValue() is called for one of the group configuration options(along with the informational return value SOPHOS_SAVI_INFO_OPT_GRP_INVAL_RTN).
Some individual options fall under the control of more than one group configuration option.
When configuring SAVI, first set the value of the group configuration option, then set the value ofindividual options. For example, if all archive formats except UUE are required, setGrpArchiveUnpack to on, then UueDecompression to off.
Note: Use of group configuration options is optional. SAVI can be configured just as well usingindividual options. Group options are available as a shortcut and to offer a degree of future-proofingin areas of SAVI configuration where precise control of every option is not critical.
2.5 Current SAVI configuration optionsThe following table lists the current SAVI configuration options.
Note: Not all settings are supported on all platforms.
The Name column lists both the name of the option and the version of the virus engine in whichsupport for the option became available. Options that have been available since version 2.0 orearlier are listed as 'ver 2.0'.
The Type column lists the data type for each configuration option (listed in SAVI configurationoption data types (page 5)). Types are abbreviated as follows:
■ U16 = (SOPHOS_TYPE_U16)
7
supplement
■ U32 = (SOPHOS_TYPE_U32)
■ GRP = (SOPHOS_TYPE_OPTION_GROUP)
■ STR = (SOPHOS_TYPE_STRING)
The Groups column lists the groups, if any, the option belongs to (listed in Currently definedgroups (page 6)). Groups are abbreviated as follows:
■ A = (GrpArchiveUnpack)
■ C = (GrpClean)
■ D = (GrpDisinfect)
■ E = (GrpExecutable)
■ I = (GrpInternet)
■ M = (GrpMisc)
■ N = (GrpWebEncoding)
■ O = (GrpMSOffice)
■ S = (GrpSelfExtract)
■ W = (GrpWebArchive)
It can be assumed that any option that belongs to a group is also in GrpSuper.
The Default column lists the default value for the option.
Global OptionsThese options will affect all SAVI instances in a process. Care should be exercised in the use ofthese options as inappropriate use could lead to inefficiencies during initialisation in particular.
DefaultGroupsDescriptionTypeName
0By default, errors in loading virus data are treatedas fatal and scanning is not allowed. Setting this
U32AllowPartialVirusData(ver 2.14)
option to 1 means such errors are treated aswarnings, and scanning using a partial virus dataset is possible.
-The passed string defines the full path name of thedirectory in which SAVI should search for IDE files.
STRIdeDir (ver 2.14)
The name must not have a trailing separatorcharacter.
0, 0, 0,1, 1, 0
-These options enable identities targetted at specificproduct types. ProductCli - identities appropriate toa command-line scanner. ProductDesktop -
U32Product CLI,ProductDesktop,ProductGateway,
identities appropriate to a desktop product.ProductMobile,ProductGateway - identities appropriate to aProductUnspecified,
ProductWeb (ver 2.47) gateway scanner. ProductMobile - identities for
8
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
threats which only affect mobile products e.g. smartphones. ProductUnspecified - non-specific identities.This includes all traditional threats: viruses, worms,trojans, PUAs etc. ProductWeb - identities specificto web gateway products. Note- Sophos stronglyrecommends that ProductUnspecified is not set to0, as this will effectively disable most of the threatdetection offered by SAVI. Product-specific optionsare targetted at the relevant products andinappropriate use may impact on scanningperformance.
--The passed string defines the full path name of thedirectory in which the main virus data file is located.
STRVirusDataDir (ver 2.0)
The name should not have a trailing directoryseparator character.
--The passed string defines the name of the virusdata file. This name should not include a directory
STRVirusDataName (ver 2.0)
component (this is defined by the VirusDataDirsetting) or a file extension. For example, if the mainvirus data file name is vdl.dat then this string shouldbe passed as vdl.
Local OptionsThese options affect only the SAVI instance to which they are applied.
Note: The EnableAutoStop option will abort the current scan if it seems to be requiring excessivesystem resources. On rare occasions it may be possible for an innocent file to trigger the AutoStopdetection (a “false positive”). However, files causing SAVI to return ...SCAN_ABORTED shouldinitially be treated in the same way as one containing a virus.
DefaultGroupsDescriptionTypeName
1OEnables scanning of databases saved in MicrosoftAccess (MDB) format.
U32Access (ver 2.13)
1IEnables the detection of macro viruses withinMicrosoft Office documents saved in ActiveMimedocument format.
U32ActiveMimeHandling (ver2.2)
1A, IEnables scanning of Macintosh files saved as asingle file in situations where support for Macintoshdual forks is not possible (e.g. MIME files).
U32AppleSingle (ver 2.12)
9
supplement
DefaultGroupsDescriptionTypeName
0AEnables decompression of Arj archives.U32ArjDecompression (ver2.0)
1SEnables scanning inside ASPack self-extractingexecutable archives.
U32ASPack (ver 2.19)
0M, I, NEnables scanning of files encoded using theBASE64 scheme in situations where this is notflagged by, for example, a MIME header line.
U32Base64 (ver 2.18)
1Enable generic detection of malware based onSophos Behavioural Genotype Detection. Note-
U32BehaviourMalware (ver2.38)
detection of malware will be significantly reduced ifthis option is turned off.
1Controls whether the Sweep and Disinfectionfunctions will block, or not, during an update. If
U32BlockOnUpdate (ver 2.79)
non-blocking is selected, an error,SOPHOS_SAVI_ERROR_WOULDBLOCK isreturned to the client. (W32 systems only)
0AEnables decompression of BZip2 archives.U32Bzip2 (ver 2.17)
1CCertain file formats (e.g. .bmp bitmap files) cannotcontain viruses. These options enable files of the
U32CleanBmp, CleanGif,CleanJpeg, CleanPng,
corresponding types to be positively identified andCleanRiff, CleanTiff (verscanning of them to be stopped.This results in moreefficient scanning of these file types.
2.17), CleanMp3 (ver2.24), CleanMpeg (ver2.25)
0Extends processing of multiple archive files whichhave been concatenated together so that they are
U32ConcatenatedArchives(ver 2.27)
all processed, even if they are separated by somejunk data. NB can increase scan times slightly.
0AEnables decompression of Cmz archives.U32CmzDecompression (ver2.0)
1ODecompresses the text part of a VBA5 project beforescanning.This area is often corrupted, but can helppositive identification of some viruses.
U32DecompressVBA5 (ver2.0)
1-Causes the entire project containing any viralmacros to be removed during disinfection.
U32DelVBA5Project (ver 2.7)
10
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
--Enables scanning of disk file images in Apple DMGformat. Note - Scanning of DMG files also requires
U32Dmg (ver 2.49)
the appropriate file system plugin (e.g. Hfs+, seeHfs option) to be enabled.
1SControls the ability to scan inside supported typesof dynamically compressed executables. This type
U32DynamicDecompression(ver 2.0)
of file appears to be a normal executable.The mainpart of the program is compressed and extractedinto memory at run-time. Sophos recommends thisoption should be turned on.
1EControls the module that interprets ELF binary files.This format is used for many Linux and FreeBSDexecutable files.
U32Elf (ver 2.10)
1EEnables the 16-bit x86 emulation engine, whichassists in the detection of polymorphic executable
U32Emulation (ver 2.0)
file viruses. Sophos recommends this option shouldbe turned on.
0-Causes scanning to be aborted for files (e.g. ""zipbombs"") whose characteristics cause the Virus
U32EnableAutoStop (ver2.20)
Engine to consume excessive system resource(disc, memory, CPU). See note 1 at the end of thissection.
1EEnables scanning of Symbian format mobile deviceexecutables.
U32Epoc (ver 2.45)
1OEnables scanning of Excel formulas for knownformula viruses. Formulas occupy cells on theworksheet and should not be confused with macros.
U32ExcelFormulaHandling(ver 2.0)
1DSome executable file viruses can be removed fromfiles fairly safely. This option enables that process.
U32ExecFileDisinfection (ver2.4)
Sophos recommends that infected executables arereplaced from the original installation disks as soonas possible.
0-Normal scanning behaviour is to only switch to""extensive"" scan mode when initial file analysis
U32ExtensiveScan (ver 2.48)
indicates that this is necessary (e.g. strangelyformed EXE header).This option overrides the testsand performs a full ""extensive"" scan on every file.Note - Enabling this option will result in scans taking
11
supplement
DefaultGroupsDescriptionTypeName
longer and could generate an occasional falsepositive report of a threat. Sophos recommends thatthis option is only enabled when performing anin-depth analysis of suspicious files.
1SEnables scanning inside FSG self-extractingexecutable archives.
U32Fsg (ver 2.19)
0-Enables a fallback mechanism that has beendeployed in the past when new file structures are
U32FullMacroSweep (ver 2.0)
encountered. Sophos recommends that you keepthis option turned off.
0-Enables every part of a PDF file to be scanned, notjust the embedded file streams. This takes longer.
U32FullPdf (ver 2.17)
0-Enables full sweeping, which performs extensivefixed pattern matching as well as the standard
U32FullSweep (ver 2.0)
intelligent virus search. Turning on this option mayhave severe performance implications.
0M, WEnables decompression of Gzipped archives.U32GzipDecompression (ver2.17)
1MEnables scanning of files embedded in MicrosoftHelp files.
U32HelpHandling (ver 2.0)
0-Enables support for the Apple HFS+ file system asoften encountered in DMG files (see also Dmgoption).
U32Hfs (ver 2.49)
0IEnables the scanning of HTTP streamsU32Http (ver 2.50)
0AControls the ability to extract files from BinHexarchives.
U32HqxDecompression (ver2.0)
1IControls the module that optimises scanning inHTML files.
U32Html (ver 2.0)
1-Microsoft Office documents that contain executablemacros will usually have a single bit in the file
U32IgnoreTemplateBit (ver2.0)
header set to 1 to indicate the presence ofexecutable code. Under normal circumstancesmacros contained in a file that does not have thisbit set are not able to execute. If this option is turnedoff, the Virus Engine will scan only files with this
12
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
template bit set to 1. Sophos recommends that youkeep this option turned on.
0AEnables decompression of Cabinet files createdusing the InstallShield compression format (e.g._sys1.cab).
U32ISCabinet (ver 2.17)
0-Increases detection reliability in old formatInstallShield files, but with a slight performanceoverhead.
U32ISCabinetFull (ver 2.17)
0A, WEnables scanning of Microsoft Compressed Helpfiles (.chm, .hxs).
U32ITSS (ver 2.0)
1E, IEnables scanning of Java class files.U32Java (ver 2.13)
0AEnables decompression of Lha archives.U32Lha (ver 2.2)
0MControls SAVI's ability to scan inside certain typesof container file (e.g. FAT container files or disk
U32LoopBackEnabled (ver2.0)
image files such as are found in CD boot sectors oron OpenVMS).
1EEnables scanning of Mach-O executables (used onMac OS X). Note that “O” is the letter, not a zero.
U32MachO (ver 2.17)
16-Controls the maximum number of times the enginewill recurse into archives when they are found (e.g.
U16MaxRecursionDepth (ver2.0)
when a zip file is compressed within another zipfile).The maximum value is 100, but SAVI internallyhas some extra levels of recursion to cover internaldata streams found within some file types.
25-As per MaxRecursionDepth but applying to internaldata streams.
U16MaxIntRecDepth (ver2.24)
0AControls the ability to look inside MacBinaryarchives.
U32MbinDecompression (ver2.0)
0IEnables scanning of Unix 'mbox' format mail stores.U32Mbox (ver 2.42)
0I, NEnables decoding and scanning inside a MIMEencoded message block.
U32Mime (ver 2.10)
13
supplement
DefaultGroupsDescriptionTypeName
1-To enable scanning of email embedded insideanother email rather than an attachment.
U32MimeEmbedded (ver2.29)
25-Maximum number of embedded file streams thatcan be extracted from a MIME file.
U16MimeEmbedLimit (ver2.31)
500-The maximum number of lines MIME source to scanlooking for embedded objects (inline BASE64).
U16MimeEmbedLines (ver2.32)
2-Enable the Virus Engine to rescan a MIME encodedobject as a single object after scanning the individual
U32MimeRescan (ver 2.29)
message parts. The default value of 2 means'automatic' i.e. the Virus Engine will decide when totemporarily enable the option while scanning MIME.
0AEnables decompression of Microsoft Cabinet files(cab). (Partial files at the beginning and end ofmulti-part cabinet files will not be fully scanned).
U32MSCabinet (ver 2.0)
0AControls the ability to scan inside files compressedwith the Microsoft compression utility.
U32MSCompress (ver 2.2)
0-Enable scanning of MS Installer files. This needsother options, such as MSCabinet, to be set to beeffective depending on the file content
U32Msi (ver 2.29)
-Controls handling of Macintosh (resource + datafork) files and archives (on platforms where these
U32NamespaceSupport (ver2.0)
are supported). Settings are SOPHOS_MAC_FILES(enable scanning for Mac viruses),SOPHOS_DOS_AND_MAC_FILES (also scan datafork) or SOPHOS_DOS_FILES (disable Mac filescanning). Note - (1) default value is platformdependent. (2) Enabling data fork scanning carriesa slight performance overhead and so is onlyrecommended on platforms where OS8/OS9 virusesmay be encountered.
1OEnables support for ""Open Document"" format,(generally consisting of XML within a zip archive).
U32Odoc (ver 2.40)
This includes both StarOffice/OpenOffice andMicrosoft OpenXML formats (see Sdoc and Oxmloptions).
14
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
1OControls the ability of the engine to understandMicrosoft Office 2001 files. This version of Officewas only released on the Macintosh platform.
U32Office2001Handling (ver2.10)
1OPassword-protected Office 95 documents areencrypted with a very simple algorithm. Enabling
U32OF95DecryptHandling(ver 2.0)
this option causes the virus engine to break thisencryption to search for viruses.
1OEnables scanning of files saved in HTML formatfrom Microsoft Office.
U32OleDataMsoHandling (ver2.13)
1I, OEnables scanning of other OLE types (e.g.messages saved in Microsoft Outlook).
U32OleRawHandling (ver2.17)
1OEnables scanning of Access macros.U32OleScriptHandling (ver2.13)
1DThis option enables disinfection of OLE2 (MicrosoftOffice) files to be configured independently of othertypes of file disinfection.
U32Ole2FileDisinfection (ver2.10)
1OEnables the intelligent scanning of OLE2 (MicrosoftOffice) format documents. Sophos recommendsthat this option should be turned on.
U32Ole2Handling (ver 2.0)
1-Enables detection and opening of Mac resourceforks in all file types scanned.
U32OpenMacRf (ver 2.17)
0IEnables scanning of files contained within OutlookExpress mailboxes. NB: to scan email attachments,also set the Mime option.
U32OutlookExpress (ver2.10)
1OEnable scanning of Microsoft Open XML documents(use in conjunction with Odoc option).
U32Oxml (ver 2.44)
1MEnables the scanning of Palm Pilot format files(.prc).
U32PalmPilotHandling (ver2.2)
1MControls the PDF file interpretation moduleU32Pdf (ver 2.10)
1SEnables scanning inside PECompact self-extractingexecutable archives.
U32PECompact (ver 2.19)
15
supplement
DefaultGroupsDescriptionTypeName
1EEnables the 32 bit executable emulator. This isrequired to support some advanced virus detectionmodes in 32 bit executable files.
U32PeEmulator (ver 2.13)
1EEnables the intelligent scanning of Win32/PE formatfiles. This is the standard format for Windowsexecutable binaries such as .exe and .dll.
U32PEHandling (ver 2.0)
1OEnables the scanning of files embedded withinMicrosoft PowerPoint presentations.
U32PowerPointEmbeddedHandling (ver 2.0)
1OEnables the scanning of macros in PowerPointpresentations.
U32PowerPointMacroHandling (ver 2.0)
1OEnables the scanning of VBA macros in MicrosoftProject.
U32ProjectHandling (ver 2.0)
0AEnables decompression of RAR archives.U32RarDecompression (ver2.0)
0AEnables the scanning of distribution archives inRedHat Package Manager format. NB: to scan .rpm
U32Rpm (ver 2.17)
files, set the GZipDecompression and UnixArchiveoptions as well.
1O, MEnables scanning for objects that may be embeddedinside Rich Text Format files.
U32Rtf (ver 2.10)
0-Enable scanning of VMS 'saveset' archivesU32Saveset (ver 2.30)
1OEnables the handling of scrap objects that are usedin the transfer of data between certain applications.
U32ScrapObjectHandling (ver2.0)
1OEnable scanning of StarOffice /OpenOfficedocuments (use in conjunction with Odoc option).
U32Sdoc (ver 2.44)
0A, SEnables the virus engine to search in supportedtypes of self-extracting archive.
U32SfxArchives (ver 2.0)
0AEnable scanning of 'SIS' (Symbian InstallationSystem) files as used on some mobile devices.
U32Sis(ver 2.44)
1-Used for Virus Engine internal control. Should beleft on (value 1) by SAVI applications.
U32Skip (ver 2.18)
16
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
1ODeals with another type of data within Officedocuments.
U32SrpStreamHandling (ver2.0)
0-Virus detection has two stages. First a file isidentified and classified according to its type. In the
U32StorageDetOnly (ver 2.0)
case of archive files, the individual files within thearchive are extracted and treated in the same way.Then scanning is then carried out according to thefile type. When StorageDetOnly is enabled, virusscanning is not carried out.The virus engine simplyidentifies the file types and returns information aboutany files contained inside.
0-When enabled, zero, one or more calls are madeto the OnClassification() callback function in INotify2for each filename passed to OnFileFound().
U32StorageReport (ver 2.0)
0-By default, only the published storage types arenotified via the OnClassification() callback. This
U32StorageReportAll (ver2.17)
option enables intermediate and weakly classifiedstorage types to be reported too. Many of these areinternal to the Engine and will not be documented.
0-Enables detection and reporting of some types ofStuffit archives.
U32Stuffit (ver 2.17)
0-Causes SAVI to report...FORMAT_NOT_SUPPORTED if the Virus Engine
U32StrictPdf (ver 2.36)
encounters data in a PDF file encoded with anunrecognised 'custom filter'. Default is to scan thestream without decoding it.
0-Causes SAVI to report... CORRUPT if it encounterssections within a PDF file which cannot beinterpreted by the Virus Engine.
U32StrongPdf (ver 2.36)
0AEnable Seven Zip support.U32Szip (ver 2.50)
0AEnables scanning inside Unix tar archives.U32TarDecompression (ver2.0)
0IEnables decoding of files encoded with the MicrosoftTNEF format, used by some mail client applications.
U32TnefAttachment Handling(ver 2.18)
17
supplement
DefaultGroupsDescriptionTypeName
0-Enables scanning of TNEF files embedded withinanother mail file.The Microsoft TNEF format is usedby some mail client applications.
U32TnefEmbedHandling (ver2.18)
0Reports the real type of the fileU32TrueFileTypeDetection(ver 2.70)
1Set file type reporting mode. When more than onefile type is detectable when examining a file, SAVI
U16TrueFileTypeDetectionLevel(ver 2.70)
reports just one or more file types depending on theTFT level set.
SOPHOS_TFT_LEVEL_ONEFILETYPE Havingfound and reported one, the most accurate file type,SAVI will not check for further file types.
SOPHOS_TFT_LEVEL_ALLFILETYPES Havingfound and reported one file type, SAVI will continueto check for further file types with the same andlower priority.
SOPHOS_TFT_LEVEL_ALLHIGHESTPRIORITYHaving found and reported one file type, SAVI willcontinue to check for further file types with the samepriority. The check for lower priority file types willnot be performed. This will reduce the number ofreports that would otherwise be reported usingSOPHOS_TFT_LEVEL_ALLFILETYPES option.
0AEnables scanning inside Unix archive types (ar,cpio).
U32UnixArchive (ver 2.17)
1SEnables scanning inside UPX-compressedself-extracting executable archives.
U32Upx (ver 2.7)
1IEnables scanning of web pages created usingUTF16 (Unicode) character encoding.
U32UTF16 (ver 2.17)
0AEnables the virus engine to decode UUEncodedfiles. The UUEncode portion must start within thefirst 4k of the document.
U32UueDecompression (ver2.0)
1OEnable the scanning of versions of Microsoft VisualBasic for Applications embedded in supported filetypes, like Office and Visio documents.
U32VBA3Handling (ver 2.0)
1OEnable the scanning of versions of Microsoft VisualBasic for Applications embedded in supported filetypes, like Office and Visio documents.
U32VBA5Handling (ver 2.0)
18
SAV Interface Developer Toolkit
DefaultGroupsDescriptionTypeName
0OOption currently unimplementedU32Vba5Dir (ver 2.22)
0OEnable scanning of files containing only Visual Basicfor Applications (e.g. PowerPoint PPA files).
U32VbaOnly (ver2.25)
1-Enables scanning of Word document table streams.U32VbaTable (ver 2.32)
1OEnables detection of macros in p-code (compiledVisual Basic) as well as in Visual Basic source code.
U32Vba5p (ver 2.17)
1IEnables the scanning of encoded VBScript files.U32Vbe (ver 2.10)
0IEnables canonicalisation of Visual Basic code.Thisincreases the detection efficiency of the other VisualBasic for Applications (VBA) plugins.
U32VbFiltering (ver 2.13)
00Enable scanning of files embedded inside MicrosoftVisio documents
U32VisioEmbedHandling (ver2.20)
1OEnables scanning of macros inside Microsoft Visiofiles.
U32VisioFileHandling (ver2.4)
1OEnables scanning of WordBasic.U32WordB (ver 2.0)
0-Enables scanning of XML files. Note - scanning offiles saved in XML format by Microsoft Office 11+is enabled using the XmlOdoc option.
U32Xml (ver 2.18)
1OEnables detection of Open Document files (andsubsequent processing) without requiring the XMLplugin (Xml option) to be enabled first.
U32XmlOdoc (ver 2.44)
0A, WEnables scanning inside Zip archives.U32ZipDecompression (ver2.0)
1-Improves reliability of scanning of Zip files createdin a non-standard way (local file directory invalid).
U32ZipUseChd (ver 2.17)
19
supplement
3 SAVI return valuesAll SAVI interface functions return values that indicate whether the function succeeded.
This table lists the least significant word of the return value. The complete numerical valuescorresponding to these symbols may vary from one platform to another. Numerical values aredefined in the file savierr.h.
SAVI client applications should be designed to behave gracefully if they encounter new returncodes not listed in the header file used at the time the application was compiled.
The list of return values has been categorised into:-
Errors that should not occur and indicate some serious condition which mayhave compromised detection. The application should consider restarting.
Fatal
Serious errors that may compromise some operations but do not necessarilyrequire a restart.
Serious
Errors or conditions that apply only to the object being scannedNormal
Fatal Return Values
ExplanationCodeValue
The function could notcomplete successfully becauseit ran out of memory.
SOPHOS_E_OUTOFMEMORY000E
The value of an argumentsupplied to the function by theSAVI client is invalid.
SOPHOS_E_INVALIDARG0057
SAVI encountered a problemwhile trying to create or write
SOPHOS_E_OUT_OF_DISK0070
to a temporary file. Checkpermissions/available diskspace in the SAVI virus enginetemporary directory.
A callback was installed usingRegisterNotification() on a
RPC_E_WRONG_THREAD010E
different thread to the currentone. Both calls must be on thesame thread.
20
SAV Interface Developer Toolkit
ExplanationCodeValue
If CreateInstance() (i.e. the firstparameter to IClassFactory())
SOPHOS_CLASS_E_NOAGGREGATION0110
is not NULL, this value isreturned.
The function was notimplemented.
SOPHOS_E_NOTIMPL4001
The caller specified aninterface type (REFIID) whichis unknown or not supported.
SOPHOS_E_NOINTERFACE4002
An unexpected error occurred.SOPHOS_E_UNEXPECTEDFFFF
The SAVI interface could notbe initialised.
SOPHOS_SAVI_ERROR_INITIALISING0200
The SAVI interface could notbe terminated.
SOPHOS_SAVI_ERROR_TERMINATING0201
The version of the on-accessscanner (InterCheck) installedis not compatible with SAVI.
SOPHOS_SAVI_ERROR_IC_INCOMPATIBLE_VERSION0205
The SAVI client process hasinsufficient rights to disable
SOPHOS_SAVI_ERROR_IC_ACCESS_DENIED0206
on-access scanning(InterCheck). The scan couldnot be performed.
The on-access scanning(InterCheck) client is active and
SOPHOS_SAVI_ERROR_IC_SCAN_PREVENTED0207
cannot be disabled. The scancould not be performed.
The setup program wasexecuted to upgrade the
SOPHOS_SAVI_ERROR_UPGRADE_FAILED020A
Sophos Anti-Virus installation,but it did not completesuccessfully. SAVI will notfunction until setup is runsuccessfully.
SAVI could not locate a versionof Sophos Anti-Virus to use.
SOPHOS_SAVI_ERROR_SAV_NOT_INSTALLED020B
21
supplement
ExplanationCodeValue
The InterCheck client is activeand could not be disabled.This
SOPHOS_SAVI_INFO_IC_ACTIVE0221
may cause calls to someSweep...() and Disinfect...()functions to fail.
SAVI must be reinitialisedbecause the virus engine is a
SOPHOS_SAVI_ERROR_MUST_REINIT0223
later version than the versionof SAVI currently running.
One of the files or sections ina split virus data set could not
SOPHOS_SAVI_ERROR_MISSING_VDL_PART022D
be located or an error wasencountered while reading it.Also see the related warningSOPHOS_SAVI_WARNING_MISSING_VDL_PARTand the configuration optionAllowPartialVirusData.
One of the files in a split-virusdata set has the wrong
SOPHOS_SAVI_ERROR_VDL_CHECKSUM022F
checksum. Also see the relatedwarningSOPHOS_SAVI_WARNING_VDL_CHECKSUMand the configuration optionAllowPartialVirusData.
A serious internal error hasoccurred. The SAVI object
SOPHOS_SAVI_ERROR_INTERNAL_ERROR0236
should be released and a newone created and initialised.
Serious Return Values
ExplanationCodeValue
A function was called when theinterface was not initialised.
SOPHOS_SAVI_ERROR_NOT_INITIALISED0204
An invalid configuration settingname was supplied.
SOPHOS_SAVI_ERROR_INVALID_CONFIG_NAME020C
22
SAV Interface Developer Toolkit
ExplanationCodeValue
An invalid configuration settingtype was supplied.
SOPHOS_SAVI_ERROR_INVALID_CONFIG_TYPE020D
An internal error occurredduring an attempt to accessSAVI configuration information.
SOPHOS_SAVI_ERROR_INIT_CONFIGURATION020E
An attempt was made toinitialise the SAVI interfacewhen it was already initialised.
SOPHOS_SAVI_ERROR_ALREADY_INIT0214
An attempt was made tore-enter the SAVI interface
SOPHOS_SAVI_ERROR_REENTRANCY021B
from within a notificationcallback. This is not permitted.
An error occurred using anotification callback within aSAVI client.
SOPHOS_SAVI_ERROR_CALLBACK021C
A call to initialise the SAVI DLLsucceeded but the internal
SOPHOS_SAVI_ERROR_OLD_VIRUS_DATA021E
virus data was old. Updatevirus data as soon as possible(by updating SophosAnti-Virus).
No valid temp directory wasfound.
SOPHOS_SAVI_ERROR_INVALID_TMP021F
The main body of virus data ismissing.
SOPHOS_SAVI_ERROR_MISSING_MAIN_VIRUS_DATA0220
The virus data main body hasan invalid version number.
SOPHOS_SAVI_ERROR_VIRUS_DATA_INVALID_VER0222
Cannot set option value as thevalue of the virus engine settingis immutable.
SOPHOS_SAVI_ERROR_CANNOT_SET_OPTION0224
Returned if GetConfigValue()is called for a grouped engine
SOPHOS_SAVI_INFO_OPT_GRP_INVAL_RTN0227
setting. This indicates that nomeaning can be assigned tothe value returned for thesetting (see section 1.4.3).
23
supplement
ExplanationCodeValue
The operation failed due to anincompatible pending or
SOPHOS_SAVI_ERROR_VDLD_ACTIVITY0228
ongoing activity on virus data(e.g. an attempt to scan a filewhile updating VDL data, or anattempt to update VDL datawhile scan is in progress).
Warning only version of theprevious code.
SOPHOS_SAVI_WARNING_MISSING_VDL_PART022E
Warning only version of theprevious code.
SOPHOS_SAVI_WARNING_VDL_CHECKSUM0230
Normal Return Values
ExplanationCodeValue
The function call succeeded.SOPHOS_S_OK0000
The function call partlysucceeded.The exact meaning
SOPHOS_S_FALSE0001
depends on the function. Referto the function details in thesection on the relevant SAVIinterface.
An error occurred during a virusscan.
SOPHOS_SAVI_ERROR_SWEEPFAILURE0202
A virus was found during avirus scan.
SOPHOS_SAVI_ERROR_VIRUSPRESENT0203
An attempt to disinfect a file orsector failed.
SOPHOS_SAVI_ERROR_DISINFECTION_FAILED0208
An attempt to disinfect a file orsector failed becausedisinfection was not available.
SOPHOS_SAVI_ERROR_DISINFECTION_UNAVAILABLE0209
SAVI has encountered anunrecognised form of one of
SOPHOS_SAVI_ERROR_NOT_SUPPORTED020F
the file types it supports and so
24
SAV Interface Developer Toolkit
ExplanationCodeValue
is unable to scan it. This errorcode is also returned when acall is made to a function whichis not supported by thisimplementation of SAVI.
An error occurred during anattempt to access the itempassed to SAVI for scanning.
SOPHOS_SAVI_ERROR_COULD_NOT_OPEN0210
The file was compressed butno virus was found at the outerlevel.
SOPHOS_SAVI_ERROR_FILE_COMPRESSED0211
The file was encrypted.SOPHOS_SAVI_ERROR_FILE_ENCRYPTED0212
The additional virus location isunavailable.
SOPHOS_SAVI_ERROR_INFORMATION_NOT_AVAILABLE0213
There was an attempt to use astub library.
SOPHOS_SAVI_ERROR_STUB0215
The caller supplied a characterbuffer that was too small to
SOPHOS_SAVI_ERROR_BUFFER_TOO_SMALL0216
contain the informationrequested.
A scan could not proceedbecause a file or sub-file wascorrupted.
SOPHOS_SAVI_ERROR_CORRUPT021A
GetVirusEngineVersion()succeeded, but not all of therequested data was available.
SOPHOS_SAVI_ERROR_PARTIAL_INFORMATION021D
The file passed for scanningrepresented part of a
SOPHOS_SAVI_ERROR_PART_VOL0225
multi-volume archive. The filecannot be scanned completely.
For ISaviStreamimplementation: ReadStreamfailed.
SOPHOS_SAVI_ERROR_STREAM_READ_FAIL0229
25
supplement
ExplanationCodeValue
For ISaviStreamimplementation: WriteStreamfailed.
SOPHOS_SAVI_ERROR_STREAM_WRITE_FAIL022A
For ISaviStreamimplementation: SeekStreamfailed.
SOPHOS_SAVI_ERROR_STREAM_SEEK_FAIL022B
For ISaviStreamimplementation: GetLengthfailed.
SOPHOS_SAVI_ERROR_STREAM_GETLENGTH_FAIL022C
Scan aborted (see""EnableAutoStop"" option,section 1).
SOPHOS_SAVI_ERROR_SCAN_ABORTED0231
The item of informationrequested is not defined for thisobject.
SOPHOS_SAVI_WARNING_INFO_UNDEFINED0232
The scan has been terminateddue to the Virus Engine
SOPHOS_SAVI_ERROR_RECURSION_LIMIT0237
reaching its storage recursionlimit (e.g.files nested insideother files ).
This return code is just an aliasfor ... VIRUSPRESENT but
SOPHOS_SAVI_INFO_THREATPRESENT0203
uses a more generic term toreflect the wider range ofthreats now detected by SAVI
26
SAV Interface Developer Toolkit
4 SAVI storage IDsThe ISweepNotify2 interface includes an OnClassification() function, which can return informationabout the types of file and data formats identified by the virus engine as it scans. For further detailsof ISweepNotify2, refer to the SAV Interface Developer Toolkit user manual.
A "storage ID" is assigned to each kind of file or data format identified. These IDs are defined inthe header file savitype.h, and are listed below. The list is updated as the virus engine isdeveloped to analyse more file types. Applications should be designed to cope with being passedstorage IDs which aren't on the list below.
Also listed below are some IDs that are not defined in savitype.h and are not normally reported,either because they are used only internally by SAVI or because classification by the virus engineis weak (i.e. less than 100% confidence). To enable reporting of these IDs too, use theStorageReportAll SAVI configuration option described in Current SAVI configuration options (page7).
DescriptionValue (hex)Storage ID name
OLE2 file20ID_OLE2_STORAGE
Zip archive30ID_SARC_ZIP_STORAGE
TAR archive31ID_SARC_TAR_STORAGE
GZip archive32ID_SARC_GZIP_STORAGE
ARJ archive33ID_SARC_ARJ_STORAGE
RAR archive34ID_SARC_RAR_STORAGE
UUE archive (not normallyreported)
35ID_SARC_UUE_STORAGE
CMZ archive36ID_SARC_CMZ_STORAGE
Compressed PowerPoint 97 (notnormally reported)
37ID_SARC_PP97_STORAGE
Mac Binhex38ID_SARC_HQX_STORAGE
MacBinary file39ID_SARC_MBIN_STORAGE
Microsoft Cabinet archive3aID_SARC_CAB_STORAGE
MS Mail winmail.dat file3bID_SARC_TNEF_STORAGE
27
supplement
DescriptionValue (hex)Storage ID name
LHA archive3cID_SARC_LHA_STORAGE
MsCompress file3dID_SARC_MS_STORAGE
MSO/Active MIME3eID_SARC_MSO_STORAGE
AppleSingle/AppleDoublepackaged file
3fID_SARC_APPLE_STORAGE
PDF (not normally reported)41ID_SARC_PDF_STORAGE
BZip2 archive42ID_SARC_BZIP2_STORAGE
Stuffit version 7 (compressionversion 5) archive
43ID_SARC_STF5_STORAGE
Older format Stuffit archive44ID_SARC_STF1_STORAGE
InstallShield Cabinet archive45ID_SARC_ICAB_STORAGE
Microsoft Compressed Help file46ID_SARC_ITSS_STORAGE
Stuffit version 8 archive47ID_SARC_STF8_STORAGE
XML-based Office file format48ID_ODOC_STORAGE
SIS archive49ID_SARC_SIS_STORAGE
'Sparse' tar file4cID_SARC_SPARSETAR_STG
DIET self-extracting executable50ID_SEXP_DIET_STORAGE
PKLite self-extracting executable51ID_SEXP_PKLT_STORAGE
LZEX self-extracting executable52ID_SEXP_LZEX_STORAGE
UPX self-extracting executable53ID_SEXP_UPX_STORAGE
Petite self-extracting executable54ID_SEXP_PETITE_STORAGE
ASPack self-extracting executable55ID_SEXP_ASPACK_STORAGE
FSG self-extracting executable56ID_SEXP_FSG_STORAGE
28
SAV Interface Developer Toolkit
DescriptionValue (hex)Storage ID name
PECompact self-extractingexecutable
57ID_SEXP_PEC_STORAGE
Self-extracting archive58ID_SFX_STORAGE
Concatenated archive file59ID_CONCAT_STORAGE
DOS/Windows executable file60ID_EXEC_STORAGE
Unix/Linux executable file68ID_ELF_STORAGE
Mach-O executable file6dID_MACHO_STORAGE
EPOC executable7cID_EPOC_STORAGE
Windows Help file90ID_HELP_STORAGE
JPG image file91ID_CLEAN_JPG_STORAGE
Bitmap image file92ID_CLEAN_BMP_STORAGE
GIF image file93ID_CLEAN_GIF_STORAGE
RIFF media file94ID_CLEAN_RIFF_STORAGE
TIFF image file95ID_CLEAN_TIFF_STORAGE
PNG image file96ID_CLEAN_PNG_STORAGE
MP3 audio file97ID_MP3_STORAGE
MPEG video file98ID_MPEG_STORAGE
“Loopback” (encoded file system)file
a0ID_LPBK_STORAGE
Word Basic macrosb0ID_COMP_WORD_STORAGE
Excel 95 macrosb1ID_COMP_VBA3_STORAGE
Visual Basic as used in Office 97or later
b2ID_COMP_VBA5_STORAGE
ProcessedID_COMP_VBA5_STORAGE type(SAVI internal type)
b3ID_COMP_VB5D_STORAGE
29
supplement
DescriptionValue (hex)Storage ID name
Excel 95 formulaeb4ID_COMP_XF95_STORAGE
Excel 97 formulaeb5ID_COMP_XF97_STORAGE
PowerPoint 97 (not normallyreported)
b6ID_COMP_PP97_STORAGE
Embedded document in OLE2 file(not normally reported)
b8ID_COMP_SCRP_STORAGE
Visio file (not normally reported)b9ID_COMP_VISIO_STORAGE
Visual Basic p-codebaID_COMP_VB5P_STORAGE
MIME encodingd0ID_MIME_STORAGE
Base64 encodingd1ID_BASE64_STORAGE
RTF filed4ID_RTF_STORAGE
Encoded Visual Basic filed8ID_VBE_STORAGE
HTML filed9ID_HTML_STORAGE
Outlook Express (Windows) filedaID_OEDBX_STORAGE
Outlook Express (Mac) filedbID_OEMAC_STORAGE
Big-endian UTF16 characterencoding
ddID_UTF16BE_STORAGE
Little-endian UTF16 characterencoding
deID_UTF16LE_STORAGE
Unix 'mbox' mail store filedfID_MBOX_STORAGE
Mac data fork (not normallyreported)
f0ID_MAC_STORAGE
Mac resource fork (not normallyreported)
f3ID_MAC_RES_STORAGE
Palm OS resource file (notnormally reported)
f4ID_PRC_RES_STORAGE
Java byte code class filef5ID_JAVA_STORAGE
30
SAV Interface Developer Toolkit
DescriptionValue (hex)Storage ID name
Access database file (MDB format)f6ID_ACCESS_STORAGE
Unix ar or cpio archivef7ID_UNIXARCHIVE_STORAGE
RedHat Package Manager filef8ID_RPM_STORAGE
XML filef9ID_XML_STORAGE
OpenDocument file (StarOffice/OpenOffice)
faID_XMLODOC_STORAGE
Apple Mac. HFS+ filesystemfbID_HFS_STORAGE
Apple Mac. DMG filesystem imagefcID_SARC_DMG_STORAGE
VMS 'Saveset' archive110ID_SAVESET_STORAGE
VMS variable-length text file112ID_VARIABLE
31
supplement
5 Data types
Invalid typeSOPHOS_TYPE_INVALID
Unsigned byte (8 bits)SOPHOS_TYPE_U08
Unsigned short (16 bits)SOPHOS_TYPE_U16
Unsigned long (32 bits) - normally used for statussettings
SOPHOS_TYPE_U32
Signed byte (8 bits)SOPHOS_TYPE_S08
Signed short (16 bits)SOPHOS_TYPE_S16
Signed long (32 bits)SOPHOS_TYPE_S32
Not usedSOPHOS_TYPE_BOOLEAN
Not usedSOPHOS_TYPE_BYTESTREAM
Group option (32 bits)SOPHOS_TYPE_OPTION_GROUP
StringSOPHOS_TYPE_STRING
32
SAV Interface Developer Toolkit
6 Technical supportYou can find technical support for Sophos products in any of these ways:
■ Visit the SophosTalk community at community.sophos.com/ and search for other users whoare experiencing the same problem.
■ Visit the Sophos support knowledgebase at www.sophos.com/en-us/support.aspx.
■ Download the product documentation at www.sophos.com/en-us/support/documentation.aspx.
■ Open a ticket with our support team athttps://secure2.sophos.com/support/contact-support/support-query.aspx.
33
supplement
7 Legal noticesCopyright © 2008–2015 Sophos Limited. All rights reserved. No part of this publication may bereproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic,mechanical, photocopying, recording or otherwise unless you are either a valid licensee wherethe documentation can be reproduced in accordance with the license terms or you otherwise havethe prior permission in writing of the copyright owner.
Sophos and Sophos Anti-Virus are registered trademarks of Sophos Limited and Sophos Group.All other product and company names mentioned are trademarks or registered trademarks oftheir respective owners.
34
SAV Interface Developer Toolkit