/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
 
<?xml-stylesheet type="text/xsl"
3
 
        href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
 
1
<?xml version="1.0" encoding="UTF-8"?>
4
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
5
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
6
4
<!ENTITY VERSION "1.0">
7
5
<!ENTITY COMMANDNAME "password-request">
 
6
<!ENTITY TIMESTAMP "2008-09-02">
8
7
]>
9
8
 
10
 
<refentry>
 
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
10
  <refentryinfo>
12
 
    <title>&COMMANDNAME;</title>
13
 
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
14
 
    <productname>&COMMANDNAME;</productname>
 
11
    <title>Mandos Manual</title>
 
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
 
13
    <productname>Mandos</productname>
15
14
    <productnumber>&VERSION;</productnumber>
 
15
    <date>&TIMESTAMP;</date>
16
16
    <authorgroup>
17
17
      <author>
18
18
        <firstname>Björn</firstname>
31
31
    </authorgroup>
32
32
    <copyright>
33
33
      <year>2008</year>
34
 
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
 
34
      <holder>Teddy Hogeborn</holder>
 
35
      <holder>Björn Påhlsson</holder>
35
36
    </copyright>
36
 
    <legalnotice>
37
 
      <para>
38
 
        This manual page is free software: you can redistribute it
39
 
        and/or modify it under the terms of the GNU General Public
40
 
        License as published by the Free Software Foundation,
41
 
        either version 3 of the License, or (at your option) any
42
 
        later version.
43
 
      </para>
44
 
 
45
 
      <para>
46
 
        This manual page is distributed in the hope that it will
47
 
        be useful, but WITHOUT ANY WARRANTY; without even the
48
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
49
 
        PARTICULAR PURPOSE.  See the GNU General Public License
50
 
        for more details.
51
 
      </para>
52
 
 
53
 
      <para>
54
 
        You should have received a copy of the GNU General Public
55
 
        License along with this program; If not, see
56
 
        <ulink url="http://www.gnu.org/licenses/"/>.
57
 
      </para>
58
 
    </legalnotice>
 
37
    <xi:include href="../legalnotice.xml"/>
59
38
  </refentryinfo>
60
39
 
61
40
  <refmeta>
73
52
  <refsynopsisdiv>
74
53
    <cmdsynopsis>
75
54
      <command>&COMMANDNAME;</command>
76
 
      <arg choice='opt'>--connect<arg choice='plain'>IP</arg></arg>
77
 
      <arg choice='opt'>--keydir<arg choice='plain'>KEYDIR</arg></arg>
78
 
      <arg choice='opt'>--interface<arg choice='plain'>INTERFACE</arg></arg>
79
 
      <arg choice='opt'>--pubkey<arg choice='plain'>PUBKEY</arg></arg>
80
 
      <arg choice='opt'>--seckey<arg choice='plain'>SECKEY</arg></arg>
81
 
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
82
 
      <arg choice='opt'>--dh-bits<arg choice='plain'>BITS</arg></arg>      
83
 
      <arg choice='opt'>--debug</arg>
84
 
    </cmdsynopsis>
85
 
    <cmdsynopsis>
86
 
      <command>&COMMANDNAME;</command>
87
 
      <arg choice='plain'>--help</arg>
88
 
    </cmdsynopsis>
89
 
    <cmdsynopsis>
90
 
      <command>&COMMANDNAME;</command>
91
 
      <arg choice='plain'>--usage</arg>
92
 
    </cmdsynopsis>
93
 
    <cmdsynopsis>
94
 
      <command>&COMMANDNAME;</command>
95
 
      <arg choice='plain'>--version</arg>
96
 
    </cmdsynopsis>    
 
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>
97
122
  </refsynopsisdiv>
98
123
 
99
124
  <refsect1 id="description">
100
125
    <title>DESCRIPTION</title>
101
126
    <para>
102
 
      <command>&COMMANDNAME;</command> is a mandos plugin that works
103
 
      like a client program that through avahi detects mandos servers,
104
 
      sets up a gnutls connect and request a encrypted password. Any
