SSL Tunneling Guide This guide tries to explain concepts and functionalities of SPR module (SSL tunneling in Orenosp). SPR stands for "Secure or SSL Packet Relay" and is the internal module name for tunneling in Orenosp. There are also sections for SPR parameter reference and trouble-shooting tips at the end. Related documents - ssltunnel_en.txt : SSL Tunneling Guide (this document) - sampleconfig_en.txt : Practical Sample Configuration - tips_en.txt : SSL Tunneling Tips (and random memos) If you want to start quick, first read "Practical Sample Configuration" and follow the instructions in it to set up the sample SSL tunneling. Then come back to this document to gain more understaning. Contents - Configuration Overview - Client Side Applets - SPR Parameters Reference - SPR Trouble-Shooting Tips ====================== Configuration Overview ====================== The primary purpose of the Orenosp SSL tunneling is to support SSL port-forwarding of many fixed-TCP-port applications. So this document will focus on SSL port-forwarding cases, but other usage scenarios are also presented as examples. To achieve SSL port forwarding, Orenosp must run both on server side and on client side. The client side tunnels an ordinary TCP connection over SSL and the server side "untunnels" it and route the connection to a PC in the LAN Actual programs to be used: === server-side programs === orenosp.exe: The same instance that works as a reverse proxy will act as the server side. You will add config parameters into sproxy.conf. === client-side programs === TnApplet: Java applet/application. otunnel.exe: A windows command line program. This program will use otunnel.conf for configuration, which uses similar or same set of parameters as those in sproxy.conf. orenosp.exe: You can also use orenosp.exe as an NT service on the client side if you want to set up a permanent SSL VPN connection. Throughout this section we will use otunnel as the primary example because its configuration is symmetric to orenosp's configuration. For wide deployment however you will probably use TnApplet (Java). It is a specialized client-side program that is simple to configure and deploy. (It uses a different set of parameters). example-1 (SSL port forwarding on a separate port from https reverse proxy) --------- A multiplexing SSL-port-forwading case for tunneling POP3 and telnet in SSL protocol. internal LAN-1 | internal LAN-2 | [host-1@110] | :110 [client-1] [orenosp-srv]--@443--[orenosp-cli] [host-1@23] | :23 [client-2] | Client-1 in LAN2 In this configuration you will use "multiplexer" (mpx) mechanism to let clients to connect to different services using a single port (443) over the internet. # configuration for orenosp-cli (in otunnel.conf) tunnel_listen_name = pop3 0.0.0.0@110 raw tunnel_listen_name = telnet 0.0.0.0@23 raw tunnel_dest_name = orenosp-srv orenosp-srv-host:443 ssl -mpx=sslvpn tunnel_pass_by = lis pop3 orenosp-srv -mpxlabel=host1:110 tunnel_pass_by = lis telnet orenosp-srv -mpxlabel=host1:23 # configuration for orenosp-srv (in sproxy.conf) tunnel_listen_name = mpx 0.0.0.0@443 ssl -mpx=sslvpn tunnel_dest_name = lan-pop3 host1:110 raw tunnel_dest_name = lan-telnet host1:23 raw tunnel_pass_by = label host1:110 lan-pop3 tunnel_pass_by = label host1:23 lan-telnet Multiplexer and labels ---------------------- Continueing with example-1 in the above, I will explain how multiplexer(mpx) and mpx lables are used. - orenosp-cli accepts a non-SSL (raw) connection from a client on port 110 (pop3). - it establishes an SSL connection to orenosp-srv-host:443. - it sends the following a pseudo-HTTP command over SSL to orenosp-srv: SSLVPN host1:110 HTTP/1.1 - orenosp-srv replies with the following HTTP status: HTTP/1.1 200 OK - orenosp-srv then starts forwarding all packets to the destination lan-pop3 (which is at host1:110). The argument for SSLVPN command (URI part) is a label. The label is used in determining a destination port to forward the connection to. It is used in "tunnel_pass_by" label mode. Note that a label can be any ASCII string with max length of 64 bytes. In the above example, "host1:110" is used as a label, but you can also use virtual path style labels, such as "/host1/pop3". Access Control and Usesr Authentication --------------------------------------- In example-1 there is no restriction on who can connect. First, each tunneling port (defined by tunnel_listen_name) can be protected by IP-based access control. See "IP-based Access Control" in SPR parameter reference down below for details. In the example-1, you could specify a range of client IP addresses: tunnel_listen_name = mpx 0.0.0.0@443 ssl -mpx=sslvpn \ -ip_allow="aa.bb.cc.dd/24" The second option is to use a pair of username and password that will be passed along in an SSLVPN command. In the example-1, you can have orenosp-srv to authenticate peer's (orenosp-cli's) identity. In the server side config (sproxy.conf), you can specify user auth info in listen port definitions. tunnel_listen_name = mpx 0.0.0.0@443 ssl -mpx=sslvpn \ -mpxusers="user1:pass1,user2:pass2" In the client side config (e.g., otunnel.conf), you specify username and password in -auth= option in tunnel_pass_by. tunnel_pass_by = lis pop3 orenosp-srv -mpxlabel=host1:110 -auth=user1:pass1 As you can see this auth mechanism works only if the listen port is configured for SSLVPN (-mpx=sslvpn). Also note that this access restriction is applied per listen port basis, not label(i.e. service), basis. You probably want to use HTTPS proxy integrated mode, described below. HTTPS proxy integrated mode --------------------------- If you need to use a single port (443, for example) for both HTTPS reverse proxy and SSL port-forwarding purposes, you need to use HTTPS proxy integrated mode. In this mode, HTTPS proxy accepts SSLVPN command in addition to regular HTTP commands and pass the connection to SPR (tunneling) module for SSL port forwarding. An advantage of integrated mode other than using a unified port for HTTPS and SPR is that you can use existing authentication and logging facilities in the proxy. As noted earlier, a mpx label can be any form, so you can use virtual path style labels. To enable integrated mode add the following parameter. You can specify multiple instances of the parameter for multiple labels. Note that you have to specify the same label twice, once in proxy_sslvpn_label and once in tunnel_pass_by. proxy_sslvpn_label = e.g., proxy_sslvpn_label = /vpn/host1/pop3 proxy_sslvpn_label = /vpn/host1/telnet Since 0.8.5, you can also specify an wild-card extended-url syntax instead of proxy_sslvpn_label parameter: proxy_sslvpn_url = e.g., proxy_sslvpn_url = /vpn/* or proxy_sslvpn_url = lis-ssl://vhost1.example.com/vpn/* All SSLVPN requests having host header and path part that match are passed to SPR (tunneling) module. examples -- parameter -- proxy_sslvpn_url = https://vhost1.example.com/vpn/* -- HTTP request -- SSLVPN /vpn/host1/rdp HTTP/1.1 Host: vhost1.example.com ==> pass connection to SPR with "/vpn/host1/rdp" as label For authentication, use HTTP basic authentication proxy_auth_path = ... or proxy_auth_url = ... SSLVPN commands are logged in proxy access.log files. example-2 (SSL port forwarding with unified port) --------- A multiplexing SSL-port-forwarding case with unified port (443) that accepts: 1) HTTPS requests (reverse proxy), 2) SSLVPN requests (SSL port-forwarding) for pop3 and telnet. # configuration for orenosp-srv (in sproxy.conf) # # --- proxy settings --- # # proxy_listen_name = lis-ssl 0.0.0.0@443 https # forward all requests received on lis-ssl to backend server (localhost:80) proxy_pass_by = lis lis-ssl http://localhost # other necessities proxy_ssl_keypass = orenosp # proxy to tunneling gateway proxy_sslvpn_label = /vpn/host1/pop3 proxy_sslvpn_label = /vpn/host1/telnet # authenticate users for both HTTPS and tunneling. any path that starts with # "/" will be subject to this authentication proxy_auth_path = / -u="user1:pass1,user2:pass2" # # --- tunneling settings --- # Notice there's no tunnel-specific listen port defined (tunnel_listen_name) # tunnel_dest_name = lan-pop3 host1:110 raw tunnel_dest_name = lan-telnet host1:23 raw tunnel_pass_by = label /vpn/host1/pop3 lan-pop3 tunnel_pass_by = label /vpn/host1/telnet lan-telnet # configuration for orenosp-cli (in otunnel.conf) tunnel_listen_name = pop3 0.0.0.0@110 raw tunnel_listen_name = telnet 0.0.0.0@23 raw tunnel_dest_name = orenosp-srv orenosp-srv-host:443 ssl -mpx=sslvpn tunnel_pass_by = lis pop3 orenosp-srv -mpxlabel=/vpn/host1/pop3 \ -auth=user1:pass1 tunnel_pass_by = lis telnet orenosp-srv -mpxlabel=/vpn/host1/telnet \ -auth=user1:pass1 Access Logging -------------- There are two types of access logs. One type is primarily used for logging access attempts to the system (intended for security audit). The other is used for collecting session duration and other resource related information (intended for statistics). The former is called access log and the latter is called session log. - Access log If you are using only the proxy integrated mode, access attempts to the tunneling are logged into proxy's access log. The HTTP command is "SSLVPN