| 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 |
|
|---|
| 8 | html { background: #eee; color: #000; }
|
|---|
| 9 |
|
|---|
| 10 | body { background: #eee; color: #000; margin: 0; padding: 0;}
|
|---|
| 11 |
|
|---|
| 12 | div.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 |
|
|---|
| 22 | div.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 |
|
|---|
| 30 | div.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 |
|
|---|
| 38 | table {
|
|---|
| 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 |
|
|---|
| 46 | td {
|
|---|
| 47 | border-width: 0 1px 1px 0;
|
|---|
| 48 | border-style: solid;
|
|---|
| 49 | border-color: #C0C0C0;
|
|---|
| 50 | }
|
|---|
| 51 |
|
|---|
| 52 | th {
|
|---|
| 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 |
|
|---|
| 62 | p { margin: 0; text-indent: 0em; margin: 0 0 0.5em 0 }
|
|---|
| 63 |
|
|---|
| 64 | h1, h2, h3, h4, h5, h6 {
|
|---|
| 65 | color: #206020; background: transparent;
|
|---|
| 66 | font-family: Optima, Arial, Helvetica, sans-serif;
|
|---|
| 67 | font-weight: normal;
|
|---|
| 68 | }
|
|---|
| 69 |
|
|---|
| 70 | h1 { font-size: 1.69em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 71 | h2 { font-size: 1.44em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 72 | h3 { font-size: 1.21em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 73 | h4 { font-size: 1.00em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 74 | h5 { font-size: 0.81em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 75 | h6 { font-size: 0.64em; margin: 1.4em 0 0.4em 0; }
|
|---|
| 76 |
|
|---|
| 77 | hr {
|
|---|
| 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 |
|
|---|
| 87 | ul { margin: 0 1em 0.6em 2em; padding: 0; }
|
|---|
| 88 | li { margin: 0.4em 0 0 0; }
|
|---|
| 89 |
|
|---|
| 90 | dl { margin: 0.6em 1em 0.6em 2em; }
|
|---|
| 91 | dt { color: #285577; }
|
|---|
| 92 |
|
|---|
| 93 | tt { color: #602020; }
|
|---|
| 94 |
|
|---|
| 95 | /* links */
|
|---|
| 96 |
|
|---|
| 97 | a.link {
|
|---|
| 98 | color: #33c; background: transparent;
|
|---|
| 99 | text-decoration: none;
|
|---|
| 100 | }
|
|---|
| 101 |
|
|---|
| 102 | a:hover {
|
|---|
| 103 | color: #000; background: transparent;
|
|---|
| 104 | }
|
|---|
| 105 |
|
|---|
| 106 | body > a {
|
|---|
| 107 | font-family: Optima, Arial, Helvetica, sans-serif;
|
|---|
| 108 | font-size: 0.81em;
|
|---|
| 109 | }
|
|---|
| 110 |
|
|---|
| 111 | h1, 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> | <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>
|
|---|
| 134 | This document aims to explain how to use samhain with <b>signed configuration
|
|---|
| 135 | and database files</b> which are checked by invoking GnuPG.
|
|---|
| 136 | </p>
|
|---|
| 137 | <h2>Introduction</h2>
|
|---|
| 138 | <p>
|
|---|
| 139 | Samhain can be compiled to recognize PGP signatures on configuration and
|
|---|
| 140 | database 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>,
|
|---|
| 142 | the executable itself is called <i>gpg</i>).
|
|---|
| 143 | </p>
|
|---|
| 144 | <p>
|
|---|
| 145 | If samhain is compiled with this option, then
|
|---|
| 146 | </p>
|
|---|
| 147 |
|
|---|
| 148 | <ol>
|
|---|
| 149 | <li>
|
|---|
| 150 | both the <i>configuration file</i>
|
|---|
| 151 | and the <i>file signature database</i> must be signed, and
|
|---|
| 152 | </li>
|
|---|
| 153 | <li>
|
|---|
| 154 | for both files the signatures must verify correctly,
|
|---|
| 155 | </li>
|
|---|
| 156 | <li>
|
|---|
| 157 | otherwise samhain will abort.
|
|---|
| 158 | </li>
|
|---|
| 159 | </ol>
|
|---|
| 160 |
|
|---|
| 161 |
|
|---|
| 162 | <h2>Prerequisites</h2>
|
|---|
| 163 | <ul>
|
|---|
| 164 | <li>
|
|---|
| 165 | <p>
|
|---|
| 166 | Obviously you need <i>gpg</i> (GnuPG), and you must
|
|---|
| 167 | have created a key pair with:
|
|---|
| 168 | </p><p>
|
|---|
| 169 | <tt> gpg --gen-key</tt>
|
|---|
| 170 | </p><p>
|
|---|
| 171 | (it does not really matter which type of key, the defaults are ok).
|
|---|
| 172 | </p><p>
|
|---|
| 173 | GnuPG uses a public-key algorithm: the key pair consists of
|
|---|
| 174 | </p>
|
|---|
| 175 | <ul>
|
|---|
| 176 | <li>
|
|---|
| 177 | a <i>secret key</i> that is
|
|---|
| 178 | used for signing and stored in <b>~user/.gnupg/secring.gpg</b>, and
|
|---|
| 179 | </li><li>
|
|---|
| 180 | a <i>public key</i> used for verifying the signature, and stored in
|
|---|
| 181 | <b>~user/.gnupg/pubring.gpg</b>.
|
|---|
| 182 | </li>
|
|---|
| 183 | </ul>
|
|---|
| 184 | <p>
|
|---|
| 185 | The secret key obviously should be
|
|---|
| 186 | kept secret, while the public key can be published.
|
|---|
| 187 | </p>
|
|---|
| 188 | </li>
|
|---|
| 189 | <li>
|
|---|
| 190 | <p>
|
|---|
| 191 | You need to compile samhain with support for GnuPG:
|
|---|
| 192 | </p><p>
|
|---|
| 193 | <tt> ./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,
|
|---|
| 200 | the TIGER192 checksum of the gpg
|
|---|
| 201 | executable will be compiled into samhain, and the gpg executable will
|
|---|
| 202 | be checksummed (to verify its integrity) before invoking it. If you
|
|---|
| 203 | don't like this, you should add the <i>configure</i> option:
|
|---|
| 204 | </p><p>
|
|---|
| 205 | <tt> --with-checksum=no</tt>
|
|---|
| 206 | </p>
|
|---|
| 207 | <div class="warnblock">
|
|---|
| 208 | <p>
|
|---|
| 209 | Compiling in the GnuPG checksum will tie the samhain executable to
|
|---|
| 210 | the gpg executable. If you upgrade GnuPG, you will need to re-compile
|
|---|
| 211 | samhain. 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
|
|---|
| 216 | is 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>.
|
|---|
| 218 | Samhain can optionally check the <i>fingerprint</i> of the key that has been
|
|---|
| 219 | used to sign the files, to verify that <i>your</i> key has been used
|
|---|
| 220 | to sign the file(s). To enable this, use the <i>configure</i> option
|
|---|
| 221 | </p><p>
|
|---|
| 222 | <tt> --with-fingerprint=FINGERPRINT</tt>
|
|---|
| 223 | </p><p>
|
|---|
| 224 | where FINGERPRINT is the hexadecimal fingerprint of the key as listed
|
|---|
| 225 | with
|
|---|
| 226 | </p><p>
|
|---|
| 227 | <tt> gpg --fingerprint</tt>
|
|---|
| 228 | </p>
|
|---|
| 229 |
|
|---|
| 230 | <h3>Example</h3>
|
|---|
| 231 |
|
|---|
| 232 | <pre style="background-color:#DDDDDD; color:#000000">
|
|---|
| 233 |
|
|---|
| 234 | rainer$ gpg --fingerprint rainer
|
|---|
| 235 | pub 1024D/0F571F6C 1999-10-31 Rainer Wichmann
|
|---|
| 236 | Key fingerprint = EF6C EF54 701A 0AFD B86A F4C3 1AAD 26C8 0F57 1F6C
|
|---|
| 237 | uid Rainer Wichmann
|
|---|
| 238 | sub 1024g/9DACAC30 1999-10-31
|
|---|
| 239 |
|
|---|
| 240 | rainer$ which gpg
|
|---|
| 241 | /usr/bin/gpg
|
|---|
| 242 |
|
|---|
| 243 | rainer$ ./configure --with-gpg=/usr/bin/gpg --with-fingerprint=EF6CEF54701A0AFDB86AF4C31AAD26C80F571F6C
|
|---|
| 244 |
|
|---|
| 245 | </pre>
|
|---|
| 246 |
|
|---|
| 247 | <h2>Signing the files</h2>
|
|---|
| 248 | <p>
|
|---|
| 249 | The <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
|
|---|
| 252 | using the command:
|
|---|
| 253 | </p><p>
|
|---|
| 254 | <tt> gpg -a --clearsign --not-dash-escaped /etc/samhainrc</tt><br/>
|
|---|
| 255 | <tt> mv /etc/samhainrc.asc /etc/samhainrc</tt>
|
|---|
| 256 | </p><p>
|
|---|
| 257 | <i>Gpg</i> will create a <i>signed copy</i> of the file,
|
|---|
| 258 | named <i>file.asc</i>.
|
|---|
| 259 | You need to <b>rename</b> (<tt>cp/mv</tt>) this signed copy
|
|---|
| 260 | to the original filename.
|
|---|
| 261 | After signing the configuration file, you can initialize the database
|
|---|
| 262 | and sign it likewise.
|
|---|
| 263 | </p>
|
|---|
| 264 | <p>
|
|---|
| 265 | <b>Note 1:</b> The installation script will ask you to
|
|---|
| 266 | sign 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>
|
|---|
| 269 | does 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 |
|
|---|
| 299 | root# gpg -a --clearsign --not-dash-escaped /etc/samhainrc
|
|---|
| 300 |
|
|---|
| 301 | You need a passphrase to unlock the secret key for
|
|---|
| 302 | user: "Rainer Wichmann"
|
|---|
| 303 | 1024-bit DSA key, ID 0F571F6C, created 1999-10-31
|
|---|
| 304 |
|
|---|
| 305 | root# mv /etc/samhainrc.asc /etc/samhainrc
|
|---|
| 306 | root# samhain -t init
|
|---|
| 307 | root# gpg -a --clearsign --not-dash-escaped /var/lib/samhain/samhain_file
|
|---|
| 308 |
|
|---|
| 309 | You need a passphrase to unlock the secret key for
|
|---|
| 310 | user: "Rainer Wichmann"
|
|---|
| 311 | 1024-bit DSA key, ID 0F571F6C, created 1999-10-31
|
|---|
| 312 |
|
|---|
| 313 | root# mv /var/lib/samhain/samhain_file.asc /var/lib/samhain/samhain_file
|
|---|
| 314 | root# samhain -D -t check
|
|---|
| 315 |
|
|---|
| 316 | </pre>
|
|---|
| 317 |
|
|---|
| 318 | <h2>Make samhain verify the signature</h2>
|
|---|
| 319 | <p>
|
|---|
| 320 | This is the part where some people run into problems. The point is,
|
|---|
| 321 | when <i>gpg</i> is invoked by samhain, it must <i>find the public key</i>
|
|---|
| 322 | needed for verification. <i>Gpg</i> expects public keys in a file
|
|---|
| 323 | located at <b>~user/.gnupg/pubring.gpg</b> where <b>~user</b>
|
|---|
| 324 | is the home directory of the user as that <i>gpg</i> is running.
|
|---|
| 325 | </p><p>
|
|---|
| 326 | It is therefore <i>crucial</i> to include the public key corresponding
|
|---|
| 327 | to te secret key used for signing into the correct <b>pubring.gpg</b>
|
|---|
| 328 | file (this file can hold many public keys, e.g. of people sending you
|
|---|
| 329 | emails signed by them).
|
|---|
| 330 | </p><p>
|
|---|
| 331 | So which is the correct file? Here we have to consider two separate
|
|---|
| 332 | cases:
|
|---|
| 333 | </p>
|
|---|
| 334 | <ol>
|
|---|
| 335 | <li>The client (or standalone) samhain daemon runs with UID 0 (i.e. root),
|
|---|
| 336 | thus the public key must be in <b>~root/.gnupg/pubring.gpg</b>
|
|---|
| 337 | </li>
|
|---|
| 338 | <li>
|
|---|
| 339 | The server (yule) <i>always</i> drops root privileges (if started with), and
|
|---|
| 340 | runs as a <i>non-root user</i>. The username to use is compiled in,
|
|---|
| 341 | either with the <i>configure</i> option <tt>--enable-identity=USER</tt>,
|
|---|
| 342 | or by default as determined by <i>configure</i> (the first existing user
|
|---|
| 343 | out of the list <i>yule, daemon, nobody</i>). Thus, the public key
|
|---|
| 344 | must be in <b>~root/.gnupg/pubring.gpg</b> (for startup) <i>and</i>
|
|---|
| 345 | in <b>~non_root_user/.gnupg/pubring.gpg</b> (for reload with SIGHUP).
|
|---|
| 346 | </li>
|
|---|
| 347 | </ol>
|
|---|
| 348 | <p>
|
|---|
| 349 | To import a public key into the public
|
|---|
| 350 | keyring (pubring.gpg) of another user, you can do:
|
|---|
| 351 | </p><p>
|
|---|
| 352 | <tt> gpg --export KEY-ID > filename</tt><br>
|
|---|
| 353 | <tt> su another_user</tt><br>
|
|---|
| 354 | <tt> 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> --status-fd 1 --verify --homedir /homedir/.gnupg --no-tty -</tt>
|
|---|
| 360 | </p><p>
|
|---|
| 361 | and 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
|
|---|
| 366 | just shows how to do the same from the shell command prompt).
|
|---|
| 367 | </p>
|
|---|
| 368 |
|
|---|
| 369 | <h3>Example for signature check</h3>
|
|---|
| 370 | <p>
|
|---|
| 371 | If you want to check the signature the same way samhain does, it should look
|
|---|
| 372 | like (note the GOODSIG and VALIDSIG keywords in the output):
|
|---|
| 373 | </p>
|
|---|
| 374 | <pre style="background-color:#DDDDDD; color:#000000">
|
|---|
| 375 |
|
|---|
| 376 | root# cat /etc/samhainrc | gpg --status-fd 1 --verify --homedir /root/.gnupg --no-tty -
|
|---|
| 377 | gpg: 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
|
|---|
| 380 | gpg: Good signature from "Rainer Wichmann"
|
|---|
| 381 | gpg: 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>
|
|---|
| 389 | First and foremost, run samhain (or yule) from the command line, in non-daemon
|
|---|
| 390 | mode, and with the command-line option <tt>-p debug</tt> for debug-level
|
|---|
| 391 | output. This will print
|
|---|
| 392 | descriptive information on setup errors and/or relevant output from
|
|---|
| 393 | the GnuPG subprocess.
|
|---|
| 394 | </p>
|
|---|
| 395 | <p>
|
|---|
| 396 | Output from the GnuPG subprocess is marked by <b>[GNUPG:]</b>, and
|
|---|
| 397 | may 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>
|
|---|
