begun step-by-step guide for TLS protected syslog

author: Rainer Gerhards <rgerhards@adiscon.com> 2008-06-18 14:40:08 +0200
committer: Rainer Gerhards <rgerhards@adiscon.com> 2008-06-18 14:40:08 +0200
commit: abc7034f0d3833da588bd636ed71542f94d3995e (patch)
tree: ab224ebfb48d7d04529a952b8038ba6e8fc8988d /doc
parent: dc88ff72346ae3104caaa98bc94aaf4ef9882605 (diff)
download: rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.tar.gz
rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.tar.xz
rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.zip
13 files changed, 207 insertions, 53 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index da2e2328..4ddb1179 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -40,6 +40,7 @@ html_files = \
 	src/queueWorkerLogic.dia \
 	queueWorkerLogic.jpg \
 	queueWorkerLogic_small.jpg \
+	tls_cert.jpg \
 	rainerscript.html \
 	rscript_abnf.html \
 	rsconf1_actionexeconlywhenpreviousissuspended.html \
@@ -72,6 +73,7 @@ html_files = \
 	rsconf1_resetconfigvariables.html \
 	rsconf1_umask.html \
 	v3compatibility.html \
+	src/tls_cert.dia \
 	src/classes.dia
 
 EXTRA_DIST = $(html_files)
diff --git a/doc/manual.html b/doc/manual.html
index 779025c1..1c0ffa7d 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -52,6 +52,7 @@ modules</a></li><li><a href="man_rsyslogd.html">rsyslogd man page</a>
 <li><a href="install.html">installing rsyslog</a></li>
 <li><a href="ipv6.html">rsyslog and IPv6</a>
 (which is fully supported)</li>
+<li><a href="rsyslog_tls.html">native TLS encryption for syslog</a></li>
 <li><a href="rsyslog_stunnel.html">ssl-encrypting
 syslog with stunnel</a></li>
 <li><a href="rsyslog_mysql.html">writing syslog
diff --git a/doc/ns_gtls.html b/doc/ns_gtls.html
index 46671f4a..fea3dc33 100644
--- a/doc/ns_gtls.html
+++ b/doc/ns_gtls.html
@@ -29,7 +29,7 @@ described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft</li>
 <li><span style="font-weight: bold;">x509/name</span>
 - certificate validation and subject name authentication as
 described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft
-[NOT YET IMPLEMENTED]</li>
+</li>
 </ul>
 Note: "anon" does not permit to authenticate the remote peer. As such,
 this mode is vulnerable to man in the middle attacks as well as
diff --git a/doc/rsyslog_secure_tls.html b/doc/rsyslog_secure_tls.html
index 29f17585..16f6835a 100644
--- a/doc/rsyslog_secure_tls.html
+++ b/doc/rsyslog_secure_tls.html
@@ -2,10 +2,22 @@
 <html><head><title>TLS-protected syslog: recommended scenario</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-06-06)</i></small></p>
-<h2>Introduction</h2>
+Gerhards</a> (2008-06-17)</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>
+
+<h2>Overview</h2>
 <p>This document describes a secure way to set up rsyslog TLS. A secure logging
 environment requires more than just encrypting the transmission channel. This document
 provides one possible way to create such a secure system.
@@ -25,6 +37,19 @@ below. Do not blame us if it doesn't provide what you need ;)</p>
 </ul>
 <p>Our secrity goals are achived via public/private key security. As such, it is 
 vital that private keys are well protected and not accessible to third parties. 
+<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>
 I private keys have become known to third parties, the system does not provide 
 any security at all. Also, our solution bases on X.509 certificates and a (very 
 limited) chain of trust. We have one instance (the CA) that issues all machine 
@@ -71,52 +96,13 @@ does not protect against this (but it may help, properly used). Keep in mind
 that syslog-transport-tls provides hop-by-hop security. It does not provide 
 end-to-end security and it does not authenticate the message itself (just the 
 last sender).</p>
