diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2008-07-03 16:50:42 +0200 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2008-07-03 16:50:42 +0200 |
| commit | 2ff7e5e73768556cef51cb1f8ef079c7d640a315 (patch) | |
| tree | 6a323a6fc8d0cc85a088e31c874cd474b31f62bd | |
| parent | aeef9bbe727d80c5882cc0a883b8dfd5df461f10 (diff) | |
| download | rsyslog-2ff7e5e73768556cef51cb1f8ef079c7d640a315.tar.gz rsyslog-2ff7e5e73768556cef51cb1f8ef079c7d640a315.tar.xz rsyslog-2ff7e5e73768556cef51cb1f8ef079c7d640a315.zip | |
finalized tutorial for creating a TLS-secured syslog infrastructure
| -rw-r--r-- | ChangeLog | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 10 | ||||
| -rw-r--r-- | doc/tls_cert_ca.html | 7 | ||||
| -rw-r--r-- | doc/tls_cert_client.html | 91 | ||||
| -rw-r--r-- | doc/tls_cert_machine.html | 11 | ||||
| -rw-r--r-- | doc/tls_cert_summary.html | 66 | ||||
| -rw-r--r-- | doc/tls_cert_udp_relay.html | 105 |
7 files changed, 288 insertions, 3 deletions
@@ -1,5 +1,6 @@ --------------------------------------------------------------------------- Version 3.19.9 (rgerhards), 2008-07-?? +- added tutorial for creating a TLS-secured syslog infrastructure - bugfix: machine certificate was required for client even in TLS anon mode Reference: http://bugzilla.adiscon.com/show_bug.cgi?id=85 The fix also slightly improves performance by not storing certificates in diff --git a/doc/Makefile.am b/doc/Makefile.am index 03b18f96..8ff207e0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -41,7 +41,17 @@ html_files = \ src/queueWorkerLogic.dia \ queueWorkerLogic.jpg \ queueWorkerLogic_small.jpg \ + tls_cert_100.jpg \ + tls_cert_ca.jpg \ tls_cert.jpg \ + tls_cert_errmsgs.html \ + tls_cert_server.html \ + tls_cert_ca.html \ + tls_cert_summary.html \ + tls_cert_machine.html \ + tls_cert_udp_relay.html \ + tls_cert_client.html \ + tls_cert_scenario.html \ rainerscript.html \ rscript_abnf.html \ rsconf1_actionexeconlywhenpreviousissuspended.html \ diff --git a/doc/tls_cert_ca.html b/doc/tls_cert_ca.html index 7427bb03..2cae4040 100644 --- a/doc/tls_cert_ca.html +++ b/doc/tls_cert_ca.html @@ -48,7 +48,12 @@ trust under this model. That is why the CA's private key is so important - everyone getting hold of it is trusted by our rsyslog instances.</p> <center><img src="tls_cert_ca.jpg"></center> <p>To create a self-signed certificate, use the following commands with GnuTLS (which -is currently the only supported TLS library, what may change in the future): </p> +is currently the only supported TLS library, what may change in the future). +Please note that GnuTLS' tools are not installed by default on many platforms. Also, +the tools do not necessarily come with the GnuTLS core package. If you do not +have certtool on your system, check if there is package for the GnuTLS tools available +(under Fedora, for example, this is named gnutls-utils-<version> and +it is NOT installed by default). </p> <ol> <li>generate the private key: <pre>certtool --generate-privkey --outfile ca-key.pem</pre> diff --git a/doc/tls_cert_client.html b/doc/tls_cert_client.html new file mode 100644 index 00000000..dbe7961b --- /dev/null +++ b/doc/tls_cert_client.html @@ -0,0 +1,91 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>TLS-protected syslog: client setup</title> +</head> +<body> + +<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> +<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer +Gerhards</a> (2008-07-03)</i></small></p> + +<ul> +<li><a href="rsyslog_secure_tls.html">Overview</a> +<li><a href="tls_cert_scenario.html">Sample Scenario</a> +<li><a href="tls_cert_ca.html">Setting up the CA</a> +<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> +<li><a href="tls_cert_server.html">Setting up the Central Server</a> +<li><a href="tls_cert_client.html">Setting up syslog Clients</a> +<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> +<li><a href="tls_cert_summary.html">Wrapping it all up</a> +</ul> + +<h3>Setting up a client</h3> +<p>In this step, we configure a client machine. We from our scenario, we use +zuse.example.net. You need to do the same steps for all other clients, too (in the +example, that meanst turng.example.net). The client check's the server's identity and +talks to it only if it is the expected server. This is a very important step. +Without it, you would not detect man-in-the-middle attacks or simple malicious servers +who try to get hold of your valuable log data. +<span style="float: left"> +<script type="text/javascript"><!-- +google_ad_client = "pub-3204610807458280"; +/* rsyslog doc inline */ +google_ad_slot = "5958614527"; +google_ad_width = 125; +google_ad_height = 125; +//--> +</script> +<script type="text/javascript" +src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> +</script> +</span> +<p><center><img src="tls_cert_100.jpg"></center> +<p>Steps to do: +<ul> +<li>make sure you have a functional CA (<a href="tls_cert_ca.html">Setting up the CA</a>) +<li>generate a machine certificate for zuse.example.net (follow instructions in + <a href="tls_cert_machine.html">Generating Machine Certificates</a>) +<li>make sure you copy over ca.pem, machine-key.pem ad machine-cert.pem to the client. +Ensure that no user except root can access them (<b>even read permissions are really bad</b>). +<li>configure the client so that it checks the server identity and sends messages only +if the server identity is known. Please note that you have the same options as when +configuring a server. However, we now use a single name only, because there is only one +central server. No using wildcards make sure that we will exclusively talk to that server +(otherwise, a compromised client may take over its role). If you load-balance to different +server identies, you obviously need to allow all of them. It still is suggested to use +explcit names. +</ul> +<p><b>At this point, please be reminded once again that your security needs may be quite different from +what we assume in this tutorial. Evaluate your options based on your security needs.</b> +<h3>Sample syslog.conf</h3> +<p>Keep in mind that this rsyslog.conf sends messages via TCP, only. Also, we do not +show any rules to write local files. Feel free to add them. +<code><pre> +# make gtls driver the default +$DefaultNetstreamDriver gtls + +# certificate files +$DefaultNetstreamDriverCAFile /rsyslog/protected/ca.pem +$DefaultNetstreamDriverCertFile /rsyslog/protected/machine-cert.pem +$DefaultNetstreamDriverKeyFile /rsyslog/protected/machine-key.pem + +$ActionSendStreamDriverAuthMode x509/name +$ActionSendStreamDriverPermittedPeer central.example.net +$ActionSendStreamDriverMode 1 # run driver in TLS-only mode +*.* @@central.example.net:10514 # forward everything to remote server +</pre></code> +<p>Note: the example above forwards every message to the remote server. Of course, +you can use the normal filters to restrict the set of information that is sent. +Depending on your message volume and needs, this may be a smart thing to do. +<p><font color="red"><b>Be sure to safeguard at least the private key (machine-key.pem)!</b> +If some third party obtains it, you security is broken!</font> +<h2>Copyright</h2> +<p>Copyright © 2008 <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> diff --git a/doc/tls_cert_machine.html b/doc/tls_cert_machine.html index 0d2955f7..5ecde0d1 100644 --- a/doc/tls_cert_machine.html +++ b/doc/tls_cert_machine.html @@ -36,7 +36,7 @@ src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> </script> </span> be specified inside the $<object>PermittedPeer config statements. -<p>For now, we assume that that a single person (or group) is responsible for the whole +<p>For now, we assume that a single person (or group) is responsible for the whole rsyslog system and thus it is OK if that single person is in posession of all machine's private keys. This simplification permits us to use a somewhat less complicated way of generating the machine certificates. So, we generate both the private @@ -56,6 +56,13 @@ breaching your security.</b> <p>Text in red is user input. Please note that for some questions, there is no user input given. This means the default was accepted by simply pressing the enter key. +<p><b>Please note:</b> you need to substitute the names specified below with values +that match your environment. Most importantly, machine.example.net must be replaced +by the actual name of the machine that will be using this certificate. For example, +if you generate a certificate for a machine named "server.example.com", you need +to use that name. If you generate a certificate for "client.example.com", you need +to use this name. Make sure that each machine certificate has a unique name. If not, +you can not apply proper access control. <code><pre> [root@rgf9dev sample]# <font color="red">certtool --generate-privkey --outfile key.pem --bits 2048</font> Generating a 2048 bit RSA private key... @@ -82,7 +89,7 @@ Extensions. Does the certificate belong to an authority? (Y/N): <font color="red">n</font> Is this a TLS web client certificate? (Y/N): <font color="red">y</font> Is this also a TLS web server certificate? (Y/N): <font color="red">y</font> -Enter the dnsName of the subject of the certificate: <font color="red">machine.example.net</font> +Enter the dnsName of the subject of the certificate: <font color="red">machine.example.net</font> <i>{This is the name of the machine that will use the certificate}</i> Will the certificate be used for signing (DHE and RSA-EXPORT ciphersuites)? (Y/N): Will the certificate be used for encryption (RSA ciphersuites)? (Y/N): X.509 Certificate Information: diff --git a/doc/tls_cert_summary.html b/doc/tls_cert_summary.html new file mode 100644 index 00000000..8e003bc8 --- /dev/null +++ b/doc/tls_cert_summary.html @@ -0,0 +1,66 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>TLS-protected syslog: Summary</title> +</head> +<body> + +<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> +<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer +Gerhards</a> (2008-07-03)</i></small></p> + +<ul> +<li><a href="rsyslog_secure_tls.html">Overview</a> +<li><a href="tls_cert_scenario.html">Sample Scenario</a> +<li><a href="tls_cert_ca.html">Setting up the CA</a> +<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> +<li><a href="tls_cert_server.html">Setting up the Central Server</a> +<li><a href="tls_cert_client.html">Setting up syslog Clients</a> +<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> +<li><a href="tls_cert_summary.html">Wrapping it all up</a> +</ul> + +<h3>Summary</h3> +<p>If you followed the steps outlined in this documentation set, you now have +<span style="float: left"> +<script type="text/javascript"><!-- +google_ad_client = "pub-3204610807458280"; +/* rsyslog doc inline */ +google_ad_slot = "5958614527"; +google_ad_width = 125; +google_ad_height = 125; +//--> +</script> +<script type="text/javascript" +src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> +</script> +</span> +a reasonable (for most needs) secure setup for the following environment: +<center><img src="tls_cert_100.jpg"></center> +<p>You have learned about the security decisions involved and which we +made in this example. <b>Be once again reminded that you must make sure yourself +that whatever you do matches your security needs!</b> There is no guarantee that +what we generally find useful actually is. It may even be totally unsuitable for +your environment. +<p>In the example, we created a rsyslog certificate authority (CA). Guard the CA's +files. You need them whenever you need to create a new machine certificate. We also saw how +to generate the machine certificates themselfs and distribute them to the individual +machines. Also, you have found some configuration samples for a sever, a client and +a syslog relay. Hopefully, this will enable you to set up a similar system in many +environments. +<p>Please be warned that you defined some expiration dates for the certificates. +After they are reached, the certificates are no longer valid and rsyslog will NOT +accept them. At that point, syslog messages will no longer be transmitted (and rsyslogd +will heavily begin to complain). So it is a good idea to make sure that you renew the +certificates before they expire. Recording a reminder somewhere is probably a good +idea. +<p>If you have any more questions, please visit the <a href="http://kb.monitorware.com/rsyslog-f40.html">rsyslog forum</a> and simply ask ;) +<h2>Copyright</h2> +<p>Copyright (c) 2008 <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> diff --git a/doc/tls_cert_udp_relay.html b/doc/tls_cert_udp_relay.html new file mode 100644 index 00000000..f4740ce7 --- /dev/null +++ b/doc/tls_cert_udp_relay.html @@ -0,0 +1,105 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>TLS-protected syslog: UDP relay setup</title> +</head> +<body> + +<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> +<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer +Gerhards</a> (2008-07-03)</i></small></p> + +<ul> +<li><a href="rsyslog_secure_tls.html">Overview</a> +<li><a href="tls_cert_scenario.html">Sample Scenario</a> +<li><a href="tls_cert_ca.html">Setting up the CA</a> +<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> +<li><a href="tls_cert_server.html">Setting up the Central Server</a> +<li><a href="tls_cert_client.html">Setting up syslog Clients</a> +<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> +<li><a href="tls_cert_summary.html">Wrapping it all up</a> +</ul> + +<h3>Setting up the UDP syslog relay</h3> +<p>In this step, we configure the UDP relay ada.example.net. +As a reminder, that machine relays messages from a local router, which only +supports UDP syslog, to the central syslog server. The router does not talk +directly to it, because we would like to have TLS protection for its sensitve +logs. If the router and the syslog relay are on a sufficiently secure private +network, this setup can be considered reasonable secure. In any case, it is the +best alternative among the possible configuration scenarios. +<span style="float: left"> +<script type="text/javascript"><!-- +google_ad_client = "pub-3204610807458280"; +/* rsyslog doc inline */ +google_ad_slot = "5958614527"; +google_ad_width = 125; +google_ad_height = 125; +//--> +</script> +<script type="text/javascript" +src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> +</script> +</span> +<p><center><img src="tls_cert_100.jpg"></center> +<p>Steps to do: +<ul> +<li>make sure you have a functional CA (<a href="tls_cert_ca.html">Setting up the CA</a>) +<li>generate a machine certificate for ada.example.net (follow instructions in + <a href="tls_cert_machine.html">Generating Machine Certificates</a>) +<li>make sure you copy over ca.pem, machine-key.pem ad machine-cert.pem to the client. +Ensure that no user except root can access them (<b>even read permissions are really bad</b>). +<li>configure the client so that it checks the server identity and sends messages only +if the server identity is known. +</ul> +<p>These were essentially the same steps as for any +<a href="tls_cert_client.html">TLS syslog client</a>. We now need to add the +capability to forward the router logs: +<ul> +<li>make sure that the firewall rules permit message recpetion on UDP port 514 (if you use +a non-standard port for UDP syslog, make sure that port number is permitted). +<li>you may want to limit who can send syslog messages via UDP. A great place to do this +is inside the firewall, but you can also do it in rsyslog.conf via an $AllowedSender +directive. We have used one in the sample config below. Please be aware that this is +a kind of weak authentication, but definitely better than nothing... +<li>add the UDP input plugin to rsyslog's config and start a UDP listener +<li>make sure that your forwarding-filter permits to forward messages received +from the remote router to the server. In our sample scenario, we do not need to +add anything special, because all messages are forwarded. This includes messages +received from remote hosts. +</ul> +<p><b>At this point, please be reminded once again that your security needs may be quite different from +what we assume in this tutorial. Evaluate your options based on your security needs.</b> +<h3>Sample syslog.conf</h3> +<p>Keep in mind that this rsyslog.conf sends messages via TCP, only. Also, we do not +show any rules to write local files. Feel free to add them. +<code><pre> +# start a UDP listener for the remote router +$ModLoad imudp # load UDP server plugin +$AllowedSender UDP, 192.0.2.1 # permit only the router +$UDPServerRun 514 # listen on default syslog UDP port 514 + +# make gtls driver the default +$DefaultNetstreamDriver gtls + +# certificate files +$DefaultNetstreamDriverCAFile /rsyslog/protected/ca.pem +$DefaultNetstreamDriverCertFile /rsyslog/protected/machine-cert.pem +$DefaultNetstreamDriverKeyFile /rsyslog/protected/machine-key.pem + +$ActionSendStreamDriverAuthMode x509/name +$ActionSendStreamDriverPermittedPeer central.example.net +$ActionSendStreamDriverMode 1 # run driver in TLS-only mode +*.* @@central.example.net:10514 # forward everything to remote server +</pre></code> +<p><font color="red"><b>Be sure to safeguard at least the private key (machine-key.pem)!</b> +If some third party obtains it, you security is broken!</font> +<h2>Copyright</h2> +<p>Copyright © 2008 <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> |