/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-02 17:42:53 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902174253-p3wxrq7z6ccnv7fs
* plugins.d/password-request.c (main): Change default GnuTLS priority
                                       string to
                             "SECURE256":!CTYPE-X.509:+CTYPE-OPENPGP".

* plugins.d/password-request.xml (DESCRIPTION): Improve wording.
  (PURPOSE, OVERVIEW): New sections.
  (OPTIONS): Improved wording.
  (EXIT STATUS): Add text.
  (ENVIRONMENT): Commented out.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/password-request.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
4
<!ENTITY VERSION "1.0">
 
5
<!ENTITY COMMANDNAME "password-request">
 
6
<!ENTITY TIMESTAMP "2008-09-02">
 
7
]>
 
8
 
 
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
10
  <refentryinfo>
 
11
    <title>Mandos Manual</title>
 
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
 
13
    <productname>Mandos</productname>
 
14
    <productnumber>&VERSION;</productnumber>
 
15
    <date>&TIMESTAMP;</date>
 
16
    <authorgroup>
 
17
      <author>
 
18
        <firstname>Björn</firstname>
 
19
        <surname>Påhlsson</surname>
 
20
        <address>
 
21
          <email>belorn@fukt.bsnet.se</email>
 
22
        </address>
 
23
      </author>
 
24
      <author>
 
25
        <firstname>Teddy</firstname>
 
26
        <surname>Hogeborn</surname>
 
27
        <address>
 
28
          <email>teddy@fukt.bsnet.se</email>
 
29
        </address>
 
30
      </author>
 
31
    </authorgroup>
 
32
    <copyright>
 
33
      <year>2008</year>
 
34
      <holder>Teddy Hogeborn</holder>
 
35
      <holder>Björn Påhlsson</holder>
 
36
    </copyright>
 
37
    <xi:include href="../legalnotice.xml"/>
 
38
  </refentryinfo>
 
39
 
 
40
  <refmeta>
 
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
 
42
    <manvolnum>8mandos</manvolnum>
 
43
  </refmeta>
 
44
  
 
45
  <refnamediv>
 
46
    <refname><command>&COMMANDNAME;</command></refname>
 
47
    <refpurpose>
 
48
      Client for mandos
 
49
    </refpurpose>
 
50
  </refnamediv>
 
51
 
 
52
  <refsynopsisdiv>
 
53
    <cmdsynopsis>
 
54
      <command>&COMMANDNAME;</command>
 
55
      <group>
 
56
        <arg choice="plain"><option>--connect
 
57
        <replaceable>IPADDR</replaceable><literal>:</literal
 
58
        ><replaceable>PORT</replaceable></option></arg>
 
59
        <arg choice="plain"><option>-c
 
60
        <replaceable>IPADDR</replaceable><literal>:</literal
 
61
        ><replaceable>PORT</replaceable></option></arg>
 
62
      </group>
 
63
      <sbr/>
 
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>
 
72
        <arg choice="plain"><option>--interface
 
73
        <replaceable>NAME</replaceable></option></arg>
 
74
        <arg choice="plain"><option>-i
 
75
        <replaceable>NAME</replaceable></option></arg>
 
76
      </group>
 
77
      <sbr/>
 
78
      <group>
 
79
        <arg choice="plain"><option>--pubkey
 
80
        <replaceable>FILE</replaceable></option></arg>
 
81
        <arg choice="plain"><option>-p
 
82
        <replaceable>FILE</replaceable></option></arg>
 
83
      </group>
 
84
      <sbr/>
 
85
      <group>
 
86
        <arg choice="plain"><option>--seckey
 
87
        <replaceable>FILE</replaceable></option></arg>
 
88
        <arg choice="plain"><option>-s
 
89
        <replaceable>FILE</replaceable></option></arg>
 
90
      </group>
 
91
      <sbr/>
 
92
      <arg>
 
93
        <option>--priority <replaceable>STRING</replaceable></option>
 
94
      </arg>
 
95
      <sbr/>
 
96
      <arg>
 
97
        <option>--dh-bits <replaceable>BITS</replaceable></option>
 
98
      </arg>
 
99
      <sbr/>
 
100
      <arg>
 
101
        <option>--debug</option>
 