105
 
      passwords given is automaticly decrypted and passed to
106
 
      cryptsetup.
107
 
    </para>
108
 
 
 
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
    
109
188
    <variablelist>
110
189
      <varlistentry>
111
 
        <term><literal>-c</literal>, <literal>--connect=<replaceable>
112
 
        IP</replaceable></literal></term>
113
 
        <listitem>
114
 
          <para>
115
 
            Connect directly to a sepcified mandos server
116
 
          </para>
117
 
        </listitem>
118
 
      </varlistentry>
119
 
 
120
 
      <varlistentry>
121
 
        <term><literal>-d</literal>, <literal>--keydir=<replaceable>
122
 
        KEYDIR</replaceable></literal></term>
123
 
        <listitem>
124
 
          <para>
125
 
            Directory where the openpgp keyring is
126
 
          </para>
127
 
        </listitem>
128
 
      </varlistentry>      
129
 
 
130
 
      <varlistentry>
131
 
        <term><literal>-i</literal>, <literal>--interface=
132
 
        <replaceable>INTERFACE</replaceable></literal></term>
133
 
        <listitem>
134
 
          <para>
135
 
            Interface that Avahi will conntect through
136
 
          </para>
137
 
        </listitem>
138
 
      </varlistentry>      
139
 
 
140
 
      <varlistentry>
141
 
        <term><literal>-p</literal>, <literal>--pubkey=<replaceable>
142
 
        PUBKEY</replaceable></literal></term>
143
 
        <listitem>
144
 
          <para>
145
 
            Public openpgp key for gnutls authentication
146
 
          </para>
147
 
        </listitem>
148
 
      </varlistentry>      
149
 
 
150
 
      <varlistentry>
151
 
        <term><literal>-s</literal>, <literal>--seckey=<replaceable>
152
 
        SECKEY</replaceable></literal></term>
153
 
        <listitem>
154
 
          <para>
155
 
            Secret openpgp key for gnutls authentication
156
 
          </para>
157
 
        </listitem>
158
 
      </varlistentry>            
159
 
      
160
 
      <varlistentry>
161
 
        <term><literal>--priority=<replaceable>PRIORITY</replaceable>
162
 
        </literal></term>
163
 
        <listitem>
164
 
          <para>
165
 
            GNUTLS priority
166
 
          </para>
167
 
        </listitem>
168
 
      </varlistentry>            
169
 
 
170
 
      <varlistentry>
171
 
        <term><literal>--dh-bits=<replaceable>BITS</replaceable>
172
 
        </literal></term>
173
 
        <listitem>
174
 
          <para>
175
 
            dh-bits to use in gnutls communication
176
 
          </para>
177
 
        </listitem>
178
 
      </varlistentry>      
179
 
      
180
 
      <varlistentry>
181
 
        <term><literal>--debug</literal></term>
182
 
        <listitem>
183
 
          <para>
184
 
            Debug mode
185
 
          </para>
186
 
        </listitem>
187
 
      </varlistentry>
188
 
      
189
 
      <varlistentry>
190
 
        <term><literal>-?</literal>, <literal>--help</literal></term>
191
 
        <listitem>
192
 
          <para>
193
 
            Gives a help message
194
 
          </para>
195
 
        </listitem>
196
 
      </varlistentry>
197
 
      
198
 
      <varlistentry>
199
 
        <term><literal>--usage</literal></term>
200
 
        <listitem>
201
 
          <para>
202
 
            Gives a short usage message
203
 
          </para>
204
 
        </listitem>
205
 
      </varlistentry>
206
 
 
207
 
      <varlistentry>
208
 
        <term><literal>-V</literal>, <literal>--version</literal></term>
209
 
        <listitem>
210
 
          <para>
211
 
            Prints the program version
212
 
          </para>
213
 
        </listitem>
214
 
      </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>
215
333
    </variablelist>
216
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
 
217
428
</refentry>
 
429
<!-- Local Variables: -->
 
430
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
431
<!-- time-stamp-end: "[\"']>" -->
 
432
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
433
<!-- End: -->