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

  • Committer: Teddy Hogeborn
  • Date: 2021-02-01 19:30:45 UTC
  • Revision ID: teddy@recompile.se-20210201193045-lpg6aprpc4srem6k
Fix issue with french translation

Initial white space was missing in both msgid and msgstr of the french
translation, leading to checking tools reporing an incomplete
translation.  The string is a raw command line command, and therefore
did not need translation, so this was never a user-visible issue.

* debian/po/fr.po: Add missing whitespace to the id and translation
  for msgid " mandos-keygen -F/dev/null|grep ^key_id".

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.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 COMMANDNAME "mandos-keygen">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
 
8
]>
 
9
 
 
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
11
  <refentryinfo>
 
12
    <title>Mandos Manual</title>
 
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
14
    <productname>Mandos</productname>
 
15
    <productnumber>&version;</productnumber>
 
16
    <date>&TIMESTAMP;</date>
 
17
    <authorgroup>
 
18
      <author>
 
19
        <firstname>Björn</firstname>
 
20
        <surname>Påhlsson</surname>
 
21
        <address>
 
22
          <email>belorn@recompile.se</email>
 
23
        </address>
 
24
      </author>
 
25
      <author>
 
26
        <firstname>Teddy</firstname>
 
27
        <surname>Hogeborn</surname>
 
28
        <address>
 
29
          <email>teddy@recompile.se</email>
 
30
        </address>
 
31
      </author>
 
32
    </authorgroup>
 
33
    <copyright>
 
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
 
39
      <year>2013</year>
 
40
      <year>2014</year>
 
41
      <year>2015</year>
 
42
      <year>2016</year>
 
43
      <year>2017</year>
 
44
      <year>2018</year>
 
45
      <year>2019</year>
 
46
      <holder>Teddy Hogeborn</holder>
 
47
      <holder>Björn Påhlsson</holder>
 
48
    </copyright>
 
49
    <xi:include href="legalnotice.xml"/>
 
50
  </refentryinfo>
 
51
  
 
52
  <refmeta>
 
53
    <refentrytitle>&COMMANDNAME;</refentrytitle>
 
54
    <manvolnum>8</manvolnum>
 
55
  </refmeta>
 
56
  
 
57
  <refnamediv>
 
58
    <refname><command>&COMMANDNAME;</command></refname>
 
59
    <refpurpose>
 
60
      Generate key and password for Mandos client and server.
 
61
    </refpurpose>
 
62
  </refnamediv>
 
63
  
 
64
  <refsynopsisdiv>
 
65
    <cmdsynopsis>
 
66
      <command>&COMMANDNAME;</command>
 
67
      <group>
 
68
        <arg choice="plain"><option>--dir
 
69
        <replaceable>DIRECTORY</replaceable></option></arg>
 
70
        <arg choice="plain"><option>-d
 
71
        <replaceable>DIRECTORY</replaceable></option></arg>
 
72
      </group>
 
73
      <sbr/>
 
74
      <group>
 
75
        <arg choice="plain"><option>--type
 
76
        <replaceable>KEYTYPE</replaceable></option></arg>
 
77
        <arg choice="plain"><option>-t
 
78
        <replaceable>KEYTYPE</replaceable></option></arg>
 
79
      </group>
 
80
      <sbr/>
 
81
      <group>
 
82
        <arg choice="plain"><option>--length
 
83
        <replaceable>BITS</replaceable></option></arg>
 
84
        <arg choice="plain"><option>-l
 
85
        <replaceable>BITS</replaceable></option></arg>
 
86
      </group>
 
87
      <sbr/>
 
88
      <group>
 
89
        <arg choice="plain"><option>--subtype
 
90
        <replaceable>KEYTYPE</replaceable></option></arg>
 
91
        <arg choice="plain"><option>-s
 
92
        <replaceable>KEYTYPE</replaceable></option></arg>
 
93
      </group>
 
94
      <sbr/>
 
95
      <group>
 
96
        <arg choice="plain"><option>--sublength
 
97
        <replaceable>BITS</replaceable></option></arg>
 
98
        <arg choice="plain"><option>-L
 
99
        <replaceable>BITS</replaceable></option></arg>
 
100
      </group>
 
101
      <sbr/>
 
102
      <group>
 
103
        <arg choice="plain"><option>--name
 
104
        <replaceable>NAME</replaceable></option></arg>
 
105
        <arg choice="plain"><option>-n
 
106
        <replaceable>NAME</replaceable></option></arg>
 
107
      </group>
 
108
      <sbr/>
 
109
      <group>
 
110
        <arg choice="plain"><option>--email
 
111
        <replaceable>ADDRESS</replaceable></option></arg>
 
112
        <arg choice="plain"><option>-e
 
113
        <replaceable>ADDRESS</replaceable></option></arg>
 
114
      </group>
 
115
      <sbr/>
 
116
      <group>
 
117
        <arg choice="plain"><option>--comment
 
118
        <replaceable>TEXT</replaceable></option></arg>
 
119
        <arg choice="plain"><option>-c
 
120
        <replaceable>TEXT</replaceable></option></arg>
 
121
      </group>
 
122
      <sbr/>
 
123
      <group>
 
124
        <arg choice="plain"><option>--expire
 
125
        <replaceable>TIME</replaceable></option></arg>
 
126
        <arg choice="plain"><option>-x
 
127
        <replaceable>TIME</replaceable></option></arg>
 
128
      </group>
 
129
      <sbr/>
 
130
      <group>
 
131
        <arg choice="plain"><option>--tls-keytype
 
132
        <replaceable>KEYTYPE</replaceable></option></arg>
 
133
        <arg choice="plain"><option>-T
 
134
        <replaceable>KEYTYPE</replaceable></option></arg>
 
135
      </group>
 
136
      <sbr/>
 
137
      <group>
 
138
        <arg choice="plain"><option>--force</option></arg>
 
139
        <arg choice="plain"><option>-f</option></arg>
 
140
      </group>
 
141
    </cmdsynopsis>
 
142
    <cmdsynopsis>
 
143
      <command>&COMMANDNAME;</command>
 
144
      <group choice="req">
 
145
        <arg choice="plain"><option>--password</option></arg>
 
146
        <arg choice="plain"><option>-p</option></arg>
 
147
        <arg choice="plain"><option>--passfile
 
148
        <replaceable>FILE</replaceable></option></arg>
 
149
        <arg choice="plain"><option>-F</option>
 
150
        <replaceable>FILE</replaceable></arg>
 
151
      </group>
 
152
      <sbr/>
 
153
      <group>
 
154
        <arg choice="plain"><option>--dir
 
155
        <replaceable>DIRECTORY</replaceable></option></arg>
 
156
        <arg choice="plain"><option>-d
 
157
        <replaceable>DIRECTORY</replaceable></option></arg>
 
158
      </group>
 
159
      <sbr/>
 
160
      <group>
 
161
        <arg choice="plain"><option>--name
 
162
        <replaceable>NAME</replaceable></option></arg>
 
163
        <arg choice="plain"><option>-n
 
164
        <replaceable>NAME</replaceable></option></arg>
 
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
 
170
    </cmdsynopsis>
 
171
    <cmdsynopsis>
 
172
      <command>&COMMANDNAME;</command>
 
173
      <group choice="req">
 
174
        <arg choice="plain"><option>--help</option></arg>
 
175
        <arg choice="plain"><option>-h</option></arg>
 
176
      </group>
 
177
    </cmdsynopsis>
 
178
    <cmdsynopsis>
 
179
      <command>&COMMANDNAME;</command>
 
180
      <group choice="req">
 
181
        <arg choice="plain"><option>--version</option></arg>
 
182
        <arg choice="plain"><option>-v</option></arg>
 
183
      </group>
 
184
    </cmdsynopsis>
 
185
  </refsynopsisdiv>
 
186
  
 
187
  <refsect1 id="description">
 
188
    <title>DESCRIPTION</title>
 
189
    <para>
 
190
      <command>&COMMANDNAME;</command> is a program to generate the
 
191
      TLS and OpenPGP keys used by
 
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
193
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
194
      normally written to /etc/keys/mandos for later installation into
 
195
      the initrd image, but this, and most other things, can be
 
196
      changed with command line options.
 
197
    </para>
 
198
    <para>
 
199
      This program can also be used with the
 
200
      <option>--password</option> or <option>--passfile</option>
 
201
      options to generate a ready-made section for
 
202
      <filename>clients.conf</filename> (see
 
203
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
204
      <manvolnum>5</manvolnum></citerefentry>).
 
205
    </para>
 
206
  </refsect1>
 
207
  
 
208
  <refsect1 id="purpose">
 
209
    <title>PURPOSE</title>
 
210
    <para>
 
211
      The purpose of this is to enable <emphasis>remote and unattended
 
212
      rebooting</emphasis> of client host computer with an
 
213
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
214
      linkend="overview"/> for details.
 
215
    </para>
 
216
  </refsect1>
 
217
  
 
218
  <refsect1 id="options">
 
219
    <title>OPTIONS</title>
 
220
    
 
221
    <variablelist>
 
222
      <varlistentry>
 
223
        <term><option>--help</option></term>
 
224
        <term><option>-h</option></term>
 
225
        <listitem>
 
226
          <para>
 
227
            Show a help message and exit
 
228
          </para>
 
229
        </listitem>
 
230
      </varlistentry>
 
231
      
 
232
      <varlistentry>
 
233
        <term><option>--dir
 
234
        <replaceable>DIRECTORY</replaceable></option></term>
 
235
        <term><option>-d
 
236
        <replaceable>DIRECTORY</replaceable></option></term>
 
237
        <listitem>
 
238
          <para>
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
 
244
      
 
245
      <varlistentry>
 
246
        <term><option>--type
 
247
        <replaceable>TYPE</replaceable></option></term>
 
248
        <term><option>-t
 
249
        <replaceable>TYPE</replaceable></option></term>
 
250
        <listitem>
 
251
          <para>
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
 
253
          </para>
 
254
        </listitem>
 
255
      </varlistentry>
 
256
      
 
257
      <varlistentry>
 
258
        <term><option>--length
 
259
        <replaceable>BITS</replaceable></option></term>
 
260
        <term><option>-l
 
261
        <replaceable>BITS</replaceable></option></term>
 
262
        <listitem>
 
263
          <para>
 
264
            OpenPGP key length in bits.  Default is 4096.
 
265
          </para>
 
266
        </listitem>
 
267
      </varlistentry>
 
268
      
 
269
      <varlistentry>
 
270
        <term><option>--subtype
 
271
        <replaceable>KEYTYPE</replaceable></option></term>
 
272
        <term><option>-s
 
273
        <replaceable>KEYTYPE</replaceable></option></term>
 
274
        <listitem>
 
275
          <para>
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
 
277
          </para>
 
278
        </listitem>
 
279
      </varlistentry>
 
280
      
 
281
      <varlistentry>
 
282
        <term><option>--sublength
 
283
        <replaceable>BITS</replaceable></option></term>
 
284
        <term><option>-L
 
285
        <replaceable>BITS</replaceable></option></term>
 
286
        <listitem>
 
287
          <para>
 
288
            OpenPGP subkey length in bits.  Default is 4096.
 
289
          </para>
 
290
        </listitem>
 
291
      </varlistentry>
 
292
      
 
293
      <varlistentry>
 
294
        <term><option>--email
 
295
        <replaceable>ADDRESS</replaceable></option></term>
 
296
        <term><option>-e
 
297
        <replaceable>ADDRESS</replaceable></option></term>
 
298
        <listitem>
 
299
          <para>
 
300
            Email address of key.  Default is empty.
 
301
          </para>
 
302
        </listitem>
 
303
      </varlistentry>
 
304
      
 
305
      <varlistentry>
 
306
        <term><option>--comment
 
307
        <replaceable>TEXT</replaceable></option></term>
 
308
        <term><option>-c
 
309
        <replaceable>TEXT</replaceable></option></term>
 
310
        <listitem>
 
311
          <para>
 
312
            Comment field for key.  Default is empty.
 
313
          </para>
 
314
        </listitem>
 
315
      </varlistentry>
 
316
      
 
317
      <varlistentry>
 
318
        <term><option>--expire
 
319
        <replaceable>TIME</replaceable></option></term>
 
320
        <term><option>-x
 
321
        <replaceable>TIME</replaceable></option></term>
 
322
        <listitem>
 
323
          <para>
 
324
            Key expire time.  Default is no expiration.  See
 
325
            <citerefentry><refentrytitle>gpg</refentrytitle>
 
326
            <manvolnum>1</manvolnum></citerefentry> for syntax.
 
327
          </para>
 
328
        </listitem>
 
329
      </varlistentry>
 
330
      
 
331
      <varlistentry>
 
332
        <term><option>--tls-keytype
 
333
        <replaceable>KEYTYPE</replaceable></option></term>
 
334
        <term><option>-T
 
335
        <replaceable>KEYTYPE</replaceable></option></term>
 
336
        <listitem>
 
337
          <para>
 
338
            TLS key type.  Default is <quote>ed25519</quote>
 
339
          </para>
 
340
        </listitem>
 
341
      </varlistentry>
 
342
      
 
343
      <varlistentry>
 
344
        <term><option>--force</option></term>
 
345
        <term><option>-f</option></term>
 
346
        <listitem>
 
347
          <para>
 
348
            Force overwriting old key.
 
349
          </para>
 
350
        </listitem>
 
351
      </varlistentry>
 
352
      <varlistentry>
 
353
        <term><option>--password</option></term>
 
354
        <term><option>-p</option></term>
 
355
        <listitem>
 
356
          <para>
 
357
            Prompt for a password and encrypt it with the key already
 
358
            present in either <filename>/etc/keys/mandos</filename> or
 
359
            the directory specified with the <option>--dir</option>
 
360
            option.  Outputs, on standard output, a section suitable
 
361
            for inclusion in <citerefentry><refentrytitle
 
362
            >mandos-clients.conf</refentrytitle><manvolnum
 
363
            >8</manvolnum></citerefentry>.  The host name or the name
 
364
            specified with the <option>--name</option> option is used
 
365
            for the section header.  All other options are ignored,
 
366
            and no key is created.  Note: white space is stripped from
 
367
            the beginning and from the end of the password; See <xref
 
368
            linkend="bugs"/>.
 
369
          </para>
 
370
        </listitem>
 
371
      </varlistentry>
 
372
      <varlistentry>
 
373
        <term><option>--passfile
 
374
        <replaceable>FILE</replaceable></option></term>
 
375
        <term><option>-F
 
376
        <replaceable>FILE</replaceable></option></term>
 
377
        <listitem>
 
378
          <para>
 
379
            The same as <option>--password</option>, but read from
 
380
            <replaceable>FILE</replaceable>, not the terminal, and
 
381
            white space is not stripped from the password in any way.
 
382
          </para>
 
383
        </listitem>
 
384
      </varlistentry>
 
385
      <varlistentry>
 
386
        <term><option>--no-ssh</option></term>
 
387
        <term><option>-S</option></term>
 
388
        <listitem>
 
389
          <para>
 
390
            When <option>--password</option> or
 
391
            <option>--passfile</option> is given, this option will
 
392
            prevent <command>&COMMANDNAME;</command> from calling
 
393
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
394
            for this host and, if successful, output suitable config
 
395
            options to use this fingerprint as a
 
396
            <option>checker</option> option in the output.  This is
 
397
            otherwise the default behavior.
 
398
          </para>
 
399
        </listitem>
 
400
      </varlistentry>
 
401
    </variablelist>
 
402
  </refsect1>
 
403
  
 
404
  <refsect1 id="overview">
 
405
    <title>OVERVIEW</title>
 
406
    <xi:include href="overview.xml"/>
 
407
    <para>
 
408
      This program is a small utility to generate new TLS and OpenPGP
 
409
      keys for new Mandos clients, and to generate sections for
 
410
      inclusion in <filename>clients.conf</filename> on the server.
 
411
    </para>
 
412
  </refsect1>
 
413
  
 
414
  <refsect1 id="exit_status">
 
415
    <title>EXIT STATUS</title>
 
416
    <para>
 
417
      The exit status will be 0 if a new key (or password, if the
 
418
      <option>--password</option> option was used) was successfully
 
419
      created, otherwise not.
 
420
    </para>
 
421
  </refsect1>
 
422
  
 
423
  <refsect1 id="environment">
 
424
    <title>ENVIRONMENT</title>
 
425
    <variablelist>
 
426
      <varlistentry>
 
427
        <term><envar>TMPDIR</envar></term>
 
428
        <listitem>
 
429
          <para>
 
430
            If set, temporary files will be created here. See
 
431
            <citerefentry><refentrytitle>mktemp</refentrytitle>
 
432
            <manvolnum>1</manvolnum></citerefentry>.
 
433
          </para>
 
434
        </listitem>
 
435
      </varlistentry>
 
436
    </variablelist>
 
437
  </refsect1>
 
438
  
 
439
  <refsect1 id="files">
 
440
    <title>FILES</title>
 
441
    <para>
 
442
      Use the <option>--dir</option> option to change where
 
443
      <command>&COMMANDNAME;</command> will write the key files.  The
 
444
      default file names are shown here.
 
445
    </para>
 
446
    <variablelist>
 
447
      <varlistentry>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
 
449
        <listitem>
 
450
          <para>
 
451
            OpenPGP secret key file which will be created or
 
452
            overwritten.
 
453
          </para>
 
454
        </listitem>
 
455
      </varlistentry>
 
456
      <varlistentry>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
 
458
        <listitem>
 
459
          <para>
 
460
            OpenPGP public key file which will be created or
 
461
            overwritten.
 
462
          </para>
 
463
        </listitem>
 
464
      </varlistentry>
 
465
      <varlistentry>
 
466
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
467
        <listitem>
 
468
          <para>
 
469
            Private key file which will be created or overwritten.
 
470
          </para>
 
471
        </listitem>
 
472
      </varlistentry>
 
473
      <varlistentry>
 
474
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
475
        <listitem>
 
476
          <para>
 
477
            Public key file which will be created or overwritten.
 
478
          </para>
 
479
        </listitem>
 
480
      </varlistentry>
 
481
      <varlistentry>
 
482
        <term><filename class="directory">/tmp</filename></term>
 
483
        <listitem>
 
484
          <para>
 
485
            Temporary files will be written here if
 
486
            <varname>TMPDIR</varname> is not set.
 
487
          </para>
 
488
        </listitem>
 
489
      </varlistentry>
 
490
    </variablelist>
 
491
  </refsect1>
 
492
  
 
493
  <refsect1 id="bugs">
 
494
    <title>BUGS</title>
 
495
    <para>
 
496
      The <option>--password</option>/<option>-p</option> option
 
497
      strips white space from the start and from the end of the
 
498
      password before using it.  If this is a problem, use the
 
499
      <option>--passfile</option> option instead, which does not do
 
500
      this.
 
501
    </para>
 
502
    <xi:include href="bugs.xml"/>
 
503
  </refsect1>
 
504
  
 
505
  <refsect1 id="example">
 
506
    <title>EXAMPLE</title>
 
507
    <informalexample>
 
508
      <para>
 
509
        Normal invocation needs no options:
 
510
      </para>
 
511
      <para>
 
512
        <userinput>&COMMANDNAME;</userinput>
 
513
      </para>
 
514
    </informalexample>
 
515
    <informalexample>
 
516
      <para>
 
517
        Create key in another directory and of another type.  Force
 
518
        overwriting old key files:
 
519
      </para>
 
520
      <para>
 
521
 
 
522
<!-- do not wrap this line -->
 
523
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
 
524
 
 
525
      </para>
 
526
    </informalexample>
 
527
    <informalexample>
 
528
      <para>
 
529
        Prompt for a password, encrypt it with the keys in <filename
 
530
        class="directory">/etc/keys/mandos</filename> and output a
 
531
        section suitable for <filename>clients.conf</filename>.
 
532
      </para>
 
533
      <para>
 
534
        <userinput>&COMMANDNAME; --password</userinput>
 
535
      </para>
 
536
    </informalexample>
 
537
    <informalexample>
 
538
      <para>
 
539
        Prompt for a password, encrypt it with the keys in the
 
540
        <filename>client-key</filename> directory and output a section
 
541
        suitable for <filename>clients.conf</filename>.
 
542
      </para>
 
543
      <para>
 
544
 
 
545
<!-- do not wrap this line -->
 
546
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
547
 
 
548
      </para>
 
549
    </informalexample>
 
550
  </refsect1>
 
551
  
 
552
  <refsect1 id="security">
 
553
    <title>SECURITY</title>
 
554
    <para>
 
555
      The <option>--type</option>, <option>--length</option>,
 
556
      <option>--subtype</option>, and <option>--sublength</option>
 
557
      options can be used to create keys of low security.  If in
 
558
      doubt, leave them to the default values.
 
559
    </para>
 
560
    <para>
 
561
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
562
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
563
      <manvolnum>8</manvolnum></citerefentry>.
 
564
    </para>
 
565
  </refsect1>
 
566
  
 
567
  <refsect1 id="see_also">
 
568
    <title>SEE ALSO</title>
 
569
    <para>
 
570
      <citerefentry><refentrytitle>intro</refentrytitle>
 
571
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
572
      <citerefentry><refentrytitle>gpg</refentrytitle>
 
573
      <manvolnum>1</manvolnum></citerefentry>,
 
574
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
575
      <manvolnum>5</manvolnum></citerefentry>,
 
576
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
577
      <manvolnum>8</manvolnum></citerefentry>,
 
578
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
579
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
580
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
581
      <manvolnum>1</manvolnum></citerefentry>
 
582
    </para>
 
583
  </refsect1>
 
584
  
 
585
</refentry>
 
586
<!-- Local Variables: -->
 
587
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
588
<!-- time-stamp-end: "[\"']>" -->
 
589
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
590
<!-- End: -->