source: trunk/docs/HOWTO-samhain+GnuPG.html@ 307

Last change on this file since 307 was 1, checked in by katerina, 19 years ago

Initial import

File size: 11.9 KB
RevLine 
[1]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<title>HOWTO samhain+GnuPG</title>
5<style type="text/css">
6<!--
7
8html { background: #eee; color: #000; }
9
10body { background: #eee; color: #000; margin: 0; padding: 0;}
11
12div.body {
13 background: #fff; color: #000;
14 margin: 0 1em 0 1em; padding: 1em;
15 font-family: serif;
16 font-size: 1em; line-height: 1.2em;
17 border-width: 0 1px 0 1px;
18 border-style: solid;
19 border-color: #aaa;
20}
21
22div.block {
23 background: #b6c5f2; color: #000;
24 margin: 1em; padding: 0 1em 0 1em;
25 border-width: 1px;
26 border-style: solid;
27 border-color: #2d4488;
28}
29
30div.warnblock {
31 background: #b6c5f2; color: #000;
32 margin: 1em; padding: 0 1em 0 1em;
33 border-width: 1px;
34 border-style: solid;
35 border-color: #FF9900;
36}
37
38table {
39 background: #F8F8F8; color: #000;
40 margin: 1em;
41 border-width: 0 0 0 1px;
42 border-style: solid;
43 border-color: #C0C0C0;
44}
45
46td {
47 border-width: 0 1px 1px 0;
48 border-style: solid;
49 border-color: #C0C0C0;
50}
51
52th {
53 background: #F8F8FF;
54 border-width: 1px 1px 2px 0;
55 border-style: solid;
56 border-color: #C0C0C0;
57}
58
59
60/* body text, headings, and rules */
61
62p { margin: 0; text-indent: 0em; margin: 0 0 0.5em 0 }
63
64h1, h2, h3, h4, h5, h6 {
65 color: #206020; background: transparent;
66 font-family: Optima, Arial, Helvetica, sans-serif;
67 font-weight: normal;
68}
69
70h1 { font-size: 1.69em; margin: 1.4em 0 0.4em 0; }
71h2 { font-size: 1.44em; margin: 1.4em 0 0.4em 0; }
72h3 { font-size: 1.21em; margin: 1.4em 0 0.4em 0; }
73h4 { font-size: 1.00em; margin: 1.4em 0 0.4em 0; }
74h5 { font-size: 0.81em; margin: 1.4em 0 0.4em 0; }
75h6 { font-size: 0.64em; margin: 1.4em 0 0.4em 0; }
76
77hr {
78 color: transparent; background: transparent;
79 height: 0px; margin: 0.6em 0;
80 border-width: 1px ;
81 border-style: solid;
82 border-color: #999;
83}
84
85/* bulleted lists and definition lists */
86
87ul { margin: 0 1em 0.6em 2em; padding: 0; }
88li { margin: 0.4em 0 0 0; }
89
90dl { margin: 0.6em 1em 0.6em 2em; }
91dt { color: #285577; }
92
93tt { color: #602020; }
94
95/* links */
96
97a.link {
98 color: #33c; background: transparent;
99 text-decoration: none;
100}
101
102a:hover {
103 color: #000; background: transparent;
104}
105
106body > a {
107 font-family: Optima, Arial, Helvetica, sans-serif;
108 font-size: 0.81em;
109}
110
111h1, h2, h3, h4, h5, h6 {
112 color: #2d5588; background: transparent;
113 font-family: Optima, Arial, Helvetica, sans-serif;
114 font-weight: normal;
115}
116
117 -->
118</style></head>
119
120<body>
121<div class="body">
122<p style="text-align: center; background: #ccc; border: 1px solid #2d5588;"><a
123 style="text-decoration: none;"
124 href="http://www.la-samhna.de/samhain/">samhain file integrity
125 scanner</a>&nbsp;|&nbsp;<a style="text-decoration: none;"
126 href="http://www.la-samhna.de/samhain/s_documentation.html">online
127 documentation</a></p>
128<br><center>
129<h1>Using samhain with GnuPG</h1>
130</center>
131<br>
132<hr>
133<p>
134This document aims to explain how to use samhain with <b>signed configuration
135and database files</b> which are checked by invoking GnuPG.
136</p>
137<h2>Introduction</h2>
138<p>
139Samhain can be compiled to recognize PGP signatures on configuration and
140database files and to invoke GnuPG in order to check such signatures.
141(<b>Note:</b> while the application usually is referred to as <i>GnuPG</i>,
142the executable itself is called <i>gpg</i>).
143</p>
144<p>
145If samhain is compiled with this option, then
146</p>
147
148<ol>
149<li>
150both the <i>configuration file</i>
151and the <i>file signature database</i> must be signed, and
152</li>
153<li>
154for both files the signatures must verify correctly,
155</li>
156<li>
157otherwise samhain will abort.
158</li>
159</ol>
160
161
162<h2>Prerequisites</h2>
163<ul>
164<li>
165<p>
166Obviously you need <i>gpg</i> (GnuPG), and you must
167have created a key pair with:
168</p><p>
169<tt>&nbsp; &nbsp;gpg --gen-key</tt>
170</p><p>
171(it does not really matter which type of key, the defaults are ok).
172</p><p>
173GnuPG uses a public-key algorithm: the key pair consists of
174</p>
175<ul>
176<li>
177a <i>secret key</i> that is
178used for signing and stored in <b>&#126;user/.gnupg/secring.gpg</b>, and
179</li><li>
180a <i>public key</i> used for verifying the signature, and stored in
181<b>&#126;user/.gnupg/pubring.gpg</b>.
182</li>
183</ul>
184<p>
185The secret key obviously should be
186kept secret, while the public key can be published.
187</p>
188</li>
189<li>
190<p>
191You need to compile samhain with support for GnuPG:
192</p><p>
193<tt>&nbsp; &nbsp;./configure --with-gpg=/path/to/gpg [more options]</tt>
194</p><p>
195</li>
196</ul>
197
198<p>
199<b>Note 1:</b> If compiled with support for GnuPG,
200the TIGER192 checksum of the gpg
201executable will be compiled into samhain, and the gpg executable will
202be checksummed (to verify its integrity) before invoking it. If you
203don't like this, you should add the <i>configure</i> option:
204</p><p>
205<tt>&nbsp; &nbsp;--with-checksum=no</tt>
206</p>
207<div class="warnblock">
208<p>
209Compiling in the GnuPG checksum will tie the samhain executable to
210the gpg executable. If you upgrade GnuPG, you will need to re-compile
211samhain. If you don't like this, use <tt>'--with-checksum=no'</tt>.
212</p>
213</div>
214<p>
215<b>Note 2:</b> The mere fact that the signature
216is correct does not prove that it has been signed by <i>you</i> with
217<i>your</i> key - it just proves that it has been signed by <i>somebody</i>.
218Samhain can optionally check the <i>fingerprint</i> of the key that has been
219used to sign the files, to verify that <i>your</i> key has been used
220to sign the file(s). To enable this, use the <i>configure</i> option
221</p><p>
222<tt>&nbsp; &nbsp;--with-fingerprint=FINGERPRINT</tt>
223</p><p>
224where FINGERPRINT is the hexadecimal fingerprint of the key as listed
225with
226</p><p>
227<tt>&nbsp; &nbsp;gpg --fingerprint</tt>
228</p>
229
230<h3>Example</h3>
231
232<pre style="background-color:#DDDDDD; color:#000000">
233
234rainer$ gpg --fingerprint rainer
235pub 1024D/0F571F6C 1999-10-31 Rainer Wichmann
236 Key fingerprint = EF6C EF54 701A 0AFD B86A F4C3 1AAD 26C8 0F57 1F6C
237uid Rainer Wichmann
238sub 1024g/9DACAC30 1999-10-31
239
240rainer$ which gpg
241/usr/bin/gpg
242
243rainer$ ./configure --with-gpg=/usr/bin/gpg --with-fingerprint=EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C
244
245</pre>
246
247<h2>Signing the files</h2>
248<p>
249The <i>configuration file</i> and the
250<i>file signature database</i>
251(created by running <tt>samhain -t init</tt>) must be signed manually
252using the command:
253</p><p>
254<tt>&nbsp; &nbsp;gpg -a --clearsign --not-dash-escaped /etc/samhainrc</tt><br/>
255<tt>&nbsp; &nbsp;mv /etc/samhainrc.asc /etc/samhainrc</tt>
256</p><p>
257<i>Gpg</i> will create a <i>signed copy</i> of the file,
258named <i>file.asc</i>.
259You need to <b>rename</b> (<tt>cp/mv</tt>) this signed copy
260to the original filename.
261After signing the configuration file, you can initialize the database
262and sign it likewise.
263</p>
264<p>
265<b>Note 1:</b> The installation script will ask you to
266sign the <i>configuration file</i> upon installation.
267</p><p>
268<b>Note 2:</b> The <i>gpg</i> option <tt>--not-dash-escaped</tt>
269does not harm if used with the
270<i>configuration file</i>, but is only required for the
271<i>file signature database</i>.
272</p>
273
274<h3>TIP</h3>
275<p>
276 In the subdirectory <tt>scripts/</tt> of the source directory you will find
277 a Perl script <b>samhainadmin.pl</b> to facilitate some
278 tasks related to the administration of signed configuration and
279 database files (e.g. examine/create/remove signatures).
280 Use with <i>--help</i> to get usage
281 information.
282</p>
283
284<h3>CAVEAT</h3>
285<p>
286 When signing, the option <i>--not-dash-escaped</i> is
287 recommended, because otherwise the database might get corrupted.
288 However, this implies that after a database update,
289 you <i>must</i> remove the old signature first, before
290 re-signing the database. Without 'dash escaping',
291 gpg will not properly handle the old signature.
292 See the tip just above.
293</p>
294
295<h3>Example</h3>
296
297<pre style="background-color:#DDDDDD; color:#000000">
298
299root# gpg -a --clearsign --not-dash-escaped /etc/samhainrc
300
301You need a passphrase to unlock the secret key for
302user: "Rainer Wichmann"
3031024-bit DSA key, ID 0F571F6C, created 1999-10-31
304
305root# mv /etc/samhainrc.asc /etc/samhainrc
306root# samhain -t init
307root# gpg -a --clearsign --not-dash-escaped /var/lib/samhain/samhain_file
308
309You need a passphrase to unlock the secret key for
310user: "Rainer Wichmann"
3111024-bit DSA key, ID 0F571F6C, created 1999-10-31
312
313root# mv /var/lib/samhain/samhain_file.asc /var/lib/samhain/samhain_file
314root# samhain -D -t check
315
316</pre>
317
318<h2>Make samhain verify the signature</h2>
319<p>
320This is the part where some people run into problems. The point is,
321when <i>gpg</i> is invoked by samhain, it must <i>find the public key</i>
322needed for verification. <i>Gpg</i> expects public keys in a file
323located at <b>&#126;user/.gnupg/pubring.gpg</b> where <b>&#126;user</b>
324is the home directory of the user as that <i>gpg</i> is running.
325</p><p>
326It is therefore <i>crucial</i> to include the public key corresponding
327to te secret key used for signing into the correct <b>pubring.gpg</b>
328file (this file can hold many public keys, e.g. of people sending you
329emails signed by them).
330</p><p>
331So which is the correct file? Here we have to consider two seperate
332cases:
333</p>
334<ol>
335<li>The client (or standalone) samhain daemon runs with UID 0 (i.e. root),
336thus the public key must be in <b>&#126;root/.gnupg/pubring.gpg</b>
337</li>
338<li>
339The server (yule) <i>always</i> drops root privileges (if started with), and
340runs as a <i>non-root user</i>. The username to use is compiled in,
341either with the <i>configure</i> option <tt>--enable-identity=USER</tt>,
342or by default as determined by <i>configure</i> (the first existing user
343out of the list <i>yule, daemon, nobody</i>). Thus, the public key
344must be in <b>&#126;root/.gnupg/pubring.gpg</b> (for startup) <i>and</i>
345in <b>&#126;non_root_user/.gnupg/pubring.gpg</b> (for reload with SIGHUP).
346</li>
347</ol>
348<p>
349To import a public key into the public
350keyring (pubring.gpg) of another user, you can do:
351</p><p>
352<tt>&nbsp; &nbsp;gpg --export KEY-ID > filename</tt><br>
353<tt>&nbsp; &nbsp;su another_user</tt><br>
354<tt>&nbsp; &nbsp;gpg --import filename</tt>
355</p>
356<p>
357<b>Note:</b> samhain will invoke <i>gpg</i> with the options:
358</p><p>
359<tt>&nbsp; &nbsp;--status-fd 1 --verify --homedir /homedir/.gnupg --no-tty -</tt>
360</p><p>
361and pipe the configuration/database file into <i>gpg</i>, similar to:
362</p><p>
363<tt>cat filename | /usr/bin/gpg --status-fd 1 --verify --homedir /root/.gnupg --no-tty -</tt>
364</p><p>
365(of course samhain does not invoke cat, or the shell; the example above
366just shows how to do the same from the shell command prompt).
367</p>
368
369<h3>Example for signature check</h3>
370<p>
371If you want to check the signature the same way samhain does, it should look
372like (note the GOODSIG and VALIDSIG keywords in the output):
373</p>
374<pre style="background-color:#DDDDDD; color:#000000">
375
376root# cat /etc/samhainrc | gpg --status-fd 1 --verify --homedir /root/.gnupg --no-tty -
377gpg: Signature made Sat Mar 15 16:08:21 2003 CET using DSA key ID 0F571F6C
378[GNUPG:] SIG_ID 9hQvRhgjWLqyFzVOHi2b0uDmBFo 2003-03-15 1047740901
379[GNUPG:] GOODSIG 1AAD26C80F571F6C Rainer Wichmann
380gpg: Good signature from "Rainer Wichmann"
381gpg: aka "Rainer Wichmann"
382[GNUPG:] VALIDSIG EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C 2003-03-15 1047740901
383[GNUPG:] TRUST_ULTIMATE
384
385</pre>
386
387<h2>Troubleshooting</h2>
388<p>
389First and foremost, run samhain (or yule) from the command line, in non-daemon
390mode, and with the command-line option <tt>-p debug</tt> for debug-level
391output. This will print
392descriptive information on setup errors and/or relevant output from
393the GnuPG subprocess.
394</p>
395<p>
396Output from the GnuPG subprocess is marked by <b>[GNUPG:]</b>, and
397may show the following errors:
398</p>
399
400<ul>
401<li><b>ERRSIG</b> and/or <b>NO_PUBKEY</b> indicates that gpg did not find
402 the public key to verify the signature. You should import that key
403 into the keyrings of root and (for yule additionaly) the yule user.
404</li>
405<li><b>BADSIG</b> indicates that the public key was found by gpg, but
406 the signature is invalid. Either the file has been modified after
407 signing, or a previous signature has not been removed.
408</li>
409<li><b>NODATA</b> indicates that there is no signed data, i.e. the
410 configuration or database file is not signed at all.
411</li>
412</ul>
413</div>
414</body>
415</html>
Note: See TracBrowser for help on using the repository browser.