I use stunnel frequently when I want to trap an HTTPS request then replay it to another server. I can't just trap the HTTPS data as it is encrypted. Therefore, I modify my client to use HTTP, trap the plain-text HTTP request, then use stunnel to do the HTTPS for me.
Stunnel is available for immediate download for *nix, Cygwin and a native Windows port.
Stunnel 4.x is configured via a conf file which is specified as the main parameter on the command line (stunnel 3.x uses cmd-line options to configure it.)
$ stunnel my.confThe configuration file stunnel uses is broken into two main parts -- Global Options and Service-Level Options.
Global Options dictate how stunnel behaves such as forked or not, logging location, logging levels, etc. Common Global options are:
- debug = 0-7, where 0=[emergency], 7=[debug] . The default is 5, [notice]
- foreground = yes|no. This dictates whether or not stunnel will fork the process into the background or stay in the foreground.
- output = somefile. This is where output goes. /dev/stdout indicates to just output to STDOUT.
- pid = somefile. If present, the name of the file to write the background process' pid.
- taskbar=yes|no. Win32 only -- shows a taskbar icon you can use to control the running instance.
- accept=port #. This is what port incoming connections will be accepted on. Only a single value can be given, but you are free to create multiple services as the following incomplete example shows:
- cert=somecert.pem. This specifies where your certificate resides. In client mode (client=yes), this cert will be used for 2-way SSL.
- connect=[host:]port. Where the backend resides.
- key=keyfile.pem. This is the private key to be used for serving up SSL connections.
1) Proxying Plain Text HTTP client Traffic to HTTPS Server
I use this feature a lot to debug client-side HTTP issues and to see the exact HTTP message on-the-wire. Basically, this is handy to do HTTP from your client, but convert to HTTPS before hitting the server.
All this entails is doing "pseudo-https" with the following stunnel configuration:
$ cat https.confThen, your client can hit http://localhost:9443 which will be proxied to localhost:443 over SSL.
foreground = yes
output = /dev/stdout
debug = 7
accept = 9443
connect = localhost:443
client = yes
2) Creating an HTTPS Listener which Proxies to non-HTTP server
Requirement -- PEM-encoded file private key with signed certificate. The private key should not have a password on it. Both the private key AND the cert should be in the PEM-encoded file.
The stunnel conf looks like this to proxy incoming HTTPS requests to your local JBoss/Jetty/Tomcat service:
$ cat accept-https.confWhen you start stunnel with "stunnel accept-https.conf", you can test it with:
$curl --insecure https://localhostNote that the "--insecure" option may be needed if the stunnel.pem file contains a cert signed by a non-trusted certificate authority. Likewise, in IE or Firefox, you'll need to add a security exception in order to test.
3) Load Balancing Incoming Connections
If multiple "connect" options are given for a service, then a round-robin algorithm is used to load-balance the back-end requests.
The following configuration will load balance incoming HTTP connects on port 80 to HTTPS ports 9080 and 9081.
$ cat loadbalance.conf
output = /dev/stdout
debug = 7
accept = 80
connect = localhost:9080
connect = localhost:9081