Why are shared assemblies signed
To distribute a shared assembly, you must first sign it. Contrary to what you might expect, Windows Side-by-Side does not use the signature to establish if the assembly is trusted or not. This would not make much sense anyway because the assembly must be installed by an administrator before it is known to the system. The assembly signature is used to verify that the assembly has not been damaged.
As the name implies, a shared assembly is available to all applications on the system. The purpose of side-by-side is to provide stability to applications. Any change to the shared assembly may break applications. But, because the assembly is signed and Windows has hashes of all assembly files, it can detect when the assembly is changed (intentionally or not).
If the installation source of the shared assembly is available to Windows, it will repair the assembly. If the repair cannot be done or fails, Windows will not run the program.
Side-by-side code in Windows uses Windows File Protection (WFP) facilities to repair shared assemblies. Unlike WFP though, it cannot guarantee the repair because it does not cache the installation files.
Very important note:
Never, ever change a shared assembly after it has been deployed.
Build a new assembly with a different version number - that is what assembly version is for.
Installation of shared assemblies
Windows requires that shared assemblies be installed using Windows Installer (MSI). This guarantees that Windows will know how to repair the assembly should it get damaged. But, like we said above, it does not guarantee that Windows will repair the assembly.
Manifest Maker supports building of shared assemblies. It signs the assembly and creates appropriate MSI file. The MSI file created by Manifest Maker is not compressed, the files are not included inside the MSI. To build a shared assembly you need to obtain or create a digital certificate - see below.
To manually install a shared assembly create by Manifest Maker you just double click the MSI file and follow the prompts - there are no options to choose, just information on what is going on. To install automatically run Windows Installer (msiexec.exe) with all the necessary command line options.
The installed assembly is saved in subdirectories %systemroot%\WinSxS directory. The manifest and the .CAT files are renamed by Windows and copied to the %systemroot%\WinSxS\Manifests and the other assembly files to a separate subdirectory with a name matching the generated manifest name. For example the name generated for Microsoft Windows Common Controls assembly version 6.0.10 is
x86_Microsoft.Windows.Common-Controls_6595b64144ccf1df_6.0.10.0_x-ww_f7fb5805
Digital certificate
To sign a shared assembly you need a digital certificate. Because the signature is not used to establish trust, only to establish the integrity of the assembly, this does not need to be a trusted certificate. There is no reason to purchase code-signing certificate from a third party certification authority for the purpose of signing shared assemblies. To the contrary, it is best to use internally generated certificates even if the signed assembly will be distributed outside of your company.
Normally, the certificate for signing shared side-by-side assemblies would be obtained from the corporate certificate authority or generated using MS SDK tools. Note that Windows 2000 Server and 2003 Server come with a certificate authority included. All you need to do is check a check box to install it.
The recommendations are:
- For corporate deployment - obtain certificates from the corporate CA.
- For outside distribution - generate a certificate, one certificate, using SDK tools or any other available facility. Use the same certificate to sign all versions of the same product. Generate separate certificate for each product you distribute. This will help you manage publisher configuration files should you need to.
How to generate a certificate
You can generate a self-signed certificate using tools included in Microsoft SDK. You can download the SDK from Windows SDK web site. Makecert.exe utility is also included in the Microsoft .NET Framework Software Development Kit.
C:\> makecert -pe -ss MY -$ individual -n "CN=your name here" -len 2048 -r
You can use any name in the CN= parameter. It is best to use something descriptive. This command will automatically add the generated certificate to your personal certificate store. You may examine and, if so desired, export the certificate using the certicicate MMC snap-in:
C:\> certmgr.msc
A certificate generated this way will be displayed in Windows with a red error indicator because it is not trusted. This is a self-signed certificate which means that it is not issued by a trusted certification authority. To get rid of the error message you can tell Windows to explicitly trust the certificate. As Manifest Maker signs a shared assembly, it automatically displays the properties of the signed .CAT file. If you do not trust the certificate, that .CAT file will be displayed with a 'no trust' error message. This error is annoying but it can be safely ignored.
Signing the MSI file
On Windows Vista and up an unsigned MSI file generates warning messages when you try to install it. You can avoid the warning message by signing the MSI file used to install the shared assembly. Manifest Maker will sign the MSI file if you check the "Sign the MSI file" checkbox in the Build tab of the Build Options dialog. The certificate used to sign the MSI file should be trusted by machines on which this shared assembly will be installed. This means that a certificate issued by a corporate CA will work fine for internal distribution but to distribute the shared assembly outside of your organization you will need a certificate issued by a third party trusted CA (Verisign, Thawte etc.)