How to: Create and Install Temporary Certificates in WCF for Message Security During Development

  • Article

patterns & practices Developer Center

Applies to

  • Microsoft Windows Communication Foundation (WCF) 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 message security. 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 Root Certificate Authority
  • Step 2: Create a Certificate Revocation List File from the Root Certificate
  • Step 3: Install Your Root CA 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 Service Certificate
  • Step 6: Give the WCF Process Identity Access to the Temporary Certificate’s Private Key
  • Deployment Considerations
  • Additional Resources

Objectives

  • Learn how to create a root certificate for the temporary certificate used for WCF message security.
  • Learn how to create a root certificate revocation list (CRL) file for the root certificate used to validate revocation.
  • Learn how to create a temporary certificate for WCF message security.
  • 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 provide message security, 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 discusses 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 message security.

Additionally, a certificate revocation list (CRL) validation is performed during message security. This validation checks the list of certificates that were revoked by the root certificate. There are three modes of revocation:

  • Online. The CRL list is retrieved and the check happens online, requiring connectivity to the URLs.
  • Offline. The CRL list is retrieved, the check happens online and is then cached for subsequent validation.
  • NoCheck. No validation is performed.

This how-to article discusses the CRL check without configuration changes when using message security.

To use chain trust validation during development time, you create a self-signed root certificate authority (CA) and install it in the Trusted Root Certification Authority location in the local machine. The certificate used by WCF is signed by the root self-signed certificate and installed in the Personal store of the local machine. To ensure that the CRL check succeeds, 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 revocation list file for the root CA. Next, you will 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 Root Certificate Authority
  • Step 2: Create a Certificate Revocation List File from the Root Certificate
  • Step 3: Install Your 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 Service Certificate
  • Step 6: Give the WCF Process Identity Access to the Temporary Certificate’s Private Key

Step 1: Create a Certificate to Act as Your 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 do the trust chain validation when encrypting and signing messages. The self-signed certificate will act as a root certificate 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=RootCATest" -r -sv RootCATest.pvk RootCATest.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 exist. This will allow creating certificates using the private key file for signing and key generation.
    • RootCATest.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 trust chain 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 RootCATest.pvk in order to generate the file RootCATest.cer containing the public key.

This step creates a certificate named RootCATest.cer and a private key file named RootCATest.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 will 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=RootCATest" -r -sv RootCATest.pvk RootCATest.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 revocation list files for the root CA.
    • -sv specifies the file that will contain the private key for CRL file generation. There is no need to create this file because it already exists. This will allow creation of CRL files using the private key file for signing.
    • RootCaTest.crl is the CRL file created with the command.

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

In this step, you install the certificate 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 for your application.

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

  1. Copy the RootCATest.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, 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. Browse to the location of the signed Root Certificate Authority RootCATest.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 RootCATest 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 for your application.

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

  1. Copy the RootCATest.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. In Files of Type, select Certificate Revocation List.
  16. Browse to the location of the signed Root Certificate Authority RootCATest.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. To view the CRL, click the Trusted Root Certification Authorities folder then press F5. A subfolder named Certificate Revocation List will be displayed. Expand this folder and you will see the RootCATest CRL installed properly.

Step 5: Create and Install Your Temporary Service Certificate

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

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

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

    makecert -sk MyKeyName -iv RootCATest.pvk -n "CN=tempCert" -ic RootCATest.cer -sr localmachine -ss my -sky exchange -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, but since the certificate needs to be available to all users, you should use the localmachine option.
    • -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 exchange makes the certificate capable of signing and encrypting the message.
    • -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 a message at the bottom stating, “You have a private key that corresponds to this certificate”. This is a requirement for message security. If the certificate does not have the corresponding private key, it cannot be used for message security.

  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.

Step 6: Give the WCF Process Identity Access to the Temporary Certificate’s Private Key

In this step, you give the process identity of the WCF service access permissions to the certificate’s private key. If your service is hosted in Internet Information Services (IIS), the identity typically is "NT AUTHORITY\NETWORK SERVICE"; in a production scenario, or if your service is hosted in a Windows service, it could be a custom domain service account.

  1. Open a Visual Studio command prompt.

  2. Run the following command:

    FindPrivateKey.exe My LocalMachine -n "CN=tempCert"

    In this command:

    • My is the store name where you have installed your temporary certificate.
    • LocalMachine is the store location for your certificate.
    • –n "CN=tempCert" is the common name for your temporary certificate.

    Note

    If FindPrivateKey is not on your machine, download the WCF samples, including the FindPrivateKey tool, at https://www.microsoft.com/downloads/details.aspx?FamilyId=2611A6FF-FD2D-4F5B-A672-C002F1C09CCD&displaylang=en.

    FindPrivateKey returns the location of the private key for the certificate, similar to "C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\Machinekeys\4d657b73466481beba7b0e1b5781db81_c225a308-d2ad-4e58-91a8-6e87f354b030".

  3. Run the following command to assign access permissions to the process identity of the WCF service.

    Note

    You should give read-only permissions to the private key.

    cacls.exe "C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\Machinekeys\4d657b73466481beba7b0e1b5781db81_c225a308-d2ad-4e58-91a8-6e87f354b030" /E /G "NT AUTHORITY\NETWORK SERVICE":R

    In this command:

    • /E edits the access control list (ACL) of the private key instead or replacing it. You should never replace the ACL but should only add the necessary permission to the process identity.
    • /G grants the permission to the process identity.
    • :R gives read-only permissions to "NT AUTHORITY\NETWORK SERVICE".

  4. Run the following command to verify the permissions on the private key. This will display all the identities and the permissions that have access to the private key:

    cacls.exe "C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\Machinekeys\4d657b73466481beba7b0e1b5781db81_c225a308-d2ad-4e58-91a8-6e87f354b030"

    You should see the following in the output from this command:

    NT AUTHORITY\NETWORK SERVICE:R

Note

If you are running Microsoft Windows® XP, give the certificate permissions for the ASPNET identity instead of the NT Authority\Network Service identity, because the IIS process runs under the ASPNET account in Windows XP.

Deployment Considerations

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

Additional Resources