HL7 Soup

Return to Tutorial Directory

Video Transcript

Before we start I just need to clarify one thing. SSL is a deprecated format that has been replaced by TLS.

However, the term "SSL" is still in common use when referring to Transport Layer Security and so I have used this term throughout the video.

Be assured that HL7 Soup uses TLS 1.2 only and will never utilise the now vulnerable SSL protocol.

So why do we need to use SSL or its replacement, TLS?

Well, when data (such as HL7) is sent between computers it doesn't always go direct. It gets bounced around a bit, particularly when it goes out onto the internet. Because you are sending sensitive medical data, you don't want this to fall into the wrong hands.

SSL/TLS fixes this problem by encrypting the message so that only the sender and the receiver can access it. To an observer in between, it looks like garbage.

It's all done with clever mathematics with very large numbers that store a secret key in a file called a "certificate".

The receiving computer needs to be configured with the certificate, and the address needs to be changed from HTTP to HTTPS but once done your data is protected.

So how do you get a certificate file?

Well, you have two options.

You can create your own. It's pretty easy to do so and I'll show you a simple way later in this video.

Alternatively, you can buy one.

So why would you buy one when you can make your own easily for free? Well, it's all about trust.

When you buy a certificate the vendor checks to make sure that you, are you. The vendors have already trusted by Microsoft, so when they state they trust you, all Windows computers will trust too. This means your certificate will work everywhere.

However, when you make your own certificate, nobody trusts it, so it just doesn't work

Fortunately, when creating a software integration between systems, both sides have already partnered up and are happy to trust each other anyway. This means that the sender can just state they trust your "homemade" certificate, and you are back in business.

For this reason, I'll be demonstrating how to create a homemade certificate first.

You can create a certificate in a command prompt with the make MakeCert command. Follow this link if you would like to know more, but let me show you the easy way!

Start by loading up IIS Manager on your receiving computer (If you don't have it, just do a quick Google for "how to enable IIS Manager for your version of windows") - it's part of windows, so don't worry, you're not installing stuff from the web.

Now double click on "Server Certificates", then up in the right-hand options, click "Create Self Signed Certificate".

Give your certificate a friendly name, select "Personal", and then click "OK". Your certificate has been created.

It's shown here in IIS, but also in your computer certificates manager. Just expand "Personal\Certificates" and there it is with the friendly name you typed.

If you had purchased a certificate from a certificate authority, they would have given you a pfx file. Let me export my created one as an example. Right-click, All Tasks, Export. I'll include the private key, take the defaults, and give it a password.

Now I just need to put it somewhere. That's it, I can delete this one now.

Now that I have a PFX file, just double-click to import it. Select "Local Machine". Put in the password. Allow it to import into the Personal folder. And it's done. Now when I refresh, my certificate is available again.

As you can see, it's pretty easy to get a certificate installed, regardless whether it was created by yourself or a certificate authority.

So now that we have a certificate installed, let's use it in HL7 Soup and create a new HTTP Receiver.

Start by loading HL7 Soup and create a new receiver workflow. I'm going to change this to an HTTP Reciever and call it "Receive HL7 over SSL".

Now I just need to give it an unused port number and select that I'm using SSL/TLS.

I'll also quickly register this address so HL7 Soup has access to this port without needing to be run as an administrator.

Now to the SSL/TLS settings themselves. Firstly, I need to locate my certificate and that can be done by either pointing at the file, or by locating it in the certificate manager.

The file option is pretty self-explanatory, so I'm going to show you how to use the certificate stored in the manager.

We stored the certificate in the Personal store, so the default folder is correct, but now we need to find the thumbprint.

Back in certificate manager, we just double-click our certificate, go to the details tab and locate the Thumbprint. I'll copy this to my clipboard, head back to HL7 Soup, and paste it in.

Now I just need my password. When I exported the certificate earlier, I added a password to it, so now I have to enter it. If I hadn't added the password then I would have left this blank.

Now all that remains is to bind the certificate to the port.

That's it, SSL/TLS is configured!

I can now copy this HTTPS address and pass it on to the sender.

Before I do though, let me quickly complete the workflow, I'm simply going to make it write out the received HL7 message to disk.

Great, so let's save this workflow and start it running.

We can now test this out by pasting the URL into my browser and hitting enter. Great, an HL7 response. We didn't actually send it an HL7 message, hence the error message, but it shows we did connect.

So what happens now if I head over to another computer and attempt to browse this address?

Well, the first thing is it will probably time out and tell you that the site can't be reached because you forgot to allow HL7 Soup through the firewall. I'll configure this properly later, but for testing purposes, I'm going to turn off my firewall.

So now when I refresh I get this nasty looking warning. That's because I have a self-signed certificate. If I used a certificate I got from a Certificate Authority, everything would be working now.

But that's ok, I'm just going to expand the advanced options and click to proceed.

I can now see the expected response. If you want your browser to fully trust a self-signed certificate, then I suggest that you google it as there are too many browsers out there to show on this video, and it doesn't actually matter. We don't actually care if the browsers don't trust the certificate, because they are not the sending app. With medical integrations the sender didn't randomly find the receivers address on the internet, they were given it directly from the receiver. Because of this, integration engines don't tend to mind that the certificate is self-signed and will allow it to be called.

So let's try it out.

We could send from an activity within another workflow, but for testing purposes, we'll create a sender in HL7 Soup and point it at our address.

That's all I need, so I'll save it and try sending through a message.

That looks a correct response to me.

And if I check, we'll see that a file has been created on the receiver, containing the HL7 message I just sent.

So that's it. SSL/TLS configured and working.

It's now time for a quick disclaimer. All we have now is a secure connection between the two computers. Just because you've done this doesn't mean that your data is 100% secure from hackers. We recommend using a security expert to help.

Also, it is worth noting that some Certificate Authorities give away free certificates these days. Check the reviews first, but they can be a great way to simplify your configuration.

If we've helped you, then please give our video a 'like' and consider subscribing to this channel for more tutorials.

Download 30 Day Free Trial of HL7 Soup