Chapter 9. Additional Features — Signed Configuration/Database Files
Prev   Next

Chapter 9. Additional Features — Signed Configuration/Database Files

Table of Contents

1. Compiling with support for signatures
1.1. If using GnuPG
1.2. If using signify
2. Installation
3. The samhainadmin script

Both the configuration file (see Section 1) and the database of file signatures ( Section 8) may always be cleartext signed by either GnuGP (gpg) or the OpenBSD signify tool (available as signify-openbsd on Debian-based Linux flavours). The recommended options are:

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

signify-openbsd -Se -s PRIVATE_KEY -m FILE

[Tip]Tip

Please take note that on Linux, there exists a Perl application named signify which is completely unrelated to the OpenBSD signify cryptographic application. For this reason, on Debian-based Linux flavours, OpenBSD signify is named signify-openbsd. Do not confuse signify-openbsd and signify on Linux. The latter is not what you want.

1. Compiling with support for signatures

1.1. If using GnuPG

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

[Tip]Tip

There is a Perl script samhainadmin.pl 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"

[Warning]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).

1.2. If using signify

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

./configure --with-signify=/full/path/to/signify --with-pubkey-checksum=PUBKEY_CHECKSUM

  • To determine the (TIGER192) checksum of the public key, you can either use samhain, by running the command: samhain -H key.pub or you can use GnuPG with the command gpg --load-extension tiger --print-md TIGER192 key.pub You only need the (48 character long) checksum part of the output, with or without whitespace stripped.

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

  • The signify executable 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 signify (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/.signify, where HOME is the home directory of the effective user (usually root). It MUST be named INSTALL_NAME.pub, where INSTALL_NAME is the name under which samhain is actually installed (defaults to 'yule' for the server, 'samhain' otherwise, but configurable with the ./configure --install-name=NAME option.)

  • From the command line, the signature must verify correctly with signify -Vem /dev/null -p ~/.signify/INSTALL_NAME.pub -x FILE when invoked by the effective user of samhain (usually root).

[Tip]Tip

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

As signatures on files are only useful as long as you can trust the signify executable, the configure script will determine the TIGER192 checksum of the signify 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/signify (the full line of output, with spaces).

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

[Warning]WARNING

Compiling in the signify checksum will tie the samhain executable to the signify executable. If you upgrade signify, you will need to re-compile samhain. If you don't like this, use '--with-checksum=no' (or '--without-checksum' , which is equivalent).

Prev   Next
2. Limitations Home 2. Installation