Subscribe to News feed

Enable SSL/HTTPS Communication in the Muhimbi Conversion Service

Posted at: 04:27 on 02 December 2014 by David Radford

secureFor 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)
      image

 
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.

 binding

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.
     
    thumbprint
  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 <add baseAddress="https://localhost:41734/Muhimbi.DocumentConverter.WebService/" />
  2. Replace http with https here <endpoint address="mex" binding="mexHttpsBinding" contract="IMetadataExchange" />
  3. Replace None with Transport here <security mode="Transport">
  4. Replace http with https here <serviceMetadata httpsGetEnabled="True" />
  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).

SharePoint

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!

.

Labels: , , , ,

3 Comments:

  • I have followed this guide step by step, and I can call the ?WSDL url fine, but when I go into Document Converter Settings in SharePoint 2013 (single server dev farm), I get an error:
    An error occurred while connecting to the Document Converter Web Service, make sure it is installed and started. The exact message is 'An error occurred while receiving the HTTP response to http://localhost:41734/Muhimbi.DocumentConverter.WebService/. This could be due to the service endpoint binding not using the HTTP protocol. This could also be due to an HTTP request context being aborted by the server (possibly due to the service shutting down). See server logs for more details.'.

    If i insert https://localhost:41734/Muhimbi.DocumentConverter.WebService/ and click TEST
    I get the error:
    An unexpected error occurred while processing your request, for details see the server's Windows Application Event Log.

    In application event log this is the only entry:
    The description for Event ID 41734 from source Microsoft-SharePoint Products-SharePoint Foundation cannot be found. Either the component that raises this event is not installed on your local computer or the installation is corrupted. You can install or repair the component on the local computer.

    If the event originated on another computer, the display information had to be saved with the event.

    The following information was included with the event:


    Muhimbi PDF Converter
    An unexpected error has occurred. Additional information:
    Complete URL: code
    Muhimbi.SharePoint.DocumentConverter.PDF.MuhimbiException: An unexpected error occurred while processing your request, for details see the server's Windows Application Event Log.
    at Muhimbi.SharePoint.DocumentConverter.PDF.WebServiceDocumentProcessor.OpenService(String address, Int32 maxRequestSize)
    at Muhimbi.SharePoint.DocumentConverter.PDF.WebAppDocumentConverterSettings.<>c__DisplayClassa.b__8()
    at Microsoft.SharePoint.SPSecurity.<>c__DisplayClass5.b__3()
    at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode)
    at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(WaitCallback secureCode, Object param)
    at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(CodeToRunElevated secureCode)
    at Muhimbi.SharePoint.DocumentConverter.PDF.WebAppDocumentConverterSettings.ValidateWebService()

    the message resource is present but the message is not found in the string/message table

    By Anonymous Anonymous, At 13 January, 2015 14:28  

  • At the top of the article it is mentioned that you need to run version 8.0 or later. At the time of writing 8.0 is not yet publicly available, but if you contact support@muhimbi.com you can request a patch for the latest public release that adds support for ssl.

    By Blogger Muhimbi, At 13 January, 2015 14:46  

  • Update, this is included in the 7.3 release, no need to wait for 8.0.

    By Blogger Muhimbi, At 23 June, 2015 17:13  

Post a Comment

Subscribe to Post Comments [Atom]

Links to this post:

Create a Link

Need support from experts?

Access our Forum

Download Free Trials