Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Code Signing Office XP Visual Basic for Applications Macro Projects

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
 

Siew-Moi Khor
Microsoft Corporation

August 2002

Applies to:
   Microsoft® Office XP
   Microsoft Visual Basic® for Applications

Summary: This article describes how to add a digital signature to a Microsoft Visual Basic for Applications (VBA) macro project in Microsoft Office XP.

Contents

Introduction
Why Code Sign a VBA Project?
Procedure to Digitally Code Sign a VBA Project
Install SelftCert.exe Program
   Create a Test Certificate
   Sign the VBA Project
   Prepare Office XP Security Settings
   Test the Digitally Signed VBA Project
Trusted Sources
Additional Notes
   Making Changes to a File
   Time-Stamping and Certificate Expiration
   Resigning VBA Macro Projects
   Microsoft Outlook 2002
   Use Microsoft Authenticode to Generate Test Certificates
Conclusion

Introduction

In this article, I will describe and discuss the steps involved in digitally signing a Microsoft Office XP Visual Basic for Applications (VBA) macro project.

A digital signature on a VBA macro project is an electronic, cryptographic-based, secure stamp of authentication. This signature confirms that the VBA macro project originated from the signer and has not been altered. When you add a digital signature to a VBA macro project, you are supplying a verifiable signature that can vouch for the authenticity and integrity of the VBA macro project.

You can digitally sign macros without understanding public key cryptography, which is the cryptographic method used in digital signatures. Public key cryptography is a very interesting topic and might be worth your time exploring. I have compiled a list of references at the end of the article where you can go for more information on topics related to public key cryptography, digital code signing, security, and so on.

Why Code Sign a VBA Project?

These days, emphasis on security is an integral part of most organizations' overall IT strategies. Many security-conscious users and administrators set their Microsoft Office XP security level to High, with the Trust all installed add-ins and templates check box cleared, which is highly recommended (see the Prepare Office XP Security Settings section to find out how to set security levels). If you are unfamiliar with the security setting options in Office XP, please refer to Table 1 below.

Digitally signing a VBA macro project has many benefits. By digitally signing the VBA macro projects you intend to publicly distribute, users of your solutions can be assured of the macro creator's identity and that the macro has not been altered since it was created.

In addition, as described in Table 1 below, when the security level is set to High and the Trust all installed add-ins and templates check box cleared, a signed and trusted VBA macro project will be loaded, and a non-signed (which makes it non-trusted) VBA macro project will be disabled automatically. The only time a user will be prompted to either enable or disable a VBA macro project is when the software publisher is not in the trusted sources list.

Aa163622.odc_dsvbaxxx(en-us,office.10).gif

Table 1. Microsoft Office XP Security Settings matrix.

Table 1 above lists the available Microsoft Office XP security settings, along with their corresponding behaviors, in the Security dialog box (Macros submenu, Tools menu).

Note   The availability of, and options within, the Security dialog box varies depending on the specific Office application. Additionally, specific Office applications silently load signed add-ins and macros only from specific directories, along with registered COM add-ins and smart tags recognizers. For more information, see the Microsoft Office XP Macro Security White Paper.

Procedure to Digitally Code Sign a VBA Project

I have broken down the process of digital code signing a VBA project to five main steps as listed below. Note that in step 3 below, which is the signing of the VBA macro project, you must have a macro project that is ready for release to end users to use for signing.

  1. Install the selfcert.exe program.
  2. Create a test certificate.
  3. Sign a VBA macro project.
  4. Prepare Office XP security settings.
  5. Test the digitally signed VBA macro project.

Install the Selfcert.exe Program

Microsoft Office XP includes a program that you can use to create test self-signed certificates for signing Microsoft Visual Basic for Applications (VBA) projects. The program is called SelfCert.exe. You should only use a self-signed certificate for personal use.

Note   Digital signatures that are created with the SelfCert.exe program are for personal use only. They are not meant for commercial distribution of VBA macro solutions. The type of certificate that is generated does not verify your identity.

The SelfCert.exe program is not part of the standard installation of Microsoft Office XP. To install the SelfCert.exe program, do the following:

  1. Rerun the Office XP setup CD or other installation media.
  2. In the Microsoft Office XP Setup dialog box, click the Add or Remove Features option. Click Next.
  3. Expand the Office Shared Features node by clicking the plus sign (+) next to it.
  4. Click Digital Signature for VBA Projects.
  5. Click Run from My Computer.
  6. Click Update to install the SelfCert.exe program.
  7. Click OK at the completion of the installation.

Create a Test Certificate

