/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugins.d/password-request.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-09-03 17:34:29 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080903173429-db2mjtddf7mgbx8z
* plugins.d/password-request.xml (OVERVIEW): Refer to
                                             password-prompt(8) by
                                             name.
  (SECURITY): Improved wording.  Add paragraph about insecurity of
              ping.
  (SEE ALSO): Add references to cryptsetup(8) and crypttab(5).
              Changed to be a <variablelist> and added text.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/password-request.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY COMMANDNAME "mandos-client">
5
 
<!ENTITY TIMESTAMP "2009-02-09">
6
 
<!ENTITY % common SYSTEM "../common.ent">
7
 
%common;
 
4
<!ENTITY VERSION "1.0">
 
5
<!ENTITY COMMANDNAME "password-request">
 
6
<!ENTITY TIMESTAMP "2008-09-03">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
10
  <refentryinfo>
12
11
    <title>Mandos Manual</title>
13
 
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
34
      <holder>Teddy Hogeborn</holder>
37
35
      <holder>Björn Påhlsson</holder>
38
36
    </copyright>
39
37
    <xi:include href="../legalnotice.xml"/>
40
38
  </refentryinfo>
41
 
  
 
39
 
42
40
  <refmeta>
43
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
44
42
    <manvolnum>8mandos</manvolnum>
47
45
  <refnamediv>
48
46
    <refname><command>&COMMANDNAME;</command></refname>
49
47
    <refpurpose>
50
 
      Client for <application>Mandos</application>
 
48
      Client for mandos
51
49
    </refpurpose>
52
50
  </refnamediv>
53
 
  
 
51
 
54
52
  <refsynopsisdiv>
55
53
    <cmdsynopsis>
56
54
      <command>&COMMANDNAME;</command>
57
55
      <group>
58
56
        <arg choice="plain"><option>--connect
59
 
        <replaceable>ADDRESS</replaceable><literal>:</literal
 
57
        <replaceable>IPADDR</replaceable><literal>:</literal
60
58
        ><replaceable>PORT</replaceable></option></arg>
61
59
        <arg choice="plain"><option>-c
62
 
        <replaceable>ADDRESS</replaceable><literal>:</literal
 
60
        <replaceable>IPADDR</replaceable><literal>:</literal
63
61
        ><replaceable>PORT</replaceable></option></arg>
64
62
      </group>
65
63
      <sbr/>
66
64
      <group>
 
65
        <arg choice="plain"><option>--keydir
 
66
        <replaceable>DIRECTORY</replaceable></option></arg>
 
67
        <arg choice="plain"><option>-d
 
68
        <replaceable>DIRECTORY</replaceable></option></arg>
 
69
      </group>
 
70
      <sbr/>
 
71
      <group>
67
72
        <arg choice="plain"><option>--interface
68
73
        <replaceable>NAME</replaceable></option></arg>
69
74
        <arg choice="plain"><option>-i
93
98
      </arg>
94
99
      <sbr/>
95
100
      <arg>
96
 
        <option>--delay <replaceable>SECONDS</replaceable></option>
97
 
      </arg>
98
 
      <sbr/>
99
 
      <arg>
100
101
        <option>--debug</option>
101
102
      </arg>
102
103
    </cmdsynopsis>
119
120
      </group>
120
121
    </cmdsynopsis>
121
122
  </refsynopsisdiv>
122
 
  
 
123
 
123
124
  <refsect1 id="description">
124
125
    <title>DESCRIPTION</title>
125
126
    <para>
126
127
      <command>&COMMANDNAME;</command> is a client program that
127
128
      communicates with <citerefentry><refentrytitle
128
129
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
129
 
      to get a password.  In slightly more detail, this client program
130
 
      brings up a network interface, uses the interface’s IPv6
131
 
      link-local address to get network connectivity, uses Zeroconf to
132
 
      find servers on the local network, and communicates with servers
133
 
      using TLS with an OpenPGP key to ensure authenticity and
134
 
      confidentiality.  This client program keeps running, trying all
135
 
      servers on the network, until it receives a satisfactory reply
136
 
      or a TERM signal is received.  If no servers are found, or after
137
 
      all servers have been tried, it waits indefinitely for new
138
 
      servers to appear.
 
130
      to get a password.  It uses IPv6 link-local addresses to get
 
131
      network connectivity, Zeroconf to find servers, and TLS with an
 
132
      OpenPGP key to ensure authenticity and confidentiality.  It
 
133
      keeps running, trying all servers on the network, until it
 
134
      receives a satisfactory reply or a TERM signal is recieved.
139
135
    </para>
140
136
    <para>
141
137
      This program is not meant to be run directly; it is really meant
195
191
      </varlistentry>
196
192
      
197
193
      <varlistentry>
198
 
        <term><option>--interface=<replaceable
199
 
        >NAME</replaceable></option></term>
 
194
        <term><option>--keydir=<replaceable
 
195
        >DIRECTORY</replaceable></option></term>
 
