Overview: Virus Scan Engine API Implementation

Applies to: SharePoint Foundation 2010

To support antivirus protection, Windows SharePoint Services 3.0 uses an API named SP VS API 1.4, the Microsoft Office SharePoint Virus Scan Engine (VSE) API, that is based on the Microsoft Exchange Server VS API 2.0. SP VS API 1.4 incorporates much of the original design but is optimized for speed in a Microsoft SQL Server environment. This is achieved by creating a lower-level API that integrates directly into the File/Save and File/Open paths of Windows SharePoint Services 3.0, and also by eliminating the dependencies of the VS API 2.0 on the Messaging Application Programming Interface (MAPI).

Because Windows SharePoint Services 3.0 is a SQL document store, not a mail store, documents are scanned in real time when they are saved (uploaded) or opened (downloaded), and the user is given the result of that scan instantly. By default Windows SharePoint Services 3.0 does not support manual scanning, which is commonly called "background" or "scheduled scanning."

SP VS API 1.4 Architecture

Windows SharePoint Services 3.0 uses an architecture that exposes SP VS API 1.0 as a COM layer for the antivirus vendor component (the VSE) to communicate with the Antivirus Manager (AVM) that is managed by Windows SharePoint Services 3.0.

The logic used by the AVM to process files is designed to do the following:

• Support two request types: upload (save) and download (open).

• Get file properties from the Windows SharePoint Services 3.0 database that indicate scanned status.

• Evaluate how to process a file by using its properties to determine whether to scan it.

• Issue the appropriate UI for the appropriate context and environment (Web page or application dialog box) or complete the desired action (open or save).

• Store file properties that indicate scanned status back to the Windows SharePoint Services 3.0 database.

The AVM logic design eliminates the need for the VSE to actually read or write directly to the database, because this functionality is managed by internal AVM processes. This design also enables the AVM to determine what action to take for each file, depending on the status codes returned by the VSE after scanning and cleaning the file.

VSE Setup and Live Update

The VSE must be a module that runs in a Web server process space and scans incoming and outgoing content for virus infection. The VSE instantiates a virus scanner object that is provided by the vendor and manages a pool of threads that call the scanner to perform scanning of content. When the VSE detects new vendor code or a new signature file, it instantiates a new instance of the scanner and begins using it to schedule new requests. When all requests that are using the previous instance finish, the scanning VSE releases the instance. In other words, all instances complete with the old scanner version, while new instances use the latest scanner version. This procedure ensures that no requests are lost or left unfinished during an update. However, this means that the instances that still remain do not complete with the current instance and are consequently re-scanned the next time the file is requested because the version is marked as older.

Scanner Updates using STSADM.EXE

Because of improved security in Windows SharePoint Services 3.0, the registry key update has been changed. A timer job (Virus Scanner Update) checks the antivirus status of each front-end Web server and updates each server when necessary. Like any timer job in Windows SharePoint Services 3.0, this timer job can be configured to run at a specified time interval. By default, it runs every 5 minutes.

The update key still functions as it did in Windows SharePoint Services 2.0 for backward compatibility, but the Windows SharePoint Services 3.0 Administration Service must be running because it enables the timer job to run. When set, the key increments the avvendorid and avvendorupdatecount values by one. In "Single-Click" installations of Windows SharePoint Services 3.0, the Administration Service is disabled by default and therefore might not be running.

To avoid complications and uncertainty about whether the timer job is running in Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007, we recommend that you use STSADM.EXE to trigger updates. This approach works regardless of whether the Administration Service is running.

By using STSADM.EXE you can get the current values of the vendor information that is installed and update those values. For information about how to use STSADM.EXE, see Introducing the Administration Tools for Windows SharePoint Services.

The following table lists the relevant new commands for scanner updates.

You must set avvendorupdatecount to permit the avvendorid command to be recognized by the system; otherwise, you must first reset Microsoft Internet Information Services (IIS) to permit avvendorid to take effect. The following commands provide a few examples:

stsadm -o getproperty -pn avvendorid
stsadm -o getproperty -pn avvendorupdatecount
stsadm -o setproperty -pn pn avvendorid -pv [numericvalue]
stsadm -o setproperty -pn avvendorupdatecount -pv [numericvalue]

Scanner Updates using the Registry

As stated previously, this mechanism is not recommended for new scanners and exists only for backward compatibility.

The VSE searches for a parameter that determines the configuration of the virus scanning solution from the vendor. This value is located in the system registry under the VSE configuration section, as in the following:

[HKLM\Software\Microsoft\Shared Tools\Web Server Extensions\AVScanner]

The parameter is a REG_SZ value that contains the CLSID of the class object implementing IMso_VirusScanner in registry format. VSE uses this value to instantiate the object. The following example shows the format of the registry value:

CLSID = "{00020906-0000-0000-C000-000000000046}"

Live Updates using the Registry

The VSE has a separate thread that receives notifications when the registry configuration section changes. The VSE initiates a scanner reload, which includes instantiating the updated CLSID and initializing with new parameters, when it finds the specific value in the VSE registry configuration section:

Update = DWORD:00000001

The VSE resets the value to 0 (zero) when the reload is complete.

Virus Signature Update Requirements

The signature update must perform vendor-specific actions to:

• Install new data files on the computer.

• Notify the VSE by setting the Update value to 1.

Virus Scanner Update Requirements

The code update must perform vendor-specific installation actions to:

• Install the new code bits on the computer.

• Modify the VSE CLSID value to point to the new class object.

• Notify VSE by setting the Update value to 1.

Layout of the VSE Registry

Following is the VSE configuration registry path:

[HKLM\Software\Microsoft\Shared Tools\Web Server Extensions\AVScanner]

The following table shows the values used for the VSE registry.

For a description of the interface that must be provided in the VSE, see Virus Scan Engine API.

Settings Page Updates

Whenever the antivirus administration page settings are updated, Windows SharePoint Services 3.0 increments avvendorid and avvendorupdatecount values by 1.

Antivirus Properties

Use the properties listed in the following table to configure antivirus protection for your server. Specify whether antivirus cleaning is enabled, whether the download and upload scans are enabled, the timeout time for scanning, the number of threads to take up with antivirus processes, and whether users can download potentially infected documents to their client computers.

Large File Support

Windows SharePoint Services 3.0 supports large files, and it also supports antivirus protection for these files.

To improve performance, try to create files as chunks so that they do not return to memory before being scanned. Keep in mind that large files can take a long time to scan, and that they may require the default timeout settings of the server or IIS to be increased to allow the scanner to complete its work.

64-Bit Support

Windows SharePoint Services 3.0 supports 64-bit systems. Existing scanners might need to be updated to support 64-bit systems and should be verified separately.