ASP.NET Under the Hood

LANGUAGES: VB.NET | C#

ASP.NET VERSIONS: 2.0

 

Working with Certificates

Create, Access, and Employ Certificates in Your Applications

 

By Michele Leroux Bustamante

 

Greetings ASP.NET architects and developers! This time I m going to answer some frequently asked questions about X.509 certificates in the development environment.

 

I ve shared a fair number of code samples that require X.509 certificates for authentication and/or secure messaging. Some examples of applications that leverage certificates include:

• SSL-enabled Web applications
• SSL-enabled Web services (ASMX)
• Secure Web services using Web Services Enhancements (WSE) and WS-Security protocols
• Secure Windows Communication Foundation (WCF) services using WS-Security protocols
• Windows CardSpace applications using SSL and IE 7

 

I frequently answer questions about the process of working with certificates on the local machine for testing, creating test certificates for development, and security issues related to accessing certificates at run time. In this article I ll provide a summary of answers to those questions to help you with your development efforts for any of the above scenarios.

 

Q. Where do I find the Certificates snap-in tool?

 

A. Let s start with the basics. If you re going to develop applications that require certificates, you ll need to know where certificates are stored, as well as how to navigate the management interface. There is an MMC (Microsoft Management Console) snap-in for Certificates (see Figure 1). From this snap-in interface you can manage your certificates; most typically for the currently logged-in user (Current User store), or the machine account (Local Machine store).

 

Figure 1: The MMC snap-in.

 

Follow these instructions to open the Certificates snap-in for the Current User and Local Machine stores:

• From the Start menu select Run and type mmc.exe. Click OK to launch the MMC console.
• From the File menu select Add/Remove Snap-in. Click Add from the dialog and select Certificates from the Add Standalone Snap-in dialog.
• Click Add and select My user account; click Finish.
• Click Add again and select Computer account. Click Next, then Finish.
• Close the Add Standalone Snap-in dialog. Click OK on the Add/Remove Snap-in dialog. You should see the console shown in Figure 1.

 

You can save these Certificates snap-in settings to a file (File | Save; name the file certificates.msc). Simply open certificates.msc the next time you load the MMC console.

 

If you expand the Certificates node for Current User or (Local Computer), you ll see several logical certificate stores. The logical stores you ll use for the scenarios I m covering are:

• Personal. Here you store certificates for which you have the associated private key.
• Trusted Root Certification Authorities. This store lists the Third-Party Root Certification Authorities (Thawte, Verisign, etc.), Microsoft root certificates, and your own root certificates for self-signed certificates.
• Trusted People. Here you place your trusted certificates (you must also trust the entire chain of certificates).

 

As I answer other common certificate questions, you ll learn how to use each of these logical stores.

 

Q. How can I generate my own test certificates for SSL Web sites or secure Web service messaging?

 

A. This is the most often-asked question I hear. It is not always easy to find a concise list of steps to follow for creating certificates. There are three popular approaches to generating certificates for testing purposes:

1)     Request a test certificate from a certificate authority (CA), such as Verisign.

2)     Issue your own certificates from your Windows Server 2003 CA.

3)     Generate certificates using makecert.exe (the Certificate Creation Tool).

 

The simplest approach is to use makecert.exe. This command line tool is installed with your .NET Framework SDK (2.0 and 3.0 each have a version of this tool).

 

