/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

  • 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">
8
 
<!ENTITY TIMESTAMP "2008-08-31">
 
6
<!ENTITY TIMESTAMP "2008-09-02">
9
7
]>
10
8
 
11
 
<refentry>
 
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
10
  <refentryinfo>
13
11
    <title>Mandos Manual</title>
14
 
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
 
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
15
13
    <productname>Mandos</productname>
16
14
    <productnumber>&VERSION;</productnumber>
17
15
    <date>&TIMESTAMP;</date>
36
34
      <holder>Teddy Hogeborn</holder>
37
35
      <holder>Björn Påhlsson</holder>
38
36
    </copyright>
39
 
    <legalnotice>
40
 
      <para>
41
 
        This manual page is free software: you can redistribute it
42
 
        and/or modify it under the terms of the GNU General Public
43
 
        License as published by the Free Software Foundation,
44
 
        either version 3 of the License, or (at your option) any
45
 
        later version.
46
 
      </para>
47
 
 
48
 
      <para>
49
 
        This manual page is distributed in the hope that it will
50
 
        be useful, but WITHOUT ANY WARRANTY; without even the
51
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
52
 
        PARTICULAR PURPOSE.  See the GNU General Public License
53
 
        for more details.
54
 
      </para>
55
 
 
56
 
      <para>
57
 
        You should have received a copy of the GNU General Public
58
 
        License along with this program; If not, see
59
 
        <ulink url="http://www.gnu.org/licenses/"/>.
60
 
      </para>
61
 
    </legalnotice>
 
37
    <xi:include href="../legalnotice.xml"/>
62
38
  </refentryinfo>
63
39
 
64
40
  <refmeta>
128
104
    <cmdsynopsis>
129
105
      <command>&COMMANDNAME;</command>
130
106
      <group choice="req">
131
 
        <arg choice='plain'><option>--help</option></arg>
132
 
        <arg choice='plain'><option>-?</option></arg>
 
107
        <arg choice="plain"><option>--help</option></arg>
 
108
        <arg choice="plain"><option>-?</option></arg>
133
109
      </group>
134
110
    </cmdsynopsis>
135
111
    <cmdsynopsis>
136
112
      <command>&COMMANDNAME;</command>
137
 
      <arg choice='plain'><option>--usage</option></arg>
 
113
      <arg choice="plain"><option>--usage</option></arg>
138
114
    </cmdsynopsis>
139
115
    <cmdsynopsis>
140
116
      <command>&COMMANDNAME;</command>
141
117
      <group choice="req">
142
 
        <arg choice='plain'><option>--version</option></arg>
143
 
        <arg choice='plain'><option>-V</option></arg>
 
118
        <arg choice="plain"><option>--version</option></arg>
 
119
        <arg choice="plain"><option>-V</option></arg>
144
120
      </group>
145
121
    </cmdsynopsis>
146
122
  </refsynopsisdiv>
148
124
  <refsect1 id="description">
149
125
    <title>DESCRIPTION</title>
150
126
    <para>
151
 
      <command>&COMMANDNAME;</command> is a mandos plugin that works
152
 
      like a client program that through avahi detects mandos servers,
153
 
      sets up a gnutls connect and request a encrypted password. Any
154
 
      passwords given is automaticly decrypted and passed to
155
 
      cryptsetup.
 
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.
156
173
    </para>
157
174
  </refsect1>
158
175
  
159
176
  <refsect1 id="options">
160
177
    <title>OPTIONS</title>
161
178
    <para>
162
 
      Commonly not invoked as command lines but from configuration
163
 
      file of plugin runner.
 
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.
164
186
    </para>
165
 
 
 
187
    
166
188
    <variablelist>
167
189
      <varlistentry>
168
190
        <term><option>--connect=<replaceable
173
195
        ><replaceable>PORT</replaceable></option></term>
174
196
        <listitem>
175
197
          <para>
176
 
            Connect directly to a specified mandos server
 
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.
177
206
          </para>
178
207
        </listitem>
179
208
      </varlistentry>
180
 
 
 
209
      
181
210
      <varlistentry>
182
211
        <term><option>--keydir=<replaceable
183
212
        >DIRECTORY</replaceable></option></term>
185
214
        <replaceable>DIRECTORY</replaceable></option></term>
186
215
        <listitem>
187
216
          <para>
188
 
            Directory where the openpgp keyring is
 
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).
189
222
          </para>
190
223
        </listitem>
191
224
      </varlistentry>
197
230
        <replaceable>NAME</replaceable></option></term>
198
231
        <listitem>
199
232
          <para>
200
 
            Interface that Avahi will connect through
 
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>.
201
236
          </para>
202
237
        </listitem>
203
238
      </varlistentry>
204
 
 
 
239
      
205
240
      <varlistentry>
206
241
        <term><option>--pubkey=<replaceable
207
242
        >FILE</replaceable></option></term>
209
244
        <replaceable>FILE</replaceable></option></term>
210
245
        <listitem>
211
246
          <para>
212
 
            Public openpgp key for gnutls authentication
 
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>.
213
251
          </para>
214
252
        </listitem>
215
253
      </varlistentry>
221
259
        <replaceable>FILE</replaceable></option></term>
222
260
        <listitem>
223
261
          <para>
224
 
            Secret OpenPGP key for GnuTLS authentication
 
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>.
225
266
          </para>
226
267
        </listitem>
227
268
      </varlistentry>
230
271
        <term><option>--priority=<replaceable
231
272
        >STRING</replaceable></option></term>
232
273
        <listitem>
233
 
          <para>
234
 
            GnuTLS priority
235
 
          </para>
 
274
          <xi:include href="mandos-options.xml" xpointer="priority"/>
236
275
        </listitem>
237
276
      </varlistentry>
238
277
 
241
280
        >BITS</replaceable></option></term>
242
281
        <listitem>
243
282
          <para>
244
 
            DH bits to use in gnutls communication
 
283
            Sets the number of bits to use for the prime number in the
 
284
            TLS Diffie-Hellman key exchange.  Default is 1024.
245
285
          </para>
246
286
        </listitem>
247
287
      </varlistentry>
250
290
        <term><option>--debug</option></term>
251
291
        <listitem>
252
292
          <para>
253
 
            Debug mode
 
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.
254
301
          </para>
255
302
        </listitem>
256
303
      </varlistentry>
260
307
        <term><option>-?</option></term>
261
308
        <listitem>
262
309
          <para>
263
 
            Gives a help message
 
310
            Gives a help message about options and their meanings.
264
311
          </para>
265
312
        </listitem>
266
313
      </varlistentry>
269
316
        <term><option>--usage</option></term>
270
317
        <listitem>
271
318
          <para>
272
 
            Gives a short usage message
 
319
            Gives a short usage message.
273
320
          </para>
274
321
        </listitem>
275
322
      </varlistentry>
279
326
        <term><option>-V</option></term>
280
327
        <listitem>
281
328
          <para>
282
 
            Prints the program version
 
329
            Prints the program version.
283
330
          </para>
284
331
        </listitem>
285
332
      </varlistentry>
289
336
  <refsect1 id="exit_status">
290
337
    <title>EXIT STATUS</title>
291
338
    <para>
292
 
    </para>
293
 
  </refsect1>
294
 
 
295
 
  <refsect1 id="environment">
296
 
    <title>ENVIRONMENT</title>
297
 
    <para>
298
 
    </para>
299
 
  </refsect1>
300
 
 
 
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
  
301
356
  <refsect1 id="file">
302
357
    <title>FILES</title>
303
358
    <para>