102
      </arg>
 
103
    </cmdsynopsis>
 
104
    <cmdsynopsis>
 
105
      <command>&COMMANDNAME;</command>
 
106
      <group choice="req">
 
107
        <arg choice="plain"><option>--help</option></arg>
 
108
        <arg choice="plain"><option>-?</option></arg>
 
109
      </group>
 
110
    </cmdsynopsis>
 
111
    <cmdsynopsis>
 
112
      <command>&COMMANDNAME;</command>
 
113
      <arg choice="plain"><option>--usage</option></arg>
 
114
    </cmdsynopsis>
 
115
    <cmdsynopsis>
 
116
      <command>&COMMANDNAME;</command>
 
117
      <group choice="req">
 
118
        <arg choice="plain"><option>--version</option></arg>
 
119
        <arg choice="plain"><option>-V</option></arg>
 
120
      </group>
 
121
    </cmdsynopsis>
 
122
  </refsynopsisdiv>
 
123
 
 
124
  <refsect1 id="description">
 
125
    <title>DESCRIPTION</title>
 
126
    <para>
 
127
      <command>&COMMANDNAME;</command> is a client program that
 
128
      communicates with <citerefentry><refentrytitle
 
129
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 
130
      to get a password.  It uses IPv6 link-local addresses to get
 
131
      network connectivity, Zeroconf to find the server, and TLS with
 
132
      an OpenPGP key to ensure authenticity and confidentiality.  It
 
133
      keeps running, trying all servers on the network, until it
 
134
      receives a satisfactory reply.
 
135
    </para>
 
136
    <para>
 
137
      This program is not meant to be run directly; it is really meant
 
138
      to run as a plugin of the <application>Mandos</application>
 
139
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
140
      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn
 
141
      runs as a <quote>keyscript</quote> specified in the
 
142
      <citerefentry><refentrytitle>crypttab</refentrytitle>
 
143
      <manvolnum>5</manvolnum></citerefentry> file.
 
144
    </para>
 
145
  </refsect1>
 
146
  
 
147
  <refsect1 id="purpose">
 
148
    <title>PURPOSE</title>
 
149
    <para>
 
150
      The purpose of this is to enable <emphasis>remote and unattended
 
151
      rebooting</emphasis> of client host computer with an
 
152
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
153
      linkend="overview"/> for details.
 
154
    </para>
 
155
  </refsect1>
 
156
  
 
157
  <refsect1 id="overview">
 
158
    <title>OVERVIEW</title>
 
159
    <xi:include href="overview.xml"/>
 
160
    <para>
 
161
      This program is the client part.  It is a plugin started by
 
162
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
163
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
 
164
      an initial <acronym>RAM</acronym> disk environment.
 
165
    </para>
 
166
    <para>
 
167
      This program could, theoretically, be used as a keyscript in
 
168
      <filename>/etc/crypttab</filename>, but it would then be
 
169
      impossible to enter the encrypted root disk password at the
 
170
      console, since this program does not read from the console at
 
171
      all.  This is why a separate plugin does that, which will be run
 
172
      in parallell to this one.
 
173
    </para>
 
174
  </refsect1>
 
175
  
 
176
  <refsect1 id="options">
 
177
    <title>OPTIONS</title>
 
178
    <para>
 
179
      This program is commonly not invoked from the command line; it
 
180
      is normally started by the <application>Mandos</application>
 
181
      plugin runner, see <citerefentry><refentrytitle
 
182
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
 
183
      </citerefentry>.  Any command line options this program accepts
 
184
      are therefore normally provided by the plugin runner, and not
 
185
      directly.
 
186
    </para>
 
187
    
 
188
    <variablelist>
 
189
      <varlistentry>
 
190
        <term><option>--connect=<replaceable
 
191
        >IPADDR</replaceable><literal>:</literal><replaceable
 
192
        >PORT</replaceable></option></term>
 
193
        <term><option>-c
 
194
        <replaceable>IPADDR</replaceable><literal>:</literal
 
195
        ><replaceable>PORT</replaceable></option></term>
 
196
        <listitem>
 
197
          <para>
 
198
            Do not use Zeroconf to locate servers.  Connect directly
 