MSDN describes the options you can pass to the command line (see http://msdn2.microsoft.com/en-us/library/bfsktky3.aspx). Still, when you are new to the tool it is often overwhelming to make sense of all the possible options. I ll simplify things by providing some steps that will work for SSL certificates and secure messaging.

 

Creating an SSL Certificate

To create a self-signed certificate to install in IIS as the SSL certificate, you can issue the following makecert.exe command from the Visual Studio 2005 command line:

 

makecert -r -pe -n "CN=localhost" -ss my -sr currentuser -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 c:\localhost.cer

 

The subject name localhost makes it possible to browse without errors to http://localhost or any path relative to it. The subject name of the SSL certificate must match the domain or machine name used in the path to access the site. If you used your machine name to browse to Web sites on your machine, for example http://idesign/, you d create the certificate with the subject name CN=idesign .

 

Creating a Secure Messaging Certificate

To create a certificate for use in Web service message exchanges, you can give the certificate any relevant name. I tend to use the following names for various samples I create:

• SubjectKey (for client applications)
• RPKey (for target service applications)
• IPKey (for identity provider services such as a security token service [STS])

 

You can use subject names that are meaningful to your applications. The syntax would be essentially the same for makecert.exe, with the exception of the subject name and certificate output filename:

 

makecert.exe -r -pe -n "CN=RPKey" -ss my -sr currentuser -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 c:\rpkey.cer

 

makecert.exe Options

You only have to understand a subset of makecert.exe options to create these certificates. The table in Figure 2 describes them.

 

Option	Description
-n certName	The subject name for the certificate. This is a distinguished name following the X.500 specification. It can be as simple as CN=localhost or include a richer description of the subject with CN=localhost, O=IDesign, OU=Architecture, E=mlb@idesign.net .
-pe	This allows the private key to be exported after generating it. It is a good idea to generate the private key pair and export the certificate to apply password protection, even if it is a test certificate.
-sr	Certificate store location where the key will be generated. It doesn t matter which store you choose, because you will likely export the key pair, password protect it, and then import it to the correct store for use. Values can be currentuser or localmachine.
-ss	Which logical store will the certificate be installed in? Specify My here; this will place it in the Personal logical store.
-sp	The cryptography provider to use. A list of possible providers can be found here: http://windowssdk.msdn.microsoft.com/en-us/library/ms731160.aspx. The Microsoft RSA SChannel Cryptographic Provider is not subject to government restrictions for usage.
-sy	Cryptography provider type; an integer representative of the provider setting for the -sp option. Use the value 12 for the Microsoft RSA SChannel Cryptographic Provider .
-r	Indicates a self-signed certificate.
-sky certType	Can be signature or exchange. Use exchange for SSL and secure messaging.

Figure 2: A subset of makecert.exe options.

 

Exporting the Certificate

The goal is to export a .pfx file (the key pair) and a .cer file (the public certificate) for later use. The .cer file is generated in the directory you specified in the makecert.exe command. The .pfx file can be exported from the Certificates snap-in tool as follows:

• Because the certificate is generated to enable exporting the private key, you can export it using the Certificates console. Open the Certificates snap-in, expand the CurrentUser | Personal store (assuming it was created in currentuser), and select All Tasks | Export (see Figure 3).
• Follow the steps in the wizard and be sure to select Yes, export the private key , and Delete the private key if the export is successful . Provide a password to protect the key upon export to the .pfx file.

 

Figure 3: Exporting a key pair.

 

Now you have a .pfx and .cer file ready to use for SSL or secure messaging.

 

Q. How do I install and troubleshoot a test SSL certificate?

 

A. During development you may need to test applications that require SSL. If you create a certificate using makecert.exe, you can use the resulting key pair as the SSL certificate. Here are the steps to accomplish this:

1)     Import the localhost.pfx certificate to the Local Machine | Personal store. You can do this from the Certificates snap-in by right-clicking on the Personal store and selecting Import. You ll be asked to provide the key pair password you used when exporting earlier.

2)     Next, open the console for Internet Information Services (IIS) from Control Panel | Administrative Tools.

3)     Open the Properties dialog for the default Web site and select Server Certificate from the Directory Security tab.

4)     Choose Assign an existing certificate. You ll be presented with keys from the Local Machine | Personal store; the localhost certificate should be listed. Select it.

 

Before you start opening ASP.NET Web sites with SSL enabled, it s a good idea to test the SSL certificate to verify the trust chain. You can use the IIS Diagnostic Toolkit to do this. Download and install the toolkit from http://www.microsoft.com/downloads/details.aspx?familyid=9BFA49BC-376B-4A54-95AA-73C9156706E7&displaylang=en. Then, from the Start menu find the program group for SSL Diagnostics and launch the SSL Diagnostics tool, as shown in Figure 4.

 

Figure 4: Accessing the IIS Diagnostic Toolkit.

 

A test certificate will fail this test with the error: A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider. That s because the certificate was not issued by a provider installed in the Trusted Root Certification Authorities store. This problem will be solved if you import the localhost.cer file into Local Machine | Trusted Root Certification Authorities.

 

