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 1107
- compare with another revision
- download diff
- download tarball
- view history from revision 1107
- Committer: Teddy Hogeborn
- Date: 2019-07-06 22:13:13 UTC
- Revision ID: teddy@recompile.se-20190706221313-uaoa5cup12s72rec
mandos-ctl: Update Emacs lisp test runner code
* mandos-ctl: Update Emacs lisp after-save-hook test runner to use
file-local-name if available (i.e. Emacs 26), or to use
file-remote-p if not (Emacs 25). Either should be more
general than the tramp-* functions were. Also use
process-file-shell-command instead of shell-command,
which enables the use of the less intrusive
display-buffer-in-side-window action function argument
to display-buffer. This stops the takeover of buffers
(and/or disappearance of windows) when saving.
* mandos-ctl: Update Emacs lisp after-save-hook test runner to use
file-local-name if available (i.e. Emacs 26), or to use
file-remote-p if not (Emacs 25). Either should be more
general than the tramp-* functions were. Also use
process-file-shell-command instead of shell-command,
which enables the use of the less intrusive
display-buffer-in-side-window action function argument
to display-buffer. This stops the takeover of buffers
(and/or disappearance of windows) when saving.
- files added:
- .bzr-builddeb
- debian
- debian/po
- debian/source
- debian/upstream
- network-hooks.d
- plugin-helpers
- files removed:
- ca.pem
- files renamed:
- mandos-clients.conf => clients.conf
- server.py => mandos
- plugbasedclient.c => plugin-runner.c
- plugins.d/mandosclient.c => plugins.d/mandos-client.c
- plugins.d/passprompt.c => plugins.d/password-prompt.c
- 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 "2019-02-10">
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.
367
</para>
368
</listitem>
369
</varlistentry>
370
<varlistentry>
371
<term><option>--passfile
372
<replaceable>FILE</replaceable></option></term>
373
<term><option>-F
374
<replaceable>FILE</replaceable></option></term>
375
<listitem>
376
<para>
377
The same as <option>--password</option>, but read from
378
<replaceable>FILE</replaceable>, not the terminal.
379
</para>
380
</listitem>
381
</varlistentry>
382
<varlistentry>
383
<term><option>--no-ssh</option></term>
384
<term><option>-S</option></term>
385
<listitem>
386
<para>
387
When <option>--password</option> or
388
<option>--passfile</option> is given, this option will
389
prevent <command>&COMMANDNAME;</command> from calling
390
<command>ssh-keyscan</command> to get an SSH fingerprint
391
for this host and, if successful, output suitable config
392
options to use this fingerprint as a
393
<option>checker</option> option in the output. This is
394
otherwise the default behavior.
395
</para>
396
</listitem>
397
</varlistentry>
398
</variablelist>
399
</refsect1>
400
401
<refsect1 id="overview">
402
<title>OVERVIEW</title>
403
<xi:include href="overview.xml"/>
404
<para>
405
This program is a small utility to generate new TLS and OpenPGP
406
keys for new Mandos clients, and to generate sections for
407
inclusion in <filename>clients.conf</filename> on the server.
408
</para>
409
</refsect1>
410
411
<refsect1 id="exit_status">
412
<title>EXIT STATUS</title>
413
<para>
414
The exit status will be 0 if a new key (or password, if the
415
<option>--password</option> option was used) was successfully
416
created, otherwise not.
417
</para>
418
</refsect1>
419
420
<refsect1 id="environment">
421
<title>ENVIRONMENT</title>
422
<variablelist>
423
<varlistentry>
424
<term><envar>TMPDIR</envar></term>
425
<listitem>
426
<para>
427
If set, temporary files will be created here. See
428
<citerefentry><refentrytitle>mktemp</refentrytitle>
429
<manvolnum>1</manvolnum></citerefentry>.
430
</para>
431
</listitem>
432
</varlistentry>
433
</variablelist>
434
</refsect1>
435
436
<refsect1 id="files">
437
<title>FILES</title>
438
<para>
439
Use the <option>--dir</option> option to change where
440
<command>&COMMANDNAME;</command> will write the key files. The
441
default file names are shown here.
442
</para>
443
<variablelist>
444
<varlistentry>
445
<term><filename>/etc/keys/mandos/seckey.txt</filename></term>
446
<listitem>
447
<para>
448
OpenPGP secret key file which will be created or
449
overwritten.
450
</para>
451
</listitem>
452
</varlistentry>
453
<varlistentry>
454
<term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
455
<listitem>
456
<para>
457
OpenPGP public key file which will be created or
458
overwritten.
459
</para>
460
</listitem>
461
</varlistentry>
462
<varlistentry>
463
<term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
464
<listitem>
465
<para>
466
Private key file which will be created or overwritten.
467
</para>
468
</listitem>
469
</varlistentry>
470
<varlistentry>
471
<term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
472
<listitem>
473
<para>
474
Public key file which will be created or overwritten.
475
</para>
476
</listitem>
477
</varlistentry>
478
<varlistentry>
479
<term><filename class="directory">/tmp</filename></term>
480
<listitem>
481
<para>
482
Temporary files will be written here if
483
<varname>TMPDIR</varname> is not set.
484
</para>
485
</listitem>
486
</varlistentry>
487
</variablelist>
488
</refsect1>
489
490
<refsect1 id="bugs">
491
<title>BUGS</title>
492
<xi:include href="bugs.xml"/>
493
</refsect1>
494
495
<refsect1 id="example">
496
<title>EXAMPLE</title>
497
<informalexample>
498
<para>
499
Normal invocation needs no options:
500
</para>
501
<para>
502
<userinput>&COMMANDNAME;</userinput>
503
</para>
504
</informalexample>
505
<informalexample>
506
<para>
507
Create key in another directory and of another type. Force
508
overwriting old key files:
509
</para>
510
<para>
511
512
<!-- do not wrap this line -->
513
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
514
515
</para>
516
</informalexample>
517
<informalexample>
518
<para>
519
Prompt for a password, encrypt it with the keys in <filename
520
class="directory">/etc/keys/mandos</filename> and output a
521
section suitable for <filename>clients.conf</filename>.
522
</para>
523
<para>
524
<userinput>&COMMANDNAME; --password</userinput>
525
</para>
526
</informalexample>
527
<informalexample>
528
<para>
529
Prompt for a password, encrypt it with the keys in the
530
<filename>client-key</filename> directory and output a section
531
suitable for <filename>clients.conf</filename>.
532
</para>
533
<para>
534
535
<!-- do not wrap this line -->
536
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
537
538
</para>
539
</informalexample>
540
</refsect1>
541
542
<refsect1 id="security">
543
<title>SECURITY</title>
544
<para>
545
The <option>--type</option>, <option>--length</option>,
546
<option>--subtype</option>, and <option>--sublength</option>
547
options can be used to create keys of low security. If in
548
doubt, leave them to the default values.
549
</para>
550
<para>
551
The key expire time is <emphasis>not</emphasis> guaranteed to be
552
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
553
<manvolnum>8</manvolnum></citerefentry>.
554
</para>
555
</refsect1>
556
557
<refsect1 id="see_also">
558
<title>SEE ALSO</title>
559
<para>
560
<citerefentry><refentrytitle>intro</refentrytitle>
561
<manvolnum>8mandos</manvolnum></citerefentry>,
562
<citerefentry><refentrytitle>gpg</refentrytitle>
563
<manvolnum>1</manvolnum></citerefentry>,
564
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
565
<manvolnum>5</manvolnum></citerefentry>,
566
<citerefentry><refentrytitle>mandos</refentrytitle>
567
<manvolnum>8</manvolnum></citerefentry>,
568
<citerefentry><refentrytitle>mandos-client</refentrytitle>
569
<manvolnum>8mandos</manvolnum></citerefentry>,
570
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
571
<manvolnum>1</manvolnum></citerefentry>
572
</para>
573
</refsect1>
574
575
</refentry>
576
<!-- Local Variables: -->
577
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
578
<!-- time-stamp-end: "[\"']>" -->
579
<!-- time-stamp-format: "%:y-%02m-%02d" -->
580
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0