HSBuddy

A mobile client for HomeSeer

If you are connecting directly to your server from HSBuddy, it is strongly recommended to use secure connections (SSL). This will keep the communication between the application and HS3 private even if your phone is connecting via public WiFi.

HomeSeer provides a way to use SSL, but the security standards it uses are old, and some devices will not allow connecting to the server because of that (pretty much all Android phones).

An alternative to HomeSeer’s built-in SSL support is to use a proxy that runs in the same server, and handles setting up SSL so that HS3 does not have to.

The previously described configuration to achieve this looks like the following diagram:

Network Configuration

Create a server certificate

You will need to create a server certificate to authenticate your home server when HSBuddy tries to connect to it. You can generate this certificate on your own; this is called a self-signed certificate. Or you can buy a certificate from a trusted authority on the Internet. HSBuddy will allow you to connect to your server regardless of which kind of certificate you use.

Requesting a certificate from a trusted authority

If you have bought a domain name that you will use to connect to your home server, you can choose to buy a certificate issued by a trusted authority to authenticate your server domain. This will make the connections between HSBuddy and your server more resilient to man-in-the-middle attacks. This is only possible if you own the domain. If you are using a product like dynamic DNS services (for example, Dyn) you will likely have to stick to self-signed certificates.

I personally use NameCheap to buy my domain and server certificate, but you can any issuer of your preference. There’s a wide range of prices for these services. From NameCheap you can get a domain for less than a dollar a year, and a PositiveSSL certificate to go with it, for additional $10USD a year.

Follow the instructions from your certificate issuer and make sure to save the key and certificate files (e.g. server.key and server.crt) for use later throughout this guide.

Using a self-signed certificate

Self-signed certificates are normally considered ‘invalid’ because they are not signed by a trusted authority (it is instead signed by your home server when generated). For the purposes of connecting HSBuddy to your server, this is not an issue, simply make sure to enable Accept invalid certificates in the app settings.

To generate a self-signed certificate you need the tool called openssl. This page has some information on how to get the right version of the tool to use on your computer.

Follow steps #1 through #4 from this page to create your certificate. The following is a short walk-through of those steps:

openssl req -new -key server.key -out server.csr
copy server.key server.key.org
openssl rsa -in server.key.org -out server.key
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Save server.key and server.crt as you will need them later on during this guide.

Generating a PFX certificate

Depending on your network configuration, you may need to generate a PFX file to use instead of the KEY and CRT files. If that is the case, you can once again use openssl to generate the PFX certificate from the KEY and CRT files. For that you can use the following command. Replace server.key, server.crt and server.pfx as appropriate:

openssl pkcs12 -export -out server.pfx -inkey server.key -in server.crt

The tool will ask you for a password for your PFX file. Make sure to remember the password because you will need it when configuring the server that uses the PFX file.

Configure Nginx as a proxy

There is a free software called Nginx that you can use to enable SSL. Nginx is an open source web server that supports SSL redirection. To set it up so that it allows you to connect to HomeSeer (and the plug-in) from HSBuddy, follow these steps:

  1. Download the appropriate version of Nginx based on your server OS from http://nginx.org/en/download.html
  2. Extract the files to the folder where it will run from (e.g. C:\Nginx)
  3. Copy your certificate files (server.key and server.crt) to the conf folder (e.g. C:\Nginx\conf)
  4. Set the appropriate configuration in the file conf\nginx.conf file (e.g. C:\Nginx\conf\nginx.conf). See below for an example.
  5. Start the nginx service (e.g. nginx.exe in Windows).

Requiring authentication

Normally, HS3 does not require username/password when browsed from the same network, e.g. from other devices connected to your same home router. But when nginx redirects traffic to HS3, it will also appear as a device within the same network, and HS3 will not ask users to authenticate. This is a problem, because nginx is making your HS3 server available publicly. Fortunately, Nginx supports setting up basic authorization (username/password) the same way that HS3 does when connecting remotely (or through MyHomeSeer). The following steps show you how to do so.

To generate the hashed passwords as explained below, you need the tool called openssl. This page has some information on how to get the right version of the tool to use on your computer.

  1. Create a file that will hold the usernames and passwords in the conf folder (e.g. C:\Nginx\conf\passwords.txt)
  2. Hash every password you want to add to the file by running the following command (replace real-password with the actual password text):
    • openssl passwd -apr1 real-password
  3. Add one line per combination of user and password to your passwords file, with the following format (replace hashed-password with the output from the last step):
    • username:hashed-password
  4. Set the configuration for location / in the nginx.conf file to require basic authentication and point it to the file you just created. See the example Nginx configuration below for more information.

You can optionally add comments to your password file, simply start the comment line with a # character. Your password file should look something like the example below. Do not copy/paste the example, you need to generate a file with your real users and passwords!

# HS3 users
user1:$apr1$D5kJ5qrK$1pDfWEWFWlZZ0dfe34qox1
user2:$apr1$L4.IJd9v$B/YS1zG/53xtqruKIM8z60

You should not add basic authorization under location /hsbuddy, which is redirected to the plug-in. The plug-in performs its own authentication of usernames and password using those you have configured in HS3.

Running Nginx as a service

Depending on the OS you are using on your HS3 server, there may be multiple options for setting up Nginx to run as a service (automatically on startup).

Windows

You can follow the steps on this article if you need a quick and simple way to setup a new Windows Service for Nginx.

Alternatively, you can use a program like AlwaysUp and configure it to run Nginx.

Linux, OSX

See the different Nginx Init Scripts offered at their website.

Example Nginx configuration

worker_processes  auto;
error_log  logs/error.log;
events {
	worker_connections  1024;
}
http {
	server {
		listen 443 ssl;
		location / {
			proxy_pass http://127.0.0.1:80;
			proxy_http_version 1.1;
			auth_basic "HS3 proxy";
			auth_basic_user_file passwords.txt;
		}
		location /hsbuddy {
			proxy_pass http://127.0.0.1:8006;
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection "upgrade";
		}
		ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
		ssl_ciphers HIGH:!aNULL:!MD5;
		ssl_certificate certs/home.avglabs.net.crt;
		ssl_certificate_key certs/home.avglabs.net.key;
		ssl_session_cache shared:SSL:10m;
		ssl_session_timeout 10m;
	}
}

The previous example sets Nginx to listen on port 443 for secure connections, which will be then forwarded to HomeSeer or the plug-in appropriately. The example assumes that HomeSeer’s server port is set to 90, and the plug-in is listening for connections on port 8006, which are the default settings. For more information, see the documentation on Server Configuration.