Biztalk 2010 and FTPS

A few days ago I got involved in setting up an encrypted ftp connection for sending sensitive information to a business partner. Something that really shouldn't be all that difficult. But getting everything right just by reading the manual didn't go too well, so I decided to do some testing in the lab in order to figure out the missing pieces. This is the story of how I got it to work

First of all, what is FTPS?

Well, it is basically ordinary FTP with the added option of SSL encryption. It comes in two distinct flawors, "Implicit" and "Explicit". The main difference between these two is that implicit FTPS is always secure, whereas explicit leaves security open for negotiation. This story is mainly about explicit FTPS.

Also, there are levels of encryption to choose from. "PROT C" is one of them, where the C apparently stands for "clear text" as in "clear to read text", ie. the data is not encrypted. Any ftp commands, including username and password is encrypted, but any data (data=files) transferred will be unencrypted. The other level is "PROT P" where the P is for "private". In this case, everything is encrypted, including the data.

In order for SSL encryption to work, we need encryption keys, aka certificates. Those certifikates also need private keys. And since we want it to run in biztalk, we want properly signed and valid certificates. The server will need one certificate and the client (Biztalk) wants another. And since we want this to work in Biztalk, they should all be properly signed and valid.

The setup.

In my little lab (which is basically a laptop with VMWare running virtual Windows Servers) I set up a scenario consisting of one server with IIS 7.5 running an FPT server and another server running Biztalk 2010.

 

For the SSL, I created four different certificates:

• root.hemma.xx
• root.borta.xx
• client.borta.xx (signed with root.borta.xx)
• ftp-server.hemma.xx (signed with root.hemma.xx)

I also created public versions of the root certificates (by exporting them from the certificate manager without including the private key). The public root certificate was installed as a trusted root certificate on the opposing machine. The client certificate was installed on the Biztalk machine on the biztalk user account (ie. the account which the host is running on), the ftp-server certificate was installed on the IIS-server on local machine.

 

I used this little tool when creating the certificates.

 

All in all, something like this:

Actually, the (private) root certificates don't serve any purpose in this scenario. In a production scenario when using real-world CA-signed certificates, you will never ever see the private root certificates.

 

The public root certificates, on the other hand, are vital. From the client perspective, trusting to root certificate used by the server allows Biztalk to evaluate the server certificate on its own, and thats a good thing.

Configure IIS 7.5

In order for the FTP-server to accept FTPS, we need to configure SSL. This is easiest to do when you create the FPT site. Just remember to install the certificates first. There are basically two levels of SSL security on the FTP server, allow SSL connections and require SSL connections. Then you can specify customized settings for the command- and data channels.

 

Note that you'll need IIS 7.5 to have FTPS out of the box. It's an addon for 7.0. If you're running 6.0 your're out of luck unless you find some third-party solution.

Configure Biztalk FTP adapter

On the client side (Biztalk 2010 FTP send adapter, that is) we also need to configure things very precisely. However, there is very little documentation available on the FTP adapter, especially so on the SSL settings, so I did some trial and error. This is what I found:

• FTP/Port: If you intend to use Implict SFTP, you should use port 990. Otherwise, you probably want to have 21 here.
• SSL/Client certificate hash: This is where you tell the adapter which certificate you want to use. Go to the certificate manager, open the certificate (in my case; client.borta.xx), scroll down to find the thumbprint (a bunch of numbers and letters in pairs). This is the certificate hash you want. If you copy/paste, make sure you don't get any of the wierd linefeed- or break characters that hides at the end.
• SSL/FTPS Connection Mode: Implicit or Explicit. You need to know which one the server is providing. Also, remember to set the port accordingly.
• SSL/Use data protection: This is where you specify if whether you want your files encrypted 
  or not. If you set this to "No", your files will be sent in clear text, ie NOT ENCRYPTED. If you set it to "Yes", everything is encrypted. If your server is configured to require full SSL connections, the adapter won't let you get away with anything less than "Yes" here. Also, "No" means "PROT C" in ftp lingo while "Yes" means "PROT P".
• SSL/Use SSL: This needs to be "Yes" in order for any of this to make sense...

 

Some of the gotchas I ran into...

Problem: After I adjusted settings in the adapter configuration, it still seemed to use to old settings.

Apparently, (going by the ftp adapter log) the ftp connection isn't closed between transfers. After adjusting the adapter configuration, it's necessary to restart the biztalk host to make sure the new settings are applied.

Error message (event log): No Client Certificate matching the provided client certificate hash was found. Verify if the certificate is present in the personal store of the corresponding BizTalk host instance user account.  

I had placed the client certificate in the certificate store for "local computer". It should be in the certificate store of the biztalk user account. An easy way of putting it there is to log on to the server as the biztalk user account, open the certificate manager and import the certificate there. Another way is to get creative with the "runas"-command.

Error message (event log): The server did not accept the current data protection level of the FTP connection. Verify the SSL settings on the FTPS server and check the adapter log for more details.

My adapter setting was "Use Data Protection = No" but the FTP server required an SSL connection. Changing the setting to "Yes" got rid of this problem. Note that other FTP servers probably have other settings with other implications.

Error message (event log): The server did not accept the current data protection level of the FTP connection. Verify the SSL settings on the FTPS server and check the adapter log for more details.

This error message can apparently have a lot of causes. In this particular instance I didn't put the client certificate thumbprint into the Client Certificate Hash property of the FTP adapter. Do not confuse this setting with the certificate property of the send port.

Conclusion

If you managed to get this far, you just need to add a recieve port with a suitable location, do some wiring and you should be able to send encrypted files to your ftp server. If not, well, I guess there are still dragons hiding in there. To find them, a good place to start is to check the log file of the FTP adapter.