How to connect with stunnel
Secure tunnels are a way to provide encryption in transit over any network connection. We often use them on your internal network to ensure that even if one system were to be comprised, your network traffic will still be secure.
Why do we use stunnel?
We use Defence in Depth and Security by Design, as shown in our Division of responsibility documentation. This requires us to encrypt communication on internal private networks. Some of the services that we offer do not include encryption "out of the box". For example, the Redis security page says:
Redis does not support encryption. In order to implement setups where trusted parties can access a Redis instance over the internet or other untrusted networks, an additional layer of protection should be implemented, such as an SSL proxy
We therefore use a tunnel to "wrap" the unencrypted connection in encryption. Our tool of choice for this purpose is stunnel.
How stunnel works
Stunnel is a secure tunnel. It is similar to an SSH tunnel, but different, in that it doesn't require the use of SSH, doesn't use PKI, and is permanently open. It creates a "wormhole" between two servers. Each server thinks that it is connecting to a port on localhost/127.0.0.1, but in fact it is connecting through encryption to the remote server.
When using stunnel:
- Your software doesn't need to know that the connection is encrypted. The encryption is transparent.
- You connect to localhost, even if you are intending to connect to a remote host. The remote port "looks like" it's on the local machine at IP address 127.0.0.1 (the loopback address).
If you want to connect to the remote host, you need to connect to 127.0.0.1
When using stunnel, always connect to 127.0.0.1, not to the remote host.
For example, if you need to connect to port 3306 on the remote host example.medstack.net using stunnel, you need to connect to 127.0.0.1 port 3306, not example.medstack.net.
If you attempt to connect to the remote host, you will get an error like this:
Unable to connect to remote host: Connection timed out
If you get this error, change the hostname that you are connecting to: 127.0.0.1.
Example: How to connect to MySQL
Please use the official MySQL command line client and libraries for following these instructions. Other tools (such as GUI tools) may also work, but we do not normally provide support for them.
In this example:
- The app is running on example-app.medstack.net
- The database is running on example-db.medstack.net
First, SSH into example-app.medstack.net.
Next, connect to MySQL on example-db by using the tunnel. Since you are using the tunnel, you will actually connect to 127.0.0.1:
deploy@example-app:~$ mysql --host 127.0.0.1 --user=root --password Enter password:
Enter the password which is contained of the file that is in your credentials package, named like `example-db-1.medstack.net_root-pass`.
When you are connected, you will see:
Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 23 Server version: 5.5.58-0+deb8u1 (Debian) Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql>
If you can't connect, check to make sure that you are connecting to 127.0.0.1. There is an issue with MySQL where connecting to localhost will not work, but 127.0.0.1 will work.