How to: Create and Install Temporary Client Certificates in WCF During Development

  • Article

patterns & practices Developer Center

Applies to

  • Microsoft Windows Communication Foundation (WCF) 3.5
  • Microsoft .NET Framework 3.5
  • Microsoft Visual Studio 2008

Summary

This how-to article walks you through the process of creating and installing temporary certificates to be used during the development and testing of WCF services that implement certificate client authentication. The article explains the process of creating, configuring, and installing these temporary certificates to work with WCF.

Contents

  • Objectives
  • Overview
  • Summary of Steps
  • Step 1: Create a Certificate to Act as Your Client Root Certificate Authority
  • Step 2: Create a Certificate Revocation List File from the Root Certificate
  • Step 3: Install Your Client Root Certificate Authority on the Server and Client Machines
  • Step 4: Install the Certificate Revocation List File on the Server and Client Machines
  • Step 5: Create and Install Your Temporary Client Certificate
  • Deployment Considerations
  • Additional Resources

Objectives

  • Learn how to create a root certificate for the temporary certificate used for certificate authentication in WCF.
  • Learn how to create a root certification revocation list (CRL) file for the root certificate used to validate the revocation.
  • Learn how to create a temporary certificate for certificate authentication in WCF.
  • Learn how to install the temporary certificate.
  • Learn how to install the root certificate for the temporary certificate.
  • Learn how to install the root CRL for the root certificate.

Overview

When developing a WCF service that uses X.509 certificates to do certificate authentication, it is necessary to work with temporary certificates. This is because production certificates are expensive and may not be readily available. There are two options for specifying trust on a certificate:

  • Peer trust validates the certificate directly.
  • Chain trust —validates the certificate against the issuer of a certificate known as a root authority.

This how-to article describes the chain trust option because it is the most commonly used approach in Business-to-Business (B2B) scenarios, and it is the default validation for WCF when using certificate authentication.

Additionally, a CRL validation is performed during the certificate authentication process. This validation checks the list of certificates that were revoked by the root certificate. Three modes of revocation exist:

  • Online. The CRL list is retrieved and checked online. This requires a network connection to retrieve the CRL and check each address listed.
  • Offline. The CRL list is retrieved and checked online and is then cached for subsequent offline validation.
  • NoCheck. No validation is performed.

For the purposes of this how-to article, the CRL is checked without configuration changes when using certificate authentication.

To use chain trust validation during development time, you first create a self-signed root certificate authority (CA) and install it in the Trusted Root Certification Authority in the local machine. The certificate used by WCF is then created and signed by the root self-signed certificate and installed in the Personal store of the local machine. To allow CRL validation to succeed, you create a self-signed root CRL file and install it in the Trusted Root Certification Authority store of the local machine.

You will use makecert.exe to create a private key file and a certificate to act as your root CA. You will then create a CRL file from the private key that will act as your CRL file for the root CA. You will have to install the root certificate and CRL file. Finally, you will create and install the temporary certificate from the root certificate, using the private key to sign and generate the key.

Summary of Steps

  • Step 1: Create a Certificate to Act as Your Client Root Certificate Authority
  • Step 2: Create a Certificate Revocation List File from the Root Certificate
  • Step 3: Install Your Client Root Certificate Authority on the Client and Server Machines
  • Step 4: Install the Certificate Revocation List File on the Server and Client Machines
  • Step 5: Create and Install Your Temporary Client Certificate

Step 1: Create a Certificate to Act as Your Client Root Certificate Authority

