Repository files navigation

Connecting to remote machines via SSH becomes increasingly complicated, when these machinesare hidden behind residential routers or corporate firewalls. In these situations, ahigh-bandwidth SSH proxy is useful that can be reached from anywhere.

This project provides such a proxy using Amazon EC2 virtual machines. It targets macOSmachines and can be used to replace Apple’s discontinued Back To My Mac service for remotemanagement using an SSH command line. Linux support should also work, but is less tested.

The system consists of four pieces:

• some initial setup at Amazon,
• a web service you need to host on a PHP-enabled web server,
• a launch daemon for the Macs you want to connect to, and
• an SSH proxy command for the machine that establishes the connection.

Each of these pieces is described below in its own section.

In order to set everything up at Amazon Web Services, you need to perform the followingsteps:

1. Create an SSH key pair and upload the public key to EC2 with the namessh-proxy. Storethe keys in a filesproxy andproxy.pub in your~/.ssh directory.
2. Create an AWS stack fromaws.json usingCloudFormation, either from theAWS Console or thecommand line. Use thenamessh-proxy for the stack.
3. Retain the credentials of the created IAM userssh-proxy.

To install the web service, you need PHP-enabled web space. Follow these steps:

1. Putindex.php and.htaccess on your webserver.
2. Obtain the latestaws.phar from theAWS SDK releases and put it next toindex.php.
3. Make sure your web server also has the credentials of thessh-proxy IAM account storedin its~/.aws/credentials file or wherever you keep your AWS credentials. Use a profilename ofssh-proxy.
4. The web service uses a pre-shared secret to authenticate its API requests. Store thisAPI key and optionally any other configuration inconfig.php.

An authentication token is formed by first generating a 10-byte random nonce. Then, aSHA256-HMAC is calculated over the string<nonce><command>?<identifier>. The result isBase64-encoded and appended to the request URL.

The web service understands three commands, all of which use an identifier for the proxiedendpoint as their query string:

/launch?<identifier>&<token>
Starts a new SSH proxy for the given endpoint, waits until the proxy is running and returnsits IP address. When a proxy is already running, only the IP address is returned.

/status?<identifier>&<token>
Returns the public IP address of the SSH proxy when such a proxy has been started for thegiven endpoint. An authentication token similar to the one used for requests is generated toverify the IP address. The same nonce is used to prevent replay attacks.

/terminate?<identifier>&<token>
Terminates the running SSH proxy.

All the machines that you want to SSH into must run a launch daemon. This daemon regularlyqueries the status of the EC2 VMs using the PHP service. A running VM signifies a connectionrequest and the daemon will forward its local SSH port to the VM.

1. You install the launch daemon by invokingmake in theproxy directory. You canoverride variables (DESTDIR,SIGNING_NAME, …) to configure the installation.
2. Register the daemon with launchd by copying the included plist file fromSSHProxy.bundle/Contents/Resources to/Library/LaunchDaemons/. You may want tocustomize the file if the defaults don’t suit your needs.

Connecting to an endpoint requires launching and later tearing down the respective EC2 VM.This can be automated and integrated into SSH by way of a proxy command. The binaryssh-connect is installed alongside the daemon in theSSHProxy.bundle/Contents/MacOSdirectory. You can use it in your SSH configuration by way of theProxyCommand directive.It understands the same command line options as the daemon:

--id
Specifies the name of the endpoint to connect to. Usage of%h in you SSH config ispractical.

--api-url
The API URL where the PHP web service can be reached.

--api-key
The pre-shared API key to authenticate web service requests.

A useful SSH config file, which establishes a local connection when possible and connectsvia proxy when necessary looks like this:

Match host <hostnames> exec "route get %h.local &> /dev/null"HostName %h.localMatch host <hostnames>ProxyCommand /path/to/SSHProxy.bundle/Contents/MacOS/ssh-connect --id %h --api-url <server> --api-key <secret>

You can also read the secret from a file using shell command substitution (`cat <keyfile>`). Be aware that the secret is still exposed to all users on the machinethrough the list of all running processes and their arguments.

This work is licensed under theWTFPL, so you can do anything youwant with it.