This document aims to explain how to use samhain with signed configuration and database files which are checked by invoking GnuPG.
Samhain can be compiled to recognize PGP signatures on configuration and database files and to invoke GnuPG in order to check such signatures. (Note: while the application usually is referred to as GnuPG, the executable itself is called gpg).
If samhain is compiled with this option, then
Obviously you need gpg (GnuPG), and you must have created a key pair with:
(it does not really matter which type of key, the defaults are ok).
GnuPG uses a public-key algorithm: the key pair consists of
The secret key obviously should be kept secret, while the public key can be published.
You need to compile samhain with support for GnuPG:
./configure --with-gpg=/path/to/gpg [more options]
Note 1: If compiled with support for GnuPG, the TIGER192 checksum of the gpg executable will be compiled into samhain, and the gpg executable will be checksummed (to verify its integrity) before invoking it. If you don't like this, you should add the configure option:
Compiling in the GnuPG checksum will tie the samhain executable to the gpg executable. If you upgrade GnuPG, you will need to re-compile samhain. If you don't like this, use '--with-checksum=no'.
Note 2: The mere fact that the signature is correct does not prove that it has been signed by you with your key - it just proves that it has been signed by somebody. Samhain can optionally check the fingerprint of the key that has been used to sign the files, to verify that your key has been used to sign the file(s). To enable this, use the configure option
where FINGERPRINT is the hexadecimal fingerprint of the key as listed with
rainer$ gpg --fingerprint rainer pub 1024D/0F571F6C 1999-10-31 Rainer Wichmann Key fingerprint = EF6C EF54 701A 0AFD B86A F4C3 1AAD 26C8 0F57 1F6C uid Rainer Wichmann sub 1024g/9DACAC30 1999-10-31 rainer$ which gpg /usr/bin/gpg rainer$ ./configure --with-gpg=/usr/bin/gpg --with-fingerprint=EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C
The configuration file and the file signature database (created by running samhain -t init) must be signed manually using the command:
gpg -a --clearsign --not-dash-escaped /etc/samhainrc
mv /etc/samhainrc.asc /etc/samhainrc
Gpg will create a signed copy of the file, named file.asc. You need to rename (cp/mv) this signed copy to the original filename. After signing the configuration file, you can initialize the database and sign it likewise.
Note 1: The installation script will ask you to sign the configuration file upon installation.
Note 2: The gpg option --not-dash-escaped does not harm if used with the configuration file, but is only required for the file signature database.
In the subdirectory scripts/ of the source directory you will find a Perl script samhainadmin.pl to facilitate some tasks related to the administration of signed configuration and database files (e.g. examine/create/remove signatures). Use with --help to get usage information.
When signing, the option --not-dash-escaped is recommended, because otherwise the database might get corrupted. However, this implies that after a database update, you must remove the old signature first, before re-signing the database. Without 'dash escaping', gpg will not properly handle the old signature. See the tip just above.
root# gpg -a --clearsign --not-dash-escaped /etc/samhainrc You need a passphrase to unlock the secret key for user: "Rainer Wichmann" 1024-bit DSA key, ID 0F571F6C, created 1999-10-31 root# mv /etc/samhainrc.asc /etc/samhainrc root# samhain -t init root# gpg -a --clearsign --not-dash-escaped /var/lib/samhain/samhain_file You need a passphrase to unlock the secret key for user: "Rainer Wichmann" 1024-bit DSA key, ID 0F571F6C, created 1999-10-31 root# mv /var/lib/samhain/samhain_file.asc /var/lib/samhain/samhain_file root# samhain -D -t check
This is the part where some people run into problems. The point is, when gpg is invoked by samhain, it must find the public key needed for verification. Gpg expects public keys in a file located at ~user/.gnupg/pubring.gpg where ~user is the home directory of the user as that gpg is running.
It is therefore crucial to include the public key corresponding to te secret key used for signing into the correct pubring.gpg file (this file can hold many public keys, e.g. of people sending you emails signed by them).
So which is the correct file? Here we have to consider two seperate cases:
To import a public key into the public keyring (pubring.gpg) of another user, you can do:
gpg --export KEY-ID > filename
gpg --import filename
Note: samhain will invoke gpg with the options:
--status-fd 1 --verify --homedir /homedir/.gnupg --no-tty -
and pipe the configuration/database file into gpg, similar to:
cat filename | /usr/bin/gpg --status-fd 1 --verify --homedir /root/.gnupg --no-tty -
(of course samhain does not invoke cat, or the shell; the example above just shows how to do the same from the shell command prompt).
If you want to check the signature the same way samhain does, it should look like (note the GOODSIG and VALIDSIG keywords in the output):
root# cat /etc/samhainrc | gpg --status-fd 1 --verify --homedir /root/.gnupg --no-tty - gpg: Signature made Sat Mar 15 16:08:21 2003 CET using DSA key ID 0F571F6C [GNUPG:] SIG_ID 9hQvRhgjWLqyFzVOHi2b0uDmBFo 2003-03-15 1047740901 [GNUPG:] GOODSIG 1AAD26C80F571F6C Rainer Wichmann gpg: Good signature from "Rainer Wichmann" gpg: aka "Rainer Wichmann" [GNUPG:] VALIDSIG EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C 2003-03-15 1047740901 [GNUPG:] TRUST_ULTIMATE
First and foremost, run samhain (or yule) from the command line, in non-daemon mode, and with the command-line option -p debug for debug-level output. This will print descriptive information on setup errors and/or relevant output from the GnuPG subprocess.
Output from the GnuPG subprocess is marked by [GNUPG:], and may show the following errors: