A few months ago I had left for a business trip and couldn’t remember if I had closed the garage door. Nearly all of us have done this at one point in our lives. I promised myself this would never happen again, and a new project was spawned!
- An Android application which posts commands to a web service. The Android application retrieves an authorization token from Google and sends it along with the requested command.
- The web service which listens for commands and credentials. These credentials are posted to Google to verify they are authentic. Once the user is verified, the command is executed.
I will be giving an overview of the project, but it is by no means a step-by-step tutorial. There have been similar projects online, but I couldn’t find any with detailed code on both sides (client + server). This should be a good reference for anyone who wants to do things like:
- Run Tomcat on their Raspberry Pi
- Authenticate users with Google’s OAuth 2 (both getting the token and authenticating the token)
- Interact with the GPIO pins of the Raspberry Pi directly in Java
- See how a basic Service to Activity (interaction / communication) model can look like in Android. I find this to be one of the most common questions asked by new developers
- Raspberry Pi Model B – It can act as the web service and physically interface with the garage door all in one device (rather than purchasing something like an Arduino, which would need a more powerful computer sitting in front of it to run the web service). Less is more.
- Edimax EW-7811Un USB Wi-Fi N Dongle – Since I don’t have CAT6 run out to my garage door opener (yet), I had to accept using Wi-Fi which I generally avoid at all costs. The chipset in this dongle (RTL8188CUS) is compatible right out of the box with the Raspberry Pi.
- Magnetic Switch – This is to determine whether the garage is opened or closed. This particular switch is fantastic for one reason; depending on which contact points you hook up to, it can be made either normally open or normally closed.
- Sainsmart Relay Module – Great little board that has relay isolation components already built into it. Separates the power supply from the signal with an optocoupler which protects your other components when the coil’s magnetic field collapses.
- Resistors – Miscellaneous resistors. Supplied link is a great pack that gives you a little bit of everything for home projects.
- Wiring of your choice.
- Control (toggle) the garage remotely, whether 5 feet away, or 5 countries away
- Check the state of the garage door, without needing to toggle / close it
- Do so from within an Android application
- Use Google as the application’s authenticator
- Take advantage of Android’s AccountManager
- Be accessible via HTTP so it could be extended to any platform in the future such as iPhone, iPad, or a simple web browser
- Run HTTPS so eavesdropping / replay attacks would not be possible
- Use an unsigned TLS certificate. There is no need to pay for one if you are the developer!
- WAF needs to be high.
- Low cost
- Must not affect normal operation of the door
- No pre-built solutions
- Rarely demonstratively secure
- Not extensible
- Not fun =P
- Authenticates the request with Google OAuth 2.0 with an subclass of RealmBase, GoogleRealm.
- Authorizes the user with a local file containing a line delineated list of valid users
- If there was a successful authentication and authorization, perform the required action, namely:
- Toggle the garage
- Get the state of the garage
- Pi4J – Java bindings which allows interaction with the GPIO pins on the Raspberry Pi. Being Tomcat is the web server, Pi4J was a perfect complement.
- json-simple – Java library which parses and extracts JSON messages.
In this application, the BasicAuthenticator is used to retrieve credentials. You may have been able to guess that BasicAuthenticator retrieves the username and password from HTTP basic access authentication. The username field contains the Google authorization token and the password field contains a shared secret among all users. The authorization token is requested with the scope oauth2:https://www.googleapis.com/auth/userinfo.email which, when posted to Google, allows the verifier to view the email address of the account that the authentication token is associated with.
I originally did not have this shared password in place but I soon realized that there was a security vulnerability in the application. Any service that you authenticate with using your Google account could post its own authorization token to your garage door opener and open your garage. In computer security, this is called the confused deputy problem. This can be mitigated by requiring an additional secret with all authorized users. With a shared secret, third party sites need an additional piece of information that only authorized users posses.
Once the user’s request is authenticated it is then checked for authorization against a line delineated local file which has a list of email addresses allowed to interact with the application. If that email exists, the proper Principal is then added to the request session and passed to servlet routing.
- Toggling the garage
- The garage door was fairly straight forward to interact with physically. I had a wall mounted control which toggles the garage door when two wires are shorted together (this is the behavior of most any door).
- When this module is activated, the garage is toggled. This module is controlled via the following wires: (Note – make sure you know which revision of the Raspberry Pi you have as their pins have changed!)
- 5V – Pin 02 on the Raspberry Pi diagram below (upper right pin) to label G on the relay diagram. This powers the relay coil.
- 3.3V – Pin 17 (fifth from the bottom, left row) to label F. This provides 3.3V as a signal current to the relay.
- 0V – Pin 25 to label E. This grounds the 5V supply. Note that the 5V and 0V are isolated via an optocoupler from the 3.3V connection(The schematic can be found here.)
- GPIO – Pin 11 (GPIO 17) to label B. This is going to be configured as an OUTPUT pin, and set LOW, which will activate the relay.
- The two top most screw-down relay holes (in the upper left) are what will be connected to each other when the relay triggers. These two wires will need to be run to your garage door in a manufacturer / model dependent fashion.
|Notated relay board|
- Checking the garage state
- This was accomplished with the magnetic switch listed above. One half of the switch is connected to the swinging door, the other half is attached to the door frame. In this case half of it was attached to the wall above the garage door, and half of it was attached to the garage door itself. When the garage door is closed, these two halves are within about a 1/4 inch of each other.
- Make a wire with an inline 1k ohm resistor (to prevent accidentally blowing out a GPIO pin).
- 3.3V – Connect this wire from Pin 1 on the Raspberry Pi and connect it to one side of the magnetic switch mentioned above (red, or white wire in diagram below)
- Connect a wire from the opposite side of the magnetic switch and run it to pin 12 (GPIO 18).
- When the door is closed, this circuit should be closed.
|This is the magnetic switch. The front side (closest in this picture) is attached to the moving door, the rear side is screwed into the wall. When they come within about 1/4 inch of each other, it toggles.|
|Sorry for the mediocre picture… it’s mounted on top of the opener.|
There are three interaction points in the application that this token is used for:
- Toggle the garage (actuate the relay which in turns activates the door)
- Close the the garage (toggles the garage if it is not in a closed state)
- Display the status of the garage (open / closed)
|Configuration Screen (accessible by hitting menu button)|
- Download the web service from Github.
- The Pi will need to be flashed with a soft-float OS in order to support Java. I used Debian Wheezy. You may find these downloads here.
- Open the GarageDoor project in eclipse (the web service)
- Export the following classes into a jar file and put them inside Tomcat’s lib folder
- Export the following classes into a jar file and put them inside Tomcat’s lib folder
- Create a file called “garage_users” and place it inside the home directory of the user that Tomcat is running as
- Add a user by entering an email on the first line of this file, with no spaces.
- Configure Tomcat to use a self-signed SSL certificate for the web app.
- Generate a war file in eclipse and load that file into the Tomcat manager.
- After the SSL certificate is generated above, we can generate our custom keystore that the application will use. Again, follow the directions on crazybob’s blog.
- Copy the generated file to res/raw/mystore.bks
- Change the password in GarageSSLSocketFactory to whatever was used when generating the keystore.