For public distribution, you will need to purchase a valid certificate from a Certification Authority (CA). The certificates generated in this tutorial are test certificates and should be used for testing purposes only. They should not be used to code sign files that will be publicly distributed. This is because since the certificates are not issued by a CA whose root certificate is already trusted on a user's machine, the test certificate will not validate correctly on the user's machine. Independent software vendors can obtain valid certificates from VeriSign, GTE, or other certification authorities to digitally sign code files that will be distributed to the public. The Frequently Asked Questions About Authenticode has more information on how to do this.

To create a test certificate to sign your Microsoft Office XP VBA projects, the steps are as follows:

  1. In Microsoft Windows® Explorer, locate the directory where you installed Microsoft Office XP, the default folder is Drive:\Program Files\Microsoft Office\Office 10.
  2. Find the SelfCert.exe program and double-click it. This displays the Create Digital Certificate dialog box.
  3. In the Your name box, type the name you would like to give to this particular test certificate that you are creating. In this example, I've named the test certificate Jay Adams SelfCert Test Certificate as can be seen in Figure 1.
  4. Click OK.

Aa163622.odc_dsvba01(en-us,office.10).gif

Figure 1. Creating a test certificate using SelfCert.exe.

Sign a VBA Macro Project

To sign a VBA macro project, the steps are as below:

  1. Open the file that contains the VBA macro project that you want to digitally sign. To make it easy to reference this file later in this article, the example I'm going to use is a Microsoft Excel 2002 workbook that contains a VBA macro project.
  2. On the Tools menu, point to Macro, and then click Visual Basic Editor.
  3. In the Project Explorer window, select the VBA macro project that you want to digitally sign.
  4. On the Tools menu, click Digital Signature. This displays the Digital Signature dialog box.
  5. Click Choose to select a digital certificate. This displays the Select Certificate dialog box as shown in Figure 2.

Aa163622.odc_dsvba02(en-us,office.10).gif

Figure 2. Digital certificate selection dialog box.

  1. Select the Jay Adams SelfCert Test Certificate you just created in step 3 in the Create a Test Certificate procedure above.
  2. Click OK twice.
  3. Quit Excel.

Prepare Office XP Security Settings

Before you can test the signed Excel 2002 VBA macro project, the security settings in Excel 2002 should be set to High, with the Trust all installed add-ins and templates check box cleared.

Note This will disable all your add-ins and templates that are not code signed as described in Table 1.

To change security settings:

  1. Start Excel 2002.
  2. Click Tools, point to Macro, and then click Security. This displays the Security dialog box.
  3. Set the Security Level to High.
  4. Click the Trusted Sources tab. Uncheck Trust all installed add-ins and templates.
  5. Click OK.
  6. Quit Excel.

Test the Digitally Signed VBA Macro Project

When you have completed this, do the following:

  1. Open the Excel workbook that contains the signed VBA macro project. You will see a Security Warning dialog box warning regarding the digitally signed macro with the issuing authority specified, as shown in Figure 3 below.

Aa163622.odc_dsvba03(en-us,office.10).gif

Figure 3. Security Warning dialog box.

Note   To view details about the digital signature, click Details. This displays the Digital Signature Details dialog box as shown in Figure 4. If you click on the Advanced tab, you will be able to view the Signature details as shown in Figure 5. To view the certificate, on the General tab, click View Certificate.

Aa163622.odc_dsvba04(en-us,office.10).gif

Figure 4. Digital Signature Details dialog box.

Note   Take a close look at the message A certificate chain processed correctly, but terminated in a root certificate which is not trusted by the trust provider in Figure 4 above. The reason for this particular message is because you are using a test certificate that is not from a trusted CA already on the machine. This is also the reason for the message This publisher has not been authenticated and therefore could be imitated. Do not trust these credentials in the Security Warning dialog box in Figure 3.
Compare the Security Warning dialog box in Figure 3 with Figure 5 which shows the Security Warning dialog box a user would receive if a macro was digitally signed using a valid CA certified certificate.

Aa163622.odc_dsvba05(en-us,office.10).gif

Figure 5. A Security Warning dialog box for a macro digitally signed with a valid certificate.

Aa163622.odc_dsvba06(en-us,office.10).gif

Figure 6. Digital certificate details.

  1. Back in the Security Warning dialog box, note that the Enable Macros button is disabled which means you cannot enable the Excel VBA macro project you just signed. To enable it, you have to first trust the source of the VBA macro project. To trust a source, select the Always trust macros from this source check box. This makes the Enable Macros selection available.
  2. Click Enable Macros. This will load your signed VBA macro project. If you click Disable Macros, the signed Excel VBA macro project is disabled and won't be loaded.
    Note   To check that the certificate you created is installed, click Tools, point to Macro and then click Security. In the Security dialog box, click the Trusted Sources tab. The certificate issued by Jay Adams that you created to code sign the Excel VBA macro project should be in the list of Trusted Sources as shown in Figure 7.

