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

1. both the configuration file and the file signature database must be signed, and
2. for both files the signatures must verify correctly,
3. 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 separate cases:

1. The client (or standalone) samhain daemon runs with UID 0 (i.e. root), thus the public key must be in ~root/.gnupg/pubring.gpg
2. 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.