199
            to only one specified <application>Mandos</application>
 
200
            server.  Note that an IPv6 address has colon characters in
 
201
            it, so the <emphasis>last</emphasis> colon character is
 
202
            assumed to separate the address from the port number.
 
203
          </para>
 
204
          <para>
 
205
            This option is normally only useful for debugging.
 
206
          </para>
 
207
        </listitem>
 
208
      </varlistentry>
 
209
      
 
210
      <varlistentry>
 
211
        <term><option>--keydir=<replaceable
 
212
        >DIRECTORY</replaceable></option></term>
 
213
        <term><option>-d
 
214
        <replaceable>DIRECTORY</replaceable></option></term>
 
215
        <listitem>
 
216
          <para>
 
217
            Directory to read the OpenPGP key files
 
218
            <filename>pubkey.txt</filename> and
 
219
            <filename>seckey.txt</filename> from.  The default is
 
220
            <filename>/conf/conf.d/mandos</filename> (in the initial
 
221
            <acronym>RAM</acronym> disk environment).
 
222
          </para>
 
223
        </listitem>
 
224
      </varlistentry>
 
225
 
 
226
      <varlistentry>
 
227
        <term><option>--interface=
 
228
        <replaceable>NAME</replaceable></option></term>
 
229
        <term><option>-i
 
230
        <replaceable>NAME</replaceable></option></term>
 
231
        <listitem>
 
232
          <para>
 
233
            Network interface that will be brought up and scanned for
 
234
            Mandos servers to connect to.  The default it
 
235
            <quote><literal>eth0</literal></quote>.
 
236
          </para>
 
237
        </listitem>
 
238
      </varlistentry>
 
239
      
 
240
      <varlistentry>
 
241
        <term><option>--pubkey=<replaceable
 
242
        >FILE</replaceable></option></term>
 
243
        <term><option>-p
 
244
        <replaceable>FILE</replaceable></option></term>
 
245
        <listitem>
 
246
          <para>
 
247
            OpenPGP public key file name.  This will be combined with
 
248
            the directory from the <option>--keydir</option> option to
 
249
            form an absolute file name.  The default name is
 
250
            <quote><literal>pubkey.txt</literal></quote>.
 
251
          </para>
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
 
255
      <varlistentry>
 
256
        <term><option>--seckey=<replaceable
 
257
        >FILE</replaceable></option></term>
 
258
        <term><option>-s
 
259
        <replaceable>FILE</replaceable></option></term>
 
260
        <listitem>
 
261
          <para>
 
262
            OpenPGP secret key file name.  This will be combined with
 
263
            the directory from the <option>--keydir</option> option to
 
264
            form an absolute file name.  The default name is
 
265
            <quote><literal>seckey.txt</literal></quote>.
 
266
          </para>
 
267
        </listitem>
 
268
      </varlistentry>
 
269
      
 
270
      <varlistentry>
 
271
        <term><option>--priority=<replaceable
 
272
        >STRING</replaceable></option></term>
 
273
        <listitem>
 
274
          <xi:include href="mandos-options.xml" xpointer="priority"/>
 
275
        </listitem>
 
276
      </varlistentry>
 
277
 
 
278
      <varlistentry>
 
279
        <term><option>--dh-bits=<replaceable
 
280
        >BITS</replaceable></option></term>
 
281
        <listitem>
 
282
          <para>
 
283
            Sets the number of bits to use for the prime number in the
 
284
            TLS Diffie-Hellman key exchange.  Default is 1024.
 
285
          </para>
 
286
        </listitem>
 
287
      </varlistentry>
 
288
      
 
289
      <varlistentry>
 
290
        <term><option>--debug</option></term>
 
291
        <listitem>
 
292
          <para>
 
293
            Enable debug mode.  This will enable a lot of output to
 
294
            standard error about what the program is doing.  The
 
295
            program will still perform all other functions normally.
 
296
          </para>
 
297
          <para>
 
298
            It will also enable debug mode in the Avahi and GnuTLS
 
299
            libraries, making them print large amounts of debugging
 
300
            output.
 
301
          </para>
 
302
        </listitem>
 
303
      </varlistentry>
 
304
      
 
305
      <varlistentry>
 
306
        <term><option>--help</option></term>
 
