Enable SSL/HTTPS Communication in the Muhimbi Conversion Service

For us in the Northern Hemisphere, this time of year is full of thoughts about warm fires cracking away inside cozy homes. When travelling between these pleasant environments, we wrap ourselves up in protective clothing to face the elements, only relaxing again once we’re back inside.  But what about our data travelling around for conversion?  Normally, it stays nice and safe behind a corporate firewall and never needs to take it’s slippers off.  This is changing- hybrid environments that incorporate a cloud component within the traditional corporate server infrastructure, remote users connecting to resources from unsecured locations, and corporate policies that require secure communications regardless of location are all part of the growing concern over secure communications.

The Muhimbi PDF Converter for SharePoint and Muhimbi PDF Converter Services both use a functionally identical web service in order to allow communication between the system initiating a conversion request and the server performing the actual conversion.  This has many advantages- accessibility from any modern web services based development environment, simplified communication debugging, and the ease of supporting fault tolerant/load balanced environments being just a few.  It also comes with one potential disadvantage when dealing with requests that travel through unsecured environments- HTTP communication does not provide any security or encryption for the data being transmitted.  The solution to this is fairly simple- use standard SSL encryption for communication to keep the advantages of a web service while addressing the concerns of secure communication.

While the solution may be ‘simple’ the implementation of it is a bit more complex.  This blog post falls under the category of ‘Advanced Configuration’ and so a certain amount of understanding of the topics/settings discussed here is required and we strongly recommend testing this is in a development environment first as it significantly changes the underlying communication transport the Converter uses and so may have unintended consequences.

Note: Setting up the Muhimbi Conversion Service to accept web service requests using SSL requires version 7.3 or newer.

Setting this up involves a few discreet sets of steps.  First is the creation of the SSL certificate for the conversion server.  This is similar to the one described in our other blog post, but the two should not be confused- one is a certificate that protects/verifies a file while this one does the same for the actual communication between systems.  It is possible to use the same certificate for both, however this adds complexity and so is not discussed here.  In order to keep this post manageable we’ll explain the creation and configuration of a self-signed server certificate.  Even with this there are a number of ways to proceed.  The most obvious is to use the built-in facility provided by IIS 7, however this can become more complicated than it appears and also causes problems when using host names that are not fully qualified, such as ‘localhost’ or ‘MyConversionServer’.  Since we’re using a self-signed certificate to keep things simple and flexible, we’ll keep to that theme and use the pre-IIS 7 method.

Please note: In this example we are using localhost as the server name.  This needs to be changed to the name of your server that is running the conversion service unless ALL conversions and requests are taking place on the SAME server.  If you have more than one (SharePoint) server or you call the web service from a remote host, the name needs to be changed in ALL steps.  As well, all these steps need to be carried out on the sever that is actually running the Muhimbi Document Converter Service.

1. Download Microsoft’s Selfssl.exe, part of the Internet Information Services (IIS) 6.0 Resource Kit Tools

2. Install only the Selfssl portion (unless you want some of the other utilities)

3. Open a command prompt in the Selfssl folder (default is C:\Program Files (x86)\IIS Resources\SelfSSL)

4. Run this command: SelfSSL /N:CN=localhost /V:3650 /P:41734 /S:1 /T  (be sure to replace localhost with the hostname of the server running the conversion service if a remote system may be sending requests).

5. Click ‘Y’ to replace the bindings for site 1 (If your IIS Site 1 already uses SSL it may lose the settings so write them down)

   

Your SSL certificate is now created and bound to the Muhimbi Converter port, 41734, however it is attached to an IIS site- not the actual conversion web service.  What we now how have to do is remove it from IIS and then bind it to the conversion web service on the correct port.

1. Open the IIS Manager

2. Go to ‘Sites’ under the server where the previous steps were run, right-click on the site with ID 1, and then open ‘bindings’

3. In there you will see an HTTPS type binding to port 41734.  Highlight this and then click ‘remove’.  If this binding is the only one (no other IIS bindings exist), then you may need to temporarily add a new port binding in order to remove this one.

The SSL certificate is still installed, however it is not bound to any service.  What we need to do is bind this certificate to the Converter web service.

1. First we need to get the certificate’s ‘Thumbprint’.  This is done in IIS manager, select the top level server name (SHARECONVERT in the screenshot above) and then open the ‘Server Certificates’ option under the ‘IIS’ group.

2. Open the relevant certificate and navigate to the ‘Details’ tab. Select the Thumbprint field at the bottom of the list, copy this value to notepad and remove all the spaces between the couplets.

   

3. Open a command prompt, replace the red text with the edited thumbprint, execute the command followed by an iisreset:

   netsh http add sslcert ipport=0.0.0.0:41734 certhash=60fa569486e84dd4b4def2c84ed7d1e31ef4cebd appid={9A817CD6-9F0F-4712-B4E5-10FC1590EAD7}

   The red portion of the command is the thumbprint that you copied and removed the spaces from in the previous step.  The rest stays the same as it includes the unique application ID for the conversion service.

Okay, Now we have created the certificate and have bound it to the conversion service.  We just haven’t told the conversion service that it has this means of communication available to it.  This requires changing the Configuration File as well as changing the server address in SharePoint (for the Converter for SharePoint) or in your client code for the non-SharePoint version of the software.

In the Configuration File we need to change the following entries.  Please note the red text as these are the changes that need to be made from the default configuration:

1. Replace http with https here

2. Replace http with https here

3. Replace None with Transport here <security mode=“Transport”>

4. Replace http with https here

5. Save the Configuration File and restart the conversion service.

If you are using SharePoint, then you need to change the Address of the server running the conversion service so that it points to ‘https’ instead of ‘http’.  This field can be found in our Central Administration Screen (Application Management / Muhimbi Document Converter Settings in SP2007 or General Application Settings / Muhimbi Document Converter Settings in SP2010/2013).

Now that this is done, the next step is- to test it!

To do this, simply open a browser on the server running the conversion service and enter this URL:

https://localhost:41734/Muhimbi.DocumentConverter.WebService/?wsdl

Obviously, if you have used something other than localhost this would need to be changed in the URL.  If everything is setup and running correctly the URL should open without error:

You now have the ability to communicate between systems requesting conversions and the Converter via HTTPS!