/mandos/trunk

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

« back to all changes in this revision

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

merge

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 "2011-10-03">
6
 
<!ENTITY % common SYSTEM "../common.ent">
7
 
%common;
 
4
<!ENTITY VERSION "1.0">
 
5
<!ENTITY COMMANDNAME "password-request">
 
6
<!ENTITY TIMESTAMP "2008-09-04">
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>
19
18
        <firstname>Björn</firstname>
20
19
        <surname>Påhlsson</surname>
21
20
        <address>
22
 
          <email>belorn@recompile.se</email>
 
21
          <email>belorn@fukt.bsnet.se</email>
23
22
        </address>
24
23
      </author>
25
24
      <author>
26
25
        <firstname>Teddy</firstname>
27
26
        <surname>Hogeborn</surname>
28
27
        <address>
29
 
          <email>teddy@recompile.se</email>
 
28
          <email>teddy@fukt.bsnet.se</email>
30
29
        </address>
31
30
      </author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
 
      <year>2011</year>
37
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
37
    <xi:include href="../legalnotice.xml"/>
41
38
  </refentryinfo>
42
 
  
 
39
 
43
40
  <refmeta>
44
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
42
    <manvolnum>8mandos</manvolnum>
48
45
  <refnamediv>
49
46
    <refname><command>&COMMANDNAME;</command></refname>
50
47
    <refpurpose>
51
 
      Client for <application>Mandos</application>
 
48
      Client for mandos
52
49
    </refpurpose>
53
50
  </refnamediv>
54
 
  
 
51
 
55
52
  <refsynopsisdiv>
56
53
    <cmdsynopsis>
57
54
      <command>&COMMANDNAME;</command>
94
91
      </arg>
95
92
      <sbr/>
96
93
      <arg>
97
 
        <option>--delay <replaceable>SECONDS</replaceable></option>
98
 
      </arg>
99
 
      <sbr/>
100
 
      <arg>
101
 
        <option>--retry <replaceable>SECONDS</replaceable></option>
102
 
      </arg>
103
 
      <sbr/>
104
 
      <arg>
105
 
        <option>--network-hook-dir<replaceable>DIR</replaceable></option>
106
 
      </arg>
107
 
      <sbr/>
108
 
      <arg>
109
94
        <option>--debug</option>
110
95
      </arg>
111
96
    </cmdsynopsis>
128
113
      </group>
129
114
    </cmdsynopsis>
130
115
  </refsynopsisdiv>
131
 
  
 
116
 
132
117
  <refsect1 id="description">
133
118
    <title>DESCRIPTION</title>
134
119
    <para>
135
120
      <command>&COMMANDNAME;</command> is a client program that
136
121
      communicates with <citerefentry><refentrytitle
137
122
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
138
 
      to get a password.  In slightly more detail, this client program
139
 
      brings up a network interface, uses the interface’s IPv6
140
 
      link-local address to get network connectivity, uses Zeroconf to
141
 
      find servers on the local network, and communicates with servers
142
 
      using TLS with an OpenPGP key to ensure authenticity and
143
 
      confidentiality.  This client program keeps running, trying all
144
 
      servers on the network, until it receives a satisfactory reply
145
 
      or a TERM signal.  After all servers have been tried, all
146
 
      servers are periodically retried.  If no servers are found it
147
 
      will wait indefinitely for new servers to appear.
 
123
      to get a password.  It uses IPv6 link-local addresses to get
 
124
      network connectivity, Zeroconf to find servers, and TLS with an
 
125
      OpenPGP key to ensure authenticity and confidentiality.  It
 
126
      keeps running, trying all servers on the network, until it
 
127
      receives a satisfactory reply or a TERM signal is received.
148
128
    </para>
149
129
    <para>
150
130
      This program is not meant to be run directly; it is really meant
204
184
      </varlistentry>
205
185
      
206
186
      <varlistentry>
207
 
        <term><option>--interface=<replaceable
208
 
        >NAME</replaceable></option></term>
 
187
        <term><option>--interface=
 
188
        <replaceable>NAME</replaceable></option></term>
209
189
        <term><option>-i
210
190
        <replaceable>NAME</replaceable></option></term>
211
191
        <listitem>
212
192
          <para>
