Introduction to the Antivirus API Reference for Office

Applies to: Office 2007 | Office 2010 | Office 2013 | Office 2016

In this article
Office Antivirus Component Implementation
Antivirus Scanner Implementation Considerations
Registry Keys That Determine How Encrypted Macros Are Scanned
Component Category Handling

The Antivirus API for Office 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.

   Note

   Item 1 is done only if component category {56FFCC30-D398-11D0-B2AE-00A0C908FA49} is created. Starting with Windows 10 build 16214, Windows will set create this component category. Please see Component Category Handling.

2. Start the installed components.

3. Query for the IOfficeAntiVirus interface.

   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.

• Register with Windows Defender Security Center

  Third party antivirus providers must disable Windows Defender by registering their antivirus software with Windows Security Center (WSC) after installation, more details are available via the Microsoft Virus Initiative (MVI) If the antivirus is not registered with WSC then Office will continue to use Windows Defender for document scanning via the IOfficeAntivirus interface.

Registry Keys That Determine How Encrypted Macros Are Scanned

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

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

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

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

Component Category Handling

Starting with Windows 10 build 16214, Windows will create the following component category: HKEY_CLASSES_ROOT\Component Categories\56FFCC30-D398-11D0-B2AE-00A0C908FA49 AV products shouldn’t change this key, nor should they remove this key on uninstall. AV products should still follow the CLSID handling as mentioned previously.