lagertonne/nut
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Wiki Activity

Imported Upstream version 2.7.1

Browse source
This commit is contained in:
Laurent Bigonville 2013-11-24 16:00:12 +01:00
parent a1fa151fc7
commit 0121794af9
451 changed files with 41339 additions and 10887 deletions
Download patch file Download diff file Expand all files Collapse all files

205
docs/security.txt
View file

@ -173,21 +173,32 @@ passwords.
Several things must happen before this will work, however. This chapter will
present these steps.
SSL is available via two back-end libraries : NSS and OpenSSL (historically).
You can choose to use one of them by specifying it with abuild option
('--with-nss' or '--with-openssl'). If any is specified, configure script will
try to detect one of them and use it with a precedence for OpenSSL.
OpenSSL backend usage
~~~~~~~~~~~~~~~~~~~~~
This section describes how to enable NUT SSL support using
link:http://www.openssl.org[OpenSSL].
Install OpenSSL
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
Install link:http://www.openssl.org[OpenSSL] as usual, either from source
or binary packages.
or binary packages including nss-tools.
Recompile and install NUT
~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^
Recompile NUT from source, starting with 'configure --with-ssl'.
Recompile NUT from source, starting with 'configure --with-openssl'.
Then install everything as usual.
Create a certificate and key for upsd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
openssl (the program) should be in your PATH, unless you installed it from
source yourself, in which case it may be in /usr/local/ssl/bin.
@ -206,7 +217,7 @@ clients may present data from it, so you might use this opportunity to
identify each server somehow.
Figure out the hash for the key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the following command to determine the hash of the certificate:
@ -217,7 +228,7 @@ hash of the certificate, which is used for naming the client-side
certificate. For the purposes of this example the hash is *0123abcd*.
Install the client-side certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the following commands to install the client-side certificate:
@ -246,7 +257,7 @@ insert a new client certificate and fool upsmon into trusting a
fake upsd.
Create the combined file for upsd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To do so, use the below commands:
@ -263,13 +274,13 @@ to read the file without being able to change the contents. This
is done to minimize the impact if someone should break into upsd.
Note on certification authorities (CAs) and signed keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are probably other ways to handle this, involving keys which have
been signed by a CA you recognize. Contact your local SSL guru.
Install the server-side certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install the certificate with the following command:
@ -284,12 +295,12 @@ After that, edit your upsd.conf and tell it where to find it:
CERTFILE /usr/local/ups/etc/upsd.pem
Clean up the temporary files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
rm -f upsd.crt upsd.key
Restart upsd
~~~~~~~~~~~~
^^^^^^^^^^^^
It should come back up without any complaints. If it says something
about keys or certificates, then you probably missed a step.
@ -298,7 +309,7 @@ If you run upsd as a separate user id (like nutsrv), make sure that
user can read the upsd.pem file.
Point upsmon at the certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Edit your upsmon.conf, and tell it where the CERTPATH is:
@ -309,7 +320,7 @@ Example:
CERTPATH /usr/local/ups/etc/certs
Recommended: make upsmon verify all connections with certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Put this in upsmon.conf:
@ -323,7 +334,7 @@ all of your upsd hosts are ready for SSL and have their certificates
in order.
Recommended: force upsmon to use SSL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Again in upsmon.conf:
@ -334,6 +345,170 @@ that nobody can sniff your sessions without a large effort. Setting
this will make upsmon drop connections if the remote upsd doesn't
support SSL, so don't use it unless all of them have it running.
NSS backend usage
~~~~~~~~~~~~~~~~~
This section describes how to enable NUT SSL support using
link:http://www.mozilla.org/projects/security/pki/nss/[Mozilla NSS].
Install NSS
^^^^^^^^^^^
Install link:http://www.mozilla.org/projects/security/pki/nss/[Mozilla NSS] as
usual, either from source or binary packages.
Recompile and install NUT
^^^^^^^^^^^^^^^^^^^^^^^^^
Recompile NUT from source, starting with 'configure --with-nss'.
Then install everything as usual.
Create certificate and key for the host
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NSS (package generally called libnss3-tools) will install a tool called
'certutil'.
It will be used to generate certificates and manage certificate database.
Certificates should be signed by a certification authorities (CAs).
Following commands are typical samples, contact your SSL guru or security officer
to follow your company procedures.
.Generate a server certificate for upsd:
- Create a directory where store the certificate database: 'mkdir cert_db'
- Create the certificate database : 'certutil -N -d cert_db'
- Import the CA certificate:
'certutil -A -d cert_db -n "My Root CA" -t "TC,," -a -i rootca.crt'
- Create a server certificate request (here called 'My nut server'):
'certutil -R -d cert_db -s "CN=My nut server,O=MyCompany,ST=MyState,C=US" -a -o server.req'
- Make your CA sign the certificate (produces server.crt)
- Import the signed certificate into server database:
'certutil -A -d cert_db -n "My nut server" -a -i server.crt -t ",,"'
- Display the content of certificate server:
'certutil -L -d cert_db'
Clients and servers in the same host could share the same certificate to authentify them
or use different ones in same or different databases.
The same operation can be done in same or different databases to generate
other certificates.
Create a self-signed CA certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NSS provides a way to create self-signed certificate which can acting as
CA certificate and to sign other certificates with this CA certificate.
This method can be used to provide CA certification chain without passing
by an 'official' CA provider.
.Generate a self-signed CA certificate:
- Create a directory where store the CA certificate database: 'mkdir CA_db'
- Create the certificate database:
'certutil -N -d CA_db'
- Generate a certificate for CA:
'certutil -S -d CA_db -n "My Root CA" -s "CN=My CA,O=MyCompany,ST=MyState,C=US" -t "CT,," -x -2'
Do not forget to answer 'Yes' to the question 'Is this a CA certificate [y/N]?'
- Extract the CA certificate to be able to import it in upsd (or upsmon) certificate database:
'certutil -L -d CA_db -n "My Root CA" -a -o rootca.crt'
- Sign a certificate request with the CA certificate (simulate a real CA signature):
'certutil -C -d CA_db -c "My Root CA" -a -i server.req -o server.crt -2 -6'
Install the server-side certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Just copy the database directory (just the directory and included 3
database .db files) at the right place like in '/usr/local/ups/etc/':
mv cert_db /usr/local/ups/etc/
upsd (required): certificate database and self certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Edit the upsd.conf to tell where find the certificate database:
CERTPATH /usr/local/ups/etc/cert_db
Also tell which is the certificate to send to clients to authenticate itself
and the password to decrypt private key associated to certificate:
CERTIDENT 'certificate name' 'database password'
NOTE: Generally, the certificate name is the server domain name, but is not
a hard rule. The certificate can be named as useful.
upsd (optional): client authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NOTE: This functionality is disabled by default. To activate it, recompile
NUT with 'WITH_CLIENT_CERTIFICATE_VALIDATION' defined:
make CFLAGS="-DWITH_CLIENT_CERTIFICATE_VALIDATION"
UPSD can accept three levels of client authentication. Just specify it with
the directive 'CERTREQUEST' with the corresponding value in the upsd.conf file:
- NO: no client authentication.
- REQUEST: a certificate is request to the client but it is not strictly validated.
If the client does not send any certificate, the connection is closed.
- REQUIRE: a certificate is requested to the client and if it is not valid
(no validation chain) the connection is closed.
Like CA certificates, you can add many 'trusted' client and CA certificates
in server's certificate databases.
upsmon (required): upsd authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order for upsmon to securely connect to upsd, it must authenticate it.
You must associate an upsd host name to security rules in upsmon.conf
with the directive 'CERTHOST'.
'CERTHOST' associate to an hostname a certificate name and if a SSL connection
is mandatory and if its certificate must be validated.
CERTHOST 'hostname' 'certificate name' 'certverify' 'forcessl'
If the flag 'forcessl' is set to '1' and the upsd answer that it can not
connect in SSL, the connection closes.
If the flag 'certverify' is set to '1' and the connection is done in ssl,
upsd's certificate is verified and its name must be the specified
'certificate name'.
To prevent security leaks, you should set all 'certverify' and 'forcessl'
flags to '1' (force SSL connection and validate all certificates for all
peers).
You can specify 'CERTVERIFY' and 'FORCESSL' directive (to '1' or '0') to
define a default security rule to apply to all host not specified with a
dedicated 'CERTHOST' directive.
If a host is not specified in a 'CERTHOST' directive, its expected certificate
name is its hostname.
upsmon (optional): certificate database and self certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Like upsd, upsmon may need to authenticate itself (upsd's 'CERTREQUEST'
directive set to 'REQUEST' or 'REQUIRE').
It must access to a certificate (and its private key) in a certificate database
configuring 'CERTPATH' and 'CERTIDENT' in upsmon.conf in the same way than upsd.
CERTPATH /usr/local/ups/etc/cert_db
CERTIDENT 'certificate name' 'database password'
Restart upsd
~~~~~~~~~~~~
It should come back up without any complaints. If it says something
about keys or certificates, then you probably missed a step.
If you run upsd as a separate user id (like nutsrv), make sure that
user can read files in certificate directory.
Restart upsmon
~~~~~~~~~~~~~~