/usr/share/doc/samhain/manual.html/signed-files.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Additional Features &#8212; Signed Configuration/Database Files</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="The Samhain Host Integrity Monitoring System"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Calling external programs"
HREF="calling-external-programs.html"><LINK
REL="NEXT"
TITLE="Additional Features &#8212; Stealth"
HREF="stealthmode.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="./docbook.css"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><!--#if expr="! ($HTTP_USER_AGENT = /MSIE/)"--><!--#include virtual="/resources/ssi/header.html"--><!--#endif --><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Samhain Host Integrity Monitoring System</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="calling-external-programs.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="stealthmode.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="SIGNED-FILES"
></A
>Chapter 8. Additional Features &mdash; Signed Configuration/Database Files</H1
><P
>  Both the configuration file (see <A
HREF="the-configuration-file.html#CONFIGFILE"
>Section C.1</A
>&#62;) and
  the database of file signatures (<A
HREF="databasefile.html"
>Section 5.8</A
>&#62;) 
  may always be cleartext signed
  by GnuGP (<B
CLASS="COMMAND"
>gpg</B
>).
  The <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>recommended</I
></SPAN
> options are:</P
><P
>  <B
CLASS="COMMAND"
>gpg -a --clearsign --not-dash-escaped <TT
CLASS="REPLACEABLE"
><I
>FILE</I
></TT
></B
></P
><P
>  If compiled with support for signatures, 
  <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> will 
  invoke <B
CLASS="COMMAND"
>gpg</B
>
  to verify the signature. To compile with 
  <B
CLASS="COMMAND"
>gpg</B
> support, use the
  option:</P
><P
>  <B
CLASS="COMMAND"
>./configure --with-gpg=/full/path/to/gpg [--with-keyid=0x&lt;hex KeyID&gt;]</B
></P
><P
><P
></P
><UL
><LI
><P
>      The optional argument <B
CLASS="COMMAND"
>--with-keyid=0x&lt;hex KeyID&gt;</B
>
      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
      <B
CLASS="COMMAND"
>samhainadmin.pl</B
> convenience script (see below).
    </P
><P
>      The installation routine (&quot;[sudo] make install&quot;) will use
      the keyring of the user running it (in <TT
CLASS="FILENAME"
>~/.gnupg</TT
>)
      for signing. At runtime, <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> will
      use the keyring of the runtime user (usually root) for verification.
    </P
></LI
><LI
><P
>      samhain will check
      that the path to the <B
CLASS="COMMAND"
>gpg</B
> executable is writeable 
      <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>only by trusted users</I
></SPAN
>
      (see <A
HREF="layout.html#DEFTRUST"
>Section 2.10.1</A
>&#62;).
    </P
></LI
><LI
><P
>      The <B
CLASS="COMMAND"
>gpg</B
> program will be called without using the shell,
      with its full path (as compiled in), and <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>with an environment 
	that is limited to the HOME variable</I
></SPAN
>.
    </P
></LI
><LI
><P
>      The public key must be in in the subdirectory 
      <TT
CLASS="FILENAME"
>HOME/.gnupg</TT
>, where HOME is the
      home directory of the effective user (usually <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>root</I
></SPAN
>).
    </P
></LI
><LI
><P
>      From the command line, the signature must verify correctly with
      <B
CLASS="COMMAND"
>/path/to/gpg --status-fd 1 --verify <TT
CLASS="REPLACEABLE"
><I
>FILE</I
></TT
></B
>
      when invoked by the effective user of samhain 
      (usually <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>root</I
></SPAN
>).
    </P
></LI
></UL
></P
><DIV
CLASS="TIP"
><P
></P
><TABLE
CLASS="TIP"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>Tip</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>   There is a Perl script <B
CLASS="COMMAND"
>samhainadmin.pl</B
> to 
   facilitate some
   tasks related to the administration of signed configuration and
   database files (see <A
HREF="signed-files.html#SAMHAINADMIN"
>Section 8.1</A
>&#62;).
 </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>Caveats</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>   When signing, the option <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>--not-dash-escaped</I
></SPAN
> is
   recommended, because otherwise the database might get corrupted. 
   However, this implies that after a database update, 
   you <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
> remove the old signature first, before
   re-signing the database. Without 'dash escaping', 
   <SPAN
CLASS="APPLICATION"
>gpg</SPAN
> will not properly handle the old signature.
   See the tip just above.
 </P
><P
>   The environment is limited to the HOME
   variable, since gpg may need it to find the the subdirectory 
   <TT
CLASS="FILENAME"
>HOME/.gnupg</TT
>. 
   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&lt;path&gt; or -Wl,-R&lt;path&gt;).
 </P
></TD
></TR
></TABLE
></DIV
><P
>  As signatures on files are only useful as long as you can trust the
  <B
CLASS="COMMAND"
>gpg</B
> executable, the <B
CLASS="COMMAND"
>configure</B
> 
  script will determine the
  TIGER192 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>checksum</I
></SPAN
> of the <B
CLASS="COMMAND"
>gpg</B
> 
  executable, which will be compiled 
  into <SPAN
CLASS="APPLICATION"
>samhain</SPAN
>. In case of an error, 
  you can specify the checksum by
  hand with:</P
><P
>  <B
CLASS="COMMAND"
>--with-checksum="<TT
CLASS="REPLACEABLE"
><I
>CHECKSUM</I
></TT
>"</B
>
  &mdash; or &mdash;  
  <B
CLASS="COMMAND"
>--without-checksum</B
></P
><P
>  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>CHECKSUM</I
></SPAN
> should be the checksum as printed by</P
><P
>  <B
CLASS="COMMAND"
>gpg --load-extension tiger --print-md TIGER192 <TT
CLASS="REPLACEABLE"
><I
>/path/to/gpg</I
></TT
></B
>
  &mdash; or &mdash;
  <B
CLASS="COMMAND"
>samhain -H <TT
CLASS="REPLACEABLE"
><I
>/path/to/gpg</I
></TT
></B
>
  (the full line of output, <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>with spaces</I
></SPAN
>).</P
><P
>  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
></SPAN
>
  <B
CLASS="COMMAND"
>--with-checksum="/usr/bin/gpg: 1C739B6A F768C949 FABEF313  5F0B37F5 22ED4A27 60D59664"</B
></P
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>WARNING</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>   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 
   <B
CLASS="COMMAND"
>'--with-checksum=no'</B
> 
   (or <B
CLASS="COMMAND"
>'--without-checksum'</B
>, which is equivalent).
 </P
></TD
></TR
></TABLE
></DIV
><P
>  Likewise, it is highly recommended to compile in the 
  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>key fingerprint</I
></SPAN
> 
  of the signature key, which then will be verified after checking the 
  signature itself:</P
><P
>  <B
CLASS="COMMAND"
>--with-fp=FINGERPRINT</B
></P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>Note</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><B
CLASS="COMMAND"
>gpg --fingerprint</B
> 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 
<B
CLASS="COMMAND"
>gpg --fingerprint --fingerprint</B
>) 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.)</P
></TD
></TR
></TABLE
></DIV
><P
>  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example</I
></SPAN
> (spaces in FINGERPRINT do not matter):
  <B
CLASS="COMMAND"
>--with-fp="EF6C EF54 701A 0AFD B86A F4C3 1AAD 26C8 0F57 1F6C"</B
></P
><DIV
CLASS="TIP"
><P
></P
><TABLE
CLASS="TIP"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>Tip</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><B
CLASS="COMMAND"
>make install</B
> will gpg sign the configuration file
before installation.</P
></TD
></TR
></TABLE
></DIV
><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>./configure --with-gpg=/usr/bin/gpg --with-fp=EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>make</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>su</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>make install</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>samhain -t init</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>gpg -a --clearsign /var/lib/samhain/samhain_file</KBD
>
<SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>mv /var/lib/samhain/samhain_file.asc /var/lib/samhain/samhain_file</KBD
></PRE
><P
>  <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> will report the 
  signature key owner and the key fingerprint
  as obtained from <B
CLASS="COMMAND"
>gpg</B
>. 
  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, 
  <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> 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.</P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SAMHAINADMIN"
>8.1. The samhainadmin script</A
></H1
><P
>   In the subdirectory <TT
CLASS="FILENAME"
>scripts/</TT
> 
   of the source directory you will find
   a Perl script <B
CLASS="COMMAND"
>samhainadmin.pl</B
> 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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not installed</I
></SPAN
>.
   </P
><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>bash$</SAMP
> <KBD
CLASS="USERINPUT"
>samhainadmin.pl --help</KBD
>
  samhainadmin.pl { -m F | --create-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 | --create-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.

  -p secretkeyring --secretkeyring secretkeyring
    Select an alternate secret keyring for gpg.
    Will use '$ENV{'HOME'}/.gnupg/secring.gpg' by default.

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

  -v            --verbose
    Verbose output.</PRE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="calling-external-programs.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="stealthmode.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Calling external programs</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Additional Features &mdash; Stealth</TD
></TR
></TABLE
></DIV
><!--#if expr="! ($HTTP_USER_AGENT = /MSIE/)"--><!--#include virtual="/resources/ssi/footer.html"--><!--#endif --></BODY
></HTML
>
samhain 3.1.0-5ubuntu1 / usr / share / doc / samhain / manual.html / signed-files.html
