Configuring TLS on Windows Vista, Windows 7 and Windows Server 2008

 

The XDS Toolkit can be used to create applications that are self-hosted services and communicate using HTTP and HTTPS/TLS.  One example is an XDS Repository Actor that runs as a Windows service and requires both server (for Provide and Register Document Set and Retrieve Document Set transactions) and client (for Register Document Set transaction) endpoints.

 

Medical Connections provide the option of using either standard Windows certificate services, or another, open-source TLS solution called Bouncy Castle.  Bouncy Castle arguably offers more control over the deployment of certificates, however it is not currently possible to use Bouncy Castle to secure a Windows server endpoint interface.  The remainder of this article discusses the steps necessary to configure a Windows system to use the built-in certificate handling for HTTP/TLS on a server endpoint.

 

Note that the following procedures apply only to Vista, Windows 7 and Windows Server 2008 (or later) platforms. 

 

The Certificates

I will not go into great detail about X509 certificates and how they are created and used – there are plenty of references available online.  Three certificates are required to secure a client-server connection:

  • A Server Certificate – authenticates a server to a client
  • A Client certificate – authenticates a client to a server
  • A Root CA Certificate – validates the authenticity of certificates.  There may also be an intermediate root certificate.

 

In addition to this, you will also need a password (sometimes called a passphrase) which is set when the certificate is created and is used to secure the Private Key. 

 

Sample code supplied by Medical Connections includes certificates as three files:

  • CARoot.crt – Contains the CA Root certificate only
  • MedConn_Connectathon_Client.pfx – contains the Server certificate, the private key, an intermediate CA certificate and the root CA certificate
  • MedConn_Connectathon_Client.pfx pfx – contains the Client certificate, the private key, an intermediate CA certificate and the root CA certificate

 

Importing Certificates in Windows

  1. From the Start menu click Run…
  2. Type mmc then enter.  Click Yes when the UAC dialogue is displayed.
  3. From the File menu select Add/Remove Snap-in.
  4. From the list select Certificates then Click Add.
  5. Click the Computer account radio button then Next.
  6. Click the Local computer radio button then Finish.
  7. Click OK in the Add/Remove Snap-ins dialogue.
  8. In the left pane expand Certificates (Local Computer) then expand Personal.
  9. Under Personal Right-click Certificates.  Click All Tasks then Import….
  10. In the Certificate Import Wizard dialogue, click Next.
  11. Browse to the Server certificate file (MedConn_Connectathon_Client.pfx in this example – you may need to change the extension search type to pfx) then click Next.
  12. Enter the password and check the box to Mark this key as exportable. Click Next.
  13. Select the radio button Place all certificates in the following store and browse to select Personal. Click Next.
  14. Click Finish.  There should now be three (new) certificates in the Personal store.
  15. Double-click on the server certificate and select the Certification Path tab to show the hierarchy of the certificates. Make a note of it and click OK to close the dialogue.
  16. Click on the Root CA certificate and drag it to the Certificates folder under the Trusted Root Certification Authorities store.
  17. Click on the Intermediate CA certificate (if there is one) and drag it to the Certificates folder under the Intermediate Certification Authorities store.
  18. Double-click on the server certificate and select the Details tab to show the properties of the server certificate. Scroll down the list to find the Thumbprint field and click on it.  In the lower text box highlight the value (20 hex numbers), and press Ctrl-C to copy to the clipboard. Click OK to close the dialogue.
  19. Open a text editor (Notepad will do) and paste the copied thumbprint value.  Delete spaces between the numbers (or search and replace space with nothing) to give a 40-character hex number.  Leave the editor open – you will need this number again shortly.

 

Associating a Certificate with a Service or Application

To allow your application to use Windows’ certificate services, you need two things:

  • Your application to be listening on a specific TCP/IP port and
  • The port on which your application is listening to be associated with a certificate

With the Medical Connection XDS Toolkit, the first of these prerequisites is easily satisfied by the following code fragment:

 

static XdsMtomServer server;

const string MyURISecure = “https://MedicalConnections_Server:9099/XDSRepository”

.......

server = new XdsMtomServer();

.......

server.ProvideAndRegisterRequestReceived +=

new RegisterDocumentSetHandler(server_ProvideAndRegisterRequestReceived);

server.RetrieveRequestReceived +=

new RetrieveHandler(server_RetrieveRequestReceived);

.......

server.Listen(MyURISecure);

 

Note the port number (9099 in the example) in the MyURISecure string.  This is used in the next stage – associating the application with a server certificate.  You will need two more items of information before proceeding:

  1. The certificate hash or thumbprint that you saved in the previous section
  2. The application GUID for your application.  You can find this by opening AssemblyInfo.cs in your application project and looking for an entry similar to the following:

    // The following GUID is for the ID of the typelib if this project is exposed to COM
    [assembly: Guid("21e9c851-4792-933b-a2f4-2d7ee6cf9b1c ")]

    The GUID is the string of hex characters between to quotation marks.

 

Now we can proceed with the final step:

  1. Open a new command prompt with Administrator privileges
    1. Start, All Programs, Accessories
    2. Right-click on Command Prompt then select Run as administrator
  2. Enter the following command (note: broken over multiple lines for clarity):
    netsh http add
    sslcert ipport=0.0.0.0:9099
    certhash=363b6936c1ff418311f6003cf7da2fd8cd3798b9
    appid={21e9c851-4792-933b-a2f4-2d7ee6cf9b1c}
    clientcertnegotiation=enable

    You need to replace the above values with those from your own environment:

    1. ipport : The port number from your own URI
    2. certhash : the hash/thumbprint saved from the certificate (no spaces)
    3. appid : the GUID of your application.  Don’t forget the curly braces.
  3. The command should return with
    SSL Certificate successfully added

This command will associate the server certificate with port 9099.  Because we have specified an IP address of 0.0.0.0, it will listen on port 9099 on any IP address.  You can lock this down to a specific IP address, but this is not generally a good idea if you are relying on DNS for host name resolution.

 

Gotchas

  • This method is specifically for the later Windows operating systems.  If you are using XP or Windows Server 2003, the netsh command line application must be replaced with httpcfg, which has similar but not identical syntax.  http://msdn.microsoft.com/en-us/library/ms733791.aspx is a good place to start.
  • Don’t forget to use an ‘elevated’ command prompt for netsh -  you must Run as administrator.  If you do not have administrator privileges then you need the assistance of someone who does.
  • Be sure that, after import, the certificates are moved to the correct stores (steps 16 and 17 in the import process, above).  If they are not correctly located, you may get an error returned from the netsh command.
  • The hostname in the server URI (MedicalConnections_Server in this example) must match the name in the Issued To field in the server certificate.  You may need to add a new CNAME or A record in your DNS, or modify your HOSTS files (on server and client) to use the correct hostname.
  • When connecting to your newly-created web service with a client application, be sure to use the correct client certificate and URI.  It is easy to miss the ‘s’ off ‘https’ during an editing session, or to specify the wrong port number.
     

 

 

 

Relevance: