/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 mandos-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-24 06:17:02 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080824061702-zxrru4r1vxmx4tuq
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
  (install-server, install-client): Use "install --directory" instead
                                    of mkdir.

* mandos-keygen: New options --subtype and --sublength.
  (trap): Added semicolons and backslashes.
  (gpg): Added "--enable-dsa2" to all invocations.

* mandos-keygen.xml: Changed single quotes to double quotes for
                     consistency.
  (/refentry/refentryinfo/copyright) Split copyright holders.
  (SYNOPSIS): Added "--subtype", "--sublength", "-s", and "-L".
  (OPTIONS): Document the subtype and sublength options.
  (SECURITY): Also note the "--subtype" and "--sublength" options.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.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 "mandos-keygen">
8
6
]>
9
7
 
10
 
<refentry>
 
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
9
  <refentryinfo>
12
10
    <title>&COMMANDNAME;</title>
13
 
    <!-- NWalsh's docbook scripts use this to generate the footer: -->
 
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
12
    <productname>&COMMANDNAME;</productname>
15
13
    <productnumber>&VERSION;</productnumber>
16
14
    <authorgroup>
31
29
    </authorgroup>
32
30
    <copyright>
33
31
      <year>2008</year>
34
 
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
 
32
      <holder>Teddy Hogeborn</holder>
 
33
      <holder>Björn Påhlsson</holder>
35
34
    </copyright>
36
35
    <legalnotice>
37
36
      <para>
87
86
        <replaceable>bits</replaceable></arg>
88
87
      </group>
89
88
      <group choice="opt">
 
89
        <arg choice="plain"><option>--subtype</option>
 
90
        <replaceable>type</replaceable></arg>
 
91
      </group>
 
92
      <group choice="opt">
 
93
        <arg choice="plain"><option>--sublength</option>
 
94
        <replaceable>bits</replaceable></arg>
 
95
      </group>
 
96
      <group choice="opt">
90
97
        <arg choice="plain"><option>--name</option>
91
98
        <replaceable>NAME</replaceable></arg>
92
99
      </group>
121
128
        <replaceable>bits</replaceable></arg>
122
129
      </group>
123
130
      <group choice="opt">
 
131
        <arg choice="plain"><option>-s</option>
 
132
        <replaceable>type</replaceable></arg>
 
133
      </group>
 
134
      <group choice="opt">
 
135
        <arg choice="plain"><option>-L</option>
 
136
        <replaceable>bits</replaceable></arg>
 
137
      </group>
 
138
      <group choice="opt">
124
139
        <arg choice="plain"><option>-n</option>
125
140
        <replaceable>NAME</replaceable></arg>
126
141
      </group>
143
158
    <cmdsynopsis>
144
159
      <command>&COMMANDNAME;</command>
145
160
      <group choice="req">
146
 
        <arg choice='plain'><option>-h</option></arg>
147
 
        <arg choice='plain'><option>--help</option></arg>
 
161
        <arg choice="plain"><option>-h</option></arg>
 
162
        <arg choice="plain"><option>--help</option></arg>
148
163
      </group>
149
164
    </cmdsynopsis>
150
165
    <cmdsynopsis>
151
166
      <command>&COMMANDNAME;</command>
152
167
      <group choice="req">
153
 
        <arg choice='plain'><option>-v</option></arg>
154
 
        <arg choice='plain'><option>--version</option></arg>
 
168
        <arg choice="plain"><option>-v</option></arg>
 
169
        <arg choice="plain"><option>--version</option></arg>
155
170
      </group>
156
171
    </cmdsynopsis>
157
172
  </refsynopsisdiv>
169
184
    </para>
170
185
  </refsect1>
171
186
  
 
187
  <refsect1 id="purpose">
 
188
    <title>PURPOSE</title>
 
189
 
 
190
    <para>
 
191
      The purpose of this is to enable <emphasis>remote and unattended
 
192
      rebooting</emphasis> of client host computer with an
 
193
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
194
      linkend="overview"/> for details.
 
195
    </para>
 
196
 
 
197
  </refsect1>
 
198
  
172
199
  <refsect1 id="options">
173
200
    <title>OPTIONS</title>
174
201
 
197
224
        <replaceable>type</replaceable></literal></term>
198
225
        <listitem>
199
226
          <para>
200
 
            Key type.  Default is DSA.
 
227
            Key type.  Default is <quote>DSA</quote>.
201
228
          </para>
202
229
        </listitem>
203
230
      </varlistentry>
213
240
      </varlistentry>
214
241
 
215
242
      <varlistentry>
 
243
        <term><literal>-s</literal>, <literal>--subtype
 
244
        <replaceable>type</replaceable></literal></term>
 
245
        <listitem>
 
246
          <para>
 
247
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
248
            encryption-only).
 
249
          </para>
 
250
        </listitem>
 
251
      </varlistentry>
 
252
 
 
253
      <varlistentry>
 
254
        <term><literal>-L</literal>, <literal>--sublength
 
255
        <replaceable>bits</replaceable></literal></term>
 
256
        <listitem>
 
257
          <para>
 
258
            Subkey length in bits.  Default is 2048.
 
259
          </para>
 
260
        </listitem>
 
261
      </varlistentry>
 
