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

- J.D. Meier, Jason Taylor, Prashant Bansode, Carlos Farre, Madhu Sundararajan, Steve Gregersen

Applies to

  • Microsoft Windows Communication Foundation (WCF) 3.5
  • Microsoft® Visual Studio® 2008

Summary

This How To article walks you through to 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.

Contents

  • Objectives
  • Overview
  • Summary of Steps
  • Step 1 – Create a Certificate to Act as Your Root Certificate Authority
  • Step 2 – Install Your Root Certificate Authority on the Server and Client Machines
  • Step 3 – Create and Install Your Temporary Service Certificate
  • Step 4 – Give the WCF Process Identity Access to the Temporary Certificate’s Private Key
  • Deployment Considerations
  • Additional Resources

Objectives

  • Learn how to create and use a temporary certificate for WCF message security.
  • Learn where to store the temporary certificate.
  • Learn how to troubleshoot common errors related to temporary certificates and message security in WCF.

Overview

When developing a service that uses X.509 certificates to provide message security, it is necessary to work with temporary certificates. 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.

To use chain trust validation during development time, you create a self-signed root certificate authority (CA) that will be placed in the Trusted Root Certification Authority store. The certificate used by WCF is then created from the root self-signed certificate and installed in the LocalMachine store.

Summary of Steps

  • Step 1 – Create a Certificate to Act as Your Root Certificate Authority
  • Step 2 – Install Your Root Certificate Authority on the Server and Client Machines
  • Step 3 – Create and Install Your Temporary Service Certificate
  • Step 4 – 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.
  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.
  • -sv – Specifies the file that contains the private key of the certificate.
  • RootCATest.cer – Specifies the name of the file containing the public key of the certificate.
  1. 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.
  2. 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 – Install Your Root Certificate Authority Certificate on the Server and Client Machines

In this step, you will 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.

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 3 – 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 privatekeyfile installed.
  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 tempCert.cer

In this command:
  • -sk – Specifies the key container name for the certificate. This needs to 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 privatekeyfile name and make sure that it is available in the current directory.
  • -n – Specifies the key subject name for the temporary certificate.
  • -ic – Specifies the file containing the root CA certificate file generated in 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 private key exportable, which is required for message security.
  • -pe – Specifies that the private key is exportable. This is useful if you want to export the key and use it in another machine for development or testing purposes.
  1. In the Enter Private Key Password dialog box, enter the password for the root CA privatekeyfile specified in STEP 2, and then click OK.

Step 4 – 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 private key. If your service is hosted in Internet Information Services (IIS), the identity typically is "NT AUTHORITY\NETWORK SERVICE"; in a production scenario, 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 – the store name where you have installed your temporary certificate.
  • LocalMachine – the store location for your certificate.
  • –n "CN=tempCert" – the common name for your temporary certificate.

Note: If FindPrivateKey is not on your machine, download the WCF samples, including the FindPrivateKey tool, at http://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".
  1. 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".
  • 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 Server or a third party.

By default, the service credentials are negotiated automatically; when using certificates for message security, certificates are the service credentials. As part of the negotiation of the service certificate, the client looks up the revocation list to ensure that the certificate is valid. However, the temporary certificates will not have a revocation list to check against. Therefore you will need to configure your client settings for RevocationMode to be set to NoCheck, so that this check is not done. You can do this by carrying out the following steps:
  1. After you have added the service reference to your client, right-click the App.config file and then click Edit WCF Configuration.
  2. In the configuration editor, expand the Advanced node and then select New Endpoint Behavior Configuration
  3. Click Add.
  4. In the Adding Behavior Element Extension Sections dialog box, select clientCredentials and then click Add.
  5. Expand the clientCredentials node, expand the serviceCertificate node, and then select authentication below it.
  6. Set the RevocationMode attribute to NoCheck by choosing this option from the drop-down list.
  7. In the configuration editor, expand the Client node, expand the Endpoints node, and then select the Endpoint node.
  8. Set the BehaviorConfiguration attribute to NewBehavior by choosing this option from the drop-down list. This is the endpoint behavior you just created.
  9. In the configuration editor dialog box, on the File menu, click Save.
  10. In Visual Studio, verify your configuration. The configuration should look as follows:

 …
<behaviors>
    <endpointBehaviors>
        <behavior *name="NewBehavior"*>
            <clientCredentials>
                <serviceCertificate>
                    <authentication *revocationMode="NoCheck"* />
                </serviceCertificate>
            </clientCredentials>
        </behavior>
    </endpointBehaviors>
</behaviors>
<client>
    <endpoint *behaviorConfiguration="NewBehavior"* ….>
    </endpoint>
