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
published by the Free Software Foundation, with the additional
exemption that compiling, linking, and/or using OpenSSL is allowed.
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
- How it works
- Requirements to install/configure/use this software
- Building/Installing (Linux)
- Building/Installing (Win32, MinGW/MSYS)
- Building/Installing (Win32, Cygwin)
- Runtime configuration
- Preparing the webbrowser for using openGalaxy
- Using openGalaxy
- Using openGalaxyCA to manage SSL certificates
- Configuring the Galaxy security control panel
- Still to do
- List of supported commands
- Command examples
(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 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
arm and disarm areas, omit zones and even to (re)set outputs. This
requires the 'remote' code to access the panel. A complete list of
commands can be found at the end of this document.
So far, this software has only been tested with a 'Galaxy G3-520' control
panel and some older Galaxy control panels (G18/G60) with varying (Dutch)
firmware versions. (with 'group' or 'blokken' mode enabled)
More information about Galaxy control panels can be found on the
manufacturers website for the european market:
http://www.security.honeywell.com/uk/
This software was written using publicly available documentation about the
SIA protocol combined with data analysis of observed rs232 traffic (in
between a Galaxy panel and other software packages) in order to figure out
how to remotely control the panel using the SIA protocol.
openGalaxy is still in a testing (BETA) phase and should not be considered
stable or secure (yet).
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 may include 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 CyaSSL project which is
released under the GNU General Public License version 2
(http://www.yassl.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.
How it works:
-------------
This program listens (on a serial port) for incoming SIA messages and
decodes them. Each message is then send to a websocket and optionaly
to a database (MySQL and/or ODBC).
The messages may also be forwarded to 1 or several email accounts.
In addition to just listening for messages, openGalaxy also provides a
method for sending commands back to the control panel.
By itself openGalaxy is not very usable apart from logging SIA messages
and sending the occasional command to a panel. openGalaxy is meant to be
used by another application that uses the interface openGalaxy provides.
The interface openGalaxy provides consists of a webinterface that uses
a websocket to send SIA messages to, and recieve commands from clients.
As such openGalaxy can be viewed as the humble beginnings of a security
management system.
Requirements to install/configure/use this software:
----------------------------------------------------
(Any build instructions in this section only apply to the Linux build)
- libmysqlclient is needed only if the MySQL output plug-in is used.
(http://dev.mysql.com/downloads/connector/c/)
I build my copy with the following command (from the source directory):
cmake . && make && sudo make install
- CyaSSL is used to secure the webinterface and to verify clients
(https://github.com/cyassl/cyassl and http://www.wolfssl.com/).
I used the following commands to build CyaSSL:
./autogen.sh
./configure --enable-crl --with-libz --enable-opensslextra --enable-static
make && make test && sudo make install
Alternatively OpenSSL may be used to secure the webinterface and
validate clients by using ./configure --with-openssl.
At this moment CyaSSL is preferred because with openSSL the
client verification code of openGalaxy does'nt fully function
resulting in some websocket-protocols not being able to connect
to the client browser if client verification is enabled.
If you build openGalaxy with OpenSSL you allways need to execute
openGalaxy with the --no-client-certs option...
- OpenSSL is used by the openGalaxyCA script that creates and manages the
SSL certificates (https://www.openssl.org/)
- libwebsockets is used to provide the webinterface.
(http://libwebsockets.org)
The latest version (1.3) of libwebsockets needs to be patched in order
to be used with the latest CyaSSL (3.1.0) and openGalaxy.
The patch works around the fact that some API functions have not been
implemented (yet?) in CyaSSL. If this patch is'nt used then
libwebsockets will make openGalaxy crash when an invalid client
certificate is send by a client, caused by a NULL pointer in
OpenSSL_verify_callback().
To apply the patch copy the file:
libwebsockets_cyassl_fix_crash_on_invalid_client_cert.patch
to the directory you unzipped/cloned the libwebsockets sources into
and from there execute the command:
patch -p2 <libwebsockets_cyassl_fix_crash_on_invalid_client_cert.patch
I then used the following commands to build libwebsockets:
mkdir build && cd build
cmake -DLWS_USE_CYASSL=1 -DLWS_CYASSL_INCLUDE_DIRS=/usr/local/include -DLWS_CYASSL_LIB=/usr/local/lib/libcyassl.so ..
make && sudo make install
I have noticed that only the latest development version of
libwebsockets is available from libwebsockets.org. The problem with
this is that the development version doesn't always compile cleanly.
To solve this issue I will provide the copy I used with the sourcecode
for openGalaxy.
- The user running this software must be a member of group 'dialout'
to be able to use the serial port, and also of group 'mail' if the
email output plugin is used.
- The SSMTP package for you distro must be installed in /usr/bin/ssmtp
(Only if you use the email output plugin.)
If you use a gmail account to send the emails then it may be nessesary
to enable 'Less Secure Apps' to allow ssmtp to use the account.
To enable this gmail option, login to the account with a browser and
go to the address:
https://www.google.com/settings/security/lesssecureapps
- Access to a MySQL server is needed if the MySQL output plug-in is used.
The nessesary users and database can be imported from the files:
CreateUser.sql and CreateDatabase.sql
Note:
The code of openGalaxy is multithreaded and uses the POSIX Threads library
(available by default on most modern Linux distributions).
Building/Installing (Linux):
----------------------------
From this directory, execute:
mkdir build && cd build
followed by:
../configure
And if there are no errors:
make && sudo make install
This will install (or write over!) the following file(s):
/usr/local/bin/openGalaxy
/usr/local/bin/openGalaxyCA
/usr/local/etc/galaxy/galaxy.conf
/usr/local/etc/galaxy/ssmtp.conf
/usr/local/etc/galaxy/CA.conf
/usr/local/share/galaxy/www/index.html
/usr/local/share/galaxy/passphrase.txt
The final step of 'make install' tries to create a new set of SSL
certificates for openGalaxy (by executing 'openGalaxyCA init' as root).
The created certificates are placed (and are expected to be) in the
directory: /usr/local/share/galaxy/ssl and its sub-directories.
The certificates will not be overwritten by 'make install'.
The most important of these certificate files (ie. the files used by
the openGalaxy executeable) are:
/usr/local/share/galaxy/ssl/certs/openGalaxyCA.pem
/usr/local/share/galaxy/ssl/certs/openGalaxyCRL.pem
/usr/local/share/galaxy/ssl/certs/server.pem
/usr/local/share/galaxy/ssl/private/serverKEY.pem
The passphrase.txt file contains the pass phrase used to secure the RSA
private key of the openGalaxy CA certificate. (If you change the contents
of this file a new set of certificates must be created!)
To create a new set of certificates delete the /usr/local/share/galaxy/ssl
directory and execute: sudo openGalaxyCA init
Note:
The configure script has several options that may assist in compiling
openGalaxy on your target:
--prefix=<DIR>
Installation prefix for installed files
The default is /usr/local
--bindir=<DIR>
Installation prefix for installed executeable files
The default is $(prefix)/bin
--sysconfdir=<DIR>
Installation prefix for installed configuration files
The default is $(prefix)/etc
--datadir=<DIR>
Installation prefix for installed data files
The default is $(prefix)/share
--without-email-plugin
Disables support for forwarding SIA messages by email
--without-mysql-plugin
Disables support for writing SIA messages to a MySQL database
--with-odbc-plugin
Enables support for writing to a ODBC database (not finished yet)
--with-libwebsockets=<DIR>
Sets the path to the libwebsockets library
The default is /usr/local/lib
--with-libwebsockets-include=<DIR>
Sets the path to the libwebsockets.h header file
The default is /usr/local/include
--enable-shared-libwebsockets
Link with the shared websockets library
The default is to link with the static library
--with-libmysqlclient=<DIR>
Sets the path to libmysqlclient
The default is /usr/local/mysql
--with-cyassl=<DIR>
Sets the path to the CyaSSL library
The default is /usr/local/lib
--with-cyassl-include=<DIR>
Sets the path to the cyassl/* header file directory.
The default is /usr/local/include
--enable-shared-cyassl
Link with the shared CyaSSL library
The default is to link with the static library
--with-openssl=<DIR>
Root of the OpenSSL directory
The default search path is /usr/local/ssl /usr/lib/ssl /usr/ssl /usr/pkg
/usr/local /usr (in that order).
The openssl executable also needs to be in the path in order to generate
the certificates for openGalaxy.
If specified (with or without DIR), OpenSSL will be used instead of
CyaSSL.
--with-zlib=<DIR>
Root directory path of zlib installation
The default is /usr/local or /usr if not found in /usr/local
Building/Installing (Win32, MinGW/MSYS):
-----------------------------------------
1. Install MSYS/MingW to the default location of C:/MinGW using the
MinGW installer. (http://www.mingw.org/)
2. Copy C:/MinGW/msys/1.0/msys.bat to your desktop (create shortcut)
3. Execute msys.bat and run the /postinstall/pi.sh script.
When it askes if you have MinGW installed answer with yes and
give the location (C:/MinGW)
4. Download and install MySQL Connector/C 6.1 from:
http://dev.mysql.com/downloads/connector/c/
(Download the Microsoft Windows (x86, 32-bit) MSI Installer).
openGalaxy expects an installation path of
C:/Program Files/MySQL/MySQL Connector C 6.1/
but this may be changed by using the --with-libmysqlclient option
to openGalaxy's configure script.
5. Download CMAKE for windows and install it in C:/CMake
6. Create mstcpip.h (needed by libwebsockets)
Create a new text file: C:\MinGW\include\mstcpip.h
--> cut here <---
struct tcp_keepalive
{
u_long onoff;
u_long keepalivetime;
u_long keepaliveinterval;
};
#ifndef USE_WS_PREFIX
#define SIO_KEEPALIVE_VALS _WSAIOW(IOC_VENDOR, 4)
#else
#define WS_SIO_KEEPALIVE_VALS _WSAIOW(WS_IOC_VENDOR, 4)
#endif
--> cut here <---
7. Download and extract the sourcecode for libwebsockets
(http://libwebsockets.org) to your MinGW/MSYS home directory.
Execute msys.bat and navigate to the libwebsockets sourcecode tree,
from there execute the following commands to build the library:
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DLWS_WITH_SSL=OFF -DLWS_WITHOUT_TESTAPPS=ON -G 'MSYS Makefiles' ..
make
make install
8. Extract the sourcecode for openGalaxy to the MinGW/MSYS home directory
and execute msys.bat. Navigate to the openGalaxy sourcecode tree and
execute the following commands to build it.
mkdir build && cd build
../configure --prefix=/c/openGalaxy --bindir=/c/openGalaxy --sysconfdir=/c/openGalaxy --datadir=/c/openGalaxy --without-email-plugin
make
make install-strip
Building/Installing (Win32, Cygwin):
-------------------------------------
TODO
Runtime configuration:
----------------------
- To configure openGalaxy, edit the configuration files:
/usr/local/etc/galaxy/galaxy.conf
/usr/local/etc/galaxy/ssmtp.conf
- An initial set of SSL certificates was generated during the installation
of openGalaxy. This set of certificates is suitable for use on the local
machine only! (ie. using the URL https://localhost:1500)
To create a set of certificates suitable for your network (or if you want
to actually host the openGalaxy webservice on the internet) edit the file:
/usr/local/etc/galaxy/CA.conf
And read the instructions in this file carefully.
- To create the initial database used by the MySQL output plug-in, execute:
mysql -u root -p -h servername <CreateDatabase.sql
mysql -u root -p -h servername <CreateUser.sql
(Edit CreateUser.sql to change the passwords used to connect to the database,
the default is 'topsecret'.)
Preparing the webbrowser for using openGalaxy
---------------------------------------------
Starting with version 0.7 openGalaxy uses SSL certificates to secure the
network connection and to authenticate clients that (try to) use the
webservice/websockets.
In order for a webbrowser to connect to the webservice it needs to:
- Verify the identity of the openGalaxy webservice.
- Present a client certificate to the webservice in order to authenticate
itself as a registered/validated user of the webservice.
To achieve this, two certificates need to be imported into the certificate
store the browser in question uses.
The first certificate is:
/usr/local/share/galaxy/ssl/certs/openGalaxyCA.crt
It should be imported into the browser as 'Certificate Authority' using
it's certificate manager (found somewhere in the settings of the browser)
and be allowed to identify websites.
The second certificate is:
/usr/local/share/galaxy/sll/certs/users/opengalaxy_client_certificate.p12
It should be imported into the webbrowser in the same maner as the first
certificate, but this time as 'Personal certificate'. (The password asked
for while importing this certificate is empty,)
v0.8 addemdum: Currently SSL is disabled for the Windows build.
Using openGalaxy:
-----------------
Connect the configured serial port to your control panel and run
'openGalaxy'. To stop the program, press CRTL+C.
openGalaxy has several command-line options available.
Use 'openGalaxy --help' to list them, together with an explanation
of what each option does.
For Windows only; The first time openGalaxy is started, Windows Firewall
will popup a dialog to ask wether or not to block the program's network
access. Choose to allow the program for the appropriate networks.
While openGalaxy is running the panel may be remotely controlled by
opening a webbrowser* and going to the URL***:
https://localhost:1500
The webbrowser will ask** what client certificate to use in order to
identify itself to the webservice.
This webpage also provides a live view of incoming SIA messages on the
websocket. The webpage is optimized for FullHD format but can be scaled
to your screen resolution by using CTRL-PLUS or CTRL-MINUS.
If you want to connect from another machine than the one running the
openGalaxy executeable, read the 'Runtime Configuration' section in this
document very carefully.
* The browser must support HTML5 websockets.
** Make sure you have read the 'Preparing the webbrowser for using
openGalaxy' section of this document.
*** On Windows, SSL has been disabled and the default port number is set
to 80. The default URL for the Windows build is:
http://localhost
To demonstrate displaying messages written to the MySQL database that
openGalaxy uses, 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'
Using openGalaxyCA to manage SSL certificates
---------------------------------------------
To manage the SSL certificates used by openGalaxy and client browsers
the program openGalaxyCA may be used.
It can be used to create additional (and revoke comprimized) client
certificates and is completely menu driven.
Just execute openGalaxyCA as root and follow instructions.
openGalaxyCA stores the certificates it creates in the dirctory
/usr/local/share/galaxy/ssl and its subdirectories.
Configuring the Galaxy security control panel:
----------------------------------------------
- Using the installer code, go to communications menu (56) and select the
RS232 module.
- Program the RS232 for SIA level 3 (or 4 if available) and select all
triggers (Realy old panels may name the SIA protocol as 'MultiPro')
- Configure the RS232 for 9600 8N1 (Use the same baudrate on the computer!)
- The account ID should not be left empty!
- The panel should be configured with 'Group mode' enabled (menu 63.1.1 = 1)
(Anything else is currently untested)
Still to do:
------------
(ordered by priority)
- Finish the ODBC database output plugin (or remove it)
- Daemonize openGalaxy so that it is started as a service
(will be done in a future release when I deem this software package
stable enough).
- 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)
List of supported commands:
---------------------------
The following is a list of commands may be executed by using the
webinterface:
-- AREA -------------------------------------------------------------------
Syntax: AREA <blknum> <action>
Where:
blknum = Area number (1-32, A1-A8, B1-B8, C1-C8, D1-D8)
Special area 0 operates on all areas.
action = UNSET Disarm an area
SET Arm an area
PARTIAL Partially arm an area
RESET Reset an area
ABORT Abort setting an area
FORCE Force setting an area
STATE Get the status of an area
0 = unset
1 = set
2 = partial
READY Area status with more states
0 = unset
1 = set
2 = partial
3 = Ready to arm
4 = Time locked
ALARM Get the alarm status of an area
0 = Normal
1 = Alarm
2 = Reset required
-- ZONE -------------------------------------------------------------------
Syntax: ZONE <nr> <action>
Where:
nr = Zone (1001-4158) or zone-type (1-100)
action = OMIT Omit a zone by number or type
UNOMIT Un-omit a zone by number or type
ISOMIT Get omit status of a zone (by number)
0 = Not omitted
1 = Omitted
STATE Get the status of a zone (by number)
0 = Tamper S/C
1 = Low resistance
2 = Zone closed
3 = High resistance
4 = Open
5 = Tamper O/C
6 = Masked
7 = Tamper CV
8 = Fault
-- ZONES ------------------------------------------------------------------
Syntax: ZONES <action>
Where:
action = READY Get the ready state of all zones
ALARM Get the alarm state of all zones
OPEN Get the open state of all zones
TAMPER Get the tamper state of all zones
RSTATE Get the resistance state of all zones
OMITTED Get the omitted state of all zones
-- OUTPUT -----------------------------------------------------------------
Syntax: OUTPUT <nr> <action> [blknum]
OUTPUT GETALL
Where:
nr = Output (1001-4154) or output type (1-100)
special output type 0 means all outputs
action = ON Turn the output on
OFF Turn the output off
blknum = Area number (1-32, A1-A8, B1-B8, C1-C8, D1-D8)
Special area 0 operates on all areas.
When not specified, area 0 is implied.
Only has effect for actions on output-types.
Note: GETALL returns an array of 32 bytes with
each bit representing the state of an output.
Note: When setting by output number the panel will ignore
that outputs programming and just performs <action>.
When setting by type, the outputs will follow their
normal programming.
-- HELP -------------------------------------------------------------------
Syntax: HELP <command>
Provides help about a specific command.
Command examples:
-----------------
# Arm area 1 (A1)
area 1 set
# Partialy arm area D7 (31)
area d7 partial
# Omit zone 2145
zone 2145 omit
# Activate output 1002
output 1002 on
Download Latest Version
opengalaxy-0.15.tar.xz (30.8 MB)
