1.12 Sign an Assembly with an Authenticode Digital Signature

Problem

You need to sign an assembly with Authenticode so that users of the assembly can be certain that you are its publisher and that the assembly is unchanged after signing.

Solution

Use the File Signing tool (signcode.exe) to sign the assembly with your Software Publisher Certificate (SPC).

Discussion

Strong names provide a unique identity for an assembly as well as proof of the assembly's integrity, but they provide no proof as to the publisher of the assembly. The .NET Framework allows you to use Authenticode technology to sign your assemblies. This enables consumers of your assemblies to confirm that you are the publisher, as well as confirm the integrity of the assembly. Authenticode signatures also act as evidence for the signed assembly, which people can use when configuring code access security policy. (Assembly evidence is discussed in recipes 13.9 and 13.10.)

To sign your assembly with an Authenticode signature, you need an SPC issued by a recognized certificate authority (CA). A CA is a company entrusted to issue SPCs (along with many other types of certificates) for use by individuals or companies. Before issuing a certificate, the CA is responsible for confirming that the requesters are who they claim to be and also making sure the requestors sign contracts to ensure they don't misuse the certificates that the CA issues them.

To obtain an SPC, you should view the list of Microsoft Root Certificate Program Members at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsecure/html/rootcertprog.asp . Here you will find a list of CAs, many of whom can issue you an SPC. For testing purposes, you can create a test SPC using the process described in recipe 1.13. However, you can't distribute your software signed with this test certificate. Because a test SPC isn't issued by a trusted CA, most responsible users won't trust assemblies signed with it.

Once you have an SPC, you use the File Signing tool to sign your assembly. The File Signing tool creates a digital signature of the assembly using the private key component of your SPC and embeds the signature and the public part of your SPC into your assembly (including your public key). When verifying your assembly, the consumer decrypts the encrypted hash code using your public key, recalculates the hash of the assembly, and compares the two hash codes to ensure they are the same. As long as the two hash codes match, the consumer can be certain that you signed the assembly, and that it has not changed since you signed it.

To Authenticode sign an assembly named MyAssembly.exe with an SPC contained in a file named MyCert.spc and a private key contained in a file named MyPrivateKey.pvk, use the command signcode -spc MyCert.spc -v MyPrivateKey.pvk MyAssembly.exe . In this instance, the File Signing tool will display the dialog box shown in Figure 1.3, prompting you for the password used to protect the private key stored in the MyPrivateKey.pvk file.

Figure 1.3: File Signing tool requests a password when accessing file- based private keys.

You can also access keys and certificates contained in key and certificate stores. Table 1.2 lists the most commonly used switches of the File Signing tool. Refer to the .NET Framework SDK documentation for a complete listing.

Table 1.2: Commonly Used Switches of the File Signing Tool

Switch	Description
-k	Specifies the name of the CSP key container where your SPC private key is stored
-s	Specifies the name of the certificate store where your SPC is stored
-spc	Specifies the name of the file that contains your SPC
-v	Specifies the name of the file that contains your SPC private key

If you are signing a multi-file assembly, specify the name of the file that contains the assembly manifest. If you intend to both strong name and Authenticode sign your assembly, you must strong name the assembly first ”see recipe 1.9 for details on strong naming assemblies.

To check the validity of a file signed with an Authenticode signature, use the Certificate Verification tool (chktrust.exe). For example, to test MyAssembly.exe, use the command chktrust MyAssembly.exe . If you have not already configured your machine to trust the SPC used to sign the assembly, you will see a dialog box similar to that shown in Figure 1.4, which shows you information about the publisher of the assembly, and gives you the opportunity to trust this publisher. (The certificate described in Figure 1.4 is a test certificate created using the process described in recipe 1-10.)

Figure 1.4: Certificate Verification tool.

If you click the Yes button, or you have previously chosen always to trust the SPC, the Certificate Verification tool confirms the validity of the signature and the assembly.