Q. How do I test an ASP.NET Web site with SSL enabled?

 

A. ASP.NET Web site projects can be file-based using the built-in Web server, or be IIS-based. Generally speaking, to test any security-related features of a Web site it is better to use IIS and only IIS supports opening Web site projects with SSL enabled. To debug with SSL, you must add the Web site project to the solution and check the Use Secure Sockets Layer checkbox, as shown in Figure 5.

 

Figure 5: Opening a Web site project in Visual Studio with SSL support.

 

Now when you debug, the browser address will use the HTTPS scheme instead of HTTP, by default. You can still browse to the Web site using HTTP if you want to test the application without SSL.

 

Had you forgotten to install the SSL certificate in the Trusted Root Certification Authorities store, you would have seen a message in IE 7 similar to that shown in Figure 6. Note: Only trusted SSL certificates will work for CardSpace-enabled sites (even for testing on your local machine).

 

Figure 6: IE 7 performs strict checking on SSL certificates while you browse.

 

Q. Can you explain the security requirements around run-time access to certificates for secure messaging?

 

A. The location of certificates used for secure messaging (ASMX, WSE, WCF) depends on the configuration of each application but there are some typical usage patterns:

• Client Certificates. When certificates are used to authenticate a client application, its certificate with the private key (.pfx) is usually installed in the Current User | Personal store. This key is used to sign messages from the client, which must be validated at the service. The service uses the client s public key to validate the authenticity of message signatures, and to identify the client. This public cert is usually installed to the Local Machine | Personal or Local Machine | Trusted People store (depending on where the service run time will look for authorized certificates).
• Service Certificates. The service certificate and private key are usually installed in the Local Machine | Personal store. This key is used to authenticate the service to the client, and to decrypt messages from the client. The client uses the service s public key to encrypt messages. When the service attempts to decrypt messages, it requires access to its private key at run time, and this poses some security constraints.

 

If you are hosting services (ASMX, WSE, WCF) in IIS, the ASP.NET account is used to access service certificates at run time. If you are running services in a file-based Web site, the logged-in user account is used. In either case, you need to make sure that the appropriate account has access to the private key at run time.

 

It turns out that Local Machine keys are installed in a directory similar to:

 

C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys

 

So, you can browse to that directory in file explorer and grant the ASP.NET (or appropriate) account access to the path. That would grant the account access to all private key certificates on the local machine. To lock this down to a particular certificate, you must know for which certificate file to modify security. Fortunately, both WSE and the .NET Framework 3.0 SDK (for WCF) provide tools that make it easy to specify security for a particular certificate.

 

The WSE X.509 Certificate Tool and the CertKeyFileTool (respectively) let you open any logical certificate store and select a certificate. You can view the properties of certificates that have private keys and modify security, as shown in Figure 7.

 

Figure 7: Both the WSE and WCF certificate tools can lead you to a properties dialog for a specific certificate file. This is where you add accounts that need run-time access to private keys.

 

Conclusion

Whether you are testing secure ASP.NET Web applications and services, using WSE, or using WCF for IIS-hosted service scenarios ... you ll definitely encounter the need to create and/or install test certificates. I hope this digest of information around creating, importing, and controlling access to certificates will help you skip past the pain of setting up your development environment to work with certificates.

 

If you have additional questions on this or other ASP.NET topics, drop me a line at mailto:underthehood@aspnetpro.com. Thanks for reading!

 

Michele Leroux Bustamante is Chief Architect at IDesign Inc., Microsoft Regional Director for San Diego, Microsoft MVP for XML Web services, and a BEA Technical Director. At IDesign Michele provides training, mentoring, and high-end architecture consulting services, specializing in scalable and secure .NET architecture design, globalization, Web services, and interoperability with Java platforms. She is a board member for the International Association of Software Architects (IASA), a frequent conference presenter, conference chair of SD s Web Services track, and a frequently published author. She is currently writing a book for O Reilly on the Windows Communication Foundation (http://www.thatindigogirl.com). Reach her at http://www.idesign.net or http://www.dasblonde.net.