Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Introduction to the Antivirus API Reference for Office 2010

Office 2010

Last modified: July 13, 2010

Applies to: Office 2007 | Office 2010

The Antivirus API for Office 2010 enables software vendors to develop applications that scan Microsoft Office documents before they open them. The main purpose of this API is to give an independent software vendor (ISV) the ability to design and implement scanning software that can be used by all applications.

Download the Msoav.h header file for the Antivirus API: Office Sample: Antivirus API for Office 2010 Header File: Msoav.h

Office Antivirus Component Implementation

The antivirus component is a standard COM component that you register as an in-process server that supports the MSOfficeAntiViruscomponent category. A component category is a group of logically-related COM classes that share a common category ID or category identifier (CATID). The antivirus software does not provide a user interface, but does scan Microsoft Office files before it opens them.

Microsoft Office implements the antivirus component as follows:

  1. Obtain the list of all the installed antivirus components registered as supporting the MSOfficeAntiVirus component category.

  2. Start the installed components.

  3. Query for the IOfficeAntiVirus interface.

    Note Note

    Items 2 and 3 are performed sequentially for each registered antivirus scanner and, if any scanner fails, successive scanners are not called. In this sense, it is not certain that a scanner will be called.

  4. Call the IOfficeAntiVirus::Scan method to obtain all the installed components.

  5. If the antivirus scanner returns an HRESULT value that indicates failure, Microsoft Office will block the file from opening. Otherwise, the file can open. For more information about registry keys that control how documents that contain encrypted macros are scanned, see Registry Keys That Determine How Encrypted Macros Are Scanned.

Antivirus Scanner Implementation Considerations

Microsoft Office does not provide a UI for the antivirus component. However, a virus scanner software vendor may provide the user options and settings, a splash screen, or a progress indicator.

Developers who want to implement UI features for the antivirus scanner should consider the following programming considerations:

  • Opening a file through Automation

    When you use Automation to open a file programmatically, be aware that the open operation never returns a run-time error and macros do not receive a result of the virus scan.

  • Uninstalling

    Virus scanners must support an uninstall program that removes the MSOfficeAntiVirus CATID registry key from the COM CLSID registration for the antivirus scanning program. Typically this is located at HKEY_CLASSES_ROOT\CLSID\<CLSID of the antivirus scanning program>\Implemented Categories\{56FFCC30-D398-11D0-B2AE-00A0C908FA49} (for example, HKEY_CLASSES_ROOT\CLSID\{781761E2-8E02-1094-9FE9-9D127C57AFEB}\Implemented Categories\{56FFCC30-D398-11D0-B2AE-00A0C908FA49}). If a virus scanner is reinstalled in a new directory, the registry must be updated. Be aware that Microsoft Office does not warn the user that a virus scanner is not found.

  • Scanning digitally signed files

    The Antivirus API is called before the host application verifies the digital signature of the document. If an antivirus scanner removes a virus from a signed document, it must remove the signature also.

  • Scanning downloaded code files

    When code is downloaded from a website, the virus scanner opens a temporary file. The virus scanner should inform the user that removing a virus from a temporary file does not clean the file on the HTTP server.

The registry subkeys in Table 1 determine how Office scans macros in Word, Excel, and PowerPoint macro-enabled document formats (.docm, .xlsm, and .pptm) that have been encrypted. In Microsoft Office 2010, Word, Excel, and PowerPoint macro-enabled document formats that contain macros can be encrypted by clicking the File tab, clicking Protect <Document, Workbook, or Presentation> on the Info tab, and then clicking one of the following commands:

  • Restrict Permission by People, and then select any of the options other than Unrestricted Access.

  • Encrypt with Password, and then add a password to the document.

In addition, in Excel, using the Protect Workbook, or Protect and Share Workbook commands on the Review tab of the ribbon will encrypt macro-enabled workbooks.

Table 1. Registry Subkeys That Determine How Encrypted Macros Are Scanned