</client>
… 


Important: This should be done in development only, when using the makecert utility for creating the certificates. In a production environment, do not overwrite the revocationMode settings.

The negotiation process checks for the name of the certificate, expecting it to match the fully qualified Domain Name System (DNS) name or NETBIOS name, depending on whether you are addressing the service using either of those two names. If your certificate name does not match the name’s fully qualified DNS or NETBIOS names, in the service endpoint configuration, set the identity with the DNS value matching the certificate name as shown below. Optionally, you can leave it blank, which will add the encoded value of the certificate to the client configuration when adding the service reference.
<services>
  <service ….>
    <endpoint ….>
	<identity>
	   <dns value="TempCert"/>
	</identity>
    </endpoint>
  </service>
</services>

Additional Resources

Contributors and Reviewers

  • External Contributors and Reviewers:
  • Microsoft Consulting Services and PSS Contributors and Reviewers:
  • Test team: Rohit Sharma, Chaitanya Bijwe, Parameswaran Vaideeswaran.
  • Edit team: Dennis Rea.
  • SEO team: Rob Boucher.

Last edited Mar 28, 2008 at 11:29 PM by prashantbansode, version 7

Comments

paul3654 Nov 17, 2010 at 12:27 PM 
I must be missing something here, but in step 3 we are creating and installing a temp cert on the server and 4 we are giving permissions to WCF identity process correct? Then we are asked to open a visual studio command prompt to run a makecert and findPrivateKey command, is this assuming that i have visual studio in stalled on the server?
Paul

chandrasena111 Aug 31, 2009 at 1:39 PM 
FindPrivateKey doesn't returns the location of the private key for the certificate.
FindPrivateKey.exe My LocalMachine –n "CN=tempCert" always providing help information like as follows...

D:\Certificates>FindPrivateKey my CurrentUser -n "CN=tempCert"
FindPrivateKey helps user to find the location of the Private Key file of a X.50
9 Certificate.
Usage: FindPrivateKey <storeName> <storeLocation> [{ {-n <subjectName>} | {-t <t
humbprint>} } [-f | -d | -a]]
<subjectName> subject name of the certificate
<thumbprint> thumbprint of the certificate (use certmgr.exe to get it)
-f output file name only
-d output directory only
-a output absolute file name
e.g. FindPrivateKey My CurrentUser -n "CN=John Doe"
e.g. FindPrivateKey My LocalMachine -t "03 33 98 63 d0 47 e7 48 71 33 62 64 76 5
c 4c 9d 42 1d 6b 52" -c

I tried providing 'thumbprint' also. But, no use.. Can any one help me how to resolve this issue?

colinbo Jun 12, 2009 at 6:23 AM 
You can use the following commands if you have the Windows SDK and Windows Resource Kit Tools installed:

MakeCert.exe -n "CN=localhost" -r -sv RootCA.pvk RootCA.cer
MakeCert.exe -n "CN=localhost" -iv RootCA.pvk -ic RootCA.cer -sky exchange -sv LocalHost.pvk LocalHost.cer

Pvk2Pfx.exe -pvk LocalHost.pvk -spc LocalHost.cer -pfx LocalHost.pfx

CertUtil.exe -AddStore Root RootCA.cer
CertUtil.exe -ImportPfx LocalHost.pfx

WinHttpCertCfg.exe -g -c LOCAL_MACHINE\MY -s localhost -a "NETWORK SERVICE"

noble1975 Jan 25, 2009 at 1:37 AM 
when run the following command makecert -sk MyKeyName -iv RootCATest.pvk -n "CN=tempCert" -ic RootCATest.cer -sr localmachine -ss my -sky exchange -pe tempCert.cer
I get the following
error makecert -sk MyKeyName -iv RootCATest.pvk -n "CN=tempCert" -ic RootCATest.cer -sr localmachine -ss my -sky exchange -pe tempCert.cer Faild
I'm using windows vista ultimate and the account I'm running is admin account, also the same machine is the client and the server.

dprTCSCcom Apr 10, 2008 at 5:58 PM 
In the command line examples above (e.g. FindPrivateKey.exe My LocalMachine –n "CN=tempCert"), if you copy and paste directly from the web page to a command line, the program will fail - typically displaying a usage message. The web page uses an "en dash" (decimal 150) character while the command line program expects a "hyphen-minus" (decimal 45) character. To avoid this problem, retype the dash before each flag.

ploeh Apr 4, 2008 at 5:49 PM 
...and if you want to automate the entire certificate installation and uninstallation, you can do this: http://blogs.msdn.com/ploeh/archive/2008/03/16/CertificateInstaller.aspx