-<h3>Sample Szenario</h3>
-<p>&nbsp;We have a quite simple scenario. There is one central syslog server, 
-named central.example.net. These server is being reported to by two Linux 
-machines with name zuse.example.net and turing.example.net. Also, there is a 
-third client - ada.example.net - which send both its own messages to the central 
-server but also forwards messages receive from an UDP-only capable router. We 
-hav decided to use ada.example.net because it is in the same local network 
-segment as the router and so we enjoy TLS' security benefits for forwarding the 
-router messages inside the corporate network.</p>
-<h3>Setting up the CA</h3>
-<p>The first step is to set up a certificate authoroty (CA). It must be 
-maintained by a trustworthy person (or group) and approves the indentities of 
-all machines. It does so by issuing there certificates. In a small setup, the 
-administrator can provide the CA function. What is important is the the CA's 
-private key is well-protocted and machine certificates are only issued if it is 
-know they are valid (in a single-admin case that means the admin should not 
-issue certificates to anyone else except himself).</p>
-<p>The CA creates a so-called self-signed certificate. That is, it approves its 
-own authenticy. This sounds useless, but the key point to understand is that 
-every machine will be provided a copy of the CA's certificate. Accepting this 
-certificate is a matter of trust. So by configuring the CA certificate, the 
-administrator tells rsyslog which certificates to trust. This is the root of all 
-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>
-<p>In our example, we will use the name "example.net" for our network. You may
-use any domain name of your liking.
-<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>
-<ol>
-<li>generate the private key:
-<pre>certtool --generate-privkey --outfile ca-key.pem</pre>
-<br>
-This takes a short while. Be sure to do some work on your workstation,
-it waits for radom input. Switching between windows is sufficient ;)
-</li>
-<li>now create the (self-signed) CA certificate itself:<br>
-<pre>certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem</pre>
-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.<br>
-</li>
-</ol>
+<h3>A very quick Intro</h3>
+<p>If you'd like to get all information very rapidly, the graphic below contains
+everything you need to know (from the certificate perspective) in a very condensed
+manner. It is no surprise if the graphic puzzles you. In this case, <a href="tls_cert_scenario.html">simply read on</a>
+for full instructions.
+<p>
+<img align="center" alt="TLS/SSL protected syslog" src="tls_cert.jpg">
 <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... ;)),
@@ -124,8 +110,8 @@ please
 <a href="mailto:rgerhards@adiscon.com">let me know</a>.</p>
 <h2>Revision History</h2>
 <ul>
-<li>2008-06-06 * <a href="http://www.gerhards.net/rainer">Rainer
-Gerhards</a> * Initial Version created</li>
+<li>2008-06-06 * <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> * Initial Version created</li>
+<li>2008-06-18 * <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> * Greatly enhanced and modularized the doc</li>
 </ul>
 <h2>Copyright</h2>
 <p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
diff --git a/doc/rsyslog_tls.html b/doc/rsyslog_tls.html
index 8cac558d..7d156c3a 100644
--- a/doc/rsyslog_tls.html
+++ b/doc/rsyslog_tls.html
@@ -108,7 +108,20 @@ certificate files, to use the gtls driver and start up a listener. This
 is done as follows:<br>
 </p>
 <blockquote><code></code>
-<pre># make gtls driver the default<br>$DefaultNetstreamDriver gtls<br><br># certificate files<br>$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem<br>$DefaultNetstreamDriverCertFile /path/to/contrib/gnutls/cert.pem<br>$DefaultNetstreamDriverKeyFile /path/to/contrib/gnutls/key.pem<br><br>$ModLoad /home/rger/proj/rsyslog/plugins/imtcp/.libs/imtcp # load listener<br><br>$InputTCPServerStreamDriverMode 1 # run driver in TLS-only mode<br>$InputTCPServerRun 10514 # start up listener at port 10514<br></pre>
+<pre># make gtls driver the default
+$DefaultNetstreamDriver gtls
+
+# certificate files
+$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem
+$DefaultNetstreamDriverCertFile /path/to/contrib/gnutls/cert.pem
+$DefaultNetstreamDriverKeyFile /path/to/contrib/gnutls/key.pem
+
+$ModLoad /home/rger/proj/rsyslog/plugins/imtcp/.libs/imtcp # load listener
+
+$InputTCPServerStreamDriverMode 1 # run driver in TLS-only mode
+$InputTCPServerStreamDriverAuthMode anon # client is NOT authenticated
+$InputTCPServerRun 10514 # start up listener at port 10514
+</pre>
 </blockquote>
 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
@@ -120,7 +133,16 @@ operational.</p>
 <p>The client setup is equally&nbsp;simple. You need less
 certificates, just the CA cert.&nbsp;</p>
 <blockquote>
-<pre># certificate files - just CA for a client<br>$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem<br><br># set up the action<br>$DefaultNetstreamDriver gtls # use gtls netstream driver<br>$ActionSendStreamDriverMode 1 # require TLS for the connection<br>*.* @@(o)server.example.net:10514 # send (all) messages<br><br></pre>
+<pre># certificate files - just CA for a client
+$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem
+
+# set up the action
+$DefaultNetstreamDriver gtls # use gtls netstream driver
+$ActionSendStreamDriverMode 1 # require TLS for the connection
+$ActionSendStreamDriverAuthMode anon # server is NOT authenticated
+*.* @@(o)server.example.net:10514 # send (all) messages
+
+</pre>
 </blockquote>
 <p>Note that we use the regular TCP forwarding syntax (@@) here.
 There is nothing special, because the encryption is handled by the