In this step, you use the makecert tool to create a root CA that will be used to sign your certificate. This certificate will be self-signed and will only have the public key that will be used to perform chain trust validation, when authenticating clients with the certificate. The self-signed certificate will act as a root CA itself, instead of pointing to a Root authority in a chain of trust.

  1. Open a Visual Studio command prompt and browse to the location where you want to save the certificate files.

  2. Run the following command to create the root CA:

    makecert -n "CN=RootCaClientTest" -r -sv RootCaClientTest.pvk RootCaClientTest.cer

    In this command:

    • -n specifies the subject name for the root CA. The convention is to prefix the subject name with "CN = " for "Common Name".
    • -r specifies that the certificate will be self-signed. This means that certificates created with this switch will act as a root certificate.
    • -sv specifies the file that will contain the private key of the certificate. The file is always created, if it does not already exist. This will allow creation of certificates using the private key file for signing and key generation.
    • RootCaClientTest.cer specifies the name of the file containing the public key of the certificate. The RootCATes.cer file will not have the private key. This is the certificate that will be installed in the store for chain trust validation on the client and server machines.

  3. In the Create Private Key Password dialog box, enter a password, confirm the password, and then click OK.

    Optionally, you can click None without entering the password, but this is not recommended for security reasons.

  4. In the Enter Private Key Password dialog box, enter the password again and then click OK.

    This is the password needed to access the private key file RootCaClientTest.pvk in order to generate the file RootCaClientTest.cer containing the public key.

This step creates a certificate named RootCaClientTest.cer and a private key file named RootCaClientTest.pvk.

Step 2: Create a Certificate Revocation List File from the Root Certificate

In this step, you create a CRL file that will be imported into the correct certificate stores of the client and service machines. You create a CRL for the temporary root certificate; the CRL is necessary because WCF clients check for the CRL when validating certificates.

  1. Open a Visual Studio command prompt and browse to the location where you want to save the CRL file for the root certificate.

  2. Run the following command to create the CRL file:

    makecert -crl -n "CN=RootCaClientTest" -r -sv RootCaClientTest.pvk RootCaClientTest.crl

    In this command:

    • -crl specifies that you want to generate the CRL file for the root certificate.
    • -n specifies the subject name for the CRL. The convention is to prefix the subject name with "CN = " for "Common Name". You can give it the same name as the root CA.
    • -r specifies that the CRL file will be self-signed. This means that CRL files created with this switch will act as CRL files for the root CA.
    • -sv specifies the file that will contain the private key for CRL file generation. The file is not created because it already exists. This allows creation of CRL files using the private key file for signing.
    • RootCaClientTest.crl is the CRL file created with the command.

Step 3: Install Your Client Root Certificate Authority on the Client and Server Machines

In this step, you install the client root CA in the Trusted Root Certification Authorities location on both the server and client machines. All certificates that are signed with this certificate will be trusted by the client machine.

Note

Important: Be sure to delete this certificate from the store after you have finished developing and testing your application.

Repeat the following steps on both the client and server machines:

  1. Copy the RootCaClientTest.cer file to the client and server machines.
  2. Click Start and then click Run.
  3. In the command line, type MMC and then click OK.
  4. In the Microsoft Management Console, on the File menu, click Add/Remove Snap-in.
  5. In the Add Remove Snap-in dialog box, click Add.
  6. In the Add Standalone Snap-in dialog box, select Certificates and then click Add.
  7. In the Certificates snap-in dialog box, select the Computer account radio button (because the certificate needs to be made available to all users), and then click Next.
  8. In the Select Computer dialog box, leave the default Local computer: (the computer this console is running on) selected and then click Finish.
  9. In the Add Standalone Snap-in dialog box, click Close.
  10. In the Add/Remove Snap-in dialog box, click OK.
  11. In the left pane, expand the Certificates (Local Computer) node, and then expand the Trusted Root Certification Authorities folder.
  12. Under Trusted Root Certification Authorities, right-click the Certificates subfolder, click All Tasks, and then click Import.
  13. On the Certificate Import Wizard welcome screen, click Next.
  14. On the File to Import screen, click Browse.
  15. Browse to the location of the signed root CA RootCaClientTest.cer file copied in Step 1, select the file, and then click Open.
  16. On the File to Import screen, click Next.
  17. On the Certificate Store screen, accept the default choice and then click Next.
  18. On the Completing the Certificate Import Wizard screen, click Finish.

The signed root CA certificate is now installed in the Trusted Root Certification Authorities store. You can expand the Certificates subfolder under Trusted Root Certification Authorities to see the RootCaClientTest certificate installed properly.

Step 4: Install the Certificate Revocation List File on the Server and Client Machines

