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, 335 insertions, 0 deletions

diff --git a/source/tutorials/tls.rst b/source/tutorials/tls.rst
new file mode 100644
index 0000000..54a07d9
--- /dev/null
+++ b/source/tutorials/tls.rst
@@ -0,0 +1,335 @@
+Encrypting Syslog Traffic with TLS (SSL) [short version]
+========================================================
+
+*Written by* `Rainer Gerhards  <http://www.gerhards.net/rainer>`_
+*(2008-05-06)*
+
+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 `rsyslog's <http://www.rsyslog.com>`_ TLS features. 
+
+Please note that TLS is the more secure successor of SSL. While people
+often talk about "SSL encryption" they actually mean "TLS encryption".
+So don't look any further if you look for how to SSL-encrypt syslog. You
+have found the right spot.
+
+This is a quick guide. There is a more elaborate guide currently under
+construction which provides a much more secure environment. It is highly
+recommended to `at least have a look at it <rsyslog_secure_tls.html>`_.
+
+Background
+----------
+
+**Traditional 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 are easy
+ways to encrypt syslog communication. 
+
+The traditional approach involves `running a wrapper like stunnel around
+the syslog session <rsyslog_stunnel.html>`_. This works quite well and
+is in widespread use. However, it is not tightly coupled with the main
+syslogd and some, even severe, problems can result from this (follow a
+mailing list thread that describes `total loss of syslog messages due to
+stunnel
+mode <http://lists.adiscon.net/pipermail/rsyslog/2008-March/000580.html>`_
+and the `unreliability of TCP
+syslog <http://rgerhards.blogspot.com/2008/04/on-unreliability-of-plain-tcp-syslog.html>`_).
+
+`Rsyslog supports syslog via GSSAP <gssapi.html>`_\ I since long to
+overcome these limitations. However, syslog via GSSAPI is a
+rsyslog-exclusive transfer mode and it requires a proper Kerberos
+environment. As such, it isn't a really universal solution. The
+`IETF <http://www.ietf.org/>`_ has begun standardizing syslog over plain
+tcp over TLS for a while now. While I am not fully satisfied with the
+results so far, this obviously has the  potential to become the
+long-term solution. The Internet Draft in question, syslog-transport-tls
+has been dormant for some time but is now (May of 2008) again being
+worked on. I expect it to turn into a RFC within the next 12 month (but
+don't take this for granted ;)). I didn't want to wait for it, because
+there obviously is need for TLS syslog right now (and, honestly, I have
+waited long enough...). Consequently, I have implemented the current
+draft, with some interpretations I made (there will be a compliance doc
+soon). So in essence, a TLS-protected syslog transfer mode is available
+right now. As a side-note, Rsyslog is the world's first implementation
+of syslog-transport-tls.
+
+Please note that in theory it should be compatible with other, non IETF
+syslog-transport-tls implementations. If you would like to run it with
+something else, please let us know so that we can create a compatibility
+list (and implement compatibility where it doesn't yet exist). 
+
+Overall System Setup
+--------------------
+
+Encryption requires a reliable stream. So It will not work over UDP
+syslog. In rsyslog, network transports utilize a so-called "network
+stream layer" (netstream for short). This layer provides a unified view
+of the transport to the application layer. The plain TCP syslog sender
+and receiver are the upper layer. The driver layer currently consists of
+the "ptcp" and "gtls" library plugins. "ptcp" stands for "plain tcp" and
+is used for unencrypted message transfer. It is also used internally by
+the gtls driver, so it must always be present on a system. The "gtls"
+driver is for GnutTLS, a TLS library. It is used for encrypted message
+transfer. In the future, additional drivers will become available (most
+importantly, we would like to include a driver for NSS).
+
+What you need to do to build an encrypted syslog channel is to simply
+use the proper netstream drivers on both the client and the server.
+Client, in the sense of this document, is the rsyslog system that is
+sending syslog messages to a remote (central) loghost, which is called
+the server. In short, the setup is as follows:
+
+**Client**
+
+-  forwards messages via plain tcp syslog using gtls netstream driver to
+   central server on port 6514
+
+**Server**
+
+-  accept incoming messages via plain tcp syslog using gtls netstream
+   driver on port 6514
+
+Setting up the system
+---------------------
+
+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. There is a set of default certificates in
+./contrib/gnutls. These are key.pem and cert.pem. These are good for
+testing. 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. So
+it is a good idea to generate the key and certificate yourself.
+
+You also need a root CA certificate. Again, there is a sample CA
+certificate in ./contrib/gnutls, named ca.cert. It is suggested to
+generate your own.
+
+To configure the server, you need to tell it where are its certificate
+files, to use the gtls driver and start up a listener. This is done as
+follows:
+
+    ::
+
+        # make gtls driver the default and set certificate files
+	global(
+	DefaultNetstreamDriver="gtls"
+	DefaultNetstreamDriverCAFile="/path/to/contrib/gnutls/ca.pem"
+        DefaultNetstreamDriverCertFile="/path/to/contrib/gnutls/cert.pem"
+        DefaultNetstreamDriverKeyFile="/path/to/contrib/gnutls/key.pem"
+	)	
+
+	# load TCP listener
+	module(
+	load="imtcp" 
+	StreamDriver.Name="gtls"
+	StreamDriver.Mode="1" 
+	StreamDriver.Authmode="anon"
+	)
+
+	# start up listener at port 6514
+	input(
+	type="imtcp"
+	port="6514"
+	)
+
+This is all you need to do. You can use the rest of your rsyslog.conf
+together with this configuration. The way messages are received does not
+interfere with any other option, so you are able to do anything else you
+like without any restrictions.
+
+Restart rsyslogd. The server should now be fully operational.
+
+Client Setup
+~~~~~~~~~~~~
+
+The client setup is equally simple. You need less certificates, just the
+CA cert. 
+
+    ::
+
+        # certificate files - just CA for a client
+	global(DefaultNetstreamDriverCAFile="/path/to/contrib/gnutls/ca.pem")
+
+        # set up the action for all messages
+	action(type="omfwd" protocol="tcp" target="s.example.net" port="6514"
+	       StreamDriver="gtls" StreamDriverMode="1" StreamDriverAuthMode="anon")
+
+Note that we use the regular TCP forwarding action here. There is
+nothing special, because the encryption is handled by the netstream
+driver. So I have just forwarded every message (\*.\*) for simplicity -
+you can use any of rsyslog's filtering capabilities (like
+expression-based filters or regular expressions).
+
+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 your sniffer, you should see that the
+traffic on the wire is actually protected.
+
+Certificates
+------------
+
+In order to be really secure, certificates are needed. This is a short
+summary on how to generate the necessary certificates with GnuTLS'
+certtool. You can also generate certificates via other tools, but as we
+currently support GnuTLS as the only TLS library, we thought it is a
+good idea to use their tools.
+
+Note that this section aims at people who are not involved with PKI at
+all. The main goal is to get them going in a reasonable secure way. 
+
+CA Certificate
+~~~~~~~~~~~~~~
+
+This is used to sign all of your other certificates. The CA cert must be
+trusted by all clients and servers. The private key must be
+well-protected and not given to any third parties. The certificate
+itself can (and must) be distributed. To generate it, do the following:
+
+#. generate the private key:
+
+   ::
+
+       certtool --generate-privkey --outfile ca-key.pem
+
+   This takes a short while. Be sure to do some work on your
+   workstation, it waits for random input. Switching between windows is
+   sufficient ;)
+
+#. now create the (self-signed) CA certificate itself:
+
+   ::
+
+       certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem
+
+   This generates the CA certificate. This command queries you for a
+   number of things. Use appropriate responses. When it comes to
+   certificate validity, keep in mind that you need to recreate all
+   certificates when this one expires. So it may be a good idea to use a
+   long period, eg. 3650 days (roughly 10 years). You need to specify
+   that the certificates belongs to an authority. The certificate is used
+   to sign other certificates.
+
+#. You need to distribute this certificate to all peers and you need to
+   point to it via the $DefaultNetstreamDriverCAFile config directive.
+   All other certificates will be issued by this CA.
+   Important: do only distribute the ca.pem, NOT ca-key.pem (the
+   private key). Distributing the CA private key would totally breach
+   security as everybody could issue new certificates on the behalf of
+   this CA.
+
+Individual Peer Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each peer (be it client, server or both), needs a certificate that
+conveys its identity. Access control is based on these certificates. You
+can, for example, configure a server to accept connections only from
+configured clients. The client ID is taken from the client instances
+certificate. So as a general rule of thumb, you need to create a
+certificate for each instance of rsyslogd that you run. That instance
+also needs the private key, so that it can properly decrypt the traffic.
+Safeguard the peer's private key file. If somebody gets hold of it, it
+can maliciously pretend to be the compromised host. If such happens,
+regenerate the certificate and make sure you use a different name
+instead of the compromised one (if you use name-based authentication). 
+
+These are the steps to generate the individual certificates (repeat: you
+need to do this for every instance, do NOT share the certificates
+created in this step):
+
+#. generate a private key (do NOT mistake this with the CA's private key
+   - this one is different):
+
+   ::
+
+       certtool --generate-privkey --outfile key.pem
+
+   Again, this takes a short while.
+
+#. generate a certificate request:
+
+   ::
+
+       certtool --generate-request --load-privkey key.pem --outfile request.pem
+
+   If you do not have the CA's private key (because you are not
+   authorized for this), you can send the certificate request to the
+   responsible person. If you do this, you can skip the remaining steps,
+   as the CA will provide you with the final certificate. If you submit
+   the request to the CA, you need to tell the CA the answers that you
+   would normally provide in step 3 below.
+
+#. Sign (validate, authorize) the certificate request and generate the
+   instances certificate. You need to have the CA's certificate and
+   private key for this:
+
+   ::
+
+       certtool --generate-certificate --load-request request.pem --outfile cert.pem \ --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem
+
+   Answer questions as follows: Cert does not belong to an authority; it
+   is a TLS web server and client certificate; the dnsName MUST be the
+   name of the peer in question (e.g. centralserver.example.net) - this
+   is the name used for authenticating the peers. Please note that you
+   may use an IP address in dnsName. This is a good idea if you would
+   like to use default server authentication and you use selector lines
+   with IP addresses (e.g. "\*.\* @@192.168.0.1") - in that case you
+   need to select a dnsName of 192.168.0.1. But, of course, changing the
+   server IP then requires generating a new certificate.
+
+After you have generated the certificate, you need to place it onto the
+local machine running rsyslogd. Specify the certificate and key via the
+$DefaultNetstreamDriverCertFile /path/to/cert.pem and
+$DefaultNetstreamDriverKeyFile /path/to/key.pem configuration
+directives. Make sure that nobody has access to key.pem, as that would
+breach security. And, once again: do NOT use these files on more than
+one instance. Doing so would prevent you from distinguishing between the
+instances and thus would disable useful authentication.
+
+Troubleshooting Certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you experience trouble with your certificate setup, it may be useful
+to get some information on what is contained in a specific certificate
+(file). To obtain that information, do 
+
+::
+
+    $ certtool --certificate-info --infile cert.pem
+
+where "cert.pem" can be replaced by the various certificate pem files
+(but it does not work with the key files).
+
+Conclusion
+----------
+
+With minimal effort, you can set up a secure logging infrastructure
+employing TLS encrypted syslog message transmission.
+
+Feedback requested
+~~~~~~~~~~~~~~~~~~
+
+I would appreciate feedback on this tutorial. If you have additional
+ideas, comments or find bugs (I \*do\* bugs - no way... ;)), please `let
+me know <mailto:rgerhards@adiscon.com>`_.
+
+Revision History
+----------------
+
+-  2008-05-06 \* `Rainer Gerhards`_ \*
+   Initial Version created
+-  2008-05-26 \* `Rainer Gerhards`_ \*
+   added information about certificates