196
        <term><option>-d
 
197
        <replaceable>DIRECTORY</replaceable></option></term>
 
198
        <listitem>
 
199
          <para>
 
200
            Directory to read the OpenPGP key files
 
201
            <filename>pubkey.txt</filename> and
 
202
            <filename>seckey.txt</filename> from.  The default is
 
203
            <filename>/conf/conf.d/mandos</filename> (in the initial
 
204
            <acronym>RAM</acronym> disk environment).
 
205
          </para>
 
206
        </listitem>
 
207
      </varlistentry>
 
208
 
 
209
      <varlistentry>
 
210
        <term><option>--interface=
 
211
        <replaceable>NAME</replaceable></option></term>
200
212
        <term><option>-i
201
213
        <replaceable>NAME</replaceable></option></term>
202
214
        <listitem>
203
215
          <para>
204
216
            Network interface that will be brought up and scanned for
205
 
            Mandos servers to connect to.  The default is the empty
206
 
            string, which will automatically choose an appropriate
207
 
            interface.
 
217
            Mandos servers to connect to.  The default it
 
218
            <quote><literal>eth0</literal></quote>.
208
219
          </para>
209
220
          <para>
210
221
            If the <option>--connect</option> option is used, this
211
222
            specifies the interface to use to connect to the address
212
223
            given.
213
224
          </para>
214
 
          <para>
215
 
            Note that since this program will normally run in the
216
 
            initial RAM disk environment, the interface must be an
217
 
            interface which exists at that stage.  Thus, the interface
218
 
            can not be a pseudo-interface such as <quote>br0</quote>
219
 
            or <quote>tun0</quote>; such interfaces will not exist
220
 
            until much later in the boot process, and can not be used
221
 
            by this program.
222
 
          </para>
223
 
          <para>
224
 
            <replaceable>NAME</replaceable> can be the string
225
 
            <quote><literal>none</literal></quote>; this will not use
226
 
            any specific interface, and will not bring up an interface
227
 
            on startup.  This is not recommended, and only meant for
228
 
            advanced users.
229
 
          </para>
230
225
        </listitem>
231
226
      </varlistentry>
232
227
      
237
232
        <replaceable>FILE</replaceable></option></term>
238
233
        <listitem>
239
234
          <para>
240
 
            OpenPGP public key file name.  The default name is
241
 
            <quote><filename>/conf/conf.d/mandos/pubkey.txt</filename
242
 
            ></quote>.
 
235
            OpenPGP public key file base name.  This will be combined
 
236
            with the directory from the <option>--keydir</option>
 
237
            option to form an absolute file name.  The default name is
 
238
            <quote><literal>pubkey.txt</literal></quote>.
243
239
          </para>
244
240
        </listitem>
245
241
      </varlistentry>
246
 
      
 
242
 
247
243
      <varlistentry>
248
244
        <term><option>--seckey=<replaceable
249
245
        >FILE</replaceable></option></term>
251
247
        <replaceable>FILE</replaceable></option></term>
252
248
        <listitem>
253
249
          <para>
254
 
            OpenPGP secret key file name.  The default name is
255
 
            <quote><filename>/conf/conf.d/mandos/seckey.txt</filename
256
 
            ></quote>.
 
250
            OpenPGP secret key file base name.  This will be combined
 
251
            with the directory from the <option>--keydir</option>
 
252
            option to form an absolute file name.  The default name is
 
253
            <quote><literal>seckey.txt</literal></quote>.
257
254
          </para>
258
255
        </listitem>
259
256
      </varlistentry>
266
263
                      xpointer="priority"/>
267
264
        </listitem>
268
265
      </varlistentry>
269
 
      
 
266
 
270
267
      <varlistentry>
271
268
        <term><option>--dh-bits=<replaceable
272
269
        >BITS</replaceable></option></term>
277
274
          </para>
278
275
        </listitem>
279
276
      </varlistentry>
280
 
 
281
 
      <varlistentry>
282
 
        <term><option>--delay=<replaceable
283
 
        >SECONDS</replaceable></option></term>
284
 
        <listitem>
285
 
          <para>
286
 
            After bringing the network interface up, the program waits
287
 
            for the interface to arrive in a <quote>running</quote>
288
 
            state before proceeding.  During this time, the kernel log
289
 
            level will be lowered to reduce clutter on the system
290
 
            console, alleviating any other plugins which might be
291
 
            using the system console.  This option sets the upper
292
 
            limit of seconds to wait.  The default is 2.5 seconds.
293
 
          </para>
294
 
        </listitem>
295
 
      </varlistentry>
296
277
      
297
278
      <varlistentry>
298
279
        <term><option>--debug</option></term>
328
309
          </para>
329
310
        </listitem>
330
311
      </varlistentry>
331
 
      
 
312
 
332
313
      <varlistentry>
333
314
        <term><option>--version</option></term>
334
315
        <term><option>-V</option></term>
