diff options
Diffstat (limited to 'README.SSL.md')
| -rw-r--r-- | README.SSL.md | 290 |
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. |