added doc on how to generate certficates

with gnutls for both the CA and individual machines

5 files changed, 349 insertions, 1 deletions

diff --git a/doc/rsyslog_secure_tls.html b/doc/rsyslog_secure_tls.html
index 16f6835a..be2811f4 100644
--- a/doc/rsyslog_secure_tls.html
+++ b/doc/rsyslog_secure_tls.html
@@ -15,6 +15,7 @@ Gerhards</a> (2008-06-17)</i></small></p>
 <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>
+<li><a href="tls_cert_errmsgs.html">Frequently seen Error Messages</a>
 </ul>
 
 <h2>Overview</h2>
diff --git a/doc/tls_cert_ca.html b/doc/tls_cert_ca.html
index 3690e93b..efe34c85 100644
--- a/doc/tls_cert_ca.html
+++ b/doc/tls_cert_ca.html
@@ -46,7 +46,7 @@ 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>
+<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>
 <ol>
@@ -67,6 +67,87 @@ the certificates belongs to an authority. The certificate is used to
 sign other certificates.<br>
 </li>
 </ol>
+<h3>Sample Screen Session</h3>
+<code><pre>
+[root@rgf9dev sample]# certtool --generate-privkey --outfile ca-key.pem
+Generating a 1024 bit RSA private key...
+[root@rgf9dev sample]# certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem
+[root@rgf9dev sample]# certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem
+Generating a self signed certificate...
+Please enter the details of the certificate's distinguished name. Just press enter to ignore a field.
+Country name (2 chars): US
+Organization name: SomeOrg
+Organizational unit name: SomeOU
+Locality name: Somewhere
+State or province name: CA
+Common name: someName (not necessarily DNS!)
+UID: 
+This field should not be used in new certificates.
+E-mail: 
+Enter the certificate's serial number (decimal): 
+
+
+Activation/Expiration time.
+The certificate will expire in (days): 3650
+
+
+Extensions.
+Does the certificate belong to an authority? (Y/N): y
+Path length constraint (decimal, -1 for no constraint): 
+Is this a TLS web client certificate? (Y/N): 
+Is this also a TLS web server certificate? (Y/N): 
+Enter the e-mail of the subject of the certificate: someone@example.net
+Will the certificate be used to sign other certificates? (Y/N): y
+Will the certificate be used to sign CRLs? (Y/N): 
+Will the certificate be used to sign code? (Y/N): 
+Will the certificate be used to sign OCSP requests? (Y/N): 
+Will the certificate be used for time stamping? (Y/N): 
+Enter the URI of the CRL distribution point:        
+X.509 Certificate Information:
+	Version: 3
+	Serial Number (hex): 485a365e
+	Validity:
+		Not Before: Thu Jun 19 10:35:12 UTC 2008
+		Not After: Sun Jun 17 10:35:25 UTC 2018
+	Subject: C=US,O=SomeOrg,OU=SomeOU,L=Somewhere,ST=CA,CN=someName (not necessarily DNS!)
+	Subject Public Key Algorithm: RSA
+		Modulus (bits 1024):
+			d9:9c:82:46:24:7f:34:8f:60:cf:05:77:71:82:61:66
+			05:13:28:06:7a:70:41:bf:32:85:12:5c:25:a7:1a:5a
+			28:11:02:1a:78:c1:da:34:ee:b4:7e:12:9b:81:24:70
+			ff:e4:89:88:ca:05:30:0a:3f:d7:58:0b:38:24:a9:b7
+			2e:a2:b6:8a:1d:60:53:2f:ec:e9:38:36:3b:9b:77:93
+			5d:64:76:31:07:30:a5:31:0c:e2:ec:e3:8d:5d:13:01
+			11:3d:0b:5e:3c:4a:32:d8:f3:b3:56:22:32:cb:de:7d
+			64:9a:2b:91:d9:f0:0b:82:c1:29:d4:15:2c:41:0b:97
+		Exponent:
+			01:00:01
+	Extensions:
+		Basic Constraints (critical):
+			Certificate Authority (CA): TRUE
+		Subject Alternative Name (not critical):
+			RFC822name: someone@example.net
+		Key Usage (critical):
+			Certificate signing.
+		Subject Key Identifier (not critical):
+			fbfe968d10a73ae5b70d7b434886c8f872997b89
+Other Information:
+	Public Key Id:
+		fbfe968d10a73ae5b70d7b434886c8f872997b89
+
+Is the above information ok? (Y/N): y
+
+
+Signing certificate...
+[root@rgf9dev sample]# chmod 400 ca-key.pem
+[root@rgf9dev sample]# ls -l
+total 8
+-r-------- 1 root root  887 2008-06-19 12:33 ca-key.pem
+-rw-r--r-- 1 root root 1029 2008-06-19 12:36 ca.pem
+[root@rgf9dev sample]# 
+</pre></code>
+<p><font color="red"><b>Be sure to safeguard ca-key.pem!</b> Nobody except the CA itself
+needs to have it. If some third party obtains it, you security is broken!</font>
 <h2>Copyright</h2>
 <p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
 Gerhards</a> and
