Microsoft KB Archive/263949

XADM: Understanding How the Antivirus API Scans Attachments

Q263949

The information in this article applies to:

Microsoft Exchange Server, version 5.5 SP3

SUMMARY

This article is intended to help Exchange Server administrators understand the architecture of the new antivirus application programming interface (API) that is introduced in Exchange Server 5.5 Service Pack 3 (SP3), and possible effects that any third-party software that uses the antivirus API may have.

MORE INFORMATION

Background

The antivirus API was introduced in Exchange Server 5.5 SP3 to allow independent software vendors (ISVs) to develop antivirus solutions to scan attachments in the Exchange Server information store. The antivirus API ensures that all attachments are scanned before a client has access to the attachment. This is accomplished by hooking the attachment at a very low level within the information store. The antivirus API gives vendors the ability to selectively repair, mark as suspicious, or replace any attachment.

How It Works

When the information store starts, or periodically while the information store is running (approximately every minute), the information store searches the registry for changes to specific keys, notably the Enabled key, which signals whether the antivirus API functionality is enabled or disabled. If the antivirus API functionality is enabled, the information store queries the value in the Library key to determine the appropriate vendor's dynamic link library (DLL) to load. After the vendor's DLL is enabled, two additional tasks start internally in the information store.

The first task is an additional check of attachments. When an attachment is new, modified, or has not been scanned by the current DLL specification (that is, Vendor or Version registry key change), the attachment is inserted into a queue of attachments to be processed by the third-party vendor's DLL. Checks on attachments occur when users perform the following actions:

A client sends a new message that contains an attachment.
An existing attachment in a message is modified and saved.
A client attempts to open an attachment in a message.

The second task is a background scan of attachments in the information store. A comparison is made for each attachment in the information store to determine if the attachments have been scanned by the current version of the DLL. This process starts with the first attachment in the information store and continues until the last attachment has been reached. New attachments that arrive are scanned as the client gains access to those attachments, and do not need to be scanned by the background process. During the background scan of attachments, if an attachment is located that has not been scanned by the current DLL, that attachment is submitted to the DLL to be scanned. It is important to note the background scan process cannot be scheduled. When the last attachment has been reached, the background scanning process "sleeps" until one of the following conditions are met:

A modification takes place to the Vendor registry key.
The change in the value for the Version registry key.
A modification takes place to the Parameters registry key.
You restart the information store.

The Benefits

The architecture of the antivirus API offers vendors very high-speed access to data in the information store. Because the vendor solution can run in process with the information store, performance is greatly improved over traditional solutions, such as MAPI-based scanning or other interprocess communication methods. In addition, each attachment is guaranteed to be scanned before a client gains access to the attachment.

Controlling the Antivirus API

After you install a vendor's solution, you may need to fine-tune the behavior of the antivirus API. The following is a list of supported registry keys that govern the behavior of the antivirus API. As noted before, make sure that you consult your vendor to determine the effects that changes to these keys may have on the vendor's antivirus software:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIS\VirusScan

The following registry values can be found under this registry key:

Value Name: Enabled

Data Type: REG_DWORD
Radix: DECIMAL
Value: 1 = Enabled 0 = Disabled (Default)

Description: This value determines if the antivirus API is in use. If this value is enabled, the information store attempts to load the DLL that is specified in the Library key. This value is examined approximately every minute for changes.

Value Name: Vendor

Data Type: REG_SZ
Value:

Description: This value represents a unique string that is used to identify the vendor of the DLL. This value is used to determine if attachments need to be rescanned because the vendor has changed. If this value is modified, all attachments in the information store are rescanned. This occurs as part of the initial background scan or when attachments are requested.

Value Name: Version

Data Type: REG_DWORD
Radix: Decimal
Value:

Description: This value is used by the vendor to identify changes that have been made to the virus signature file or version of software. Any increases in this value cause the information store to rescan all attachments in the information store.

Value Name: Library

Data Type: REG_SZ
Value: (Path to DLL)

Description: This string is the path and name of the DLL that the information store loads. The information store periodically (approximately every minute) checks for changes in this value, and unloads and reloads the DLL that is specified if the value changes, without stopping the information store.

