Digital Code Signing Step-by-Step Guide

Article
06/14/2014

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

March 2002

Applies to:
Microsoft® Office XP

Summary: Step-by-step instructions on how to digitally sign a smart tag DLL using Microsoft Authenticode technology for testing purposes. The steps can also be used to sign EXEs, OCXs, CABs, and other types of DLLs with slight modifications. (20 printed pages)

Introduction
Why Sign a Smart Tag DLL?
Procedure to Digitally Code Sign a Smart Tag DLL
   Download the Code Signing Executables
   Generate a Test X.509 Certificate
   Create a Software Publishing Certificate (SPC)
   Sign the Smart Tag DLL
   Prepare Office XP Security Settings
   Test the Signed Smart Tag DLL
Trusted Sources
Conclusion
Glossary

Introduction

Microsoft® Authenticode® technology allows software publishers to digitally sign executable (EXE), Microsoft ActiveX® controls (OCX), cabinet (CAB), and dynamic-link library (DLL) files. This article will describe and discuss the steps involved in digitally signing a smart tag DLL using Authenticode for testing purposes. These steps can also be used to digitally sign EXEs, OCXs, CABs, and other types of DLLs with slight modifications; that is, by skipping steps that pertain only to smart tag DLLs.

To learn more about Authenticode, the Frequently Asked Questions About Authenticode is a good place to start. From there, you will find many links to topics related to digital code signing.

It's assumed that the reader knows what a smart tag is and how to install and register a smart tag DLL. To find out more about smart tags, including how to install and register a smart tag DLL, the Microsoft Office XP Smart Tag SDK 1.1 is available for download on MSDN Downloads.

You can digitally sign code files without understanding public key cryptography, which is the encryption method used in digital signatures. To fully understand how digital code signing ensures authenticity and integrity of a code file, one has to understand public key infrastructure (PKI), which is a very big topic by itself. If you are unfamiliar with public key cryptography, the terminologies associated with public key cryptographic concepts and its implementation can be confusing. For easy reference, I have compiled a list of terms used in this article under the Glossary section.

A discussion about public key infrastructure is beyond the scope of this article. A list of references is included at the end of this article where you can go for more information on topics related to digital code signing, security, PKI, and so on.

Why Sign a Smart Tag DLL?

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 default trust all installed add-ins and templates setting disabled, which is highly recommended (see the Prepare Office XP Security Settings section to find out how to set security levels).

Therefore, digitally signing smart tag DLLs has many benefits. A signed and trusted smart tag DLL will be loaded and a non-signed (which makes it non-trusted) smart tag DLL will be disabled automatically. The only time a user will be prompted to either enable or disable a smart tag DLL is when a smart tag DLL is signed but the software publisher is not in the trusted sources list.

Procedure to Digitally Code Sign a Smart Tag DLL

The digital code signing steps have been broken down to six main steps as listed below. Note that in step 4 below which is the signing of the smart tag DLL, you must have an unsigned smart tag DLL that is ready for release to end users to use for signing.

Download the code signing executables needed to digitally sign code files.
Create a test certificate.
Create a Software Publishing Certificate (SPC) file.
Sign the smart tag DLL.
Prepare Office XP security settings.
Test the digitally signed smart tag DLL.

Download the Code Signing Executables

Before you can generate a certificate and sign the smart tag DLL, first you need to install the Microsoft Authenticode for Internet Explorer 5.0 programs from MSDN Downloads.

Download and save the codesign.exe file on the local machine. In this example, save it in a folder named codesign; that is, c:\codesign.
Unzip codesign.exe to the same folder or any folder of your choice. To unzip to the same folder, double-click on codesign.exe. A WinZip Self-Extractor dialog box will be displayed. Type c:\codesign in the Unzip To Folder box.
Click Unzip.

If you examine the c:\codesign folder after you have unzipped the codesign.exe file, you will find eight programs extracted into that folder. For this particular tutorial, you will only be using three programs: makecert.exe, cert2spc.exe, and signCode.msi.

Generate a Test X.509 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 sign code files that will be publicly distributed. 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 certificate for testing purposes, the steps are as follows. From a command prompt, get into the directory containing all the digital code signing executables. This would be the folder you unzipped the codesign.exe file to (in the example above, this would be c:\codesign). To do this, follow the steps below:

Click Start.
Click Run.
Type cmd in the edit box and press Enter.
Type cd\codesign and press Enter, as shown in Figure 1 below.

Figure 1. Changing the directory using the command prompt
Generate an X.509 certificate (conforming to the industry standard X.509 certificate format) using the makecert.exe program. For more information about X.509 certificate and its format, see Appendix B: X.509 Certificate of the Authenticode Appendixes documentation.

