HTTPS Certificates and Port Binding
Securing your HL7 messages with Integration Host and HL7 Soup really is as easy as clicking a checkbox. However, that simple action hides the background complexities from the user. Occasionally, it might be handy to adjust the HTTPS configuration manually. Perhaps you need to access an HTTP Receiver from the internet, perhaps you are running Integration Host as a user that doesn’t have permissions to bind to a port, or maybe you have certificate issues. This document explains what’s happening behind the scenes to help you work through these and other challenges.
The first thing you need to know is, does an HTTP Receiver do? Essentially it is a .net framework object called an HttpListener that is doing the listening. When you select HTTPS, HL7 Soup will configure the port to use a certificate that secures the channel. Selecting the default certificate will use the one created during installation. Note that this certificate automatically generates with each installation; it isn't a shared with others. Each installation gets its own certificate with its own private key.
Although the generated certificate is perfectly secure, you still may wish to replace it with your own. It's easy to do this by entering the thumbprint of your certificate. You could go one step further by replacing the default thumbprint with your certificate's thumbprint.
The contents of this file contain the default certificate thumbprint
C:\ProgramData\Popokey\SharedSettings\DefaultSSLCertificateThumbprint.txt
If you update this to point to your certificate, you won’t need to configure HTTP to use your certificate manually each time. It would also mean that communication between Integration Host and Integration Client can also use your certificate.
The rules of http.sys control what's allowed with the .net HttpListener. To receive a message on a specific port, from another computer (on the same network), we have to bind to the port using the http.sys command:
netsh http add urlacl url=https://+:Port user=CurrentUser
This is done silently but is a requirement to allow messages through. If you are not running as an administrator, you’ll get a request to elevate when you start the workflow. This elevation is to allow this registration.
At the same time, we also register your SSL certificate using a similar command:
http add sslcert ipport=0.0.0.0:Port certhash=XXX appid=AppID
The AppID varies depending on the application you are using:
HL7 Soup = d6928ca8-e8bc-4ff7-9099-85a168c96061
Integration Host = c5198a6b-9e11-4535-a634-2b47154dcfc5
All of this is to show that our registration isn’t magical in any way, it uses the same command lines that you would use yourself to register a port to an address via an elevated command prompt.
This means you can also view the registered setting with this command:
netsh http show urlacl url=Url
Or to list all registrations on the machine:
netsh http show urlacl
It also means that you can manually delete the registration created by HL7 Soup and re-register it yourself with whatever settings you like.
One thing to note is that when a workflow is swapped between Integration Host or HL7 Soup, the bindings are automatically updated for you to point the SSL certificate at the other application. However, automation is limited to between these two applications. If you have another app or service that is already registered in that space, it will not remove it. You will need to do it manually. This is to prevent any other services being disrupted by accident.
Some users have reported issues replacing the Popokey certificate with there own. The solution was to put a full chain of trust into a PFX file and import that to the Personal/Certificates path in MMC Certificates snap-in. The command used was:
openssl pkcs12 -export -out server1.pfx -inkey Privatekey.key -in ServerCertificate.crt -certfile CARoot.crt
Another potential solution was to include the certificate in both the Computer/Personal and Machine/Personal Stores, though our testing results with this option have been mixed.