ASP.NET, SQL Server, WPF, C#, VB.NET

Certificate Creation Tool (Makecert.exe):

The Certificate Creation tool generates X.509 certificates for testing purposes only. It creates a public and private key pair for digital signatures and stores it in a certificate file. This tool also associates the key pair with a specified publisher's name and creates an X.509 certificate that binds a user-specified name to the public part of the key pair.

NOTE: Only the Makecert from the .NET Framework 1.1 (Everett) has the capability to create test certificates that can be used successfully with the WSE! Because this can be difficult to find, I have included a copy of the newest Makecert.exe in the downloadable ZIP file for this solution at the bottom of the article.

Makecert.exe includes basic and extended options. Basic options are those most commonly used to create a certificate. Extended options provide more flexibility.

makecert [options] outputCertificateFile

Basic Options

Extended Options

Examples

The following command creates a test certificate and writes it to testCert.cer.

makecert testCert.cer

The following command creates a test certificate and writes it to testPAB.cer, using the subject's key container and the certificate subject's X.500 name, and writes it to the root store:

makecert -sk PAB -n "CN=PeterBromberg" -ss root -sr localmachine testPAB.cer

If you do not specify "localmachine" with the "sr" switch, or do not provide this switch, when this is executed from a Visual Studio.NET command prompt you will see the following dialog upon success:

NOTE: to enable a Visual Studio.NET "command prompt here" context menu item, just save the following lines to a text file with a .REG extension and double-click on the saved file:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Directory\shell\Command Prompt\Command]
@="Cmd.exe /k \"C:\\Program Files\\Microsoft Visual Studio .NET\\Common7\\Tools\\vsvars32.bat\" "

Voila! Context menu choice for a Command Prompt with VS.NET environment by simply right-clicking on any folder!

OK, so that was our hot-shot crash course in Certmgr.exe and Makecert.exe! Now we can build a BinarySecurityToken. First thing we need in order to include a certificate with a request is to tell .NET where to find it. Certificates are normally kept in a Certificate Store, and each user has a private store of certificates. The certificate itself is not really "private" since it is only a digitally - signed way to give out a public key. What's important is that it matches the private key in the secure key store of the person who is going to use the certificate. In this manner, you can digitally sign a message with your private key, and the receiver would be able to verify your digital signature using the matching public key that you have included along with the message. If you are somewhat fuzzy on how RSA encryption and public / private keys work, you might find my article "RSA Encryption Demystified" enlightening.

WSE provides classes to open Windows Certificate stores and access the certificates. If you would like to iterate some of your certificates programmatically, here is how to access them:

You can also retrieve certificates by using one of the search methods, like so:

X509CertificateCollection cc=store.FindCertificateBySubjectString(strName);
foreach(X509Certificate cert3 in cc)
listBox1.Items.Add(cert3.GetName());

The above will match on a substring, which can be very useful.

Now that we have seen how to create certificates, manipulate them and access them programmatically, we can access the certificate on the server side in a manner not too different from the way we got our UsernameToken in the previous article. We are almost ready to start with our code, but before we do, let's make sure that ASP.NET has the required permissions to access the certificate store on the server.

Required Permissions forWSE to Sign or Decrypt with an X.509 Certificate

In order for WSE to obtain the X.509 private key from the local computer certificate store, it must have permission to do so. By default, only the owner and the System account can access the private key of a certificate. Also by default, the ASP.NET service runs under the ASPNET account, and that account does not have access to the private key.

To give the ASPNET account access to the private key, give the account under which ASP.NET is running Full Control access to the files containing the keys the WSE will need to retrieve in the following folder:
C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys

The account the ASP.NET worker process runs under is controlled by the <processModel> element in the Machine.config file. Set the userName attribute of the <processModel> element to specify the account ASP.NET runs under. By default, the userName attribute is set to the special machine account, which maps to the low-privileged ASPNET user account created when the .NET Framework SDK is installed.

Creating the Web Service Methods

At the server, we need to specify where the WSE searches for X.509 certificates when it attempts to retrieve or verify a certificate. Typically, a client application sets the storeLocation attribute to CurrentUser and an XML Web service sets it to LocalMachine. The default is LocalMachine.
This attribute also specifies the certificate store the CA certificate chain is retrieved from during the signature verification process. The signature verification process occurs when a SOAP message that is signed is received to verify the integrity of the signature. If the SOAP message recipient is an XML Web service, then the WSE always retrieves the CA certificate chain from the LocalMachine, unless the process identity for ASP.NET (ASPNET by default) is changed to an account with log-on permissions. The identity of the ASP.NET account is specified in the <processModel> element. Since in this case we are also using a test certificate created by Makecert.exe, we also need to specify that the AllowTestRoot attribute is set to "true". our <x509 ... element goes in the <configuration> <microsoft.web.services> <security> section of web.config, and should look like the following:

<x509 storeLocation="CurrentUser" verifyTrust="true" allowTestRoot="true" />

We also need to add the X509 class to our Webservice (both on the client and the server) with:

using Microsoft.Web.Services.Security.X509;

So now, on the server, our WebMethod will look like the following:

Not very different at all from how we handled UsernameTokens! Now on the client, our method will look like this:

Under the hood, our SOAP Header now sports a nice addition, the BinarySecurityToken element:

With this, we are 95 percent of the way to "First Base" -- we've learned how to code the Web Service to look for a valid X509 Certificate in the SOAP headers from the Client, and we've learned how to retrieve and send a specific certificate from the local machine store for the client and add it to the SOAP headers according to the WS-Security specifications with WSE. However, the mere act of sending a certificate in our SOAP messages is not much of a way to authenticate anything. The idea is to sign some entity (SOAP Body, whatever) with the private key corresponding to the public key contained in the certificate that is sent. Then, the recipient can use the public key to determine that the message is intact and has not been altered, and that the sender is who they say they are.

With WSE, creating these digital signatures is easy and fast. We have a SoapContext.Security.Elements collection that allows us to add various WS-Security conformant elements. So by simply adding to the code above where we retrieved and included our certificate, we can now use it to sign the request as well. On the client, this only requires a few additional lines of code:

Now we'll need to verify the digital signature on the server in our Web Service. Our final WebMethod looks like this:

Voila! We have now retreived an X509 Certificate on the client, included it in the SOAP Headers, and used it to sign the SOAP Body. On the server, we checked to see if a valid X509 Certificate was used and verified that it indeed has been used to sign the message Body using the SignatureOptions property. Since we now know who sent the message and that it arrived at the Web Service unaltered, we send back the requested DataSet. You can download the full solution at the link below. Of course, you will need to either create your own certificate, or use one that is common to both client and server machines, and change the various portions of the code where it is retrieved and referenced. In the next installment of this series, we'll look more deeply at the various SignatureOptions properties, perform partial message signing as well as XML Encryption, and look into the WSE "pipeline", including how to use DIME attachments.