sav interface developer toolkit supplement · 1 about this supplement this supplement documents the...

34
SAV Interface Developer Toolkit supplement 4.9 Product version: April 2015 Document date:

Upload: truongquynh

Post on 28-Apr-2019

232 views

Category:

Documents


0 download

TRANSCRIPT

SAV Interface DeveloperToolkitsupplement

4.9Product version:April 2015Document date:

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