262
 
 
263
      <varlistentry>
216
264
        <term><literal>-e</literal>, <literal>--email</literal>
217
265
        <replaceable>address</replaceable></term>
218
266
        <listitem>
228
276
        <listitem>
229
277
          <para>
230
278
            Comment field for key.  The default value is
231
 
            "<literal>Mandos client key</literal>".
 
279
            <quote><literal>Mandos client key</literal></quote>.
232
280
          </para>
233
281
        </listitem>
234
282
      </varlistentry>
256
304
    </variablelist>
257
305
  </refsect1>
258
306
 
 
307
  <refsect1 id="overview">
 
308
    <title>OVERVIEW</title>
 
309
    <xi:include href="overview.xml"/>
 
310
    <para>
 
311
      This program is a small utility to generate new OpenPGP keys for
 
312
      new Mandos clients.
 
313
    </para>
 
314
  </refsect1>
 
315
 
259
316
  <refsect1 id="exit_status">
260
317
    <title>EXIT STATUS</title>
261
318
    <para>
 
319
      The exit status will be 0 if new keys were successfully created,
 
320
      otherwise not.
262
321
    </para>
263
322
  </refsect1>
264
323
  
 
324
  <refsect1 id="environment">
 
325
    <title>ENVIRONMENT</title>
 
326
    <variablelist>
 
327
      <varlistentry>
 
328
        <term><varname>TMPDIR</varname></term>
 
329
        <listitem>
 
330
          <para>
 
331
            If set, temporary files will be created here. See
 
332
            <citerefentry><refentrytitle>mktemp</refentrytitle>
 
333
            <manvolnum>1</manvolnum></citerefentry>.
 
334
          </para>
 
335
        </listitem>
 
336
      </varlistentry>
 
337
    </variablelist>
 
338
  </refsect1>
 
339
  
265
340
  <refsect1 id="file">
266
341
    <title>FILES</title>
267
342
    <para>
 
343
      Use the <option>--dir</option> option to change where
 
344
      <command>&COMMANDNAME;</command> will write the key files.  The
 
345
      default file names are shown here.
268
346
    </para>
 
347
    <variablelist>
 
348
      <varlistentry>
 
349
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
350
        <listitem>
 
351
          <para>
 
352
            OpenPGP secret key file which will be created or
 
353
            overwritten.
 
354
          </para>
 
355
        </listitem>
 
356
      </varlistentry>
 
357
      <varlistentry>
 
358
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
359
        <listitem>
 
360
          <para>
 
361
            OpenPGP public key file which will be created or
 
362
            overwritten.
 
363
          </para>
 
364
        </listitem>
 
365
      </varlistentry>
 
366
      <varlistentry>
 
367
        <term><filename>/tmp</filename></term>
 
368
        <listitem>
 
369
          <para>
 
370
            Temporary files will be written here if
 
371
            <varname>TMPDIR</varname> is not set.
 
372
          </para>
 
373
        </listitem>
 
374
      </varlistentry>
 
375
    </variablelist>
269
376
  </refsect1>
270
377
 
271
378
  <refsect1 id="bugs">
272
379
    <title>BUGS</title>
273
380
    <para>
 
381
      None are known at this time.
274
382
    </para>
275
383
  </refsect1>
276
384
 
277
 
  <refsect1 id="examples">
278
 
    <title>EXAMPLES</title>
279
 
    <para>
280
 
    </para>
 
385
  <refsect1 id="example">
 
386
    <title>EXAMPLE</title>
 
387
    <informalexample>
 
388
      <para>
 
389
        Normal invocation needs no options:
 
390
      </para>
 
391
      <para>
 
392
        <userinput>mandos-keygen</userinput>
 
393
      </para>
 
394
    </informalexample>
 
395
    <informalexample>
 
396
      <para>
 
397
        Create keys in another directory and of another type.  Force
 
398
        overwriting old key files:
 
399
      </para>
 
400
      <para>
 
401
 
 
402
<!-- do not wrap this line -->
 
403
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
 
404
 
 
405
      </para>
 
406
    </informalexample>
281
407
  </refsect1>
282
408
 
283
409
  <refsect1 id="security">
284
410
    <title>SECURITY</title>
285
411
    <para>
 
412
      The <option>--type</option>, <option>--length</option>,
 
413
      <option>--subtype</option>, and <option>--sublength</option>
 
414
      options can be used to create keys of insufficient security.  If
 
415
      in doubt, leave them to the default values.
 
416
    </para>
 
417
    <para>
 
418
      The key expire time is not guaranteed to be honored by
 
419
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
420
      <manvolnum>8</manvolnum></citerefentry>.
286
421
    </para>
287
422
  </refsect1>
288
423
 
292
427
      <citerefentry><refentrytitle>password-request</refentrytitle>
293
428
      <manvolnum>8mandos</manvolnum></citerefentry>,
294
429
      <citerefentry><refentrytitle>mandos</refentrytitle>
295
 
      <manvolnum>8</manvolnum></citerefentry>, and
 
430
      <manvolnum>8</manvolnum></citerefentry>,
296
431
      <citerefentry><refentrytitle>gpg</refentrytitle>
297
432
      <manvolnum>1</manvolnum></citerefentry>
298
433
    </para>