Chapter 9. Additional Features — Signed Configuration/Database Files

Both the configuration file (see Section 1) and the database of file signatures ( Section 8) may always be cleartext signed by GnuGP (gpg). The recommended options are:

gpg -a --clearsign --not-dash-escaped FILE

1. Compiling with support for signatures

If compiled with support for signatures, samhain will invoke gpg to verify the signature. To compile with gpg support, use the option:

./configure --with-gpg=/full/path/to/gpg --with-fp=FINGERPRINT [--with-keyid=0x<hex KeyID>]

  • Note that gpg --fingerprint will only list the fingerprint of primary keys. If you are signing with a secondary key, you need to repeat the '--fingerprint' option (i.e. run gpg gpg --fingerprint --fingerprint ) in order to obtain the fingerprint for the signing (secondary) key. (If you don't know what a secondary key is, then this note is probably irrelevant for you.)

    Example(spaces in FINGERPRINT do not matter): --with-fp="EF6C EF54 701A 0AFD B86A F4C3 1AAD 26C8 0F57 1F6C"

  • The optional argument --with-keyid=0x<hex KeyID> allows to specify a key ID, if there is more than one key in your keyring. This is only used for the installation routine, and for configuring the convenience script (see below).

    The installation routine ("[sudo] make install") will use the keyring of the user running it (in ~/.gnupg) for signing. At runtime, samhain will use the keyring of the runtime user (usually root) for verification.

  • samhain will check that the path to the gpg executable is writeable only by trusted users(see Section 10.1 ).

  • The gpg program will be called without using the shell, with its full path (as compiled in), and with an environment that is limited to the HOME variable.

    If you need LD_LIBRARY_PATH, because your gpg executable relies on libraries that are not in the search path of the loader, you can either (i) use a wrapper script to set the environment and exec gpg (take care not to mess with file descriptors), (ii) update the system loader configuration file, or (iii) recompile with loader paths (-Wl,-r<path> or -Wl,-R<path>).

  • The public key must be in in the subdirectory HOME/.gnupg, where HOME is the home directory of the effective user (usually root).

  • From the command line, the signature must verify correctly with /path/to/gpg --status-fd 1 --verify FILE when invoked by the effective user of samhain (usually root).


There is a Perl script to facilitate some tasks related to the administration of signed configuration and database files (see Section 3).

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.

As signatures on files are only useful as long as you can trust the gpg executable, the configure script will determine the TIGER192 checksum of the gpg executable, which will be compiled into samhain. In case of an error, you can specify the checksum by hand with:

--with-checksum=" CHECKSUM" — or — --without-checksum

CHECKSUM should be the checksum as printed by

gpg --load-extension tiger --print-md TIGER192 /path/to/gpg — or — samhain -H /path/to/gpg (the full line of output, with spaces).

Example: --with-checksum="/usr/bin/gpg: 1C739B6A F768C949 FABEF313 5F0B37F5 22ED4A27 60D59664"


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' (or '--without-checksum' , which is equivalent).