340
321
      </varlistentry>
341
322
    </variablelist>
342
323
  </refsect1>
343
 
  
 
324
 
344
325
  <refsect1 id="overview">
345
326
    <title>OVERVIEW</title>
346
327
    <xi:include href="../overview.xml"/>
355
336
      <filename>/etc/crypttab</filename>, but it would then be
356
337
      impossible to enter a password for the encrypted root disk at
357
338
      the console, since this program does not read from the console
358
 
      at all.  This is why a separate plugin runner (<citerefentry>
359
 
      <refentrytitle>plugin-runner</refentrytitle>
360
 
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
361
 
      both this program and others in in parallel,
362
 
      <emphasis>one</emphasis> of which will prompt for passwords on
363
 
      the system console.
 
339
      at all.  This is why a separate plugin (<citerefentry>
 
340
      <refentrytitle>password-prompt</refentrytitle>
 
341
      <manvolnum>8mandos</manvolnum></citerefentry>) does that, which
 
342
      will be run in parallell to this one by the plugin runner.
364
343
    </para>
365
344
  </refsect1>
366
345
  
373
352
      program will exit with a non-zero exit status only if a critical
374
353
      error occurs.  Otherwise, it will forever connect to new
375
354
      <application>Mandos</application> servers as they appear, trying
376
 
      to get a decryptable password and print it.
 
355
      to get a decryptable password.
377
356
    </para>
378
357
  </refsect1>
379
358
  
387
366
    </para>
388
367
  </refsect1>
389
368
  
390
 
  <refsect1 id="files">
 
369
  <refsect1 id="file">
391
370
    <title>FILES</title>
392
371
    <variablelist>
393
372
      <varlistentry>
412
391
<!--     <para> -->
413
392
<!--     </para> -->
414
393
<!--   </refsect1> -->
415
 
  
 
394
 
416
395
  <refsect1 id="example">
417
396
    <title>EXAMPLE</title>
418
397
    <para>
432
411
    </informalexample>
433
412
    <informalexample>
434
413
      <para>
435
 
        Search for Mandos servers (and connect to them) using another
436
 
        interface:
 
414
        Search for Mandos servers on another interface:
437
415
      </para>
438
416
      <para>
439
417
        <!-- do not wrap this line -->
442
420
    </informalexample>
443
421
    <informalexample>
444
422
      <para>
445
 
        Run in debug mode, and use a custom key:
 
423
        Run in debug mode, and use a custom key directory:
446
424
      </para>
447
425
      <para>
448
 
 
449
 
<!-- do not wrap this line -->
450
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
451
 
 
 
426
        <!-- do not wrap this line -->
 
427
        <userinput>&COMMANDNAME; --debug --keydir keydir</userinput>
452
428
      </para>
453
429
    </informalexample>
454
430
    <informalexample>
455
431
      <para>
456
 
        Run in debug mode, with a custom key, and do not use Zeroconf
457
 
        to locate a server; connect directly to the IPv6 link-local
 
432
        Run in debug mode, with a custom key directory, and do not use
 
433
        Zeroconf to locate a server; connect directly to the IPv6
458
434
        address <quote><systemitem class="ipaddress"
459
 
        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
460
 
        using interface eth2:
 
435
        >2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
 
436
        port 4711, using interface eth2:
461
437
      </para>
462
438
      <para>
463
439
 
464
440
<!-- do not wrap this line -->
465
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
 
441
<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
466
442
 
467
443
      </para>
468
444
    </informalexample>
469
445
  </refsect1>
470
 
  
 
446
 
471
447
  <refsect1 id="security">
472
448
    <title>SECURITY</title>
473
449
    <para>
493
469
      The only remaining weak point is that someone with physical
494
470
      access to the client hard drive might turn off the client
495
471
      computer, read the OpenPGP keys directly from the hard drive,
496
 
      and communicate with the server.  To safeguard against this, the
497
 
      server is supposed to notice the client disappearing and stop
498
 
      giving out the encrypted data.  Therefore, it is important to
499
 
      set the timeout and checker interval values tightly on the
500
 
      server.  See <citerefentry><refentrytitle
 
472
      and communicate with the server.  The defense against this is
 
473
      that the server is supposed to notice the client disappearing
 
474
      and will stop giving out the encrypted data.  Therefore, it is
 
475
      important to set the timeout and checker interval values tightly
 
476
      on the server.  See <citerefentry><refentrytitle
501
477
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
502
478
    </para>
503
479
    <para>
514
490
      confidential.
515
491
    </para>
516
492
  </refsect1>
517
 
  
 
493
 
518
494
  <refsect1 id="see_also">
519
495
    <title>SEE ALSO</title>
520
496
    <para>
645
621
      </varlistentry>
646
622
    </variablelist>
647
623
  </refsect1>
 
624
 
648
625
</refentry>
649
 
 
650
626
<!-- Local Variables: -->
651
627
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
652
628
<!-- time-stamp-end: "[\"']>" -->