Additional Features — Signed Configuration/Database Files

Samhain
Prev |  | Next

# Chapter 8. Additional Features — Signed Configuration/Database Files

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

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

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

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

- The 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.

- 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).

| Tip
| There is a Perl script samhainadmin.pl to facilitate some tasks related to the administration of signed configuration and database files (see Section 8.1>).

| 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.

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"

| WARNING
| 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).

Likewise, it is highly recommended to compile in the key fingerprint of the signature key, which then will be verified after checking the signature itself:

--with-fp=FINGERPRINT

| Note
| 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"

| Tip
| make install will gpg sign the configuration file before installation.

    bash$ ./configure --with-gpg=/usr/bin/gpg --with-fp=EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C
    bash$ make
    bash$ su
    bash$ make install
    bash$ samhain -t init
    bash$ gpg -a --clearsign /var/lib/samhain/samhain_file
    bash$ mv /var/lib/samhain/samhain_file.asc /var/lib/samhain/samhain_file

samhain will report the signature key owner and the key fingerprint as obtained from gpg. If both files are present and checked (i.e. when checking files against the database), both must be signed with the same key. If the verification is successful, samhain will only report the signature on the configuration file. If the verification fails, or the key for the configuration file is different from that of the database file, an error message will result.

# 8.1. The samhainadmin script

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). By default, this script is not installed.

    bash$ samhainadmin.pl --help
      samhainadmin.pl { -m F | --sign-cfgfile }      [options] [in.cfgfile]
        Sign the configuration file. If in.cfgfile is given, sign it
        and install it as configuration file.

      samhainadmin.pl { -m f | --print-cfgfile }     [options]
        Print the configuration file to stdout. Signatures are removed.

      samhainadmin.pl { -m D | --sign-datafile }     [options] [in.datafile]
        Sign the database file. If in.datafile is given, sign it
        and install it as database file.

      samhainadmin.pl { -m d | --print-datafile }    [options]
        Print the database file to stdout. Signatures are removed. Use
        option --list to list files in database rather than printing the raw file.

      samhainadmin.pl { -m R | --remove-signature }  [options] file1 [file2 ...]
        Remove cleartext signature from input file(s). The file
        is replaced by the non-signed file.

      samhainadmin.pl { -m E | --sign }              [options] file1 [file2 ...]
        Sign file(s) with a cleartext signature. The file
        is replaced by the signed file.

      samhainadmin.pl { -m e | --examine }           [options] file1 [file2 ...]
        Report signature status of file(s).

      samhainadmin.pl { -m G | --generate-keys }     [options]
        Generate a PGP keypair to use for signing.

    Options:
      -c cfgfile    --cfgfile cfgfile
        Select an alternate configuration file.

      -d datafile   --datafile datafile
        Select an alternate database file.

      -p passphrase --passphrase passphrase
        Set the passphrase for gpg. By default, gpg will ask.

      -l            --list
        List the files in database rather than printing the raw file.

      -v            --verbose
        Verbose output.

Prev | Home | Next
Calling external programs |  | Additional Features — Stealth