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
- browse files at revision 742
- compare with another revision
- download diff
- download tarball
- view history from revision 742
- Committer: Teddy Hogeborn
- Date: 2015-03-10 18:03:38 UTC
- Revision ID: teddy@recompile.se-20150310180338-pcxw6r2qmw9k6br9
Add ":!RSA" to GnuTLS priority string, to disallow non-DHE kx.
If Mandos was somehow made to use a non-ephemeral Diffie-Hellman key
exchange algorithm in the TLS handshake, any saved network traffic
could then be decrypted later if the Mandos client key was obtained.
By default, Mandos uses ephemeral DH key exchanges which does not have
this problem, but a non-ephemeral key exchange algorithm was still
enabled by default. The simplest solution is to simply turn that off,
which ensures that Mandos will always use ephemeral DH key exchanges.
There is a "PFS" priority string specifier, but we can't use it because:
1. Security-wise, it is a mix between "NORMAL" and "SECURE128" - it
enables a lot more algorithms than "SECURE256".
2. It is only available since GnuTLS 3.2.4.
Thanks to Andreas Fischer <af@bantuX.org> for reporting this issue.
If Mandos was somehow made to use a non-ephemeral Diffie-Hellman key
exchange algorithm in the TLS handshake, any saved network traffic
could then be decrypted later if the Mandos client key was obtained.
By default, Mandos uses ephemeral DH key exchanges which does not have
this problem, but a non-ephemeral key exchange algorithm was still
enabled by default. The simplest solution is to simply turn that off,
which ensures that Mandos will always use ephemeral DH key exchanges.
There is a "PFS" priority string specifier, but we can't use it because:
1. Security-wise, it is a mix between "NORMAL" and "SECURE128" - it
enables a lot more algorithms than "SECURE256".
2. It is only available since GnuTLS 3.2.4.
Thanks to Andreas Fischer <af@bantuX.org> for reporting this issue.
- files added:
- .bzr-builddeb
- debian
- debian/po
- debian/source
- debian/upstream
- network-hooks.d
- files removed:
- network-protocol.txt
- files renamed:
- mandos-client.c => plugin-runner.c
- mandos-client.xml => plugin-runner.xml
- plugins.d/password-request.c => plugins.d/mandos-client.c
- plugins.d/password-request.xml => plugins.d/mandos-client.xml
- files modified:
- Makefile
added
removed
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 "2014-06-22">
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>2011</year>
37
<year>2012</year>
38
<holder>Teddy Hogeborn</holder>
39
<holder>Björn Påhlsson</holder>
40
</copyright>
41
<xi:include href="legalnotice.xml"/>
42
</refentryinfo>
43
44
<refmeta>
45
<refentrytitle>&COMMANDNAME;</refentrytitle>
46
<manvolnum>8</manvolnum>
47
</refmeta>
48
49
<refnamediv>
50
<refname><command>&COMMANDNAME;</command></refname>
51
<refpurpose>
52
Generate key and password for Mandos client and server.
53
</refpurpose>
54
</refnamediv>
55
56
<refsynopsisdiv>
57
<cmdsynopsis>
58
<command>&COMMANDNAME;</command>
59
<group>
60
<arg choice="plain"><option>--dir
61
<replaceable>DIRECTORY</replaceable></option></arg>
62
<arg choice="plain"><option>-d
63
<replaceable>DIRECTORY</replaceable></option></arg>
64
</group>
65
<sbr/>
66
<group>
67
<arg choice="plain"><option>--type
68
<replaceable>KEYTYPE</replaceable></option></arg>
69
<arg choice="plain"><option>-t
70
<replaceable>KEYTYPE</replaceable></option></arg>
71
</group>
72
<sbr/>
73
<group>
74
<arg choice="plain"><option>--length
75
<replaceable>BITS</replaceable></option></arg>
76
<arg choice="plain"><option>-l
77
<replaceable>BITS</replaceable></option></arg>
78
</group>
79
<sbr/>
80
<group>
81
<arg choice="plain"><option>--subtype
82
<replaceable>KEYTYPE</replaceable></option></arg>
83
<arg choice="plain"><option>-s
84
<replaceable>KEYTYPE</replaceable></option></arg>
85
</group>
86
<sbr/>
87
<group>
88
<arg choice="plain"><option>--sublength
89
<replaceable>BITS</replaceable></option></arg>
90
<arg choice="plain"><option>-L
91
<replaceable>BITS</replaceable></option></arg>
92
</group>
93
<sbr/>
94
<group>
95
<arg choice="plain"><option>--name
96
<replaceable>NAME</replaceable></option></arg>
97
<arg choice="plain"><option>-n
98
<replaceable>NAME</replaceable></option></arg>
99
</group>
100
<sbr/>
101
<group>
102
<arg choice="plain"><option>--email
103
<replaceable>ADDRESS</replaceable></option></arg>
104
<arg choice="plain"><option>-e
105
<replaceable>ADDRESS</replaceable></option></arg>
106
</group>
107
<sbr/>
108
<group>
109
<arg choice="plain"><option>--comment
110
<replaceable>TEXT</replaceable></option></arg>
111
<arg choice="plain"><option>-c
112
<replaceable>TEXT</replaceable></option></arg>
113
</group>
114
<sbr/>
115
<group>
116
<arg choice="plain"><option>--expire
117
<replaceable>TIME</replaceable></option></arg>
118
<arg choice="plain"><option>-x
119
<replaceable>TIME</replaceable></option></arg>
120
</group>
121
<sbr/>
122
<group>
123
<arg choice="plain"><option>--force</option></arg>
124
<arg choice="plain"><option>-f</option></arg>
125
</group>
126
</cmdsynopsis>
127
<cmdsynopsis>
128
<command>&COMMANDNAME;</command>
129
<group choice="req">
130
<arg choice="plain"><option>--password</option></arg>
131
<arg choice="plain"><option>-p</option></arg>
132
<arg choice="plain"><option>--passfile
133
<replaceable>FILE</replaceable></option></arg>
134
<arg choice="plain"><option>-F</option>
135
<replaceable>FILE</replaceable></arg>
136
</group>
137
<sbr/>
138
<group>
139
<arg choice="plain"><option>--dir
140
<replaceable>DIRECTORY</replaceable></option></arg>
141
<arg choice="plain"><option>-d
142
<replaceable>DIRECTORY</replaceable></option></arg>
143
</group>
144
<sbr/>
145
<group>
146
<arg choice="plain"><option>--name
147
<replaceable>NAME</replaceable></option></arg>
148
<arg choice="plain"><option>-n
149
<replaceable>NAME</replaceable></option></arg>
150
</group>
151
<group>
152
<arg choice="plain"><option>--no-ssh</option></arg>
153
<arg choice="plain"><option>-S</option></arg>
154
</group>
155
</cmdsynopsis>
156
<cmdsynopsis>
157
<command>&COMMANDNAME;</command>
158
<group choice="req">
159
<arg choice="plain"><option>--help</option></arg>
160
<arg choice="plain"><option>-h</option></arg>
161
</group>
162
</cmdsynopsis>
163
<cmdsynopsis>
164
<command>&COMMANDNAME;</command>
165
<group choice="req">
166
<arg choice="plain"><option>--version</option></arg>
167
<arg choice="plain"><option>-v</option></arg>
168
</group>
169
</cmdsynopsis>
170
</refsynopsisdiv>
171
172
<refsect1 id="description">
173
<title>DESCRIPTION</title>
174
<para>
175
<command>&COMMANDNAME;</command> is a program to generate the
176
OpenPGP key used by
177
<citerefentry><refentrytitle>mandos-client</refentrytitle>
178
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
179
normally written to /etc/mandos for later installation into the
180
initrd image, but this, and most other things, can be changed
181
with command line options.
182
</para>
183
<para>
184
This program can also be used with the
185
<option>--password</option> or <option>--passfile</option>
186
options to generate a ready-made section for
187
<filename>clients.conf</filename> (see
188
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
189
<manvolnum>5</manvolnum></citerefentry>).
190
</para>
191
</refsect1>
192
193
<refsect1 id="purpose">
194
<title>PURPOSE</title>
195
<para>
196
The purpose of this is to enable <emphasis>remote and unattended
197
rebooting</emphasis> of client host computer with an
198
<emphasis>encrypted root file system</emphasis>. See <xref
199
linkend="overview"/> for details.
200
</para>
201
</refsect1>
202
203
<refsect1 id="options">
204
<title>OPTIONS</title>
205
206
<variablelist>
207
<varlistentry>
208
<term><option>--help</option></term>
209
<term><option>-h</option></term>
210
<listitem>
211
<para>
212
Show a help message and exit
213
</para>
214
</listitem>
215
</varlistentry>
216
217
<varlistentry>
218
<term><option>--dir
219
<replaceable>DIRECTORY</replaceable></option></term>
220
<term><option>-d
221
<replaceable>DIRECTORY</replaceable></option></term>
222
<listitem>
223
<para>
224
Target directory for key files. Default is
225
<filename class="directory">/etc/mandos</filename>.
226
</para>
227
</listitem>
228
</varlistentry>
229
230
<varlistentry>
231
<term><option>--type
232
<replaceable>TYPE</replaceable></option></term>
233
<term><option>-t
234
<replaceable>TYPE</replaceable></option></term>
235
<listitem>
236
<para>
237
Key type. Default is <quote>RSA</quote>.
238
</para>
239
</listitem>
240
</varlistentry>
241
242
<varlistentry>
243
<term><option>--length
244
<replaceable>BITS</replaceable></option></term>
245
<term><option>-l
246
<replaceable>BITS</replaceable></option></term>
247
<listitem>
248
<para>
249
Key length in bits. Default is 4096.
250
</para>
251
</listitem>
252
</varlistentry>
253
254
<varlistentry>
255
<term><option>--subtype
256
<replaceable>KEYTYPE</replaceable></option></term>
257
<term><option>-s
258
<replaceable>KEYTYPE</replaceable></option></term>
259
<listitem>
260
<para>
261
Subkey type. Default is <quote>RSA</quote> (Elgamal
262
encryption-only).
263
</para>
264
</listitem>
265
</varlistentry>
266
267
<varlistentry>
268
<term><option>--sublength
269
<replaceable>BITS</replaceable></option></term>
270
<term><option>-L
271
<replaceable>BITS</replaceable></option></term>
272
<listitem>
273
<para>
274
Subkey length in bits. Default is 4096.
275
</para>
276
</listitem>
277
</varlistentry>
278
279
<varlistentry>
280
<term><option>--email
281
<replaceable>ADDRESS</replaceable></option></term>
282
<term><option>-e
283
<replaceable>ADDRESS</replaceable></option></term>
284
<listitem>
285
<para>
286
Email address of key. Default is empty.
287
</para>
288
</listitem>
289
</varlistentry>
290
291
<varlistentry>
292
<term><option>--comment
293
<replaceable>TEXT</replaceable></option></term>
294
<term><option>-c
295
<replaceable>TEXT</replaceable></option></term>
296
<listitem>
297
<para>
298
Comment field for key. Default is empty.
299
</para>
300
</listitem>
301
</varlistentry>
302
303
<varlistentry>
304
<term><option>--expire
305
<replaceable>TIME</replaceable></option></term>
306
<term><option>-x
307
<replaceable>TIME</replaceable></option></term>
308
<listitem>
309
<para>
310
Key expire time. Default is no expiration. See
311
<citerefentry><refentrytitle>gpg</refentrytitle>
312
<manvolnum>1</manvolnum></citerefentry> for syntax.
313
</para>
314
</listitem>
315
</varlistentry>
316
317
<varlistentry>
318
<term><option>--force</option></term>
319
<term><option>-f</option></term>
320
<listitem>
321
<para>
322
Force overwriting old key.
323
</para>
324
</listitem>
325
</varlistentry>
326
<varlistentry>
327
<term><option>--password</option></term>
328
<term><option>-p</option></term>
329
<listitem>
330
<para>
331
Prompt for a password and encrypt it with the key already
332
present in either <filename>/etc/mandos</filename> or the
333
directory specified with the <option>--dir</option>
334
option. Outputs, on standard output, a section suitable
335
for inclusion in <citerefentry><refentrytitle
336
>mandos-clients.conf</refentrytitle><manvolnum
337
>8</manvolnum></citerefentry>. The host name or the name
338
specified with the <option>--name</option> option is used
339
for the section header. All other options are ignored,
340
and no key is created.
341
</para>
342
</listitem>
343
</varlistentry>
344
<varlistentry>
345
<term><option>--passfile
346
<replaceable>FILE</replaceable></option></term>
347
<term><option>-F
348
<replaceable>FILE</replaceable></option></term>
349
<listitem>
350
<para>
351
The same as <option>--password</option>, but read from
352
<replaceable>FILE</replaceable>, not the terminal.
353
</para>
354
</listitem>
355
</varlistentry>
356
<varlistentry>
357
<term><option>--no-ssh</option></term>
358
<term><option>-S</option></term>
359
<listitem>
360
<para>
361
When <option>--password</option> or
362
<option>--passfile</option> is given, this option will
363
prevent <command>&COMMANDNAME;</command> from calling
364
<command>ssh-keyscan</command> to get an SSH fingerprint
365
for this host and, if successful, output suitable config
366
options to use this fingerprint as a
367
<option>checker</option> option in the output. This is
368
otherwise the default behavior.
369
</para>
370
</listitem>
371
</varlistentry>
372
</variablelist>
373
</refsect1>
374
375
<refsect1 id="overview">
376
<title>OVERVIEW</title>
377
<xi:include href="overview.xml"/>
378
<para>
379
This program is a small utility to generate new OpenPGP keys for
380
new Mandos clients, and to generate sections for inclusion in
381
<filename>clients.conf</filename> on the server.
382
</para>
383
</refsect1>
384
385
<refsect1 id="exit_status">
386
<title>EXIT STATUS</title>
387
<para>
388
The exit status will be 0 if a new key (or password, if the
389
<option>--password</option> option was used) was successfully
390
created, otherwise not.
391
</para>
392
</refsect1>
393
394
<refsect1 id="environment">
395
<title>ENVIRONMENT</title>
396
<variablelist>
397
<varlistentry>
398
<term><envar>TMPDIR</envar></term>
399
<listitem>
400
<para>
401
If set, temporary files will be created here. See
402
<citerefentry><refentrytitle>mktemp</refentrytitle>
403
<manvolnum>1</manvolnum></citerefentry>.
404
</para>
405
</listitem>
406
</varlistentry>
407
</variablelist>
408
</refsect1>
409
410
<refsect1 id="files">
411
<title>FILES</title>
412
<para>
413
Use the <option>--dir</option> option to change where
414
<command>&COMMANDNAME;</command> will write the key files. The
415
default file names are shown here.
416
</para>
417
<variablelist>
418
<varlistentry>
419
<term><filename>/etc/mandos/seckey.txt</filename></term>
420
<listitem>
421
<para>
422
OpenPGP secret key file which will be created or
423
overwritten.
424
</para>
425
</listitem>
426
</varlistentry>
427
<varlistentry>
428
<term><filename>/etc/mandos/pubkey.txt</filename></term>
429
<listitem>
430
<para>
431
OpenPGP public key file which will be created or
432
overwritten.
433
</para>
434
</listitem>
435
</varlistentry>
436
<varlistentry>
437
<term><filename class="directory">/tmp</filename></term>
438
<listitem>
439
<para>
440
Temporary files will be written here if
441
<varname>TMPDIR</varname> is not set.
442
</para>
443
</listitem>
444
</varlistentry>
445
</variablelist>
446
</refsect1>
447
448
<!-- <refsect1 id="bugs"> -->
449
<!-- <title>BUGS</title> -->
450
<!-- <para> -->
451
<!-- </para> -->
452
<!-- </refsect1> -->
453
454
<refsect1 id="example">
455
<title>EXAMPLE</title>
456
<informalexample>
457
<para>
458
Normal invocation needs no options:
459
</para>
460
<para>
461
<userinput>&COMMANDNAME;</userinput>
462
</para>
463
</informalexample>
464
<informalexample>
465
<para>
466
Create key in another directory and of another type. Force
467
overwriting old key files:
468
</para>
469
<para>
470
471
<!-- do not wrap this line -->
472
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
473
474
</para>
475
</informalexample>
476
<informalexample>
477
<para>
478
Prompt for a password, encrypt it with the key in <filename
479
class="directory">/etc/mandos</filename> and output a section
480
suitable for <filename>clients.conf</filename>.
481
</para>
482
<para>
483
<userinput>&COMMANDNAME; --password</userinput>
484
</para>
485
</informalexample>
486
<informalexample>
487
<para>
488
Prompt for a password, encrypt it with the key in the
489
<filename>client-key</filename> directory and output a section
490
suitable for <filename>clients.conf</filename>.
491
</para>
492
<para>
493
494
<!-- do not wrap this line -->
495
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
496
497
</para>
498
</informalexample>
499
</refsect1>
500
501
<refsect1 id="security">
502
<title>SECURITY</title>
503
<para>
504
The <option>--type</option>, <option>--length</option>,
505
<option>--subtype</option>, and <option>--sublength</option>
506
options can be used to create keys of low security. If in
507
doubt, leave them to the default values.
508
</para>
509
<para>
510
The key expire time is <emphasis>not</emphasis> guaranteed to be
511
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
512
<manvolnum>8</manvolnum></citerefentry>.
513
</para>
514
</refsect1>
515
516
<refsect1 id="see_also">
517
<title>SEE ALSO</title>
518
<para>
519
<citerefentry><refentrytitle>intro</refentrytitle>
520
<manvolnum>8mandos</manvolnum></citerefentry>,
521
<citerefentry><refentrytitle>gpg</refentrytitle>
522
<manvolnum>1</manvolnum></citerefentry>,
523
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
524
<manvolnum>5</manvolnum></citerefentry>,
525
<citerefentry><refentrytitle>mandos</refentrytitle>
526
<manvolnum>8</manvolnum></citerefentry>,
527
<citerefentry><refentrytitle>mandos-client</refentrytitle>
528
<manvolnum>8mandos</manvolnum></citerefentry>,
529
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
530
<manvolnum>1</manvolnum></citerefentry>
531
</para>
532
</refsect1>
533
534
</refentry>
535
<!-- Local Variables: -->
536
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
537
<!-- time-stamp-end: "[\"']>" -->
538
<!-- time-stamp-format: "%:y-%02m-%02d" -->
539
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0