Adding upstream version 3.2.1.upstream/3.2.1upstream

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

1 files changed, 290 insertions, 0 deletions

diff --git a/README.SSL.md b/README.SSL.md
new file mode 100644
index 0000000..9f30613
--- /dev/null
+++ b/README.SSL.md
@@ -0,0 +1,290 @@
+NRPE With SSL/TLS
+=================
+
+This document covers the different methods of SSL transport
+that NRPE allows for. 
+
+If there was a TL;DR here, it is these:
+
+### Don't use NRPE without encryption
+
+and
+
+### Use Public Key Encryption
+
+Contents
+--------
+
+1. [Introduction](#introduction)
+2. [NRPE Changes](#nrpe-changes)
+3. [check_nrpe Changes](#check_nrpe-changes)
+4. [Certificate Generation Example](#certificate-generation-example)
+
+
+Introduction
+------------
+
+NRPE has had basic support for SSL/TLS for some time now, but it was
+severely lacking. It only allowed anonymous Diffie Hellman (ADH) key
+exchange, it used a fixed 512-bit key (generated at `./configure`
+time and extremely insecure) and originally allowed SSLv2. In 2004,
+SSLv2 and SSLv3 support was disabled.
+
+`nrpe` and `check_nrpe` have been updated to offer much more secure
+encryption and more options. And the updates are done in a backward-
+compatible way, allowing you to migrate to the newer versions
+without having to do it all at once, and possibly miss updating some
+machines, causing lost reporting.
+
+
+
+NRPE Changes
+------------
+
+Running `./configure` will now create a 2048-bit DH key instead
+of the old 512-bit key. The most current versions of openSSL will
+still not allow it. In my testing, openSSL 1.0.1e allowed DH keys
+of 512 bits, and 1.0.1k would not allow 2048 bit keys. In addition
+we now call `SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE)` so a
+new key is generated on each connection, based on the 2048-bit
+key generated.
+
+The NRPE configuration file has added new SSL/TLS options. The
+defaults currently will allow old check_nrpe plugins to continue to
+connect to the nrpe daemon, but can report on "old style"
+connections, or enforce more secure communication as your migration
+progresses. The new options are in the "SSL/TLS OPTIONS" section of
+nrpe.cfg, about two-thirds of the way down.
+
+If you are upgrading NRPE from a prior version, you can run the
+`update-cfg.pl` script to add the new parameters to your nrpe.cfg.
+
+The `ssl_version` directive lets you set which versions of SSL/TLS
+you want to allow. SSLv2, SSLv3, TLSv1, TLSv1.1 and TLSv1.2 are
+allowed, or those litereals with a `+` after them (as in TLSv1.1+).
+Without the `+`, *that version only* will be used. With the `+`,
+that *version or above* will be used. openSSL will always negotiate
+the highest available allowed version available on both ends. This
+directive currently defaults to `TLSv1+`.
+
+The `ssl_use_adh` directive is **DEPRECATED**, even though it is new.
+Possible values are `0` to not allow ADH at all, `1` to allow ADH,
+and `2` to require ADH. The `2` should never be required, but it's
+there just in case it's needed, for whatever reason. `1` is currently
+the default, which allows older `check_nrpe` plugins to connect using
+ADH. When all the plugins are migrated to the newer version, it
+should be set to `0`. In an upcoming version of NRPE, ADH will no
+longer be allowed at all. Note that if you use a `2` here, NRPE will
+override any `ssl_cipher_list` entries (below) to *only* allow ADH.
+
+The `ssl_cipher_list` directive lets you specify which ciphers you
+want to allow. It currently defaults to `ALL:!MD5:@STRENGTH` but can
+take any value allowed by openSSL. In an upcoming version of NRPE, it
+will be changed to something more secure, something like
+`ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH`. Note that
+if you have `ssl_use_adh=2`, this string will be overridden with
+`ADH` which only only allow ADH.
+
+The `ssl_cacert_file`, `ssl_cert_file` and `ssl_privatekey_file`
+directives are used to specify which *.pem files are to be used for
+Public-Key Encryption (PKE). Setting these will allow clients to use
+PKE to communicate with the server, similar to how the HTTPS
+protocol works.
+
+The `ssl_client_certs` directive specifies whether or not a client
+certificate will be requested when a client tries to connect. A value
+of `0` means the nrpe daemon will not ask for or require a client
+certificate. A `1` will cause it to ask for a client certificate, but
+not require one. A `2` will require the client to present a valid
+certificate. This currently defaults to `0`. If you want to use
+client certificates and are upgrading the clients over time, you can
+set this to `1` once many have been upgraded, then set to `2` to
+force the use of client certs. Note that the client certs _must_ be
+signed by the CA cert specified in the `ssl_cacert_file` directive.
+
+The `ssl_logging` directive allows you to log some additional data
+to syslog. OR (or add) values together to have more than one option
+enabled. Values are `0` for no additional logging (the default),
+`1` to log startup SSL/TLS parameters from the nrpe.cfg file, `2` to
+log the SSL/TLS version of connections, `4` to log which cipher is
+being used for the connection, `8` to log if the plugin has a cert, and
+`16` to log details of plugin's certificate. `-1` will enable all.
+This can be especially helpful during plugin migration, so you can
+tell which plugins have certificates, what SSL/TLS version is being
+used, and which ciphers are being used.
+
+
+check_nrpe Changes
+------------------
+
+The `check_nrpe` plugin has also been updated to provide more secure
+encryption and allow the use of client certificates. The command line
+has several new options, which are outlined below. Both the long and
+short arguments are presented.
+
+`--no-adh` or `-d` will disable the use of ADH. This option is
+**DEPRECATED**, even though it's new. It will be removed in a
+future version.
+
+`--ssl-version=<ver>` or `-S <ver>` specifies minimum SSL/TLS version
+to use. See the `ssl_version` directive above for possible values.
+
+`--cipher-list=<value.` or `-L <value>` determines which ciphers will
+and won't be allowed. See the `ssl_cipher_list` directive above.
+
+`--client-cert=<path>` or `-C <path>` specifies an optional client
+certificate to use. If this value is entered, the next one below is
+required.
+
+`--key-file=<path>` or `-K <path>` specifies the client certificate
+key file to use. This goes along with `--client-cert` above.
+
+`--ca-cert-file=<path>` or `-A <path>` specifies the CA certificate
+to use in order to validate the nrpe daemon's public key.
+
+`--no-adh` or `-d` is **DEPRECATED**
+
+`--use-adh` or `-d [num]` is **DEPRECATED**, even though it is new.
+If you use `-d` or `-d 0` it acts the same way as as the old `-d`.
+Otherwise, use `1` to allow ADH, and `2` to require ADH.
+
+`--ssl-logging=<num>` or `-s <num>` allows you to log some additional
+data to syslog. OR (or add) values together to have more than one
+option enabled. See the description of the `ssl_logging` directive
+from NRPE above.
+
+
+
+Certificate Generation Example
+------------------------------
+
+**Note** _The following example does not follow best practice for
+creating and running a CA or creating certificates. It is for testing
+or possibly for use in a small environment. Sloppy security is as bad
+as no security._
+
+In this example, we are going to put everything in the
+`/usr/local/nagios/etc/ssl` directory. You may want to use the more
+common `/etc/ssl` directory, or somewhere else entirely.
+
+We are going to assume your company name is Foo Widgets, LLC; the
+server running the nagios process (and thus the check_nrpe program)
+is called `nag_serv`; and there are two Linux machines that will
+run the nrpe daemon: `db_server` and `bobs_workstation`.
+
+
+#### Set up the directories
+
+As root, do the following:
+
+        mkdir -p -m 750 /usr/local/nagios/etc/ssl
+        chown root:nagios /usr/local/nagios/etc/ssl
+        cd /usr/local/nagios/etc/ssl
+        mkdir -m 750 ca
+        chown root:root ca
+        mkdir -m 750 server_certs
+        chown root:nagios server_certs
+        mkdir -m 750 client_certs
+        chown root:nagios client_certs
+
+
+#### Create Certificate Authority
+
+If you want to validate client or server certificates, you will need
+to create a Certificate Authority (CA) that will sign all client and
+server certificates. If your organization already has a CA, you can
+use that.
+
+As root, do the following:
+
+        cd /usr/local/nagios/etc/ssl/ca
+        openssl req -x509 -newkey rsa:4096 -keyout ca_key.pem \
+           -out ca_cert.pem -utf8 -days 3650
+
+When asked, enter a passphrase. Then follow the prompts. You will
+probably want to include `CA` or `Certificate Authority` in for
+`Organizational Unit Name` and `Common Name`. For example:
+
+        Organization Name (eg, company) []:Foo Widgets LLC
+        Organizational Unit Name (eg, section) []:Foo Certificate Authority
+        Common Name (e.g. server FQDN or YOUR name) []:Foo Nagios CA
+
+
+#### Create NRPE Server Certificate Requests
+
+For each of the hosts that will be running the nrpe daemon, you will
+need a server certificate. You can create a key, and the CSR
+(Certificate Signing Request) separately, but the following commands
+will do both with one command. As root, do the following:
+
+        cd /usr/local/nagios/etc/ssl/server_certs
+        openssl req -new -newkey rsa:2048 -keyout db_server.key \
+           -out db_server.csr -nodes
+        openssl req -new -newkey rsa:2048 -keyout bobs_workstation.key \
+           -out bobs_workstation.csr -nodes
+
+Follow the prompts. The `-nodes` at the end of the lines tells
+openssl to generate the key without a passphrase. Leave it off if you
+want someone to enter a passphrase whenever the machine boots.
+
+Now you need to sign the CSRs with your CA key.
+
+If you have the default `/etc/openssl.cnf`, either change it, or as root, do:
+
+        cd /usr/local/nagios/etc/ssl
+        mkdir demoCA
+        mkdir demoCA/newcerts
+        touch demoCA/index.txt
+        echo "01" > demoCA/serial
+        chown -R root:root demoCA
+        chmod 700 demoCA
+        chmod 700 demoCA/newcerts
+        chmod 600 demoCA/serial
+        chmod 600 demoCA/index.txt
+
+Now, sign the CSRs. As root, do the following:
+
+        cd /usr/local/nagios/etc/ssl
+        openssl ca -days 365 -notext -md sha256 \
+           -keyfile ca/ca_key.pem -cert ca/ca_cert.pem \
+           -in server_certs/db_server.csr \
+           -out server_certs/db_server.pem
+        chown root:nagios server_certs/db_server.pem
+        chmod 440 server_certs/db_server.pem
+        openssl ca -days 365 -notext -md sha256 \
+           -keyfile ca/ca_key.pem -cert ca/ca_cert.pem \
+           -in server_certs/bobs_workstation.csr \
+           -out server_certs/bobs_workstation.pem
+        chown root:nagios server_certs/bobs_workstation.pem
+        chmod 440 server_certs/bobs_workstation.pem
+
+Now, copy the `db_server.pem` and `db_server.key` files to the
+db_server machine, and the `bobs_workstation.pem` and
+`bobs_workstation.key` files to bobs_workstation. Copy the
+`ca/ca_cert.pem` file to both machines.
+
+
+#### Create NRPE Client Certificate Requests
+
+Now you need to do the same thing for the machine that will be
+running the check_nrpe program.
+
+        cd /usr/local/nagios/etc/ssl/client_certs
+        openssl req -new -newkey rsa:2048 -keyout nag_serv.key \
+           -out nag_serv.csr -nodes
+
+        cd /usr/local/nagios/etc/ssl
+        openssl ca -extensions usr_cert -days 365 -notext -md sha256 \
+           -keyfile ca/ca_key.pem -cert ca/ca_cert.pem \
+           -in client_certs/nag_serv.csr \
+           -out client_certs/nag_serv.pem
+        chown root:nagios client_certs/nag_serv.pem
+        chmod 440 client_certs/nag_serv.pem
+
+Now, copy the `nag_serv.pem`, `nag_serv.key` and `ca/ca_cert.pem`
+files to the nag_serv machine, if you did the above on a different
+computer.
+
+Put the location of each computers' three files in the `nrpe.cfg`
+file or in the check_nrpe command line. You should now have
+encryption and, if desired, key validation.