In this step, you install the CRL from the file in the Trusted Root Certification Authorities location on both the server and client machines. The CRL is checked during the certificate validation process.

Note

Important: Be sure to delete the certificate from the store after you have finished developing and testing your application.

Repeat the following steps on both the client and server machines:

  1. Copy the RootCaClientTest.crl file to the client and server machines.
  2. Click Start and then click Run.
  3. In the command line, type MMC and then click OK.
  4. In the Microsoft Management Console, on the File menu, click Add/Remove Snap-in.
  5. In the Add Remove Snap-in dialog box, click Add.
  6. In the Add Standalone Snap-in dialog box, select Certificates and then click Add.
  7. In the Certificates snap-in dialog box, select the Computer account radio button (because the certificate needs to be made available to all users), and then click Next.
  8. In the Select Computer dialog box, leave the default Local computer: (the computer this console is running on) selected and then click Finish.
  9. In the Add Standalone Snap-in dialog box, click Close.
  10. In the Add/Remove Snap-in dialog box, click OK.
  11. In the left pane, expand the Certificates (Local Computer) node, and then expand the Trusted Root Certification Authorities folder.
  12. Under Trusted Root Certification Authorities, right-click the Certificates subfolder, select All Tasks, and then click Import.
  13. On the Certificate Import Wizard welcome screen, click Next.
  14. On the File to Import screen, click Browse.
  15. On the Files of Type screen, select Certificate Revocation List.
  16. Browse to the location of the signed root CA RootCaClientTest.crl file copied in Step 1, select the file, and then click Open.
  17. On the File to Import screen, click Next.
  18. On the Certificate Store screen, accept the default choice and then click Next.
  19. On the Completing the Certificate Import Wizard screen, click Finish.

The CRL for the root CA certificate is now installed in the Trusted Root Certification Authorities store. You can click the Trusted Root Certification Authorities folder and then press F5 to display the subfolder named Certificate Revocation List. You can expand this folder to see the RootCaClientTest certificate revocation list installed properly.

Step 5: Create and Install Your Temporary Client Certificate

In this step, you create the temporary certificate from the signed root CA created in the previous step and install it on the server machine.

  1. Open a Visual Studio command prompt and browse to the location where the root CA certificate and private key file you created are stored.

  2. Run the following command for creating a certificate signed by the root CA certificate:

    makecert -sk MyKeyName -iv RootCaClientTest.pvk -n "CN=tempClientcert" -ic RootCaClientTest.cer -sr currentuser -ss my -sky signature -pe

    In this command:

    • -sk specifies the key container name for the certificate. This needs to be unique for each certificate you create.
    • -iv specifies the private key file from which the temporary certificate will be created. You need to specify the root certificate private key file name that was created in the previous step and make sure that it is available in the current directory. This will be used for signing the certificate and for key generation.
    • -n specifies the key subject name for the temporary certificate. The convention is to prefix the subject name with "CN = " for "Common Name".
    • -ic specifies the file containing the root CA certificate file generated in the previous step.
    • -sr specifies the store location where the certificate will be installed. The default location is currentuser. For certificate authentication, this is the default location that Microsoft Internet Explorer uses for when browsing Web sites that require a client certificate.
    • -ss specifies the store name for the certificate. My is the personal store location of the certificate.
    • -sky specifies the key type, which could be either signature or exchange. Using signature makes the certificate capable of signing and enables certificate authentication.
    • -pe specifies that the private key is generated in the certificate and installed with it in the certificate store. When you double-click the certificate on the General tab, you should see the message “You have a private key that corresponds to this certificate” displayed at the bottom. This is a requirement for certificate authentication. If the certificate does not have the corresponding private key, it cannot be used for certificate authentication.

  3. In the Enter Private Key Password dialog box, enter the password for the root CA private key file specified in Step 2, and then click OK.

Deployment Considerations

Temporary certificates should only be used for development and testing purposes. In real-world production environments, use a certificate provided by a CA such as Microsoft Windows Server® 2003 Certificate Server or a third party.

Additional Resources