213
193
            Network interface that will be brought up and scanned for
214
 
            Mandos servers to connect to.  The default is the empty
215
 
            string, which will automatically choose an appropriate
216
 
            interface.
 
194
            Mandos servers to connect to.  The default it
 
195
            <quote><literal>eth0</literal></quote>.
217
196
          </para>
218
197
          <para>
219
198
            If the <option>--connect</option> option is used, this
220
199
            specifies the interface to use to connect to the address
221
200
            given.
222
201
          </para>
223
 
          <para>
224
 
            Note that since this program will normally run in the
225
 
            initial RAM disk environment, the interface must be an
226
 
            interface which exists at that stage.  Thus, the interface
227
 
            can not be a pseudo-interface such as <quote>br0</quote>
228
 
            or <quote>tun0</quote>; such interfaces will not exist
229
 
            until much later in the boot process, and can not be used
230
 
            by this program.
231
 
          </para>
232
 
          <para>
233
 
            <replaceable>NAME</replaceable> can be the string
234
 
            <quote><literal>none</literal></quote>; this will not use
235
 
            any specific interface, and will not bring up an interface
236
 
            on startup.  This is not recommended, and only meant for
237
 
            advanced users.
238
 
          </para>
239
202
        </listitem>
240
203
      </varlistentry>
241
204
      
252
215
          </para>
253
216
        </listitem>
254
217
      </varlistentry>
255
 
      
 
218
 
256
219
      <varlistentry>
257
220
        <term><option>--seckey=<replaceable
258
221
        >FILE</replaceable></option></term>
275
238
                      xpointer="priority"/>
276
239
        </listitem>
277
240
      </varlistentry>
278
 
      
 
241
 
279
242
      <varlistentry>
280
243
        <term><option>--dh-bits=<replaceable
281
244
        >BITS</replaceable></option></term>
286
249
          </para>
287
250
        </listitem>
288
251
      </varlistentry>
289
 
 
290
 
      <varlistentry>
291
 
        <term><option>--delay=<replaceable
292
 
        >SECONDS</replaceable></option></term>
293
 
        <listitem>
294
 
          <para>
295
 
            After bringing the network interface up, the program waits
296
 
            for the interface to arrive in a <quote>running</quote>
297
 
            state before proceeding.  During this time, the kernel log
298
 
            level will be lowered to reduce clutter on the system
299
 
            console, alleviating any other plugins which might be
300
 
            using the system console.  This option sets the upper
301
 
            limit of seconds to wait.  The default is 2.5 seconds.
302
 
          </para>
303
 
        </listitem>
304
 
      </varlistentry>
305
 
 
306
 
      <varlistentry>
307
 
        <term><option>--retry=<replaceable
308
 
        >SECONDS</replaceable></option></term>
309
 
        <listitem>
310
 
          <para>
311
 
            All Mandos servers are tried repeatedly until a password
312
 
            is received.  This value specifies, in seconds, how long
313
 
            between each successive try <emphasis>for the same
314
 
            server</emphasis>.  The default is 10 seconds.
315
 
          </para>
316
 
        </listitem>
317
 
      </varlistentry>
318
 
 
319
 
      <varlistentry>
320
 
        <term><option>--network-hook-dir=<replaceable
321
 
        >DIR</replaceable></option></term>
322
 
        <listitem>
323
 
          <para>
324
 
            Network hook directory.  The default directory is
325
 
            <quote><filename class="directory"
326
 
            >/lib/mandos/network-hooks.d</filename></quote>.
327
 
          </para>
328
 
        </listitem>
329
 
      </varlistentry>
330
252
      
331
253
      <varlistentry>
332
254
        <term><option>--debug</option></term>
362
284
          </para>
363
285
        </listitem>
364
286
      </varlistentry>
365
 
      
 
287
 
366
288
      <varlistentry>
367
289
        <term><option>--version</option></term>
368
290
        <term><option>-V</option></term>
374
296
      </varlistentry>
375
297
    </variablelist>
376
298
  </refsect1>
377
 
  
 
299
 
378
300
  <refsect1 id="overview">
379
301
    <title>OVERVIEW</title>
380
302
    <xi:include href="../overview.xml"/>
389
311
      <filename>/etc/crypttab</filename>, but it would then be
