Two Kinds of Assemblies, Two Kinds of Deployment
A strongly named assembly consists of four attributes that uniquely identify the assembly: a file name (without an extension), a version number, a culture identity, and a public key. Because public keys are very large numbers, we frequently use a small hash value derived from a public key. This hash value is called a public key token. The following assembly identity strings (sometimes called an assembly display name) identify four completely different assembly files.
- "MyTypes, Version=1.0.8123.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
- "MyTypes, Version=1.0.8123.0, Culture="en-US", PublicKeyToken=b77a5c561934e089"
- "MyTypes, Version=2.0.1234.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
- "MyTypes, Version=1.0.8123.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
Giving an Assembly a Strong Name
Here’s what it means to sign a file: When you build a strongly named assembly, the assembly’s FileDef manifest metadata table includes the list of all the files that make up the assembly. As each file’s name is added to the manifest, the file’s contents are hashed, and this hash value is stored along with the file’s name in the FileDef table. You can override the default hash algorithm used with AL.exe’s /algid switch or apply the assembly-level System.Reflection.AssemblyAlgorithmIdAttribute custom attribute in one of the assembly’s source code files. By default, a SHA-1 algorithm is used.
After the PE file containing the manifest is built, the PE file’s entire contents (except for any Authenticode Signature, the assembly’s strong name data, and the PE header checksum) are hashed, as shown in Figure 3-1. This hash value is signed with the publisher’s private key, and the resulting RSA digital signature is stored in a reserved section (not included in the hash) within the PE file. The CLR header of the PE file is updated to reflect where the digital signature is embedded within the file.
when you compile your source code, the compiler detects the types and members that your code references. You must specify the referenced assemblies to the compiler. For the C# compiler, you use the /reference compiler switch. Part of the compiler’s job is to emit an AssemblyRef metadata table inside the resulting managed module. Each entry in the AssemblyRef metadata table indicates the referenced assembly’s name (without path and extension), version number, culture, and public key information.
1 AssemblyRef #1 (23000001) 2 ------------------------------------------------------- 3 Token: 0x23000001 4 Public Key or Token: b7 7a 5c 56 19 34 e0 89 5 Name: mscorlib 6 Version: 4.0.0.0 7 Major Version: 0x00000004 8 Minor Version: 0x00000000 9 Build Number: 0x00000000 10 Revision Number: 0x00000000 11 Locale: <null> 12 HashValue Blob: 13 Flags: [none] (00000000)
1 Assembly 2 ------------------------------------------------------- 3 Token: 0x20000001 4 Name : L 5 Public Key : 00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 6 : 00 04 00 00 01 00 01 00 bb ee e9 61 d3 89 57 8a 23 34 b6 00 c7 31 f6 d1 7 : 9b 76 02 06 c7 b4 ff 8f 96 3a 53 c6 dc 96 c9 19 70 55 4b f2 8f 0f 83 9b 8 : c3 29 f5 89 3b 64 96 41 fd 79 1b ff 5e f6 c1 e0 1b 5e a0 c8 d0 18 b8 74 9 : 41 d2 ef 78 55 9b 3d ff 18 a6 76 fa 4e 0d 73 89 2b 53 1f d5 b0 1c 27 72 10 : ae 9e f6 ad 90 04 7b 86 d3 a5 01 a9 f7 a0 1b e0 bb 2b 99 9f ce 30 4b c2 11 : d9 b9 c2 20 b8 40 0a 76 a2 23 ae 25 02 93 1b d9 12 Hash Algorithm : 0x00008004 13 Version: 1.0.0.0 14 Major Version: 0x00000001 15 Minor Version: 0x00000000 16 Build Number: 0x00000000 17 Revision Number: 0x00000000 18 Locale: <null> 19 Flags : [PublicKey] (00000001)
Strongly Named Assemblies Are Tamper-Resistant
Signing an assembly with a private key and embedding the signature and public key within an assembly allows the CLR to verify that the assembly has not been modified or corrupted. When an assembly is installed into the GAC, the system hashes the contents of the file containing the manifest and compares the hash value with the RSA digital signature value embedded within the PE file (after unsigning it with the public key). If the values are identical, the file’s contents haven’t been tampered with. In addition, the system hashes the contents of the assembly’s other files and compares the hash values with the hash values stored in the manifest file’s FileDef table. If any of the hash values don’t match, at least one of the assembly’s files has been tampered with, and the assembly will fail to install into the GAC.
When strongly named assembly files are loaded from a location other than the GAC (via the application’s base directory or via a codeBase element in a configuration file), the CLR compares hash values when the assembly is loaded. In other words, a hash of the file is performed every time an application executes and loads the assembly. This performance hit is a tradeoff for being certain that the assembly file’s content hasn’t been tampered with. When the CLR detects mismatched hash values at run time, it throws a System.IO.FileLoadException.
When a strongly named assembly is installed in the GAC, the system ensures that the file containing the manifest hasn’t been tampered with. This check occurs only once, at installation time. In addition, to improve performance, the CLR does not check if a strongly named assembly has been tampered with if the assembly is fully trusted and is being loaded into a fully trusted AppDomain. On the other hand, when a strongly named assembly is loaded from a directory other than the GAC, the CLR verifies the assembly’s manifest file to ensure that the file’s contents have not been tampered with, causing an additional performance hit every time this file is loaded.
Privately Deploying Strongly Named Assemblies
In addition to deploying a strongly named assembly in the GAC or privately, a strongly named assembly can be deployed to some arbitrary directory that a small set of applications know about.
1 <?xml version="1.0" encoding="utf-8" ?> 2 <configuration> 3 <startup> 4 <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" /> 5 </startup> 6 <runtime> 7 <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> 8 <probing privatePath="D_" /> 9 <dependentAssembly> 10 <assemblyIdentity name="L" publicKeyToken="357f90d80abcd77e" culture="neutral" /> 11 <codeBase version="1.0.0.0" href="file:///E:/Coding/HappyStudy/AssemblyStudy/L/bin/Debug/L.dll" /> 12 </dependentAssembly> 13 </assemblyBinding> 14 </runtime> 15 </configuration>
How the Runtime Resolves Type References
When resolving a referenced type, the CLR can find the type in one of three places:
- Same file Access to a type that is in the same file is determined at compile time (sometimes referred to as early bound). The type is loaded out of the file directly, and execution continues.
- Different file, same assembly The runtime ensures that the file being referenced is, in fact, in the assembly’s ModuleRef table of the current assembly’s manifest. The runtime then looks in the directory where the assembly’s manifest file was loaded. The file is loaded, its hash value is checked to ensure the file’s integrity, the type’s member is found, and execution continues.
- Different file, different assembly When a referenced type is in a different assembly’s file, the runtime loads the file that contains the referenced assembly’s manifest. If this file doesn’t contain the type, the appropriate file is loaded. The type’s member is found, and execution continues.
If any errors occur while resolving a type reference—file can’t be found, file can’t be loaded, hash mismatch, and so on—an appropriate exception is thrown.
If you want, your code can register callback methods with System.AppDomain’s AssemblyResolve, ReflectionOnlyAssemblyResolve, and TypeResolve events. In your callback methods, you can execute code that resolves the binding problem and allows the application to continue running without throwing an exception.
Advanced Administrative Control (Configuration)
1 <?xml version="1.0"?> 2 <configuration> 3 <runtime> 4 <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> 5 <probing privatePath="AuxFiles;binsubdir" /> 6 <dependentAssembly> 7 <assemblyIdentity name="SomeClassLibrary" 8 publicKeyToken="32ab4ba45e0a69a1" culture="neutral"/> 9 <bindingRedirect 10 oldVersion="1.0.0.0" newVersion="2.0.0.0" /> 11 <codeBase version="2.0.0.0" 12 href="http://www.Wintellect.com/SomeClassLibrary.dll" /> 13 </dependentAssembly> 14 <dependentAssembly> 15 <assemblyIdentity name="TypeLib" 16 publicKeyToken="1f2e74e897abbcfe" culture="neutral"/> 17 <bindingRedirect 18 oldVersion="3.0.0.0-3.5.0.0" newVersion="4.0.0.0" /> 19 <publisherPolicy apply="no" /> 20 </dependentAssembly> 21 </assemblyBinding> 22 </runtime> 23 </configuration>
This XML file gives a wealth of information to the CLR. Here’s what it says:
- probing element Look in the application base directory’s AuxFiles and binsubdir subdirectories when trying to find a weakly named assembly. For strongly named assemblies, the CLR looks in the GAC or in the URL specified by the codeBase element. The CLR looks in the application’s private paths for a strongly named assembly only if no codeBase element is specified.
- First dependentAssembly, assemblyIdentity, and bindingRedirect elements When attempting to locate version 1.0.0.0 of the culture-neutral SomeClassLibrary assembly published by the organization that controls the 32ab4ba45e0a69a1 public key token, locate version 2.0.0.0 of the same assembly instead.
- codeBase element When attempting to locate version 2.0.0.0 of the culture-neutral Some- ClassLibrary assembly published by the organization that controls the 32ab4ba45e0a69a1 CHAPTER 3 Shared Assemblies and Strongly Named Assemblies 85 public key token, try to find it at the following URL: www.Wintellect.com/SomeClassLibrary.dll. Although a codeBase element can also be used with weakly named assemblies. In this case, the assembly’s version number is ignored and should be omitted from the XML’s codeBase element. Also, the codeBase URL must refer to a directory under the application’s base directory.
- Second dependentAssembly, assemblyIdentity, and bindingRedirect elements When attempting to locate version 3.0.0.0 through version 3.5.0.0 inclusive of the culture-neutral TypeLib assembly published by the organization that controls the 1f2e74e897abbcfe public key token, locate version 4.0.0.0 of the same assembly instead.
- publisherPolicy element If the organization that produces the TypeLib assembly has deployed a publisher policy file (described in the next section), the CLR should ignore this file.
When compiling a method, the CLR determines the types and members being referenced. Using this information, the runtime determines, by looking in the referencing assembly’s AssemblyRef table, the assembly that was originally referenced when the calling assembly was built. The CLR then looks up the assembly/version in the application’s configuration file and applies any version number redirections; the CLR is now looking for this assembly/version.
If the publisherPolicy element's apply attribute is set to yes—or if the element is omitted— the CLR examines the GAC for the new assembly/version and applies any version number redirections that the publisher of the assembly feels is necessary; the CLR is now looking for this assembly/version. Finally, the CLR looks up the new assembly/ version in the machine’s Machine.config file and applies any version number redirections there.
At this point, the CLR knows the version of the assembly that it should load, and it attempts to load the assembly from the GAC. If the assembly isn’t in the GAC, and if there is no codeBase element, the CLR probes for the assembly. If the configuration file that performs the last redirection also contains a codeBase element, the CLR attempts to load the assembly from the codeBase element’s specified URL.
Publisher Policy Control
In the scenario described in the previous section, the publisher of an assembly simply sent a new version of the assembly to the administrator, who installed the assembly and manually edited the application’s or machine’s XML configuration files. In general, when a publisher fixes a bug in an assembly, the publisher would like an easy way to package and distribute the new assembly to all of the users. But the publisher also needs a way to tell each user’s CLR to use the new assembly version instead of the old assembly version. Sure, each user could modify his or her application’s or machine’s XML configuration file, but this is terribly inconvenient and error prone. What the publisher needs is a way to create policy information that is installed on the user’s computer when the new assembly is installed. In this section, I’ll show how an assembly’s publisher can create this policy information.
A publisher policy assembly is a way for a publisher to make a statement about the compatibility of different versions of an assembly. If a new version of an assembly isn’t intended to be compatible with an earlier version, the publisher shouldn’t create a publisher policy assembly. In general, use a publisher policy assembly when you build a new version of your assembly that fixes a bug. You should test the new version of the assembly for backward compatibility. On the other hand, if you’re adding new features to your assembly, you should consider the assembly to have no relationship to a previous version, and you shouldn’t ship a publisher policy assembly. In addition, there’s no need to do any backward compatibility testing with such an assembly.