ClickOnce Manifest Signing and Strong-Name Assembly Signing Using Visual Studio Project Designer's Signing Page

  • Article

 

Robert Schoen
SDET, Visual Basic

April 2006

Applies to:
   Microsoft Visual Studio 2005

Summary: This article discusses how to sign assemblies and ClickOnce manifests using Visual Studio 2005. (5 printed pages)

Contents

Introduction
Signing ClickOnce Manifests
Signing Assemblies
Conclusion

Introduction

Microsoft Visual Studio 2005 has added support to the development environment's Project Designer, to allow you to sign ClickOnce manifests, as well as to perform strong-name signing on assemblies. You can perform both of these signing tasks on the Project Designer's Signing page. However, note that manifest signing and assembly signing are two different processes: the first is for signing ClickOnce deployment manifests, and the second is for signing the application's assembly. Additionally, this paper provides requirements and guidelines to help with signing tasks.

To access the signing features, select the project node in Solution Explorer, and then click the Project menu and click Properties. When the new Project Designer appears, click the Signing page. The Signing page has two sections: Sign the ClickOnce manifests and Sign the assembly.

Signing ClickOnce Manifests

To publish an application using ClickOnce deployment, the application and deployment manifests must be signed with a cryptographic x509 certificate. ClickOnce deployment uses the RSA private key encryption scheme; the manifests are signed with the key information from the certificate. The Signing page allows you to sign manifests with a Personal Information Exchange (.pfx) key file, or with a certificate from your personal certificate store.

Note   Signing manifests within the Project Designer is accomplished by using the selected certificate from your personal certificate store. If you select a .pfx file for signing, you will be prompted for the key's password in order to import it into the personal certificate store.

Signing Options

There are several options on the Signing page that are available for selecting your certificate source. Please see How to: Sign Application and Deployment Manifests for more details.

Requirements for Certificates

The following are requirements and general rules regarding selecting certificates from the store and from .pfx files for ClickOnce manifest signing within the Signing page:

  • Windows should properly recognize chaining information for the certificate.
  • The certificate must include private key information.
  • The certificate must have been created using the RSA digital signature process.
  • The certificate must support code signing. If the EKU (Extended Key Usage) or KU (Key Usage) setting for the certificate is set, it must also explicitly contain the Code Signing setting.
  • The certificate cannot have expired.

Most of the problems that occur when selecting certificates for manifest signing generally result when the preceding requirements are not met. The most common problem is caused by moving certificates (.pfx files) from machine to machine, which can result in lost certificate chaining information and publish/build failures if you do not manage your certificates properly. To avoid losing chaining information, make sure that you retain a copy of the trusted root certificate of your certificate authority (CA), and that your .pfx file, when generated (or exported) locally, contained all the certificates in the path. You can use the Certificate MMC snap-in tool (Certmgr.msc) to help manage your local certificates, and you can also use it to complete your importing and exporting tasks.

Test Certificates

Test certificates should be used for testing purposes only. Test certificates do contain cryptographic key pair information. They can be used for publishing, but they do not contain verifiable information about the publisher, and you will not be able to use the Trusted Application Deployment (TAD) feature of ClickOnce.

Obtaining a Signed Certificate

There are a number of ways to obtain a signed certificate. For example, you can purchase one from a number of Certificate Authorities (CAs), such as Verisign, Inc. Also, can create your own certificate and have a CA sign it.

Timestamp Server URL

The Timestamp Server URL feature allows you to supply a service that will time stamp your manifest during the publishing process. When a published application's certificate expires, the time stamp service can be called upon by the client to verify whether the application was signed while the certificate was still valid and is needed to utilize the TAD features. Verisign, Inc. is an example of a CA that provides this kind of service.

Signing Assemblies

Signing an assembly gives a software component a unique identity, prevents spoofing, and guarantees dependencies and configuration mappings of components and versions. Typically, you sign DLLs, not EXEs. You should avoid strong-name signing an assembly unless it will be deployed to the global assembly cache (GAC), or unless it will be a shared resource (DLL). For an overview on when to strong-name sign, see Strong-Name Signing for Managed Applications.