390
312
      impossible to enter a password for the encrypted root disk at
391
313
      the console, since this program does not read from the console
392
 
      at all.  This is why a separate plugin runner (<citerefentry>
393
 
      <refentrytitle>plugin-runner</refentrytitle>
394
 
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
395
 
      both this program and others in in parallel,
396
 
      <emphasis>one</emphasis> of which will prompt for passwords on
397
 
      the system console.
 
314
      at all.  This is why a separate plugin (<citerefentry>
 
315
      <refentrytitle>password-prompt</refentrytitle>
 
316
      <manvolnum>8mandos</manvolnum></citerefentry>) does that, which
 
317
      will be run in parallel to this one by the plugin runner.
398
318
    </para>
399
319
  </refsect1>
400
320
  
405
325
      server could be found and the password received from it could be
406
326
      successfully decrypted and output on standard output.  The
407
327
      program will exit with a non-zero exit status only if a critical
408
 
      error occurs.  Otherwise, it will forever connect to any
409
 
      discovered <application>Mandos</application> servers, trying to
410
 
      get a decryptable password and print it.
 
328
      error occurs.  Otherwise, it will forever connect to new
 
329
      <application>Mandos</application> servers as they appear, trying
 
330
      to get a decryptable password.
411
331
    </para>
412
332
  </refsect1>
413
333
  
421
341
    </para>
422
342
  </refsect1>
423
343
  
424
 
  <refsect1 id="files">
 
344
  <refsect1 id="file">
425
345
    <title>FILES</title>
426
346
    <variablelist>
427
347
      <varlistentry>
446
366
<!--     <para> -->
447
367
<!--     </para> -->
448
368
<!--   </refsect1> -->
449
 
  
 
369
 
450
370
  <refsect1 id="example">
451
371
    <title>EXAMPLE</title>
452
372
    <para>
488
408
    <informalexample>
489
409
      <para>
490
410
        Run in debug mode, with a custom key, and do not use Zeroconf
491
 
        to locate a server; connect directly to the IPv6 link-local
492
 
        address <quote><systemitem class="ipaddress"
493
 
        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
494
 
        using interface eth2:
 
411
        to locate a server; connect directly to the IPv6 address
 
412
        <quote><systemitem class="ipaddress"
 
413
        >2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
 
414
        port 4711, using interface eth2:
495
415
      </para>
496
416
      <para>
497
417
 
498
418
<!-- do not wrap this line -->
499
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
 
419
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
500
420
 
501
421
      </para>
502
422
    </informalexample>
503
423
  </refsect1>
504
 
  
 
424
 
505
425
  <refsect1 id="security">
506
426
    <title>SECURITY</title>
507
427
    <para>
527
447
      The only remaining weak point is that someone with physical
528
448
      access to the client hard drive might turn off the client
529
449
      computer, read the OpenPGP keys directly from the hard drive,
530
 
      and communicate with the server.  To safeguard against this, the
531
 
      server is supposed to notice the client disappearing and stop
532
 
      giving out the encrypted data.  Therefore, it is important to
533
 
      set the timeout and checker interval values tightly on the
534
 
      server.  See <citerefentry><refentrytitle
 
450
      and communicate with the server.  The defense against this is
 
451
      that the server is supposed to notice the client disappearing
 
452
      and will stop giving out the encrypted data.  Therefore, it is
 
453
      important to set the timeout and checker interval values tightly
 
454
      on the server.  See <citerefentry><refentrytitle
535
455
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
536
456
    </para>
537
457
    <para>
548
468
      confidential.
549
469
    </para>
550
470
  </refsect1>
551
 
  
 
471
 
552
472
  <refsect1 id="see_also">
553
473
    <title>SEE ALSO</title>
554
474
    <para>
555
 
      <citerefentry><refentrytitle>intro</refentrytitle>
556
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
557
475
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
558
476
      <manvolnum>8</manvolnum></citerefentry>,
559
477
      <citerefentry><refentrytitle>crypttab</refentrytitle>
681
599
      </varlistentry>
682
600
    </variablelist>
683
601
  </refsect1>
 
602
 
684
603
</refentry>
685
 
 
686
604
<!-- Local Variables: -->
687
605
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
688
606
<!-- time-stamp-end: "[\"']>" -->