Installing CardSpace Sample Certificates

To use the CardSpace samples, SSL certificates, virtual Web directories and host file entries must be installed. This document shows how to install the required certificates, and examines the steps to use to install alternative certificates.

Before You Start

The setup for the CardSpace samples depends on the successful installation of the One-Time Setup Procedure for the Windows Communication Foundation Samples.

Quick Installation of the Sample

To install the certificates, create the virtual hosts for the Web sites, and create the hosts entries at the same time, run the Setup.bat batch file in the sample directory. This runs each script one at a time.

To uninstall everything, run the Cleanup.bat batch file in the sample directory. This uninstalls the scripts, Web site, and hosts entries. It does not delete any files.

About Certificates

This document shows how to install the included certificates. For more information about certificates, see the following documents:

What Are Certificates?

How Certificates Work

Certificates Tools and Settings

For more information about CA certificates, see the following documents:

What Are CA Certificates?

How CA Certificates Work

CA Certificates Tools and Settings

Requirements

This walkthrough is designed for Windows XP SP2, Windows Server 2003 SP1, and Windows Vista. The following components must be installed:

• Microsoft ..NET Framework 3.0 or a later version.

• IIS 5.0, IIS 6.0, or IIS 7.0.

The following certificates are in the certificates folder:

• adatum.sst

• www.contoso.com.pfx

• www.fabrikam.com.pfx

• www.woodgrovebank.com.pfx

• www.adatum.com.pfx

The following files are in the Web site folder:

• images\adatum.gif

• images\contoso.gif

• images\fabrikam.gif

• crldata\adatum.crl

• CardSpace\default.html

The following script files are found in the scripts folder:

• Install-certificates.vbs

• Remove-certificates.vbs

• Install-website.vbs

• Remove-website.vbs

• Install-hosts.vbs

• Remove-hosts.vbs

About these Certificates

The certificates presented here are for demonstration purposes only. The root CA certificate is stored as a .sst (Microsoft Serialized Certificate Store) file. The Web site certificates are all stored as .pfx files. The certificates are used for two categories of scenarios—Browser scenarios and Windows Communication Foundation (WCF) scenarios.

The sample certificates are High-Assurance certificates that have embedded logo images in them. High-Assurance (HA) certificates are issued from a CA that has performed additional steps to verify the subject the certificate is issued for. In Internet Explorer 7.0, these HA certificates cause the address bar to change color. If the browser can verify the details and the certificate checks out, the address bar turns green:

If there are problems verifying the certificate (HA or not), Internet Explorer 7.0 turns the address bar yellow:

As well, if Internet Explorer 7.0 suspects a phishing site, the address bar turns red:

Regular SSL certificates leave the address bar white.

Logo Extensions allow the CA to embed a graphic image into the certificate and provide a URL to verify that against. The URLs for the logo graphics in the sample certificates are configured to http://www.adatum.com/images/\<logo>.gif, where <logo> is the name of the logo.

For the Internet Explorer 7.0 browser scenarios and WCF scenarios, the certificates must be installed on the Web server and have the graphic logos set up under a virtual directory in IIS, and the hosts file must be modified to include the sample domain names (Fabrikam, Contoso, and Adatum).

For all scenarios: To use the samples between multiple computers, manually change the c:\windows\system32\drivers\etc\hosts file by using Notepad to edit the hosts file:

Add in the following entries (substituting the appropriate IP address of the server instead of 127.0.0.1):

127.0.0.1       www.adatum.com adatum.com
127.0.0.1       www.contoso.com contoso.com
127.0.0.1       www.fabrikam.com fabrikam.com

Sample Web sites and URLs

The sample applications and Web sites create virtual directories in IIS under the default Web application, which should be bound to port 80 and do not use a host header, thereby allowing www.fabrikam.com, www.adatum.com, and www.contoso.com to all share the same Web server. The SSL channel is bound to the certificate for www.fabrikam.com and is used for the HTTPS connections. The individual samples create virtual directories in the default Web site to illustrate the examples.

Installation of the Certificates

The root CA certificate from our fictitious CA (Adatum) must be installed into the “Trusted Root Certification Authorities” location in the local computer store. (localMachine:root).

