diff options
Diffstat (limited to 'doc/rsyslog_stunnel.html')
| -rw-r--r-- | doc/rsyslog_stunnel.html | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/doc/rsyslog_stunnel.html b/doc/rsyslog_stunnel.html new file mode 100644 index 00000000..71bb878d --- /dev/null +++ b/doc/rsyslog_stunnel.html @@ -0,0 +1,248 @@ +<html><head>
+<title>SSL Encrypting syslog with stunnel</title>
+<meta name="KEYWORDS" content="syslog encryption, rsyslog, stunnel, secure syslog, tcp, reliable, howto, ssl">
+</head>
+<body>
+<h1>SSL Encrypting Syslog with Stunnel</h1>
+ <P><small><i>Written by
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
+ Gerhards</a> (2005-07-22)</i></small></P>
+<h2>Abstract</h2>
+<p><i><b>In this paper, I describe how to encrypt <a href="http://www.monitorware.com/en/topics/syslog/">syslog</a>
+messages on the network.</b> Encryption
+is vital to keep the confidiental content of syslog messages secure. I describe the overall
+approach and provide an HOWTO do it with the help of
+<a href="http://www.rsyslog.com">rsyslogd</a> and <a href="http://www.stunnel.org">stunnel</a>.</i></p>
+<h2>Background</h2>
+<P><b>Syslog is a
+clear-text protocol. That means anyone with a sniffer can have
+a peek at your data.</b> In some environments, this is no problem at all. In
+others, it is a huge setback, probably even preventing deployment of syslog
+solutions. Thankfully, there is an easy way to encrypt syslog communication. I
+will describe one approach in this paper.</P>
+<P>The most straigthforward solution would be that the syslogd itself encrypts
+messages. Unfortuantely, encryption is only standardized in
+<a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a>. But there
+is currently no syslogd that implements RFC 3195's encryption features,
+so this route leads to nothing. Another approach would be to use vendor- or
+project-specific syslog extensions. There are a few around, but the problem here
+is that they have compatibility issues. However, there is one surprisingly easy
+and interoperable solution: though not standardized, many vendors and projects
+implement plain tcp syslog. In a nutshell, plain tcp syslog is a mode where
+standard syslog messages are transmitted via tcp and records are separated by
+newline characters. This mode is supported by all major syslogd's (both on Linux/Unix
+and Windows) as well as log sources (for example,
+<a href="http://www.eventreporter.com/en/">EventReporter</a> for Windows
+Event Log forwarding). Plain tcp syslog offers reliability, but it does not
+offer encryption in itself. However, since it operates on a tcp stream, it is now easy
+to add encryption. There are various ways to do that. In this paper, I will
+describe how it is done with stunnel (an
+other alternative would be <a href="http://en.wikipedia.org/wiki/IPSec">IPSec</a>, for example).</P>
+<P>Stunnel is open source and it is available both for Unix/Linux and Windows.
+It provides a way to
+ use ssl communication for any non-ssl aware client and server - in this case,
+ our syslogd.</P>
+ <P>Stunnel works much like a wrapper. Both on the client and on the server machine,
+ tunnel portals are created. The non-ssl aware client and server software is
+ configured to not directly talk to the remote partner, but to the local
+ (s)tunnel portal instead. Stunnel, in turn, takes the data received from the
+ client, encrypts it via ssl, sends it to the remote tunnel portal and that
+ remote portal sends it to the recipient process on the remote machine. The
+ transfer to the portals is done via unencrypted communication. As such,
+ it is vital that
+ the portal and the respective program that is talking to it are on the same
+ machine, otherwise data would travel partly unencrypted. Tunneling, as done by stunnel,
+ requires connection oriented communication. This is why you need to use
+ tcp-based syslog. As a side-note, you can also encrypt a plain-text RFC
+ 3195 session via stunnel, though this definitely is not what the
+ protocol designers had on their mind ;)</P>
+<P>In the rest of this document, I assume that you use rsyslog on both the
+client and the server. For the samples, I use <a href="http://www.debian.org/">Debian</a>.
+Interestingly, there are
+some annoying differences between stunnel implementations. For example, on
+Debian a comment line starts with a semicolon (';'). On
+<a href="http://www.redhat.com">Red Hat</a>, it starts with
+a hash sign ('#'). So you need to watch out for subtle issues when setting up
+your system.</P>
+<h2>Overall System Setup</h2>
+<P>In ths paper, I assume two machines, one named "client" and the other named "server".
+It is obvious that, in practice, you will probably have multiple clients but
+only one server. Syslog traffic shall be transmitted via stunnel over the
+network. Port 60514 is to be used for that purpose. The machines are set up as
+follows:</P>
+<P><b>Client</b></P>
+<ul>
+ <li>rsyslog forwards message to stunnel local portal at port 61514</li>
+ <li>local stunnel forwards data via the network to port 60514 to its remote
+ peer</li>
+</ul>
+<P><b>Server</b></P>
+<ul>
+ <li>stunnel listens on port 60514 to connections from its client peers</li>
+ <li>all connections are forwarded to the locally-running rsyslog listening
+ at port 61514</li>
+</ul>
+<h2>Setting up the system</h2>
+<P>For Debian, you need the "stunnel4" package. The "stunnel" package is the
+older 3.x release, which will not support the configuration I describe below.
+Other distributions might have other names. For example, on Red Hat it is just "stunnel".
+Make sure that you install the appropriate package on both the client and the
+server. It is also a good idea to check if there are updates for either stunnel
+or openssl (which stunnel uses) - there are often security fixes available and
+often the latest fixes are not included in the default package.</P>
+<P>In my sample setup, I use only the bare minimum of options. For example, I do
+not make the server check client cerficiates. Also, I do not talk much about
+certificates at all. If you intend to really secure your system, you should
+probably learn about certificates and how to manage and deploy them. This is
+beyond the scope of this paper. For additional information,
+<a href="http://www.stunnel.org/faq/certs.html">
+http://www.stunnel.org/faq/certs.html</a> is a good starting point.</P>
+<P>You also need to install rsyslogd on both machines. Do this before starting
+with the configuration. You should also familarize yourself with its
+configuration file syntax, so that you know which actions you can trigger with
+it. Rsyslogd can work as a drop-in replacement for stock
+<a href="http://www.infodrom.org/projects/sysklogd/">sysklogd</a>. So if you know
+the standard syslog.conf syntax, you do not need to learn any more to follow
+this paper.</P>
+<h3>Server Setup</h3>
+<P>At the server, you need to have a digital certificate. That certificate
+enables SSL operation, as it provides the necessary crypto keys being used to
+secure the connection. Many versions of stunnel come with a default certificate,
+often found in /etc/stunnel/stunnel.pem. If you have it, it is good for testing
+only. If you use it in production, it is very easy to break into your secure
+channel as everybody is able to get hold of your private key. I didn't find an
+stunnel.pem on my Debian machine. I guess the Debian folks removed it because of
+its insecurity.</P>
+<P>You can create your own certificate with a simple openssl tool - you need to
+do it if you have none and I highly recommend to create one in any case. To
+create it, cd to /etc/stunnel and type:</P>
+<p><blockquote><code>openssl req -new -x509 -days 3650 -nodes -out
+stunnel.pem -keyout stunnel.pem</code></blockquote></p>
+<P>That command will ask you a number of questions. Provide some answer for
+them. If you are unsure, read
+<a href="http://www.stunnel.org/faq/certs.html">
+http://www.stunnel.org/faq/certs.html</a>. After the command has finished, you
+should have a usable stunnel.pem in your working directory.</P>
+<P>Next is to create a configuration file for stunnel. It will direct stunnel
+what to do. You can used the following basic file:</P>
+<P><blockquote><code><pre>; Certificate/key is needed in server mode
+cert = /etc/stunnel/stunnel.pem
+
+<i>; Some debugging stuff useful for troubleshooting
+debug = 7
+foreground=yes</i>
+
+[ssyslog]
+accept = 60514
+connect = 61514</pre>
+</code></blockquote></P>
+<p>Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that the
+settings in <i>italics</i> are for debugging only. They run stunnel
+with a lot of debug information in the foreground. This is very valuable while
+you setup the system - and very useless once everything works well. So be sure
+to remove these lines when going to production.</p>
+<p>Finally, you need to start the stunnel daemon. Under Debian, this is done via
+"stunnel /etc/stunnel/syslog.server.conf". If you have enabled the debug
+settings, you will immediately see a lot of nice messages.</p>
+<p>Now you have stunnel running, but it obviously unable to talk to rsyslog -
+because it is not yet running. If not already done, configure it so that it does
+everything you want. If in doubt, you can simply copy /etc/syslog.conf to /etc/rsyslog.conf
+and you probably have what you want. The really important thing in rsyslogd
+configuration is that you must make it listen to tcp port 61514 (remember: this
+is where stunnel send the messages to). Thankfully, this is easy to achive: just
+add "-t 61514" to the rsyslogd startup options in your system startup script.
+After done so, start (or restart) rsyslogd.</p>
+<p>The server should now be fully operational.</p>
+<h3>Client Setup</h3>
+<P>The client setup is simpler. Most importantly, you do not need a certificate
+(of course, you can use one if you would like to authenticate the client, but
+this is beyond the scope of this paper). So the basic thing you need to do is
+create the stunnel configuration file.</P>
+<P><blockquote><code><pre><i>; Some debugging stuff useful for troubleshooting
+debug = 7
+foreground=yes</i>
+
+<b>client=yes</b>
+
+[ssyslog]
+accept = 127.0.0.1:61514
+connect = <font color="#FF0000">192.0.2.1</font>:60514
+</pre>
+</code></blockquote></P>
+<P>Again, the text in <i>italics</i> is for debugging purposes only. I suggest
+you leave it in during your initial testing and then remove it. The most
+important difference to the server configuration outlined above is the "client=yes"
+directive. It is what makes this stunnel behave like a client. The accept
+directive binds stunnel only to the local host, so that it is protected from
+receiving messages from the network (somebody might fake to be the local sender).
+The address "192.0.2.1" is the address of the server machine. You must change it
+to match your configuration. Save this file to /etc/stunnel/syslog-client.conf.</P>
+<P>Then, start stunnel via "stunnel4 /etc/stunnel/syslog-client.conf". Now
+you should see some startup messages. If no errors appear, you have a running
+client stunnel instance.</P>
+<P>Finally, you need to tell rsyslogd to send data to the remote host. In stock
+syslogd, you do this via the "@host" forwarding directive. The same works with
+rsyslog, but it suppports extensions to use tcp. Add the following line to your
+/etc/rsyslog.conf:</P>
+<P><blockquote><code><pre>*.* @<font color="#FF0000">@</font>127.0.0.1:61514
+</pre>
+</code></blockquote><i></P>
+
+</i>
+
+<P>Please note the double at-sign (@@). This is no typo. It tells rsyslog to use
+tcp instead of udp delivery. In this sample, all messages are forwarded to the
+remote host. Obviously, you may want to limit this via the usual rsyslog.conf
+settings (if in doubt, use man rsyslog.con).</P>
+<P>You do not need to add any special startup settings to rsyslog on the client.
+Start or restart rsyslog so that the new configuration setting takes place.</P>
+<h3>Done</h3>
+<P>After following these steps, you should have a working secure syslog
+forwarding system. To verify, you can type "logger test" or a similar smart
+command on the client. It should show up in the respective server log file. If
+you dig out you sniffer, you should see that the traffic on the wire is actually
+protected. In the configuration use above, the two stunnel endpoints should be
+quite chatty, so that you can follow the action going on on your system.</P>
+<P>If you have only basic security needs, you can probably just remove the debug
+settings and take the rest of the configuration to production. If you are
+security-sensitve, you should have a look at the various stunnel settings that
+help you further secure the system.</P>
+<h2>Preventing Systems from talking directly to the rsyslog Server</h2>
+<P>It is possible that remote systems (or attackers) talk to the rsyslog server
+by directly connecting to its port 61514. Currently (Jule of 2005), rsyslog does
+not offer the ability to bind to the local host, only. This feature is planned,
+but as long as it is missing, rsyslog must be protected via a firewall. This can
+easily be done via e.g iptables. Just be sure not to forget it.</P>
+<h2>Conclusion</h2>
+<P>With minumal effort, you can set up a secure logging infrastructure employing
+ssl encrypted syslog message transmission. As a side note, you also have the
+benefit of reliable tcp delivery which is far less prone to message loss than
+udp.</P>
+<h3>Feedback requested</h3>
+<P>I would appreciate feedback on this tutorial. If you have additional ideas,
+comments or find bugs (I *do* bugs - no way... ;)), please
+<a href="mailto:rgerhards@adiscon.com">let me know</a>.</P>
+<h2>Revision History</h2>
+<ul>
+ <li>2005-07-22 *
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Initial Version created</li>
+ <li>2005-07-26 *
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Some text brush-up, hyperlinks added</li>
+ <li>2005-08-03 *
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
+ * license added</li>
+</ul>
+<h2>Copyright</h2>
+<p>Copyright (c) 2005
+<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> and
+<a href="http://www.adiscon.com/en/">Adiscon</a>.</p>
+<p> Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license can be viewed at
+<a href="http://www.gnu.org/copyleft/fdl.html">
+http://www.gnu.org/copyleft/fdl.html</a>.</p>
+
+</body>
+</html>
\ No newline at end of file |