diff --git a/doc/src/tls_cert.dia b/doc/src/tls_cert.dia
new file mode 100644
index 00000000..e76431df
--- /dev/null
+++ b/doc/src/tls_cert.dia
diff --git a/doc/src/tls_cert_100.dia b/doc/src/tls_cert_100.dia
new file mode 100644
index 00000000..baed5e0f
--- /dev/null
+++ b/doc/src/tls_cert_100.dia
diff --git a/doc/src/tls_cert_ca.dia b/doc/src/tls_cert_ca.dia
new file mode 100644
index 00000000..7ce27a8d
--- /dev/null
+++ b/doc/src/tls_cert_ca.dia
diff --git a/doc/tls_cert.jpg b/doc/tls_cert.jpg
new file mode 100644
index 00000000..920e998d
--- /dev/null
+++ b/doc/tls_cert.jpg
diff --git a/doc/tls_cert_100.jpg b/doc/tls_cert_100.jpg
new file mode 100644
index 00000000..beeedc58
--- /dev/null
+++ b/doc/tls_cert_100.jpg
diff --git a/doc/tls_cert_ca.html b/doc/tls_cert_ca.html
new file mode 100644
index 00000000..3690e93b
--- /dev/null
+++ b/doc/tls_cert_ca.html
@@ -0,0 +1,80 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>TLS-protected syslog: scenario</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-06-17)</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 CA</h3>
+<p>The first step is to set up a certificate authority (CA). It must be 
+maintained by a trustworthy person (or group) and approves the indentities of 
+all machines. It does so by issuing their certificates. In a small setup, the 
+administrator can provide the CA function. What is important is the the CA's 
+<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>
+private key is well-protocted and machine certificates are only issued if it is 
+know they are valid (in a single-admin case that means the admin should not 
+issue certificates to anyone else except himself).</p>
+<p>The CA creates a so-called self-signed certificate. That is, it approves its 
+own authenticy. This sounds useless, but the key point to understand is that 
+every machine will be provided a copy of the CA's certificate. Accepting this 
+certificate is a matter of trust. So by configuring the CA certificate, the 
+administrator tells <a href="http://www.rsyslog.com">rsyslog</a> which certificates to trust. This is the root of all 
+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 align="right" 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>
+<ol>
+<li>generate the private key:
+<pre>certtool --generate-privkey --outfile ca-key.pem</pre>
+<br>
+This takes a short while. Be sure to do some work on your workstation,
+it waits for radom input. Switching between windows is sufficient ;)
+</li>
+<li>now create the (self-signed) CA certificate itself:<br>
+<pre>certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem</pre>
+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.<br>
+</li>
+</ol>
+<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_ca.jpg b/doc/tls_cert_ca.jpg
new file mode 100644
index 00000000..f2da0454
--- /dev/null
+++ b/doc/tls_cert_ca.jpg
diff --git a/doc/tls_cert_scenario.html b/doc/tls_cert_scenario.html
new file mode 100644
index 00000000..82527d66
--- /dev/null
+++ b/doc/tls_cert_scenario.html
@@ -0,0 +1,63 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>TLS-protected syslog: scenario</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-06-17)</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>Sample Scenario</h3>
+<p>We have a quite simple scenario. There is one central syslog server, 
+<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>
+named central.example.net. These server is being reported to by two Linux 
+machines with name zuse.example.net and turing.example.net. Also, there is a 
+third client - ada.example.net - which send both its own messages to the central 
+server but also forwards messages receive from an UDP-only capable router. We 
+hav decided to use ada.example.net because it is in the same local network 
+segment as the router and so we enjoy TLS' security benefits for forwarding the 
+router messages inside the corporate network. All systems (except the router) use
+<a href="http://www.rsyslog.com/">rsyslog</a> as the syslog software.</p>
+<p>
+<center><img src="tls_cert_100.jpg"></center>
+<p>Please note that the CA must not necessarily be connected to the rest of the
+network. Actually, it may be considered a security plus if it is not. If the CA
+is reachable via the regular network, it should be sufficiently secured (firewal
+rules et al). Keep in mind that if the CA's security is breached, your overall
+system security is breached.
+<p>In case the CA is compromised, you need to regenerate the CA's certificate as well
+as all individual machines certificates.
+<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>
author	Rainer Gerhards <rgerhards@adiscon.com>	2008-06-18 14:40:08 +0200
committer	Rainer Gerhards <rgerhards@adiscon.com>	2008-06-18 14:40:08 +0200
commit	abc7034f0d3833da588bd636ed71542f94d3995e (patch)
tree	ab224ebfb48d7d04529a952b8038ba6e8fc8988d /doc
parent	dc88ff72346ae3104caaa98bc94aaf4ef9882605 (diff)
download	rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.tar.gz rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.tar.xz rsyslog-abc7034f0d3833da588bd636ed71542f94d3995e.zip