Value Name: Parameters

Data Type: REG_SZ
Value:

Description: This string is a collection of vendor-specific options that the information store sends to the DLL. The information store does not process these options, but simply sends the options to the specified DLL to be interpreted. This registry key never needs to be adjusted because the key is specific to the vendor.

Value Name: OpenRetryDelay

Data Type: REG_DWORD
Radix: Decimal
Value: 500 (default)

Description: The time interval in milliseconds that the information store pauses before the information store attempts to reopen an attachment that is currently being scanned when the attachment is requested by the client. If this value is set too high, clients may time out, but if this value is set too low, additional processing overhead by the information store may occur.

Value Name: BackgroundScanning

Data Type: REG_DWORD
Radix: Decimal
Value: 1 (default)

Description: This value indicates whether the information store needs to scan the attachments table to locate attachments that have not been scanned by the current vendor or if a version change has been made. After a complete scan of the attachment table has been made, no further scanning occurs unless certain conditions outlined in the "How It Works" section of this article are met. If this process is forced by adjusting the registry key, messages may be rescanned, which causes additional processing overhead and inaccessible attachments for short periods.

Value Name: SendRetries

Data Type: REG_DWORD
Radix: Decimal
Value: 2 (default)

Description: When a client is sending a message that contains an attachment, the attachment must be scanned before the message is sent. If the message delivery process determines that the attachment is currently being scanned, this value is the number of times the information store attempts to resend the message, including the first attempt to deliver the message. If this value is increased, that only provides more opportunities for messages to be processed. This value, coupled with the value of SendRetryInterval, may cause extended delivery times.

Value Name: SendRetryInterval

Data Type: REG_DWORD
Radix: Decimal
Value: 60000 (default)

Description: When a message is being sent that currently has an attachment that is being scanned, this is the interval in milliseconds that the information store waits before the information store attempts to redeliver the message. If this value is set too high, there may be delays in sending messages. If this value is set too low, messages may expire from the sending queue because the number of send retries may be exceeded before the message completes the scan process.

Other Considerations

If you are considering a move to third-party products that use the antivirus API, you must be aware that issues may arise that may seem related to performance of the information store. Based on the architecture of the antivirus API, the speed at which attachments are scanned is bound by the vendor's implementation of the scanning DLL. In addition, because third-party vendor's solutions run in process with the information store service, issues (such as memory or processor use and access violations in the Store.exe program) may become harder to troubleshoot because there is no way to distinguish between the information store and the vendor's DLL.

Other processes and operations that rely on e-mail and attachments to send data may also be affected. The most common effect is an increased latency. In the Exchange Server environment, you may notice the following issues:

Increased latency of directory and public folder replication.
Offline folder (*.ost) synchronization time-outs.
Inaccessible attachments.
Messages that seem to be stuck in the Outbox.

Suggested Troubleshooting Steps

The following is a list of troubleshooting steps that may help you isolate issues when products are involved that use the antivirus API:

Change the value in the Enabled registry entry to disable the antivirus API. Consider the ramifications carefully before you disable the antivirus API, because you may cause attachments to be rescanned. Also, a vendor's software may be monitoring this key and may automatically re-enable the key. If you disable the key, allow at least two minutes for the information store to detect changes in the value before you test.
If possible, change the vendor's software to MAPI-based scanning and determine if the issue continues to occur. If you select MAPI-based scanning, be aware that the vendor's software may not scan all attachments because first and exclusive access is not guaranteed.
If the preceding steps do not yield noticeable results, you must remove the vendor's software. Then verify that the API is disabled by examining the registry key and allowing time for the information store to detect the changes in the registry.

For additional information about fixes to the antivirus API, click the article number below to view the article in the Microsoft Knowledge Base:

Q248838 XADM: Exchange Server 5.5 Post-SP3 Information Store Fixes Available

Additional query words: AVAPI Anti-Virus API

Keywords : exc55sp3
Issue type : kbinfo
Technology : kbExchangeSearch kbExchange550 kbZNotKeyword2