307
        <term><option>-?</option></term>
 
308
        <listitem>
 
309
          <para>
 
310
            Gives a help message about options and their meanings.
 
311
          </para>
 
312
        </listitem>
 
313
      </varlistentry>
 
314
      
 
315
      <varlistentry>
 
316
        <term><option>--usage</option></term>
 
317
        <listitem>
 
318
          <para>
 
319
            Gives a short usage message.
 
320
          </para>
 
321
        </listitem>
 
322
      </varlistentry>
 
323
 
 
324
      <varlistentry>
 
325
        <term><option>--version</option></term>
 
326
        <term><option>-V</option></term>
 
327
        <listitem>
 
328
          <para>
 
329
            Prints the program version.
 
330
          </para>
 
331
        </listitem>
 
332
      </varlistentry>
 
333
    </variablelist>
 
334
  </refsect1>
 
335
 
 
336
  <refsect1 id="exit_status">
 
337
    <title>EXIT STATUS</title>
 
338
    <para>
 
339
      This program will exit with a successful (zero) exit status if a
 
340
      server could be found and the password received from it could be
 
341
      successfully decrypted and output on standard output.  The
 
342
      program will exit with a non-zero exit status only if a critical
 
343
      error occurs.  Otherwise, it will forever connect to new
 
344
      <application>Mandosservers</application> servers as they appear,
 
345
      trying to get a decryptable password.
 
346
    </para>
 
347
  </refsect1>
 
348
  
 
349
<!--   <refsect1 id="environment"> -->
 
350
<!--     <title>ENVIRONMENT</title> -->
 
351
<!--     <para> -->
 
352
<!--       This program does not use any environment variables. -->
 
353
<!--     </para> -->
 
354
<!--   </refsect1> -->
 
355
  
 
356
  <refsect1 id="file">
 
357
    <title>FILES</title>
 
358
    <para>
 
359
    </para>
 
360
  </refsect1>
 
361
  
 
362
  <refsect1 id="bugs">
 
363
    <title>BUGS</title>
 
364
    <para>
 
365
    </para>
 
366
  </refsect1>
 
367
 
 
368
  <refsect1 id="example">
 
369
    <title>EXAMPLE</title>
 
370
    <para>
 
371
    </para>
 
372
  </refsect1>
 
373
 
 
374
  <refsect1 id="security">
 
375
    <title>SECURITY</title>
 
376
    <para>
 
377
    </para>
 
378
  </refsect1>
 
379
 
 
380
  <refsect1 id="see_also">
 
381
    <title>SEE ALSO</title>
 
382
    <para>
 
383
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
384
      <manvolnum>8</manvolnum></citerefentry>,
 
385
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
 
386
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
387
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
388
      <manvolnum>8mandos</manvolnum></citerefentry>
 
389
    </para>
 
390
    <itemizedlist>
 
391
      <listitem><para>
 
392
        <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
393
      </para></listitem>
 
394
      
 
395
      <listitem><para>
 
396
        <ulink url="http://www.avahi.org/">Avahi</ulink>
 
397
      </para></listitem>
 
398
      
 
399
      <listitem><para>
 
400
        <ulink
 
401
            url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
 
402
      </para></listitem>
 
403
      
 
404
      <listitem><para>
 
405
        <ulink
 
406
        url="http://www.gnupg.org/related_software/gpgme/">
 
407
        GPGME</ulink>
 
408
      </para></listitem>
 
409
      
 
410
      <listitem><para>
 
411
        <citation>RFC 4880: <citetitle>OpenPGP Message
 
412
        Format</citetitle></citation>
 
413
      </para></listitem>
 
414
      
 
415
      <listitem><para>
 
416
        <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
417
        Transport Layer Security</citetitle></citation>
 
418
      </para></listitem>
 
419
      
 
420
      <listitem><para>
 
421
        <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
422
        Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
423
        Unicast Addresses</citation>
 
424
      </para></listitem>
 
425
    </itemizedlist>
 
426
  </refsect1>
 
427
 
 
428
</refentry>
 
429
<!-- Local Variables: -->
 
430
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
431
<!-- time-stamp-end: "[\"']>" -->
 
432
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
433
<!-- End: -->