Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 164 insertions, 0 deletions

diff --git a/source/tutorials/tls_cert_machine.rst b/source/tutorials/tls_cert_machine.rst
new file mode 100644
index 0000000..e04d171
--- /dev/null
+++ b/source/tutorials/tls_cert_machine.rst
@@ -0,0 +1,164 @@
+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 a single person (or group) is responsible for
+the whole rsyslog system and thus it is OK if that single person is in
+possession 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 gets 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 impersonate as the machine
+to which it belongs, thus breaching your security.**
+
+Sample Screen Session
+~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+**Please note:** 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. 
+
+::
+
+    [root@rgf9dev sample]# certtool --generate-privkey --outfile key.pem --bits 2048
+    Generating a 2048 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 dnsName of the subject of the certificate:
+    Enter the IP address of the subject of the certificate:
+    Enter the e-mail of the subject of the certificate:
+    Enter a challenge password:
+    Does the certificate belong to an authority? (y/N): n
+    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):
+    Is this a TLS web client certificate? (y/N): y
+    Is this also a TLS web server certificate? (y/N): y
+    [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.
+    Do you want to honour the extensions from the request? (y/N):
+    Does the certificate belong to an authority? (Y/N): n
+    Will the certificate be used for IPsec IKE operations? (y/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 {This is the name of the machine that will use the certificate}
+    Enter the IP address of the subject of certificate:
+    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 2048):
+                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:
+
+````
+
+::
+
+	global(
+	DefaultNetstreamDriver="gtls"
+	DefaultNetstreamDriverCAFile="/path/to/contrib/gnutls/ca.pem"
+        DefaultNetstreamDriverCertFile="/path/to/contrib/gnutls/cert.pem"
+        DefaultNetstreamDriverKeyFile="/path/to/contrib/gnutls/key.pem"
+	)
+
+**Never provide anyone with ca-key.pem!** Also, make sure nobody but the
+machine in question gets hold of key.pem.