openGalaxy Files

opengalaxy - a SIA receiver for Galaxy security control panels.
Copyright (C) 2015, Alexander Bruines <alexander.bruines@gmail.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
as published by the Free Software Foundation, or (at your option)
any later version.

In addition, as a special exception, the author of this program
gives permission to link the code of its release with the OpenSSL
project's "OpenSSL" library (or with modified versions of it that
use the same license as the "OpenSSL" library), and distribute the
linked executables. You must obey the GNU General Public License
in all respects for all of the code used other than "OpenSSL".
If you modify this file, you may extend this exception to your
version of the file, but you are not obligated to do so.
If you do not wish to do so, delete this exception statement
from your version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.



INDEX:
======

- About openGalaxy
- Acknoledgements
- Note about the diffrent lines of Galaxy panels
- NEW IN THIS VERSION
- Installing openGalaxy
- Preparing, configuring and using openGalaxy
- Using the MySQL database created by openGalaxy
- Still to do
- Building openGalaxy from source:

(Consult the changelog file for changes between versions of openGalaxy.)



About openGalaxy:
=================

openGalaxy is a software tool that listens on a serial port for incoming
SIA formatted alarm messages from a Galaxy security control panel. These
messages are sent to a websocket interface and may optionally be stored
in a MySQL database and/or (on Linux) forwarded by email.

This software is written for use by trained security professionals, but 
it could also be used by a layperson who wants to receive the exact same
messages that are normally send to a private emergency response company.

In addition to just listening for messages, openGalaxy can also be used
to (depending on the panels firmware version) arm and disarm areas,
omit zones, (re)set outputs and even change the programming of zones.

This requires the 'remote' code to access the panel. A complete list of
commands can be found in the file 'API.TXT'

More information about Galaxy control panels can be found on the
manufacturers website for the european market:
http://www.security.honeywell.com/uk/



Acknoledgements:
================