Note   As mentioned in the introduction, strong-name signing the assembly is a distinct process from ClickOnce manifest signing, and these two tasks should be considered separately. Also note that ClickOnce applications at install time cannot install files into the GAC or shared locations. If your ClickOnce application requires strong-name signing, consider the following for publishing and updating: the ClickOnce store on the end user's machine maintains one copy of a strong-named assembly, which means that all installed ClickOnce applications using that component will share that one copy. Therefore, when making updates to strong-named assemblies, you will have to update the assembly version and the publish version number before a new update can be published, in order to enable the end user to see the new strong-named assembly.

The Signing page supports signing with .pfx or .snk key files. When selecting a .pfx key file for assembly signing, Visual Studio will prompt for the .pfx's password, and it will create a personal key container and use information from the container to complete the assembly signing. For detailed information on how to sign using a key file, see How to: Sign an Assembly. The following are requirements and general rules regarding selecting key files for assembly signing:

  • The .pfx file cannot include certificate chaining information. (If the .pfx file does include this information, the following import error will occur: "Cannot find the certificate and private key for decryption.")
  • Must include private key information.
  • Must have been created using the RSA digital signature process.
  • Must support code signing. If the EKU (Extended Key Usage) or KU (Key Usage) setting for the certificate is set, it must also explicitly contain the Code Signing setting.
  • There are no restrictions on expirations.

The most common problem arises when using a .pfx file that contains chaining information. You can remove chaining information from the key file by running the Certificate Manager snap-in (Certmgr.msc), importing the pfx file into the personal certificate store, and then exporting it without including the certificate chain information. You can accomplish this by doing the following:

  1. On the Start menu, click Run, type mmc, and then click OK. The Console1 dialog box appears.
  2. On the File menu, click Add/Remove Snap-in. The Add/Remove Snap-in dialog box appears.
  3. Click Add. The Add Standalone Snap-in dialog box appears.
  4. Click Certificates, and then click Add. The Certificates snap-in dialog box appears.
  5. Select My User account, click Finish, click Close, and then click OK to close the dialog boxes.
  6. Expand Certificates - Current User, expand Personal and then expand Certificates.
  7. Right click on the Certificates node and from the context menu select All Tasks and Import.
  8. The Certificate Import Wizard appears; click Next.
  9. At the File to Import step, browse and select the .pfx file and then click Next.
  10. Enter private key password information, check the option to mark this key as exportable, and then click Next.
  11. At the Certificate Store step, go with the defaults to place into the Personal Certificate store, click Next, and then click Finish.
  12. The certificate is now imported and ready for export. Select and right click on this certificate and, from the context menu, select All Tasks and Export.
  13. The Certificate Export Wizard dialog appears; click Next.
  14. At the Export Private Key step, select the option Yes to export the private key and then click Next.
  15. At the Export File Format step, make sure the option to include all certificates in the certificate path is unchecked and click Next.
  16. At the Password step, enter desired password information and click Next.
  17. At the File to Export step, specify the file name, click Next, and then click Finish.
  18. This should display the export was successful dialog; click OK.

For more information, see Certificate Manager Tool (Certmgr.exe).

Signing Multi-Project Solutions

The Project Designer's Signing page supports setting the signing properties, one project at a time. If you are working with a solution with multiple projects, and you want to sign all of them with the same key file, without copying the key file to all the projects, you can modify the *.xxproj file directly (for example, with Notepad) and change the AssemblyOriginatorKeyFile value to the path of the key file. One benefit of this solution is that you can keep all signing certificates in one location for safekeeping and tracking. The following is an example of how this can be done.

By default the value would look something like this in the *.xxproj file:

<AssemblyOriginatorKeyFile>mypfxkeyfile.pfx</AssemblyOriginatorKeyFile>

By changing the value to look something like D:\MyCerts\myMainKey.pfx, you can use one centrally located key file for all assembly signing needs:

<AssemblyOriginatorKeyFile>D:\MyCerts\mymainkey.pfx</AssemblyOriginatorKeyFile>

Delay Signing

The Signing page also has an option for delay signing only. This is provided in order to help in the testing of signed assemblies during the development cycle, but it also allows developers to keep the private key information private and secure. Note that delay signed projects will not run and cannot be debugged. However, you can use the Strong Name Tool (Sn.exe) with the -Vr option to skip strong-name verification, and to enable running and debugging during the development cycle.

Conclusion

Visual Studio 2005 has a new Project Designer with a Signing page that can assist developers in signing ClickOnce manifests, as well as in strong-name signing assemblies. Although both signing tasks are done from the Signing page, these are two distinct processes that should be considered separately, with each having particular key file requirements.

© Microsoft Corporation. All rights reserved.