HORATIO

horatio − Network access authentication http(s) server

horatio [file]

The Horatio system is a firewall authentication tool. The premise: Legitimate users want to attach laptops and other mobile hosts to the network, but security demands that illegitimate users be prevented from accessing the internal, secure network and from abusing the general Internet. The approach taken by Horatio is to provide a separate, untrusted, network that only connects to the internal network (and thus to the Internet) through a firewall that by default does not pass any traffic.

When a legitimate user connects his or her host, it is assigned an address by a DHCP server, but is unable to contact anything outside the untrusted network. The user must must point a web browser at the horatio web server, which runs on the firewall machine, and provide a username and password. Once the username and password have been validated, the firewall rules are modified to allow the host access to the rest of the network.

When leaving, the user can log out, removing his or her host from the access list. If the user does not log out, a periodic rollcall (using fping) will detect that the host is no longer accessible and remove it from the access list.

The horatio server uses syslog to log the actions it takes, including log-ins, log-outs, web accesses, rollcalls, and process starts and stops.

This package contains the horatio web server and firewall scripts.

More details about the firewall are available in the horatio-firewall(8) man page and about the host management in the horatio-hostlist(8) man page.

Other software will be needed, including a DHCP server. Please check the documentation for the extra packages for information on configuring them.

I MAKE NO CLAIMS REGARDING THE SECURITY OR UTILITY OF THIS SOFTWARE. The GNU General Public License, under which this software is made available, says,

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Please keep that in mind.

We have taken some effort to make sure this system works as advertised, but I am not a security expert and this software should not be blindly trusted. (In fact, it should only be considered a "technology demonstration," or perhaps a piece of performance art.) As well, there is a trade-off between security and convenience, and by making it easier to allow random people to connect to your network you are decreasing your security. YOU HAVE BEEN WARNED.

The horatio daemon reads a configuration file file, which can be given on the command line. It defaults to %sysconfdir%/horatio.conf.

The configuration file is line oriented, with each line being a configuration directive followed by the directive’s arguments. Comments start with the # character and continue to the end of the line. Lines can be continued by a backslash (\) being the last character on the line. The directive and arguments are separated by whitespace.

The configuration directives are:

state_directory directory

The state_directory is used as the working directory for the server and contains the state information, log files, certificates, etc. If a relative path is used for any of the other directives, it is interpreted relative to the state_directory.

password_files file...

This directive lists one or more files, separated by spaces, which contain lines consisting of username/password pairs separated by colons. The password should be encrypted with crypt(3). Horatio can use the standard Unix password file format—it ignores the remaining fields.

html_directory directory

The html_directory should contain the HTML files that horatio needs internally. This directory can also be used to contain other files, such as those backing specific URLs as described below. The necessary, internal files are

403.html, 404.html, 500.html

Error message pages.

authorized.html

The page indictaing that the user has sucessfully been authenticated.

logout_ok.html

The page indicating that the user has been removed from the firewall.

http URL MIME-type filename

The horatio server responds only to those specific URLs mentioned in the configuration file. The http directive lists a file which will be available using an HTTP connection. Each http directive (there may be any number) gives the URL (such as / or /index.html), the MIME-type of the URL (such as text/html or image/png), and the filename which will be delivered to a browser requesting that URL. The filename can be absolute or relative to the state_directory. If no http directives are given, the HTTP server process is not started. Before the file is passed to the browser, two strings, PEER and ACCESS, are replaced in it with the browser’s IP address and either "allowed" or "denied", based on the state of the firewall for the IP address.

https URL MIME-type filename

The https directive is similar to the http directive, but used for HTTPS connections (which are encrypted and use SSL).

rollcall_period period

The length of time between calls to horatio-hostlist rollcall, which removes inactive hosts from the firewall access list. A host is judged to be inactive if it does not respond to pings (ICMP echo requests). This defaults to 300 seconds and horatio complains if it is set lower that 30 seconds.

ssl_key filename

ssl_certificate filename

The HTTPS server process needs the SSL certificate and key files to establish trust (encryption and authentication) with browsers. If the filenames are relative, they are interpreted relative to the state_directory. The certificate and key files can be generated yourself using tools provided by OpenSSL (see openssl(1) and ssl(3)) although that may result in complaints from some browsers. Alternatively, the certificate and key can be created by a certificate authority such as VeriSign. This is not an advertisment—that is simply the configuration I have used.

Horatio has been used for several years in the University of Texas Department of Computer Sciences.

—

We are currently using exclusively Cisco ethernet switches for the trusted, production network and untrusted network. Using VLANs, the two networks share the same physical hardware, allowing better range than separate physical networks and better configurability (to set up a Horatio ethernet port, the port simply has to be added to the Horatio VLAN).

—

Wireless networks (which work fine, except when they don’t) should be treated as broadcast media. Any traffic using a wireless network in general, or any Horatio network for that matter, should use encrypted connections such as ssh and HTTPS.

—

If you use the VeriSign certificate authority for HTTPS, tell them you are using Apache with SSLeay as your server; the PEM files they provide work pretty well.

%sysconfdir%/horatio.conf

The default configuration file.

%pkgdatadir%/horatio-hostlist

Program that manages the authenticated hosts.

%pkgdatadir%/horatio-firewall

Program that initializes the firewall.

state_dir/horatio.pid

The pid of the horatio master process.

state_dir/horatio.out

The stdout and stderr of the horatio processes. This file is rolled each time the horatio daemon is started.

state_dir/html files

The HTML files required for horatio’s operation. See the html_directory configuration directive above.

state_dir/OPEN_ADDRESSES

The list of IP addresses belonging to hosts that are currently in the firewall access list.

horatio-firewall(8), horatio-hostlist(8), crypt(3), passwd(5), perl(1), openssl(1), ssl(3), ssh(1), fping(1), sysklogd(8).

Horatio is based on SPINACH developed at Stanford University. For more information, see http://mosquitonet.stanford.edu/spinach/spinach_info/.

Plenty. Do not trust it.

Seriously, some browsers apparently cause the HTTPS server to go off into the weeds. The symptoms include the server not responding to browsers and, when the HTTPS server process is strace’d, it is blocked on a read system call rather than an accept. I have found no workaround other than to restart the server.

Update (18 Mar 2003): This bug may have been fixed, by using SSL_no_shutdown when closing the socket returned by accept in the parent process as well as the parent’s listening socket in the child.

Some versions of the Perl SSL modules leak file descriptors (by failing to close the SSL connection in the accepting server process). Again, the only workaround is to restart the horatio server.

Update (10 Feb 2003): The fix for this problem in the SSL modules may have caused the previous problem. Both may be fixed now.

Some hosts do not respond to ICMP Echo requests and are therefore removed from the access list by the first rollcall after they are added. These hosts are broken.

Replacing PEER and ACCESS in non-HTML files (like, say, image/png files) is probably not a good idea.

—

Tommy M. McGuire (mcguire@cs.utexas.edu) wrote this.