KeyConfig Sample

Sample Overview

This sample tool allows the user to change the default assembly key pair or public key that is used when building assemblies in the Shared Source CLI (SSCLI) distribution. For more information on assembly signing in the SSCLI see the topic SSCLI Assembly Keys in the release notes.

Using this tool you can choose to use either full or delay signing (also called partial-signing) as the default for all assemblies built with the provided key during the SSCLI build process.

The tool modifies two files in the SSCLI distribution:

sscli\rotorenv\bin\strongnamekey.inc
- This file contains a text representation of the assembly key that will be used when building SSCLI assemblies.
sscli\clr\src\dlls\mscorsn\thekey.h
- This file contains the same information but in a C header file format which is used when building the core SSCLI components. This is required because the SSCLI treats the key described in this file as the special ECMA key as described in the release notes.

To generate a key pair or public key file, use the Strong Name tool. For example, to generate a full key pair containing both the public and private keys in a file named test.snk use the following command:

sn -k test.snk

To now generate just the pubic portion of the key pair in test.snk use the following command:

sn -p test.snk testpublic.snk

If you use the delaysign option, the public key that you used must be entered for verification skipping since delay-signed assemblies cannot be verified. The keyconfig tool will do this for you automatically. If you choose this option all assemblies built will be delay signed; they will all only contain public keys and not be signed.

The keyconfig tool will also allow you to roll back to your initial assembly key settings using the rollback option. This option will restore the original SSCLI files and remove the modified key file information.

To use the keyconfig tool you must be in a SSCLI build console window with the environment variables correctly set using env.bat, or the env.csh or env.sh scripts depending on your platform and shell type. The SSCLI must be built and functional.

The following is a summary of the steps required to use the keyconfig tool:

Create an SSCLI build console window using env.bat, env.csh, or env.sh.
Build the SSCLI.
Build a new key pair or public key using the Strong Name tool.
Use the clix launcher to run the keyconfig tool with the desired options.
Rebuild the SSCLI using buildall -c.

Now all the SSCLI assemblies (other than samples) will use the new key pair or public key.

Usage

clix keyconfig sign keyfilename
clix keyconfig delaysign keyfilename
clix keyconfig rollback

The following table shows the command-line options supported by this sample.

Option	Description
sign keyfilename	Changes the default signing key for the SSCLI distribution to the key pair contained in keyfilename. You must rebuild the SSCLI after making this change to apply the change.
delaysign keyfilename	Changes the default signing key for the SSCLI distribution to the public key contained in keyfilename which can be either a key pair or only the public key of a key pair. Only the public key portion will be used in subsequent builds of the SSCLI.
rollback	Rolls back the modifications made using the other two options.

Sample Source and Build Output Locations

The sample source is found in sscli\samples\utilities\keyconfig.

The source files are:

keyconfig.cs

The build output location is %TARGETCOMPLUS%\samples\utilities\keyconfig. The output file is an executable assembly named keyconfig.exe.

Building the Sample

All samples are built from the buildall script.

You can also build all the samples by switching to the root of the sample directory, sscli\samples, and typing build -c.

You can build this specific sample by switching to the sample directory and typing build -c.

Running the Sample

These steps require that the Shared Source CLI (SSCLI) be already built and functional.

Run env.bat or source the env.csh or env.sh script files, depending on your platform.
Switch to the %TARGETCOMPLUS%\samples\utilities\keyconfig directory.
Type the following command:

clix keyconfig.exe option [keyfilename]

where option is one of the options described above and keyfilename is the name of a file containing a public key or key pair.