samhain file integrity scanner | online documentation

Using samhain with GnuPG

This document aims to explain how to use samhain with signed configuration and database files which are checked by invoking GnuPG.

Introduction

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

both the configuration file and the file signature database must be signed, and
for both files the signatures must verify correctly,
otherwise samhain will abort.

Prerequisites

Obviously you need gpg (GnuPG), and you must have created a key pair with:
gpg --gen-key
(it does not really matter which type of key, the defaults are ok).
GnuPG uses a public-key algorithm: the key pair consists of
- a secret key that is used for signing and stored in ~user/.gnupg/secring.gpg, and
- a public key used for verifying the signature, and stored in ~user/.gnupg/pubring.gpg.
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:

--with-checksum=no

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

--with-fingerprint=FINGERPRINT

where FINGERPRINT is the hexadecimal fingerprint of the key as listed with

gpg --fingerprint

Example


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

Signing the files

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.

TIP

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.

CAVEAT

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.

Example


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

Make samhain verify the signature

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:

The client (or standalone) samhain daemon runs with UID 0 (i.e. root), thus the public key must be in ~root/.gnupg/pubring.gpg
The server (yule) always drops root privileges (if started with), and runs as a non-root user. The username to use is compiled in, either with the configure option --enable-identity=USER, or by default as determined by configure (the first existing user out of the list yule, daemon, nobody). Thus, the public key must be in ~root/.gnupg/pubring.gpg (for startup) and in ~non_root_user/.gnupg/pubring.gpg (for reload with SIGHUP).

To import a public key into the public keyring (pubring.gpg) of another user, you can do:

gpg --export KEY-ID > filename
su another_user
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).

Example for signature check

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

Troubleshooting

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:

ERRSIG and/or NO_PUBKEY indicates that gpg did not find the public key to verify the signature. You should import that key into the keyrings of root and (for yule additionaly) the yule user.
BADSIG indicates that the public key was found by gpg, but the signature is invalid. Either the file has been modified after signing, or a previous signature has not been removed.
NODATA indicates that there is no signed data, i.e. the configuration or database file is not signed at all.