diff options
Diffstat (limited to '')
| -rw-r--r-- | source/tutorials/tls.rst | 335 |
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 |