openGalaxy is based in part on the work of the libwebsockets project
(http://libwebsockets.org)

openGalaxy makes use of MySQL Connector/C 6.1 (libmysqlclient) which is
released under the GNU General Public License version 2 and Copyright (c)
2000, 2015, Oracle and/or its affiliates. All rights reserved.

This product includes software developed by the OpenSSL Project for
use in the OpenSSL Toolkit. (http://www.openssl.org/)

openGalaxy is based in part on the work of the wolfSSL project which is
released under the GNU General Public License version 2
(http://www.wolfssl.com/)

This product makes use of zlib. openGalaxy gratefully acknoledges the
contributions of Jean-loup Gailly and Mark Adler in creating the zlib
general purpose compresssion library.

openGalaxy uses GTK+ 3.0. GTK+ is covered by the GNU Lesser General
Public License (http://www.gtk.org/)

openGalaxy uses jQuery and jQuery-UI whitch are provided under the
MIT license (http://jquery.org/license/).

openGalaxy uses the GNOME Adwaita icon theme witch is released under the
the terms of either the GNU LGPL v3 or Creative Commons Attribution-Share
Alike 3.0 United States License.



Note about the diffrent lines of Galaxy panels:
===============================================

Galaxy security panels have always been backwards compatible
(with the exception of G2 panels). The oldest class of panels are now
called XL (or classic) panels and the new ones G2, G3, Dimension 
and Galaxy Flex.

The Galaxy XL panels may not support all of the functionality
provided by openGalaxy. Their level of support depends on the firmware
version of each of these panels.

I have only been able to test with the panels at my disposal so I do'nt
know about every quirk and caveat, you will have to test that out
for yourself.

On my Galaxy 18 v1.07 for instance the outputs may only be set by type and 
not by address. Also the area and output status can not be fetched or
seems to work but doesn't.

The newest panel that I can test with is a G3-520 v5.57. All functions in
openGalaxy work on this panel and should also work on the newer
(Dimension) panels.

G2 panels are not supported!
The README for openGalaxy version 0.11 stated that G2 panels are supported,
this turns out to be false. The 'INTRUDER G2-44 RS232 LEAD' (model A228)
cable for these panels can only be used to service the panel,
it does not provide SIA access.

I have never seen one myself (yet), but from what I'm hearing openGalaxy
should also work with 'Galaxy Flex' panels. (Please correct me if I am 
wrong!!)



NEW IN THIS VERSION:
====================

0.13:

As you may notice there are still very few updates to the client
application. Its lack of functionality remains the same in this version.
The webinterface is still the better option.

The reason is that I'm focussed on the security of the client/server
communications. Not completely unimportant for an application that focusses
on security ;-) Only when this is at an acceptable level will I continue with
the client application and/or add features to other parts of openGalaxy.
(I realize that many users do not want to use SSL because they run openGalaxy
on a local network only. I still recommend using SSL in this and all other
situations. Using no SSL at all is only recommended for testing purposes!)

This version (0.13) implements the optional use of a username and password
(stored in each client certificate) and openGalaxy is now able to maintain a
'session id' for each client that connects to the server. Also, with the
upgrade to libwebsockets version 1.7.4 and using a better cipher-suite, the
SSL connection now has perfect forward secrecy. Addionally openGalaxy now uses
a single websocket for both SIA messages and commands send to the Galaxy panel.

With SSL fully enabled all clients must:
 - present a valid client certificate.
 - provide the username and password for that specific certificate.

The credentials stored in each client certificate are encrypted with a public
RSA key and can only be decrypted with a private key maintained by openGalaxy.

If a client opens a second session using his/her certificate, this automaticly
invalidates the first session. The first session still receives SIA messages
but commands can only be executed by the last session.

The only thing I'm not quite happy with is that the current implementation
uses 'HTTP Basic Auth' to ask users for their credentials. The fact that this
method sends the password in plain text is resolved by using SSL, but there
are other issues (like the browser offering to store the credentials and
caching the credentials at least as long as the window is kept open). The
next version of openGalaxy will most likely drop the 'Basic Auth' method in
favour of something else.

There also is a new option that will automaticly logoff clients after a
configurable time of inactivity. This option can be enabled with commandline
option --enable-auto-logoff. The length of inactivity before automatic logoff
can be configured in galaxy.conf Logged off clients cannot execute commands but
will still receive SIA messages. (Disabled by default because it does not work
100% yet and can be circumvented by making use of the cached (basic auth)
credentials.)

As a result of these new features any pre version 0.13 certificates will need
to be updated to include user credentials (this can be done by invalidating
them with openGalaxy-ca and then creating a new private key, the password field
is now unlocked and a password can be entered after which a new certificate
request can be made and signed).

This version has two bugfixes; When running from Windows, the commands
to get the current status of a zone or output should now function correctly.
Also the 'passphrase.txt' file is no longer overwritten by the Windows
installer.


Installing openGalaxy:
======================

For Windows: Use the installer executable.

For Debian and Ubuntu:

  Build or download all .deb packages and run:
    sudo spt-get install libmysqlclient18 menu menu-xdg openssl libssl
    sudo dpkg -i *.deb

For Raspbian:

  Build or download all .deb packages and run:
    sudo spt-get install libmysqlclient18 menu menu-xdg openssl libssl1.0.0
    sudo dpkg -i *.deb


  The openGalaxy applications are now available in your menu as:
    Debian -> Applications -> System -> Security -> openGalaxy*

  Or they may be executed from the commandline as:
    opengalaxy
    opengalaxy-client
    opengalaxy-ca

For other Linux:

  There is no installer, you must install from the sourcecode.
  See README.BUILDING



Preparing, configuring and using openGalaxy:
============================================

Several manual pages are provided to aid in preparing the SSL
certificates, configuring both openGalaxy and the attached Galaxy
security control panel and how to use the openGalaxy applications.

On Linux these 'man' pages are accessible with the commands:

man galaxy.conf
man opengalaxy
man opengalaxy-ca
man opengalaxy-client

On Windows a number of PDF document are installed in the programs
directory:

galaxy.conf.pdf
opengalaxy.pdf
opengalaxy-ca.pdf
opengalaxy-client.pdf



Using the MySQL database created by openGalaxy:
===============================================

To demonstrate displaying messages written to the MySQL database that
openGalaxy creates, a small example webinterface for installation on a
webserver (like apache2) is included in the example directory:

It is written using php5, JQuery and JQuery UI and displays decoded SIA
messages in a web browser as soon as they are written to a MySQL database.

How to set up a web server is beyond the scope of this documentation, but
the files in the example directory may be copied to the 'docroot' of your
web server. The web server will need to support php5 and you'll need to
adjust the settings in 'example/dbconnect.php'



Still to do:
============

- Finish the client application.

- Finish the ODBC database output plugin (or remove it)

- (Linux only) Daemonize openGalaxy so that it is started as a service

- See if newer Galaxy panels (Galaxy Dimension series) support more/other
  functions to remotely control those panels. *

- Add support for receiving/sending SIA messages over a network using the
  Galaxy Ethernet module. *

* I don't own either of these hardware components so support for them is
  currently on hold. Donations are welcome ;)

(Abandoned goals)

- Enable SSL on the MySQL database connection.
  (Why: Users of a remote database server should tunnel with SSH)




Building openGalaxy from source:
================================

If you are interested in building openGalaxy yourself then read the file:

- "README-BUILDING"     For building openGalaxy on x86 Linux computers
- "README-MSYS2.TXT"    For building openGalaxy on x86 Windows computers
- "README-RaspberryPi"  For building openGalaxy on the Raspberry Pi

These readme files are included with the source distribution.