The syntax for invoking makecert.exe is:
```
makecert [basic options | extended options] outputFile
```
For this example, use the following command line options to invoke makecert.exe.
```
makecert -sk subjectKey -r -n "CN=<Issuer>,
   OU=<OrgName>,O=<CompanyName>,E=<Email>" 
      –ss subjectCertStoreName saveCertificate.cer
```

The syntax is as follows:

-sk subjectKey The location of the subject's key container which holds the private key. If a key container does not exist, one is created. If neither of the -sk or -sv options is used, a key container called JoeSoft will be created by default.
-r Creates a self-signed certificate.
-n name Name for the publisher's certificate. This name must conform to the X.500 standard. The simplest method is to use "CN=MyName" format. For example: -n "CN=Test".
<Issuer> - Name of the software publisher or issuing authority of the certificate, for example: Jay Adams.
<OrgName> - Name of the organization/department inside the company, for example: Certification.
<CompanyName> - Name of the company, for example: A Datum Corporation.
**-ss subjectCertStoreName **Name of the subject's certificate store where the generated certificate will be stored.
saveCertificate.cer Save the certificate to a file and name the file as saveCertificate.cer.

Type the following syntax after c:\codesign> as shown in Figure 2.

makecert -sk myNewKey -r -n "CN=Jay Adams,
   OU=Certification,O=A Datum Corporation,E=adatum@adatum.com" 
      -ss my myNew.cer

Figure 2. Makecert.exe invocation syntax (click image to see larger picture)

Here is what the syntax means: create a self-signed certificate using the default test root. Also, create a key container (named myNewKey) and output the certificate to both a store (named myNewKey) and a file (named myNew.cer).

For a comprehensive list of command line options for the Authenticode set of programs, see the Signing and Checking Code with Authenticode documentation.

Create a Software Publishing Certificate (SPC)

After generating a test X.509 certificate (myNew.cer in this example), you can now create a Software Publishing Certificate (SPC) using the cert2spc.exe program. The cert2spc.exe program wraps either one or multiple X.509 certificates (depending on the command line syntax used to invoke the program) into a PKCS #7 signed-data object, which conforms to the Public Key Certificate Standards (PKCS). For more information about PKCS #7, refer to the RSA specification listed in Appendix C: Suggested Reading of the Authenticode Appendixes documentation.

The syntax for invoking the cert2spc.exe is:

cert2spc cert1.cer [cert2.cer...certN.cer] outputSPCfile.spc

cert1.cer…certN.cer Name of the X.509 certificate to include in the SPC. Multiple names separated by spaces can be specified.
outputSPCfile.spc Name of the PKCS #7 object that will contain the X.509 certificate(s).

Type the following syntax after c:\codesign> as shown in Figure 3.

cert2spc myNew.cer myNew.spc

Figure 3. Cert2spc.exe invocation syntax (click image to see larger picture)

This wraps myNew.cer (which is an X.509 certificate) into a PKCS #7 SPC called myNew.spc.

**Note **This is a test SPC and is not valid for public software publishing.

Sign the Smart Tag DLL

You can now sign the unsigned smart tag DLL using the signCode.msi program. To do this, follow the steps below:

At command prompt, type the following to invoke signCode.msi:
c:\codesign>signCode.msi

This will launch the Digital Signature Wizard as shown in Figure 4.

Figure 4. The Digital Signature Wizard (click image to see larger picture)
Click Next.
Select the smart tag DLL you want signed by browsing to the location of the smart tag DLL. An example is shown in Figure 5.

Figure 5. Selecting the smart tag DLL to be signed
Click Next.
Select the Custom radio button under Signing Options.
Click Next.
Click Select from File.
Browse to the myNew.spc file generated in the Create a Software Publishing Certificate (SPC) section. An example is shown in Figure 6.

Figure 6. Selecting the SPC from a file
Click Next.
Select the Private key in a CSP radio button.
From the Key container drop-down list, select myNewKey, which you generated in step 5 of the Generate a Test X.509 Certificate section as the key container. The Key type will automatically default to the value of Signature, which is what myNewKey key type is as shown in Figure 7.

**Note **If neither of the -sk (or -sv options) are used in step 5 of the Generate a Test X.509 Certificate section, a key container called JoeSoft is created by default which you can use as the value of the Key container.

Figure 7. Selecting the private key
Click Next. You can choose either md5 or sha1 as the hash algorithm. Sha1 is theoretically a factor of 232 more secure than md5.
Click Next on the next four screens.
Click Finish as shown in Figure 8.

Figure 8. Completing the Digital Signature Wizard

Viewing the certificate

If you want to view details about the certificate you just created, do the following:

In Microsoft Internet Explorer, click on Tools, then click Internet Options to display the Internet Options menu.

