学步园

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

• For more information on how to work with temporary certificates, see “How to: Create Temporary Certificates for Use During Development” at
  http://msdn2.microsoft.com/en-us/library/ms733813.aspx
• For more information on how to view certificates using the MMC snap in, see “How to: View Certificates with the MMC Snap-in” at
  http://msdn2.microsoft.com/en-us/library/ms788967.aspx
• For more information on differences in certificate validation between Microsoft Internet Explorer and WCF, see “Differences Between Service Certificate Validation Done by Internet Explorer and WCF” at
  http://msdn2.microsoft.com/en-us/library/aa702599.aspx
• For more information on differences in certificate validation between protocols, see “Certificate Validation Differences Between HTTPS, SSL over TCP, and SOAP Security” at
  http://msdn2.microsoft.com/en-us/library/aa702579.aspx
• For more information on how to obtain a certificate, see “How to: Obtain a Certificate (WCF)” at
  http://msdn2.microsoft.com/en-us/library/aa702761.aspx
• For more information on WCF command-line tools, see “Windows Communication Foundation Tools” at
  http://msdn2.microsoft.com/en-us/library/ms732015.aspx
• To download the WCF samples, including the FindPrivateKey tool, see “Windows Communication Foundation (WCF), Windows Workflow Foundation (WF) and Windows CardSpace Samples” at
  

  http://www.microsoft.com/downloads/details.aspx?FamilyId=2611A6FF-FD2D-4F5B-A672-C002F1C09CCD&displaylang=en

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.