diff --git a/doc/tls_cert_errmsgs.html b/doc/tls_cert_errmsgs.html
new file mode 100644
index 00000000..d002174c
--- /dev/null
+++ b/doc/tls_cert_errmsgs.html
@@ -0,0 +1,103 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>TLS-protected syslog: error messages</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>
+<li><a href="tls_cert_errmsgs.html">Frequently seen Error Messages</a>
+</ul>
+
+<h3>Error Messages</h3>
+<p>This page covers error message you may see when setting up
+<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 href="http://www.rsyslog.com">rsyslog</a> with TLS. Please note that many
+of the message stem back to the TLS library being used. In those cases, there is
+not always a good explanation available in rsyslog alone.
+<p>A single error typically results in two or more message being emitted: (at
+least) one is the actual error cause, followed by usually one message with additional
+information (like certificate contents). In a typical system, these message should
+immediately follow each other in your log. Kepp in mind that they are reported
+as syslog.err, so you need to capture these to actually see errors (the default
+rsyslog.conf's shipped by many systems will do that, recording them e.g. in
+/etc/messages).
+<h3>certificate invalid</h3>
+<p>Sample:
+<code>
+not permitted to talk to peer, certificate invalid: <font color="red">insecure algorithm</font>
+</code>
+<p>This message may occur during connection setup. It indicates that the remote peer's
+certificate can not be accepted. The reason for this is given in the message part that
+is shown in red. Please note that this red part directly stems back to the TLS library,
+so rsyslog does acutally not have any more information about the reason. 
+<p>With GnuTLS, the following reasons have been seen in practice:
+<h4>insecure algorith</h4>
+<p>The certificate contains information on which encryption algorithms are to be used.
+This information is entered when the certificate is created.
+Some older alogrithms are no longer secure and the TLS library does not accept
+them. Thus the connection request failed. The cure is to use a certificate with sufficiently secure
+alogorithms.
+<p>Please note that noi encryption algorithm is totally secure. It only is secure based
+on our current knowledge AND on computing power available. As computers get more and more
+powerful, previously secure algorithms become insecure over time. As such, algorithms
+considered secure today may not be accepted by the TLS library in the future.
+<p>So in theory, after a system upgrade, a connection request may fail with the "insecure
+algorithm" failure without any change in rsyslog configuration or certificates. This could be
+caused by a new perception of the TLS library of what is secure and what not.
+<h3>GnuTLS error -64</h3>
+<p>Sample: <code>unexpected GnuTLS error -64 in nsd_gtls.c:517: Error while reading file.</code>
+<p>This error points to an encoding error witht the pem file in question. It means "base 64 encoding error".
+From my experience, it can be caused by a couple of things, some of them not obvious:
+<ul>
+<li>You specified a wrong file, which is not actually in .pem format
+<li>The file was incorrectly generated
+<li>I think I have also seen this when I accidently swapped private key files and
+certificate files. So double-check the type of file you are using.
+<li>It may even be a result of an access (permission) problem. In theory, that
+should lead to another error, but in practice it sometimes seems to lead to
+this -64 error.
+</ul>
+<h3>info on invalid cert</h3>
+<p>Sample:
+<code>
+info on invalid cert: peer provided 1 certificate(s). Certificate 1 info: certificate valid from Wed Jun 18 11:45:44 2008 to Sat Jun 16 11:45:53 2018; Certificate public key: RSA; DN: C=US,O=Sample Corp,OU=Certs,L=Somehwere,ST=CA,CN=somename; Issuer DN: C=US,O=Sample Corp,OU=Certs,L=Somewhere,ST=CA,CN=somename,EMAIL=xxx@example.com; SAN:DNSname: machine.example.net;
+</code>
+<p>This is <b>not</b> an error message in itself. It always follows the actual error message and
+tells you what is seen in the peer's certificate. This is done to give you a chance to evaluate
+the certificate and better understand why the initial error message was issued.
+<p>Please note that you can NOT diagnose problems based on this message alone. It follows
+in a number of error cases and does not pinpoint any problems by itself.
+<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_machine.html b/doc/tls_cert_machine.html
new file mode 100644
index 00000000..f7868caa
--- /dev/null
+++ b/doc/tls_cert_machine.html
@@ -0,0 +1,162 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>TLS-protected syslog: generating the machine certificate</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-18)</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>generating the machine certificate</h3>
+<p>In this step, we generate certificates for each of the machines. Please note
+that both clients and servers need certificates. The certificate identifies each
+machine to the remote peer. The DNSName specified inside the certificate can
+<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>
+be specified inside the $&lt;object&gt;PermittedPeer config statements.
+<p>For now, we assume that 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
+and public key on the CA (which is NOT a server!) and then copy them over to the
+respective machines.
+<p>If the roles of machine and CA administrators are split, the private key must
+be generated by the machine administrator. This is done via a certificate request.
+This request is then sent to the CA admin, which in turn generates the certificate
+(containing the public key). The CA admin then sends back the certificate to the
+machine admin, who installs it. That way, the CA admin never get's hold of the
+machine's private key. Instructions for this mode will be given in a later revision
+of this document.
+<p><b>In any case, it is vital that the machine's private key is protected. Anybody
+able to obtain that private key can imporsonate as the machine to which it belongs, thus
+breaching your security.</b>
+<h3>Sample Screen Session</h3>
+<code><pre>
+[root@rgf9dev sample]# <b>certtool --generate-privkey --outfile key.pem</b>
+Generating a 1024 bit RSA private key...
+[root@rgf9dev sample]# <b>certtool --generate-request --load-privkey key.pem --outfile request.pem</b>
+Generating a PKCS #10 certificate request...
+Country name (2 chars): US
+Organization name: SomeOrg
+Organizational unit name: SomeOU
+Locality name: Somewhere
+State or province name: CA
+Common name: machine.example.net
+UID: 
+Enter a challenge password: 
+[root@rgf9dev sample]# <b>certtool --generate-certificate --load-request request.pem --outfile cert.pem --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem</b>
+Generating a signed certificate...
+Enter the certificate's serial number (decimal): 
+
+
+Activation/Expiration time.
+The certificate will expire in (days): 1000
+
+
+Extensions.
+Does the certificate belong to an authority? (Y/N): n
+Is this a TLS web client certificate? (Y/N): y
+Is this also a TLS web server certificate? (Y/N): y
+Enter the dnsName of the subject of the certificate: machine.example.net
+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:
+	Version: 3
+	Serial Number (hex): 485a3819
+	Validity:
+		Not Before: Thu Jun 19 10:42:54 UTC 2008
+		Not After: Wed Mar 16 10:42:57 UTC 2011
+	Subject: C=US,O=SomeOrg,OU=SomeOU,L=Somewhere,ST=CA,CN=machine.example.net
+	Subject Public Key Algorithm: RSA
+		Modulus (bits 1024):
+			b2:4e:5b:a9:48:1e:ff:2e:73:a1:33:ee:d8:a2:af:ae
+			2f:23:76:91:b8:39:94:00:23:f2:6f:25:ad:c9:6a:ab
+			2d:e6:f3:62:d8:3e:6e:8a:d6:1e:3f:72:e5:d8:b9:e0
+			d0:79:c2:94:21:65:0b:10:53:66:b0:36:a6:a7:cd:46
+			1e:2c:6a:9b:79:c6:ee:c6:e2:ed:b0:a9:59:e2:49:da
+			c7:e3:f0:1c:e0:53:98:87:0d:d5:28:db:a4:82:36:ed
+			3a:1e:d1:5c:07:13:95:5d:b3:28:05:17:2a:2b:b6:8e
+			8e:78:d2:cf:ac:87:13:15:fc:17:43:6b:15:c3:7d:b9
+		Exponent:
+			01:00:01
+	Extensions:
+		Basic Constraints (critical):
+			Certificate Authority (CA): FALSE
+		Key Purpose (not critical):
+			TLS WWW Client.
+			TLS WWW Server.
+		Subject Alternative Name (not critical):
+			DNSname: machine.example.net
+		Subject Key Identifier (not critical):
+			0ce1c3dbd19d31fa035b07afe2e0ef22d90b28ac
+		Authority Key Identifier (not critical):
+			fbfe968d10a73ae5b70d7b434886c8f872997b89
+Other Information:
+	Public Key Id:
+		0ce1c3dbd19d31fa035b07afe2e0ef22d90b28ac
+
+Is the above information ok? (Y/N): y
+
+
+Signing certificate...
+[root@rgf9dev sample]# <b>rm -f request.pem</b>
+[root@rgf9dev sample]# <b>ls -l</b>
+total 16
+-r-------- 1 root root  887 2008-06-19 12:33 ca-key.pem
+-rw-r--r-- 1 root root 1029 2008-06-19 12:36 ca.pem
+-rw-r--r-- 1 root root 1074 2008-06-19 12:43 cert.pem
+-rw-r--r-- 1 root root  887 2008-06-19 12:40 key.pem
+[root@rgf9dev sample]# # it may be a good idea to rename the files to indicate where they belong to
+[root@rgf9dev sample]# <b>mv cert.pem machine-cert.pem</b>
+[root@rgf9dev sample]# <b>mv key.pem machine-key.pem</b>
+[root@rgf9dev sample]# 
+</pre></code>
+<h3>Distributing Files</h3>
+<p>Provide the machine with:
+<ul>
+<li>a copy of ca.pem
+<li>cert.pem
+<li>key.pem
+</ul>
+<p>This is how the relevant part of rsyslog.conf looks on the target machine:
+<p>
+<code><pre>
+$DefaultNetstreamDriverCAFile /home/rger/proj/rsyslog/sample/ca.pem
+$DefaultNetstreamDriverCertFile /home/rger/proj/rsyslog/sample/machine-cert.pem
+$DefaultNetstreamDriverKeyFile /home/rger/proj/rsyslog/sample/machine-key.pem
+</pre></code>
+<p><b><font color="red">Never</font> provide anyone with ca-key.pem!</b> Also, make sure
+nobody but the machine in question gets hold of key.pem.
+<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_scenario.html b/doc/tls_cert_scenario.html
index 82527d66..dced5393 100644
--- a/doc/tls_cert_scenario.html
+++ b/doc/tls_cert_scenario.html
@@ -16,6 +16,7 @@ Gerhards</a> (2008-06-17)</i></small></p>
 <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>
+<li><a href="tls_cert_errmsgs.html">Frequently seen Error Messages</a>
 </ul>
 
 <h3>Sample Scenario</h3>