The company certificates (Contoso and Fabrikam) must be installed into the “Personal” location in the local computer store. (localMachine:My). The passwords for all the .pfx files are blank. Run the script Install-certificates.vbs from the scripts folder. The script installs the certificates into the appropriate stores. When the script is run, it prompts before continuing:

As an additional security precaution (from CAPICOM), the script might show a warning that a CA certificate is being installed. Accept the certificate to proceed.

The script also supports two optional command line parameters, DEBUG and VERBOSE, which provide additional information during execution.

Expert Users: Install the certificates manually through the Microsoft Management Console.

Installation of the Graphic Logos and CRL

The graphic images for the logo extensions inside the certificates must be available to the clients to verify them.

Run the script Install-website.vbs from the scripts folder. The script creates the virtual directories for the certificate logos and the certificate revocation list (CRL).

Expert Users: Create the virtual directories manually through the IIS MMC snap-in. The three directories that point to folders inside the install folder are listed in the following table.

Modification of the Hosts File

The c:\windows\system32\drivers\etc\hosts file is modified for the samples so that the URLs resolve to the local machine.

Run the script Install-hosts.vbs from the scripts folder. The script creates the entries in the hosts file for the samples.

Expert Users: Create the entries manually by editing the c:\windows\system32\drivers\etc\hosts file, and adding the following lines:

127.0.0.1       www.adatum.com atatum.com
127.0.0.1       www.contoso.com contoso.com
127.0.0.1       www.fabrikam.com fabrikam.com

Verifying a Successful Install

To verify the hosts file and the virtual Web directory installation, use Internet Explorer and navigate to http://www.fabrikam.com/CardSpace. The browser displays the default page for the sample.

IIS: ACLs for Certificate Private Keys

For IIS to access the private keys of the certificates, the ACLs must be set for the IIS Service account (ASPNET on Windows XP and Windows Vista, and NETWORK SERVICE on Windows Server 2003) to have read access to the files. The certificate installation script handles that. To set the permission on private keys for other certificates, use Findprivatekey.exe from the Windows SDK and Cacls.exe, substituting in the thumbprint of the other certificate:

findprivatekey.exe my localmachine -t "d47de657fa4902555902cb7f0edd2ba9b05debb8" –a
ProgramData\Microsoft\Crypto\RSA\MachineKeys\6799c8288a6ee49d3fc35f2424524993_4872db96-95c8-43fa-8498-b2d31edcc120cacls 
cacls  C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys\6799c8288a6ee49d3fc35f2424524993_4872db96-95c8-43fa-8498-b2d31edcc120 /G ASPNET:R
Are you sure (Y/N)?y
processed file: C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys\6799c8288a6ee49d3fc35f2424524993_4872db96-95c8-43fa-8498-b2d31edcc120

Uninstall

To uninstall the sample certificates, virtual directories, and hosts entries, run the following scripts:

• Remove-certificates.vbs

• Remove-website.vbs

• Remove-hosts.vbs

The registration of the certificates, Web site, and hosts are removed.

When the CA certificate is removed from the system, the script might display the following message:

Click Yes to allow the certificate to be removed.

Troubleshooting

Internet Explorer Proxy Settings: For the browser samples to work properly, you might have to add the following to your Internet Explorer settings to bypass the proxy:

www.fabrikam.com;fabrikam.com;www.contoso.com;contoso.com;adatum.com;www.adatum.com;woodgrovebank.com;www.woodgrovebank.com

If you use an automatically discovered proxy, turn off automatic discovery and manually enter the proxy information. Ask your system administrator for details about your proxy configuration.

If you are having problems seeing certificate changes properly, clear your SSL certificate cache in Internet Explorer. From Internet Explorer, click Tools and then Internet Options, and select the Clear SSL State button, and then close all instances of Internet Explorer.

The Internet Explorer 7.0 browser scenarios use SSL connections and require you to set up the default Web site with an SSL certificate. While troubleshooting SSL connections can often be time consuming, with a few quick tips, you can solve most of your issues easily.

To begin, download the SSL Diagnostic Utility Download for IIS.

See Also

Other Resources

Using CardSpace in Windows Communication Foundation

© 2007 Microsoft Corporation. All rights reserved.