From 8bd173f72327aa905ed1ab979b612edd5509c209 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 19 Jun 2008 13:04:46 +0200 Subject: added doc on how to generate certficates with gnutls for both the CA and individual machines --- doc/rsyslog_secure_tls.html | 1 + doc/tls_cert_ca.html | 83 ++++++++++++++++++++++- doc/tls_cert_errmsgs.html | 103 ++++++++++++++++++++++++++++ doc/tls_cert_machine.html | 162 ++++++++++++++++++++++++++++++++++++++++++++ doc/tls_cert_scenario.html | 1 + 5 files changed, 349 insertions(+), 1 deletion(-) create mode 100644 doc/tls_cert_errmsgs.html create mode 100644 doc/tls_cert_machine.html 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 (2008-06-17)

Frequently seen Error Messages

Overview

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

Sample Screen Session

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

Be sure to safeguard ca-key.pem! Nobody except the CA itself +needs to have it. If some third party obtains it, you security is broken!

Copyright

Copyright (c) 2008 Rainer Gerhards 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 @@ + +TLS-protected syslog: error messages + + + +

Encrypting Syslog Traffic with TLS (SSL)

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

+ +

Error Messages

This page covers error message you may see when setting up + + + + +rsyslog 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. +

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

certificate invalid

Sample: ++not permitted to talk to peer, certificate invalid: insecure algorithm + +

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

With GnuTLS, the following reasons have been seen in practice: +

insecure algorith

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

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

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

GnuTLS error -64

Sample: unexpected GnuTLS error -64 in nsd_gtls.c:517: Error while reading file. +

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

You specified a wrong file, which is not actually in .pem format +
The file was incorrectly generated +
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. +
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. +

info on invalid cert

Sample: ++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; + +

This is not 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. +

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

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_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 @@ + +TLS-protected syslog: generating the machine certificate + + + +

Encrypting Syslog Traffic with TLS (SSL)

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

+ +

generating the machine certificate

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 + + + + +be specified inside the $<object>PermittedPeer config statements. +

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

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

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

Sample Screen Session

+[root@rgf9dev sample]# certtool --generate-privkey --outfile key.pem
+Generating a 1024 bit RSA private key...
+[root@rgf9dev sample]# certtool --generate-request --load-privkey key.pem --outfile request.pem
+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]# certtool --generate-certificate --load-request request.pem --outfile cert.pem --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem
+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]# rm -f request.pem
+[root@rgf9dev sample]# ls -l
+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]# mv cert.pem machine-cert.pem
+[root@rgf9dev sample]# mv key.pem machine-key.pem
+[root@rgf9dev sample]# 
+

Distributing Files

Provide the machine with: +

a copy of ca.pem +
cert.pem +
key.pem +

This is how the relevant part of rsyslog.conf looks on the target machine: +

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

Never provide anyone with ca-key.pem! Also, make sure +nobody but the machine in question gets hold of key.pem. +

Copyright

+ 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 (2008-06-17)

Setting up syslog Clients

Setting up the UDP syslog relay

Wrapping it all up +

Frequently seen Error Messages

Sample Scenario

-- cgit