From abc7034f0d3833da588bd636ed71542f94d3995e Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 18 Jun 2008 14:40:08 +0200 Subject: begun step-by-step guide for TLS protected syslog --- doc/Makefile.am | 2 ++ doc/manual.html | 1 + doc/ns_gtls.html | 2 +- doc/rsyslog_secure_tls.html | 86 +++++++++++++++++++------------------------- doc/rsyslog_tls.html | 26 ++++++++++++-- doc/src/tls_cert.dia | Bin 0 -> 2531 bytes doc/src/tls_cert_100.dia | Bin 0 -> 1885 bytes doc/src/tls_cert_ca.dia | Bin 0 -> 1230 bytes doc/tls_cert.jpg | Bin 0 -> 68335 bytes doc/tls_cert_100.jpg | Bin 0 -> 16607 bytes doc/tls_cert_ca.html | 80 +++++++++++++++++++++++++++++++++++++++++ doc/tls_cert_ca.jpg | Bin 0 -> 9635 bytes doc/tls_cert_scenario.html | 63 ++++++++++++++++++++++++++++++++ runtime/nsd_gtls.c | 2 +- runtime/obj.c | 2 +- 15 files changed, 209 insertions(+), 55 deletions(-) create mode 100644 doc/src/tls_cert.dia create mode 100644 doc/src/tls_cert_100.dia create mode 100644 doc/src/tls_cert_ca.dia create mode 100644 doc/tls_cert.jpg create mode 100644 doc/tls_cert_100.jpg create mode 100644 doc/tls_cert_ca.html create mode 100644 doc/tls_cert_ca.jpg create mode 100644 doc/tls_cert_scenario.html 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

rsyslog and IPv6 (which is fully supported)

native TLS encryption for syslog

ssl-encrypting syslog with stunnel

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

x509/name - certificate validation and subject name authentication as described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft -[NOT YET IMPLEMENTED]

+ 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 @@ TLS-protected syslog: recommended scenario +

Encrypting Syslog Traffic with TLS (SSL)

Written by Rainer -Gerhards (2008-06-06)

Introduction

+Gerhards (2008-06-17)

+ +

Overview

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 ;)

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. + + + + 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).

Sample Szenario

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.

Setting up the CA

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).

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.

In our example, we will use the name "example.net" for our network. You may -use any domain name of your liking. -

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):

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 radom 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.
-

A very quick Intro

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, simply read on +for full instructions. +

+ TLS/SSL protected syslog

Feedback requested

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 let me know.

Revision History

2008-06-06 * Rainer -Gerhards * Initial Version created
2008-06-06 * Rainer Gerhards * Initial Version created
2008-06-18 * Rainer Gerhards * Greatly enhanced and modularized the doc

Copyright

Copyright (c) 2008 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:

# 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
$InputTCPServerRun 10514 # start up listener at port 10514

# 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
+

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.

The client setup is equally simple. You need less certificates, just the CA cert.

# 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
*.* @@(o)server.example.net:10514 # send (all) messages

# 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
+
+

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 Binary files /dev/null and b/doc/src/tls_cert.dia differ diff --git a/doc/src/tls_cert_100.dia b/doc/src/tls_cert_100.dia new file mode 100644 index 00000000..baed5e0f Binary files /dev/null and b/doc/src/tls_cert_100.dia differ diff --git a/doc/src/tls_cert_ca.dia b/doc/src/tls_cert_ca.dia new file mode 100644 index 00000000..7ce27a8d Binary files /dev/null and b/doc/src/tls_cert_ca.dia differ diff --git a/doc/tls_cert.jpg b/doc/tls_cert.jpg new file mode 100644 index 00000000..920e998d Binary files /dev/null and b/doc/tls_cert.jpg differ diff --git a/doc/tls_cert_100.jpg b/doc/tls_cert_100.jpg new file mode 100644 index 00000000..beeedc58 Binary files /dev/null and b/doc/tls_cert_100.jpg differ 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 @@ + +TLS-protected syslog: scenario + + + +

Encrypting Syslog Traffic with TLS (SSL)

Written by Rainer +Gerhards (2008-06-17)

+ +

Setting up the CA

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 + + + + +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).

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.

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):

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 radom 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.
+

Copyright

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 +http://www.gnu.org/copyleft/fdl.html.

+ diff --git a/doc/tls_cert_ca.jpg b/doc/tls_cert_ca.jpg new file mode 100644 index 00000000..f2da0454 Binary files /dev/null and b/doc/tls_cert_ca.jpg differ 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 @@ + +TLS-protected syslog: scenario + + + +

Encrypting Syslog Traffic with TLS (SSL)

Written by Rainer +Gerhards (2008-06-17)

+ +

Sample Scenario

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. All systems (except the router) use +rsyslog as the syslog software.

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. +

In case the CA is compromised, you need to regenerate the CA's certificate as well +as all individual machines certificates. +

Copyright

+ diff --git a/runtime/nsd_gtls.c b/runtime/nsd_gtls.c index 567701dc..f55361cc 100644 --- a/runtime/nsd_gtls.c +++ b/runtime/nsd_gtls.c @@ -485,7 +485,7 @@ finalize_it: pGnuErr = gtlsStrerror(gnuRet); errno = 0; errmsg.LogError(NO_ERRCODE, "error adding our certificate. GnuTLS error %d, message: '%s', " - "key: '%s', cert: '%s'\n", gnuRet, pGnuErr, certFile, keyFile); + "key: '%s', cert: '%s'\n", gnuRet, pGnuErr, keyFile, certFile); free(pGnuErr); } RETiRet; diff --git a/runtime/obj.c b/runtime/obj.c index 312ed223..af59a955 100644 --- a/runtime/obj.c +++ b/runtime/obj.c @@ -1192,7 +1192,7 @@ ReleaseObj(char *srcFile, uchar *pObjName, uchar *pObjFile, interface_t *pIf) objInfo_t *pObjInfo; - dbgprintf("source file %s releasing object '%s', ifIsLoaded %d\n", srcFile, pObjName, pIf->ifIsLoaded); + /* dev debug only dbgprintf("source file %s releasing object '%s', ifIsLoaded %d\n", srcFile, pObjName, pIf->ifIsLoaded); */ if(pObjFile == NULL) FINALIZE; /* if it is not a lodable module, we do not need to do anything... */ -- cgit v1.2.3