Installing .NET Passport Encryption Keys
.jpg)
Installing .NET Passport Encryption Keys
You will need two different encryption keys: one for your Preproduction (PREP) site, and one for your Production site.
To download an encryption key
From the .NET Services Manager Home page, click Create and Manage an Application, and then click Manage Applications.
From the Select an Application drop-down list, select your .NET Passport application.
In the Steps section of the Manage Applications page, click Download Key.
In the Operating System drop-down list, select the operating system that will host your .NET Passport application.
In the Web Server list, select the Web server that will host your .NET Passport application, and then click Next.
Your key request will be confirmed. An e-mail message containing the Web address where you can download the key will be sent to the address specified on the User Information page.
Follow the instructions contained in the encryption key e-mail.
From the Download Key page, print the instructions for installing your encryption key.
You can also find these instructions on the Key Installation Instructions page.
Click Download Key and save the encryption key to a restricted-access location on your hard drive.
Important You must take steps to restrict access to this encryption key. This includes keeping it in a restricted place on your server and, if you have it on a disk, storing that disk in a restricted location, such as a safe. If you suspect your key has been compromised, contact Microsoft Product Support Services immediately.
The Key Installation Program
The key installation program is a command-line executable file with two basic functions:
To install the source material of an asymmetric triple-DES key into the server's registry.
To specify and synchronize the stored key that Passport Manager should use to encrypt and decrypt communication with the .NET Passport network.
Each installation program is specifically compiled to be used by one and only one site and Site ID. The same program can be used to install keys to multiple servers (for example, in configuring a cluster of servers). The name of the program contains the Site ID for which it is intended, as well as the version of the key. For example, if your site's assigned Site ID is 1000, and this is the first time your site has downloaded the encryption key, the name of the key installation program for your site will be Partner1000_1.exe (where 1000 is your Site ID and 1 is the version of the key contained by the program).
Installing Keys After Initial Site Registration
Use a command prompt window to run the program. Type the executable program name followed by a command-line argument for each specific action. For purposes of the following examples, the file name of the executable is Partner1000_1.exe; remember that your executable's file name will be specific to your Site ID and the command line you enter will differ accordingly.
To install the base key material and store it permanently in the server's registry, enter the following:
Partner1000_1 /addkey
Reinstalling Encryption Keys
If you have previously installed an encryption key and you are working in the same environment in which you installed the key initially, you must reinstall that key in the same environment (using the instructions given in the preceding section) if any of the following circumstances are true:
The server has become corrupted.
You have reinstalled an old version of Passport Manager on the server.
A new network card has been installed on the server.
However, if you are switching from PREP to Production (or vice versa) on the same computer, download a new encryption key from the .NET Services Manager .gif)
.
Updating Keys
If your server already has a previous version of the encryption key installed, and you wish to install a new key for periodic update or security reasons, follow these directions.
Typically, an individual representing a site would contact the .NET Passport team with a key update request, and a new key installation program is sent as an executable file e-mail attachment to the site contact person. The program containing the updated key typically will have a version number of "_2" or later in the file name, and the version in the file name will match the /showcurrent value after it is installed.
Copy the executable program to your server and run it from a command line with the arguments shown in the following example.
Replace oldKeyValidTime with an integer time value. This specifies the period of time (in seconds) during which Tickets and Profiles encrypted in the old key will still be accepted by Passport Manager. After this period of time, Tickets and Profiles encrypted in the old key will not be considered valid, and any Tickets or Profiles found in cookies with old keys will subsequently generate Microsoft® Windows NT event number 5012 and will require those users to be reauthenticated. 7200 seconds (two hours) is the suggested default for this value. If you are reinstalling keys on a server that is actively using Passport Manager, it is recommended that you provide a changeover period during which both old and new key values are valid. However, using both keys will slow performance, so the /t value should not be set for periods in excess of eight hours. You may wish to set oldKeyValidTime to the same value as the TimeWindow default set in the Passport Manager Administration utility; any keys issued just before the changeover will thus have the same validation life span in the timestamps as the keys in which the Ticket was actually encrypted.
Partner####.exe /addkey Partner####.exe /makecurrent /t oldKeyValidTime
Restart your server application. If the server was running previously, make sure to stop all services using the following command line:
net stop iisadmin /y
In some rare cases, it may be necessary to shut down the server completely and restart it.
Other Command-Line Options
The following are two other command-line options available for use with your key installation program:
To check the version of the currently installed key, type the following on the command line:
Partner###_#.exe /showcurrent
Key versions can be 0 through F (hexadecimal digits), with the first installed key starting at 1 (one). If you install a new key to supercede key version F, the next key version will wrap around to become key version 0. Only the current key and immediately previous key are relevant for .NET Passport encryption, so it does not matter that keys created 15 versions ago are overwritten.
To cause the currently installed key to expire immediately, enter the following from the command line:
Partner###_#.exe /expire
Do not cause the current key to expire unless either a known security breach has occurred or another key will be installed shortly. Causing the key to expire takes effect immediately and prevents Passport Manager from writing valid cookies in the calling domain until a new key is enabled. If you caused the currently installed key to expire and you want to reactivate it, you can do so by running the installation program using the /makecurrent argument again; it is not necessary to reinstall the existing key using the /addkey argument in this case. The /makecurrent argument always enables the key version that corresponds to the installation program being run, and the /expire argument disables the key version that corresponds to that particular installation program.
Installing Keys to Remote Servers
The key installation program can be used to install encryption keys to multiple remote servers as long as all servers are accessible through the local area network (LAN). Local (where the key installation program runs) and remote computers must both already have Passport Manager objects installed.
To install keys to a remote server, add the /m machineName argument to the end of each of the key installation program command lines. For example, to install a new key to a computer named "myServer1" on the local area network, enter the following command lines:
Partner###_#.exe /addkey /m \\myServer1 Partner###_#.exe /makecurrent /t 0 /m \\myServer1
The /m machineName argument can also be combined with /showCurrent or /expire to run these arguments against a remote computer.
Media access control (MAC) identification on a server's network card is used to write the key into the registry in a manner that is unique for each computer even when the same decrypted key and key installation program are used for many computers. For this reason, it is not adequate to propagate key material from one server to another simply by copying the entire registry or the .NET Passport branch of the registry. The key installation program must either be run physically on each server, or it must be run remotely against that server using the /m argument. Running the key installation program will overwrite some of the \KeyData and \KeyTimes branches of the .NET Passport registry information, so be sure to do this after running any registry script (.reg) files you use to propagate server configuration.
Installing Keys for Multiple Sites Sharing a Single Passport Manager Installation
The key installation program can be used to install different keys for each Site ID configured to share a common Passport Manager installation. This situation is more common if you are using a single development computer for material that will eventually be deployed to multiple live environments, but it is also possible to host multiple Site IDs on a single computer for the Production environment.
To install keys for a particular named site that exists on a server, add the /s siteName argument to the end of each of the key installation program command lines. For example, to install a new key to a site named "mySite1" on the current computer, type the following command lines:
Partner###_#.exe /addkey /s mySite1 Partner###_#.exe /makecurrent /t 0 /s mySite1
The /s siteName option can also be added to /showCurrent or /expire to run these options for a particular shared Site ID and named site. The /s argument for site name and /m argument for remote installation may be used together to configure multiple sites on a remote computer. The values given for siteName should match the values listed in the Web Site Name field of the Passport Manager Administration utility. Remember that ordinarily each Site ID has its own unique encryption keys, although it is possible upon request to obtain the same key for use in two related domains and Site IDs. To obtain an identical key for use within multiple domains or Site IDs, contact Microsoft Product Support Services.
See Also
Registering Your .NET Passport Site | .NET Passport Environments | Configuring Multiple Sites