Aa163622.odc_dsvba07(en-us,office.10).gif

Figure 7. Trusted Sources list after the test certificate used to digitally sign the Excel VBA macro project was added to the Always trust macros from this source list.

Note   If you want to retest the enabling and disabling of the digitally signed VBA macro project, remove the Jay Adams SelfCert Test Certificate from the of Trusted Sources list by first highlighting it, and then clicking Remove.

Trusted Sources

To understand what being in a trusted sources list means, do the following:

  1. Leave the Jay Adams SelfCert Test Certificate in the Trusted Sources list (to get there, click Tools, point to Macro, and then click Security. In the Security dialog box, click the Trusted Sources tab).
  2. Code sign another VBA macro project (the VBA macro project can be from any Office XP application) using the same Jay Adams SelfCert Test Certificate.
  3. Close the file containing the VBA macro project you just signed.
  4. Re-open the file.

You will find that you won't be prompted and asked whether you want to enable the VBA macro project when you open it. Instead, the VBA macro project will be loaded without any user intervention. This is because that VBA macro project was digitally signed using a certificate that corresponds with one that is in the list of Trusted Sources certificates.

Additional Notes

The following is some important information related to code signing VBA macro projects to take note of.

Making Changes to a File

You might ask if digitally signing a VBA macro project means you cannot make any further changes to the file (for example a document or workbook) that uses the signed VBA macro template. Changing a document or workbook and resaving it does not invalidate a VBA macro project signature. This is because, when you digitally sign, for example, an Excel VBA macro project, only the Excel VBA macro project is digitally signed, not the whole workbook.

The following scenarios can cause a VBA macro project digital signature to become invalid:

  • You make changes to the VBA macro project itself.
  • You make changes to a document or workbook causing the VBA project to change, for example, if you copy or delete a worksheet in a workbook.

Time-Stamping and Certificate Expiration

Regularly changing digital certificates is good practice as it greatly reduces the susceptibility and opportunity (in terms of length of time) for a malicious attacker to try to derive a digital certificate's private key from its public key.

As such, digital certificate issued by a Certification Authority expires after a certain period of time (usually one year) and therefore must be replaced periodically. Any signature applied to a file or a VBA macro project after the digital certificate expires is invalid.

So that you don't have to resign your VBA macro projects every time your certificate expires, you should add the time when the VBA macro project was code signed to the digital signature. To enable the verification that a signature was applied before the certificate expired, the digital signature should be time-stamped by the Certification Authority that issued the certificate.

That way, even after the certificate has expired, signature verification software (in this example Office XP signature verification feature) will be able to verify that the signature was applied while the certificate was still valid. If you don't include a time-stamp, even though your VBA macro project was signed while the digital certificate was valid, when the digital certificate expires, the validity of the digital signature will expire with it.

For more details about time-stamping Office XP VBA macro project signatures and how to set registry keys so that Office XP will use a time-stamping service with all future digital signatures, see the "Timestamping Office Macro Signatures" section of the Microsoft Office XP Macro Security White Paper.

Resigning VBA Macro Projects

If your organization is using custom VBA macro projects developed by someone external to your organization, you might want to resign the VBA macro projects using your organization's certificate. This way, your organization can restrict the set of custom solutions that the users in your organization can use; in this case, only macros signed using your organization certificate.

Microsoft Outlook 2002

It should be noted that the security model for Microsoft Outlook 2002 differs from other Office XP applications. In addition to a user's security settings, described in Table 1, Outlook 2002 VBA macro projects (regardless of whether they are digitally signed or not) are subjected to the restrictions on certain Outlook 2002 object model property and method calls imposed by the Outlook E-mail Security Update that is an integral component of Outlook 2002. There is no way to bypass these restrictions except if a Microsoft Exchange Server administrator uses the Default Security Settings (Admin.oft) template to lower the Outlook security settings. However, this is not recommended as it also has the side effect of lowering overall security restrictions, including the ability to run viruses.

For more information on the Outlook 2002 Security Update and the Default Security Settings item in the Outlook Security Settings public folder, see:

Use Microsoft Authenticode to Generate Test Certificates

Besides SelfCert.exe, you can also use Microsoft Authenticode® tools to generate test certificates. For detailed information on how to use the Authenticode tools, see the Digital Code Signing Step-by-Step Guide.

Conclusion

As can be seen, the steps involved in signing a VBA macro project are quite straightforward. When you want to test different installation scenarios, the SelfCert.exe program will come in very handy. For example, you can generate as many test certificates to use for signing as you want without having to pay for each of them. And when you are satisfied testing your code using a test certificate, you can then use your valid certificate to sign the code.

For those who are interested to know more about code signing and topics related to security, I have compiled a list of articles related to security for your reference:

Show:
© 2014 Microsoft