Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 277 insertions, 0 deletions

diff --git a/source/historical/stunnel.rst b/source/historical/stunnel.rst
new file mode 100644
index 0000000..90a3e06
--- /dev/null
+++ b/source/historical/stunnel.rst
@@ -0,0 +1,277 @@
+SSL Encrypting Syslog with Stunnel
+==================================
+
+*Written by* `Rainer Gerhards <https://rainer.gerhards.net>`_ *(2005-07-22)*
+
+**HISTORICAL DOCUMENT**
+
+**Note: this is an outdated HISTORICAL document.** A much better description on
+`securing syslog with TLS  <http://www.rsyslog.com/doc/master/tutorials/tls_cert_summary.html>`_
+is available.
+
+Abstract
+--------
+
+**In this paper, I describe how to encrypt**
+`syslog <http://www.monitorware.com/en/topics/syslog/>`_ **messages on the
+network.** Encryption is vital to keep the confidential content of
+syslog messages secure. I describe the overall approach and provide an
+HOWTO do it with the help of `rsyslogd <http://www.rsyslog.com>`_ and
+`stunnel <http://www.stunnel.org>`_.*
+
+Please note that starting with rsyslog 3.19.0, `rsyslog provides native
+TLS/SSL encryption <rsyslog_tls.html>`_ without the need of stunnel. I
+strongly recommend to use that feature instead of stunnel. The stunnel
+documentation here is mostly provided for backwards compatibility. New
+deployments are advised to use native TLS mode.\ **
+
+Background
+----------
+
+**Syslog is a clear-text protocol. That means anyone with a sniffer can
+have a peek at your data.** 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.
+
+The most straightforward solution would be that the syslogd itself
+encrypts messages. Unfortunately, encryption is only standardized in
+`RFC 3195 <http://www.monitorware.com/Common/en/glossary/rfc3195.php>`_.
+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,
+`EventReporter <http://www.eventreporter.com/en/>`_ 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 `IPSec <http://en.wikipedia.org/wiki/IPSec>`_, for
+example).
+
+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.
+
+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 ;)
+
+In the rest of this document, I assume that you use rsyslog on both the
+client and the server. For the samples, I use
+`Debian <http://www.debian.org/>`_. Interestingly, there are some
+annoying differences between stunnel implementations. For example, on
+Debian a comment line starts with a semicolon (';'). On `Red
+Hat <http://www.redhat.com>`_, it starts with a hash sign ('#'). So you
+need to watch out for subtle issues when setting up your system.
+
+Overall System Setup
+--------------------
+
+In this 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:
+
+**Client**
+
+-  rsyslog forwards  message to stunnel local portal at port 61514
+-  local stunnel forwards data via the network to port 60514 to its
+   remote peer
+
+**Server**
+
+-  stunnel listens on port 60514 to connections from its client peers
+-  all connections are forwarded to the locally-running rsyslog
+   listening at port 61514
+
+Setting up the system
+---------------------
+
+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.
+
+In my sample setup, I use only the bare minimum of options. For example,
+I do not make the server check client certificates. 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,
+`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_
+is a good starting point.
+
+You also need to install rsyslogd on both machines. Do this before
+starting with the configuration. You should also familiarize 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 `sysklogd <http://www.infodrom.org/projects/sysklogd/>`_. So if
+you know the standard syslog.conf syntax, you do not need to learn any
+more to follow this paper.
+
+Server Setup
+~~~~~~~~~~~~
+
+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.
+
+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:
+
+    ``openssl req -new -x509 -days 3650 -nodes -out  stunnel.pem -keyout stunnel.pem``
+
+That command will ask you a number of questions. Provide some answer for
+them. If you are unsure, read
+`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_.
+After the command has finished, you should have a usable stunnel.pem in
+your working directory.
+
+Next is to create a configuration file for stunnel. It will direct
+stunnel what to do. You can use the following basic file:
+
+::
+
+; Certificate/key is needed in server modecert = /etc/stunnel/stunnel.pem; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes
+
+        [ssyslog]
+        accept  = 60514
+        connect = 61514
+
+Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that
+the settings in *italics* 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.
+
+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.
+
+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 achieve: just add "-t
+61514" to the rsyslogd startup options in your system startup script.
+After done so, start (or restart) rsyslogd.
+
+The server should now be fully operational.
+
+Client Setup
+~~~~~~~~~~~~
+
+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.
+
+    ::
+
+        ; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes
+
+        client=yes
+
+        [ssyslog]
+        accept  = 127.0.0.1:61514
+        connect = 192.0.2.1:60514
+
+Again, the text in *italics* 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.
+
+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.
+
+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 supports extensions to use tcp. Add the
+following line to your /etc/rsyslog.conf:
+
+    ::
+
+        *.*      @@127.0.0.1:61514
+
+
+
+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).
+
+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.
+
+Done
+~~~~
+
+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.
+
+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-sensitive, you should have a look at the various stunnel
+settings that help you further secure the system.
+
+Preventing Systems from talking directly to the rsyslog Server
+--------------------------------------------------------------
+
+It is possible that remote systems (or attackers) talk to the rsyslog
+server by directly connecting to its port 61514. Currently (July 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.
+
+Conclusion
+----------
+
+With minimal 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.