**Note **Alternatively, you can also get to the Internet Options menu in Microsoft Windows XP by clicking Start, clicking Control Panel, and clicking Internet Options. Or, in Microsoft Windows 2000, click Start, point to Settings, click Control Panel, and click Internet Options.
On the Internet Options menu, click the Content tab.
Under Certificates, click Certificates. This displays the Certificates dialog box. If the Personal tab is not already selected by default, click on it to view the certificate you created earlier. An example is shown in Figure 9. In this example, there are three different certificates issued: Contoso, Contoso2, and Jay Adams (the certificate created in this tutorial).

Figure 9. The Certificates dialog box with the Jay Adams certificate highlighted
Double-click on the Jay Adams certificate to display the certificate as shown in Figure 10.

Figure 10. General information about the Jay Adams certificate
To view details about the certificate, click the Details tab as shown in Figure 11.

Figure 11. Viewing Jay Adams certificate details

Prepare Office XP Security Settings

Before you can test the signed smart tag DLL, the security settings in both Microsoft Word and Microsoft Excel should be set to High, with the Trust all installed add-ins and templates settings disabled.

**Note **This will disable all your add-ins and templates that are not code signed. After you are done testing, you can reset these security settings to whatever level they were at prior to testing by making the appropriate changes in the Security dialog box as shown in the steps below.

To change security settings:

Start Microsoft Word.
Click Tools, point to Macro, and then click Security. This displays the Security dialog box.
Set the Security Level to High.
Click the Trusted Sources tab. Uncheck Trust all installed add-ins and templates as shown in Figure 12.

Figure 12. An unchecked Trust all installed add-ins and templates box
Quit Word.
Repeat the steps above with Microsoft Excel.

Enable smart tags in Excel

Make sure smart tags are enabled in Excel. To do this:

Start Microsoft Excel.
Click Tools, then click AutoCorrect Options. This displays the AutoCorrect dialog box.
Click the Smart Tags tab.
Check the Label text with smart tags box as shown in Figure 13.

Figure 13. Enabling smart tags in Excel
Click OK and quit Excel.

Test the Signed Smart Tag DLL

Before you can start testing your signed smart tag DLL, install and register the signed smart tag DLL on your computer as described in the Smart Tag SDK 1.1 Register the SimpleTerm DLL topic (which can be found in the Visual Basic Tutorial: Creating a List recognizer and Action subsection). When you have completed this, do the following:

Open either Microsoft Word or Microsoft Excel. You will see a Security Warning dialog box warning that a signed smart tag is installed with the issuing authority specified as shown in Figure 14.

Figure 14. 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 15. If you click on the Advanced tab, you will be able to view the Signature details as shown in Figure 16. On the General tab, to view the certificate, click View Certificate.

Figure 15. Digital Signature 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 15 above. The reason for this particular message is 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 14.

Figure 16. Viewing details for a digital signature
Back in the Security Warning dialog box, note that the Enable Macros button is disabled, which means you cannot enable the smart tag DLL you just signed. To enable it, select the Always trust macros from this source check box. This makes the Enable Macros selection available.
Click Enable Macros. This will load your signed smart tag. If you click Tools, click AutoCorrect Options, and click the Smart Tags tab, you will find your smart tag in the Recognizers list. If you click Disable Macros, the signed smart tag 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 sign the smart tag DLL should be in the list of Trusted Sources as shown in Figure 17. Compare Figure 17 with Figure 12 (before the signed smart tag DLL was installed and enabled).

Figure 17. Trusted Sources list after the signed smart tag DLL was added to the Always trust macros from this source list
Test your smart tag functionality.

**Note **If you want to retest the enabling and disabling of the signed smart tag DLL, remove the Jay Adams certificate from the 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:

Leave the Jay Adams 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).
Sign another smart tag DLL using the same Jay Adams certificate. To sign using the Jay Adams certificate, in step 7 of the Sign the Smart Tag DLL section, instead of clicking Select from File, click Select from Store. You will be asked to select the certificate you want to use for signing as shown in Figure 18.

Figure 18. Selecting a certificate for signing from the certificate store
Install and register the signed smart tag DLL.
Open either Microsoft Word or Microsoft Excel.

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

Conclusion

As can be seen, the steps involved in signing a smart tag DLL are quite straightforward and the Authenticode set of digital signing tools is easy to use. When you want to test different installation scenarios, the Authenticode tools will be very useful. For example, you can generate as many test certificates to use for signing as you want without having to pay for each of them. 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:

The Smart Tag Installation and Security for Microsoft Office XP article is a must read for more information on smart tags and security in Office XP.
Microsoft Office XP Macro Security White Paper.
To find out more about digital code signing, the Introduction to Code Signing article is a good starting point.
What Are Digital Certificates? discusses digital certificates.
Using Digital Certificates to Produce Trusted Solutions.
Digital Certificates discusses digital certificates.
To obtain a valid certificate for software publishing, see Getting a Software Publisher Certificate for more information on how to purchase one from a certification authority.

Glossary

The definition of the following cryptographic and security terminologies were taken from the Platform SDK: Security documentation.

CA
Certification Authority**.**
Certificate
A digitally signed statement that contains information about an entity and the entity's public key, thus binding these two pieces of information together. A certificate is issued by a trusted organization (or entity) called a Certification Authority (CA) after the CA has verified that the entity is who it says it is.

Certificates can contain different types of data. For example, an X.509 certificate includes the format of the certificate, the serial number of the certificate, the algorithm used to sign the certificate, the name of the CA that issued the certificate, the name and public key of the entity requesting the certificate, and the CA's signature.
Certificate request
A specially formatted electronic message (sent to a CA) used to request a certificate. The request must contain the information required by the CA to authenticate the request, plus the public key of the entity requesting the certificate.
Certificate revocation list
(CRL) A document maintained and published by a certification authority (CA) that lists certificates issued by the CA that are no longer valid.
Certificate server
A server that issues certificates for a particular CA. The certificate server software provides customizable services for issuing and managing certificates used in security systems employing public-key cryptography.
Certificate trust list
(CTL) A predefined list of items that have been signed by a trusted entity. A CTL can be anything, such as a list of hashes of certificates, or a list of file names. All the items in the list are authenticated (approved) by the signing entity.
Certification Authority
An entity entrusted to issue certificates asserting that the recipient individual, machine, or organization requesting the certificate fulfills the conditions of an established policy.
Certificate store
Typically, a permanent storage where certificates, certificate revocation lists (CRLs), and certificate trust lists (CTLs) are stored.
Cryptography
The art and science of information security. It includes information confidentiality, data integrity, entity authentication, and data origin authentication.
hash
A fixed-size result obtained by applying a mathematical function (the hashing algorithm) to an arbitrary amount of data (also known as "message digest").
hashing algorithm
An algorithm used to produce a hash value of some piece of data, such as a message or session key. Typical hashing algorithms include MD2, MD4, MD5, and SHA-1.
Key container
A part of the key database that contains all the key pairs (exchange and signature key pairs) belonging to a specific user.
MD5
The CryptoAPI algorithm name for the MD5 hash algorithm. Other hashing algorithms include MD2, MD4, and SHA. See also MD5 algorithm.
MD5 algorithm
A hashing algorithm that creates a 128-bit hash value. MD5 was optimized for 32-bit computers.
PKCS #7 Signed Data
A Public Key Certificate Standard #7 (PKCS #7) signed-data object encapsulates the information used to sign a file. Typically, it includes the signer's certificate and the root certificate.
PKCS #7 STANDARD
A standard that defines a general syntax for encryption and authentication, as well as adding other message attributes, such as timestamps, to the message.
Private key
The secret half of a key pair used in a public key algorithm. Private keys are typically used to encrypt a symmetric session key, digitally sign a message, or decrypt a message that has been encrypted with the corresponding public key.
Public key
A cryptographic key typically used when decrypting a session key or a digital signature. The public key can also be used to encrypt a message, guaranteeing that only the person with the corresponding private key can decrypt the message.
Root Authority
The certification authority (CA) at the top of a CA hierarchy. The root authority certifies CAs in the next level of the hierarchy.
Root certificate
A self-signed certification authority (CA) certificate that identifies a CA. It is called a root certificate because it is the certificate for the root CA. The root CA must sign its own CA certificate because by definition there is no higher certifying authority to sign its CA certificate.
RSA
RSA Data Security, Inc., a major developer and publisher of public-key cryptography standards (PKCS). The "RSA" in the name stands for the names of the company's three developers and the owners: Rivest, Shamir, and Adelman.
Self-signed certificate
See Root certificate.
Secure Hash Algorithm
See SHA.
SHA
The CryptoAPI name for the Secure Hash algorithm, SHA-1. Other hashing algorithms include MD2, MD4, and MD5. Also see SHA-1.
SHA-1
A hashing algorithm that generates a 160-bit hash value. SHA-1 was developed by the National Institute of Standards and Technology (NIST) and by the National Security Agency (NSA). Also see SHA.
Signature certificate
A certificate containing a public key that is used to verify digital signatures.
SPC
Software Publishing Certificate—a PKCS #7 signed-data object containing X.509 certificates.
Trust provider
The software that decides whether or not a given file is trusted. This decision is based on the certificate associated with the file.
X.509
An internationally recognized standard for certificates that defines their required parts.