/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-08-24 09:40:58 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080824094058-bdqng3t1e3hfnk2e
* plugin-runner.c (getplugin): Only copy "name" if not NULL.  Free
                               "copy_name" if any error occurs.
  (free_plugin_list): Do not free "name" member; it it freed as part
                      of argv.
  (main): Set plugin_list to NULL after freeing it.

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"?>
 
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"?>
2
4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
5
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
6
<!ENTITY VERSION "1.0">
5
7
<!ENTITY COMMANDNAME "password-request">
6
 
<!ENTITY TIMESTAMP "2008-09-02">
7
8
]>
8
9
 
9
 
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
10
<refentry>
10
11
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
12
 
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
12
    <title>&COMMANDNAME;</title>
 
13
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
 
14
    <productname>&COMMANDNAME;</productname>
14
15
    <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</holder>
35
 
      <holder>Björn Påhlsson</holder>
 
34
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
36
35
    </copyright>
37
 
    <xi:include href="../legalnotice.xml"/>
 
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>
38
59
  </refentryinfo>
39
60
 
40
61
  <refmeta>
52
73
  <refsynopsisdiv>
53
74
    <cmdsynopsis>
54
75
      <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>
 
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>    
122
97
  </refsynopsisdiv>
123
98
 
124
99
  <refsect1 id="description">
125
100
    <title>DESCRIPTION</title>
126
101
    <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>
 
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
  </refsect1>  
175
109
  
176
110
  <refsect1 id="options">
177
111
    <title>OPTIONS</title>
178
112
    <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.
 
113
      Commonly not invoked as command lines but from configuration
 
114
      file of plugin runner.
186
115
    </para>
187
 
    
 
116
 
188
117
    <variablelist>
189
118
      <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>
 
119
        <term><literal>-c</literal>, <literal>--connect=<replaceable>
 
120
        IP</replaceable></literal></term>
 
121
        <listitem>
 
122
          <para>
 
123
            Connect directly to a specified mandos server
 
124
          </para>
 
125
        </listitem>
 
126
      </varlistentry>
 
127
 
 
128
      <varlistentry>
 
129
        <term><literal>-d</literal>, <literal>--keydir=<replaceable>
 
130
        KEYDIR</replaceable></literal></term>
 
131
        <listitem>
 
132
          <para>
 
133
            Directory where the openpgp keyring is
 
134
          </para>
 
135
        </listitem>
 
136
      </varlistentry>      
 
137
 
 
138
      <varlistentry>
 
139
        <term><literal>-i</literal>, <literal>--interface=
 
140
        <replaceable>INTERFACE</replaceable></literal></term>
 
141
        <listitem>
 
142
          <para>
 
143
            Interface that Avahi will conntect through
 
144
          </para>
 
145
        </listitem>
 
146
      </varlistentry>      
 
147
 
 
148
      <varlistentry>
 
149
        <term><literal>-p</literal>, <literal>--pubkey=<replaceable>
 
150
        PUBKEY</replaceable></literal></term>
 
151
        <listitem>
 
152
          <para>
 
153
            Public openpgp key for gnutls authentication
 
154
          </para>
 
155
        </listitem>
 
156
      </varlistentry>      
 
157
 
 
158
      <varlistentry>
 
159
        <term><literal>-s</literal>, <literal>--seckey=<replaceable>
 
160
        SECKEY</replaceable></literal></term>
 
161
        <listitem>
 
162
          <para>
 
163
            Secret openpgp key for gnutls authentication
 
164
          </para>
 
165
        </listitem>
 
166
      </varlistentry>            
 
167
      
 
168
      <varlistentry>
 
169
        <term><literal>--priority=<replaceable>PRIORITY</replaceable>
 
170
        </literal></term>
 
171
        <listitem>
 
172
          <para>
 
173
            GNUTLS priority
 
174
          </para>
 
175
        </listitem>
 
176
      </varlistentry>            
 
177
 
 
178
      <varlistentry>
 
179
        <term><literal>--dh-bits=<replaceable>BITS</replaceable>
 
180
        </literal></term>
 
181
        <listitem>
 
182
          <para>
 
183
            dh-bits to use in gnutls communication
 
184
          </para>
 
185
        </listitem>
 
186
      </varlistentry>      
 
187
      
 
188
      <varlistentry>
 
189
        <term><literal>--debug</literal></term>
 
190
        <listitem>
 
191
          <para>
 
192
            Debug mode
 
193
          </para>
 
194
        </listitem>
 
195
      </varlistentry>
 
196
      
 
197
      <varlistentry>
 
198
        <term><literal>-?</literal>, <literal>--help</literal></term>
 
199
        <listitem>
 
200
          <para>
 
201
            Gives a help message
 
202
          </para>
 
203
        </listitem>
 
204
      </varlistentry>
 
205
      
 
206
      <varlistentry>
 
207
        <term><literal>--usage</literal></term>
 
208
        <listitem>
 
209
          <para>
 
210
            Gives a short usage message
 
211
          </para>
 
212
        </listitem>
 
213
      </varlistentry>
 
214
 
 
215
      <varlistentry>
 
216
        <term><literal>-V</literal>, <literal>--version</literal></term>
 
217
        <listitem>
 
218
          <para>
 
219
            Prints the program version
 
220
          </para>
 
221
        </listitem>
 
222
      </varlistentry>            
333
223
    </variablelist>
334
224
  </refsect1>
335
225
 
336
226
  <refsect1 id="exit_status">
337
227
    <title>EXIT STATUS</title>
338
228
    <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
229
    </para>
347
230
  </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
 
  
 
231
 
 
232
  <refsect1 id="environment">
 
233
    <title>ENVIRONMENT</title>
 
234
    <para>
 
235
    </para>
 
236
  </refsect1>  
 
237
 
356
238
  <refsect1 id="file">
357
239
    <title>FILES</title>
358
240
    <para>
359
241
    </para>
360
 
  </refsect1>
 
242
  </refsect1>  
361
243
  
362
244
  <refsect1 id="bugs">
363
245
    <title>BUGS</title>
364
246
    <para>
365
247
    </para>
366
 
  </refsect1>
 
248
  </refsect1>  
367
249
 
368
250
  <refsect1 id="example">
369
251
    <title>EXAMPLE</title>
379
261
 
380
262
  <refsect1 id="see_also">
381
263
    <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
264
    <itemizedlist>
391
265
      <listitem><para>
 
266
        <citerefentry><refentrytitle>mandos</refentrytitle>
 
267
        <manvolnum>8</manvolnum></citerefentry>
 
268
      </para></listitem>
 
269
      
 
270
      <listitem><para>
 
271
        <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
272
        <manvolnum>8mandos</manvolnum></citerefentry>
 
273
      </para></listitem>
 
274
      
 
275
      <listitem><para>
 
276
        <citerefentry><refentrytitle>password-prompt</refentrytitle>
 
277
        <manvolnum>8mandos</manvolnum></citerefentry>
 
278
      </para></listitem>
 
279
      
 
280
      <listitem><para>
392
281
        <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
393
282
      </para></listitem>
394
283
      
426
315
  </refsect1>
427
316
 
428
317
</refentry>
429
 
<!-- Local Variables: -->
430
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
431
 
<!-- time-stamp-end: "[\"']>" -->
432
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
433
 
<!-- End: -->