Key

Value name

Value type

HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Excel\Security

ExcelBypassEncryptedMacroScan

REG_DWORD

HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Word\Security

WordBypassEncryptedMacroScan

REG_DWORD

HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\PowerPoint\Security

PowerPointBypassEncryptedMacroScan

REG_DWORD

The following table lists how the value set for an ExcelBypassEncryptedMacroScan, WordBypassEncryptedMacroScan, or PowerPointBypassEncryptedMacroScan entry affects Microsoft Office macro security behavior when antivirus scanning software is (or is not) installed. The default value is 1.

Table 2. BypassEncryptedMacroScan Entry Values

Value

Antivirus scanning software installed

Result

0

Yes

Calls the antivirus scanner software. If the antivirus scanning software detects a virus, all macros in the document are blocked.

0

No

Blocks macros in all documents.

1

Yes

Calls the antivirus scanner software. If the antivirus scanning software detects a virus, all macros in the document are blocked.

1

No

Does not block macros in documents.

2

Yes

Does not call the antivirus scanning software. Does not block macros in documents.

2

No

Does not block macros in documents.

The following table lists each value (0, 1, or 2) for the ExcelBypassEncryptedMacroScan, WordBypassEncryptedMacroScan, or PowerPointBypassEncryptedMacroScan entry. These values affect Microsoft Office macro security behavior.

Table 3. Summary of BypassEncryptedMacroScan Entry Value Behavior

Value

Description

0

This is designed to be the most secure setting. If no antivirus scanning software is installed, macros in all files are blocked. If antivirus scanning software is installed, any macros that are declared unsafe by the antivirus software are blocked.

1

This is the default setting. If antivirus scanning software is installed, any macros that the antivirus software declares are unsafe are blocked. Allows everything else to open. If there is no antivirus scanning software installed, all documents can be opened.

2

All antivirus scans are skipped. All documents are opened without even trying to scan.

Important note Important

In Table 2, "Antivirus scanning software installed" means that if a 32-bit antivirus software program is installed on a computer that is running on a 64-bit OS (that is, the program is installed and registered in the 32-bit registry), the 32-bit version of Microsoft Office will detect the antivirus software as installed, whereas the 64-bit version of Microsoft Office will not. Installing and registering a 32-bit antivirus software program in the 64-bit registry will cause the 64-bit version of Microsoft Office to detect the antivirus program as installed. However, the 64-bit version of Microsoft Office will be unable to use it. Table 4 lists each OS, antivirus installation, and registration permutation and its effect in Microsoft Office 2010.

Table 4. Summary of the Effect of OS, Antivirus Installation, and Registration

OS

Antivirus program

Antivirus program registration

Office

Description

32-bit

32-bit

32-bit

32-bit

Office detects and uses the antivirus scanning software.

64-bit

32-bit

32-bit

32-bit

Office detects and uses the antivirus scanning software.

64-bit

64-bit

64-bit

64-bit

Office detects and uses the antivirus scanning software.

32-bit

Any

Any

64-bit

64-bit Office cannot be installed on a 32-bit OS.

32-bit

64-bit

Any

Any

64-bit antivirus software cannot be installed on a 32-bit OS.

64-bit

32-bit

32-bit

64-bit

Office will not detect or use the antivirus scanning software.

64-bit

32-bit

64-bit

32-bit

Office will not detect or use the antivirus scanning software. 32-bit versions of antivirus software should not be registered as 64-bit COM components.

64-bit

64-bit

64-bit

32-bit

Office will not detect or use the antivirus scanning software.

64-bit

32-bit

64-bit

64-bit

Office will detect the antivirus scanning software but cannot use it. 32-bit versions of antivirus software should not be registered as 64-bit COM components.

64-bit

64-bit

32-bit

32-bit

Office will detect the antivirus scanning software but cannot use it. 64-bit versions of antivirus software should not be registered as 32-bit COM components.

Show:
© 2015 Microsoft