athenahealth Interface Connectivity SSH Implementation Guide 1. OVERVIEW... 2 2. INTERFACE LOGICAL SCHEMATIC... 3 3. INTERFACE PHYSICAL SCHEMATIC... 4 4. SECURE SHELL... 5 5. NETWORK CONFIGURATION... 6 A. WHERE TO INSTALL THE SSH SERVER... 6 B. ALLOWING SSH INBOUND... 6 C. DETAILED WALK-THROUGH... 7 6. REQUEST MODELS... 11 7. APPENDIX: HTTPS/WEB SERVICES... 12 8. APPENDIX: IPSEC... 13
1. Overview From a network and security standpoint, deploying a custom application interface with the athenanet Message Exchange interface engine ( MX engine ) poses some unique technical challenges. Because the athenanet MX engine is located in a secured data center, it is by definition remote to all systems that will interface with it; all communications will travel over a wide-area network (regardless of whether it is trusted or un-trusted) and it is critical that they be secured for regulatory and privacy purposes. The default athenanet MX engine architecture involves authenticated and encrypted sessions originating from the athenanet secured data center to the practice/vendor network/system, but at least one alternative is supported (please contact athenahealth for details). This document describes the standard architecture supported by the athenanet MX engine. It assumes a certain level of familiarity with TCP/IP and general networking and security. 2
2. Interface Logical Schematic The logical flow of an outbound interface is shown in Figure 1. 1. User activity in the athenanet application triggers application events. 2. These events cause the athenanet MX interface engine to generate interface messages. 3. The athenanet MX interface engine sends the interface messages to the remote system, in realtime or batch mode (see Request Models for more details on how messages are sent). Inbound interfaces proceed in a similar fashion, but in the reverse order. athenanet data center athenanet athenanet / Waltham, MX MA Data HL7 Center engine athenanet MX HL7 Engine from athenanet to athenanet Customer site Other Interface Engine(s) located on customer premises (e.g. OpenLink, LinkLogic) Interface Server LAN LAN athenanet / Waltham, MA Data Center athenanet Database Server Other Application Database Database Server 128-bit SSL LAN Client Browser (IE6+) Other Application (e.g. Logician, labs) Figure 1 3
3. Interface Physical Schematic The most critical part of the architecture shown in Figure 1 is the connection to and from the athenanet MX engine; the standard architecture uses the Secure Shell (SSH) protocol to provide the necessary protections for the sensitive data that the interface will transport. Additionally, the athenanet MX engine will originate all connections to remote systems, for a number of reasons, primarily: Better monitoring and support is possible Better tasked software on the client side See Allowing SSH Inbound below for more details. 4
4. Secure Shell The standard architecture employed by the athenanet MX engine relies heavily on the SSH protocol. SSH is a protocol that provides authentication, encryption and data integrity to secure network communications 1. In addition, SSH provides secure forwarding of arbitrary TCP connections, also known as tunneling, and SSH2 (SSH version 2) provides secure file transfers via SFTP ( secure FTP). Tunneling TCP/IP sockets over an SSH connection provides authentication (the SSH connection must be authenticated), security (the tunneled traffic is encrypted) and the ability to bridge connections across networks with virtual sockets (the local socket is actually a remote socket on the athenanet MX interface engine). It is important to understand that the SSH connection is distinct from the tunneled TCP/IP socket; that is, a successful SSH connection does not imply success for the tunneled TCP/IP socket. SFTP is an interactive file transfer program, similar in most respects to FTP, with the exception that all operations are performed over an encrypted SSH session. In this sense, SFTP is well suited for file drop interfaces. SSH protects against 2 : IP spoofing, where a remote host sends out packets which pretend to come from another, trusted host. IP source routing, where a host can pretend that an IP packet comes from another, trusted host. DNS spoofing, where an attacker forges name server records Interception of clear text passwords and other data by intermediate hosts Manipulation of data by people in control of intermediate hosts SSH also supports multiple encryption ciphers, including DES, 3DES, IDEA and AES (multiple key sizes). In essence, SSH by default treats its network environment as hostile, making it a good choice for securing persistent sessions that carry sensitive data. SSH is commercially maintained and supported by SSH Communications Security, though vendor-neutral standards are maintained by the Internet Engineering Task Force (IETF). 1 http://www.vandyke.com/solutions/ssh_overview/ssh_overview_introduction.html 2 http://www.employees.org/~satch/ssh/faq/ssh-faq-1.html#ss1.6 5
5. Network Configuration The customer will be responsible for any network changes required to allow the inbound SSH connection from the athenanet MX engine. For more detailed information, please contact athenahealth. Athenahealth frequently points clients to the SSH server application from the vendor Vandyke (www.vandyke.com). The VShell SSH server is lightweight, downloadable and easily configurable. Vandyke sells VShell server in packages of number of concurrent connections, typically the smallest package is sufficient, consult your athenahealth contact if unsure. a. Where to Install the SSH Server The SSH server can be installed on the same host as the interfaced software (Figure 2), or it can be installed on a physically separate host (Figure 3). Generally, the SSH server works best when installed on the same host with the interfaced software a local connection, whether for a TCP/IP socket or filesystem access, is more reliable than a remote network connection. Inbound SSH connection SSH server software EMR server software Figure 2 Inbound SSH connection SSH server software TCP/IP socket connection EMR server software Inbound SSH connection SSH server software Shared filesystem folder EMR server software Figure 3 b. Allowing SSH Inbound As noted, SSH is a well-known protocol; many devices (firewalls, NAT/routers, etc.) recognize and support it natively. By default, all connections originate from the athenanet MX engine; therefore, it is necessary to create a remote-side configuration capable of supporting an inbound SSH connection. This often involves allowing port 22 through a firewall, or configuration of port address translation (PAT) on a firewall or router (note that any authorizations or additional fees that may be required to allow this configuration work are the responsibility of the customer and not athenahealth). In addition, the custom is responsible for providing or making available a business-class Internet circuit that supports and allows inbound connections, and has a static IP address. 6
An example of PAT configuration on Cisco IOS: ip nat inside source static tcp 10.0.0.1 22 192.168.2.2 22 extendable This command would forward connections to port 22 of the router on its WAN interface (192.168.2.2) to port 22 on an internal host at IP address 10.0.0.1. Additionally, in the event that the SSH server were not the ultimate endpoint (e.g. if it were in a DMZ), the SSH server would need to have network connectivity to/from the internal host that is the ultimate endpoint. The athenanet MX engine is located in the athenahealth production network, which currently occupies the address range 209.202.186.160/32. Multiple source IP addresses may be visible, so any firewall rules should allow the full network range. Note that athenahealth is responsible for the connection only up to the point that it reaches the customer network. The customer is responsible for creating and supporting the SSH server, and resolving connection problems including, but not limited to: Caching or timeout problems on the customer router/firewall Unexpected firewall/router failures or changes Extended support time from athenahealth resolving problems for these reasons may result in fees assessed to the customer. c. Detailed Walk-Through Let s say that the client-side interface engine wants to sends messages on port 8000 and wants to receive messages on port 8001. From a technical set-up perspective, all that needs to be done on the client interface engine is to direct it to send messages to the SSH Server on port 8000 and receive messages from the SSH Server on port 8001. In order to make this work end-to-end, the following additional steps have to be taken on the client side: 1. Designate a machine on the local network to be the SSH server as described above, and install the VShell server. 7
2. VShell authentication slaves off Windows authentication. Therefore, create a user on the local Windows machine named Athena (suggested default): Figure 4 8
3. Next, in the Access Control tab in VShell, add this new user Athena to the access control list and give the user the ability to log on and do port-forwarding/remote port-forwarding or SFTP as appropriate for this interface. Have your IT representative consult with your athenahealth contact if unsure: Figure 5 4. Your network administrator should configure the firewall so athenahealth can reach port 22 on the SSH server from Watertown. There are two options here: a. If you are using network address translation (NAT) on your internal network, you can generally use port-address translation at the router level to map port 22 on the firewall to port 22 on the SSH server. b. If your SSH server has a routable Internet address, then you can simply open up port 22 on your firewall. 5. Finally, complete the Interface Connectivity Worksheet 3 from athenahealth: a. The External Firewall IP address. b. The port choosen to be forwarded through your Firewall, typically the default of 22. c. The IP address of the SSH host. d. For SFTP, the Folder path (skip if not SFTP). 3 http://www.athenahealth.com/files/interfacesupportdocs/interface+connectivity+worksheet.doc 9
e. The user name and password of the user created in step 2 above. Password rules, the password should not be a word, should be 8 or more characters long and should include all of capital letters, lower case letter, number and preferably symbols. f. The internal IP address of the interface engine. Could be the same as the SSH server if VShell is installed on this host. g. If 5d. (sftp) above is skipped, The Interface App port (for data from athena to interface). h. The Interface App port (for data from interface to athena, as appropriate). That should be it! From a security perspective, you should set up Port-Forward filters in VShell so that the SSH server can only port-forward to the specified port on the interface engine. However, this is just a restriction that is not necessary for testing the interface, and can be done later. If you re curious, from the Athena end, we will be executing the following command from the ssh client machine (In this example: ernie1 is the SSH client located in athenanet s data center; mxengine.athenahealth.com is the athenanet MX engine; vshell.client.com is the client SSH server; and 192.168.1.25 is the client interface engine). Figure 6 This can be translated as follows: 1. Create an ssh connection to vshell.client.com. 2. Do not start up a shell (-N). 3. Log in as user athena. 4. Create a listen port on vshell.client.com on port 8000 that tunnels connections to mxengine.athenahealth.com:8000. 5. Create a listen port on the ssh client (this machine) that will listen on port 8001 and tunnel connections to 192.168.1.25:8001 on the client s internal network. 10
6. Request Models The athenanet MX engine supports both real-time and batched message delivery and pickup. By default, a maximum of 60 seconds may elapse before a message is delivered by the MX engine; inbound messages are processed immediately. The athenanet MX engine can also be configured to deliver and pickup messages on a scheduled (e.g. once nightly) basis. 11
7. Appendix: HTTPS/Web services The athenanet MX engine can also support messages transferred via web services. As these connections are stateless, proper authentication information must be included in every transaction. Web services are vendor-specific the athenanet MX engine does not currently have a standard web service interface. The transport layer is required to be implemented using SSL (e.g. HTTPS). When deployed with SSL, web services obviate the need for SSH. 12
8. Appendix: IPsec While it is possible to deploy IPsec as the underlying protocol to secure remote connections, the default architecture uses SSH for a number of reasons: SSH is well suited to tunneling a single protocol, e.g. (multiple) TCP/IP sockets. IPsec is designed to tunnel entire networks/protocols. SSH is a significantly simpler protocol that provides all the necessary functionality for an interface connection. SSH generally does not require any routing changes. As long as the athenanet MX interface engine can reach the remote SSH server, and that server has the necessary internal network connectivity, routing changes are not required when SSH is deployed. Deploying an IPsec connection requires routing changes, as each endpoint network needs to recognize and route its remote network. SSH traverses NAT more reliably then IPsec. The application of this advantage is limited, but there are no known issues with SSH NAT traversal. IPsec can traverse NAT in most cases, and has a draft specification for standardizing this functionality. SSH is more easily recovered from minor network problems. A dead SSH connection can be detected and restarted by the athenanet MX interface engine as it is the source of the actual SSH connections. IPsec connections are generally handled by custom tasked hardware; non-interactive control of this hardware is usually not available. SSH capabilities are generally easier to restrict. Port-forward filters are usually trivial to deploy with SSH. IPsec port/packet filters can be deployed but are usually more complicated. 13