1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
5
<!ENTITY TIMESTAMP "2019-02-10">
6
<!ENTITY % common SYSTEM "common.ent">
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
<title>&COMMANDNAME;</title>
12
<title>Mandos Manual</title>
11
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
<productname>&COMMANDNAME;</productname>
13
<productnumber>&VERSION;</productnumber>
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
16
19
<firstname>Björn</firstname>
17
20
<surname>Påhlsson</surname>
19
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
23
26
<firstname>Teddy</firstname>
24
27
<surname>Hogeborn</surname>
26
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
32
45
<holder>Teddy Hogeborn</holder>
33
46
<holder>Björn Påhlsson</holder>
37
This manual page is free software: you can redistribute it
38
and/or modify it under the terms of the GNU General Public
39
License as published by the Free Software Foundation,
40
either version 3 of the License, or (at your option) any
45
This manual page is distributed in the hope that it will
46
be useful, but WITHOUT ANY WARRANTY; without even the
47
implied warranty of MERCHANTABILITY or FITNESS FOR A
48
PARTICULAR PURPOSE. See the GNU General Public License
53
You should have received a copy of the GNU General Public
54
License along with this program; If not, see
55
<ulink url="http://www.gnu.org/licenses/"/>.
48
<xi:include href="legalnotice.xml"/>
61
52
<refentrytitle>&COMMANDNAME;</refentrytitle>
62
53
<manvolnum>8</manvolnum>
66
57
<refname><command>&COMMANDNAME;</command></refname>
68
Generate keys for <citerefentry><refentrytitle>password-request
69
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
59
Generate key and password for Mandos client and server.
75
65
<command>&COMMANDNAME;</command>
77
<arg choice="plain"><option>--dir</option>
78
<replaceable>directory</replaceable></arg>
81
<arg choice="plain"><option>--type</option>
82
<replaceable>type</replaceable></arg>
85
<arg choice="plain"><option>--length</option>
86
<replaceable>bits</replaceable></arg>
89
<arg choice="plain"><option>--subtype</option>
90
<replaceable>type</replaceable></arg>
93
<arg choice="plain"><option>--sublength</option>
94
<replaceable>bits</replaceable></arg>
97
<arg choice="plain"><option>--name</option>
98
<replaceable>NAME</replaceable></arg>
101
<arg choice="plain"><option>--email</option>
102
<replaceable>EMAIL</replaceable></arg>
105
<arg choice="plain"><option>--comment</option>
106
<replaceable>COMMENT</replaceable></arg>
109
<arg choice="plain"><option>--expire</option>
110
<replaceable>TIME</replaceable></arg>
67
<arg choice="plain"><option>--dir
68
<replaceable>DIRECTORY</replaceable></option></arg>
69
<arg choice="plain"><option>-d
70
<replaceable>DIRECTORY</replaceable></option></arg>
74
<arg choice="plain"><option>--type
75
<replaceable>KEYTYPE</replaceable></option></arg>
76
<arg choice="plain"><option>-t
77
<replaceable>KEYTYPE</replaceable></option></arg>
81
<arg choice="plain"><option>--length
82
<replaceable>BITS</replaceable></option></arg>
83
<arg choice="plain"><option>-l
84
<replaceable>BITS</replaceable></option></arg>
88
<arg choice="plain"><option>--subtype
89
<replaceable>KEYTYPE</replaceable></option></arg>
90
<arg choice="plain"><option>-s
91
<replaceable>KEYTYPE</replaceable></option></arg>
95
<arg choice="plain"><option>--sublength
96
<replaceable>BITS</replaceable></option></arg>
97
<arg choice="plain"><option>-L
98
<replaceable>BITS</replaceable></option></arg>
102
<arg choice="plain"><option>--name
103
<replaceable>NAME</replaceable></option></arg>
104
<arg choice="plain"><option>-n
105
<replaceable>NAME</replaceable></option></arg>
109
<arg choice="plain"><option>--email
110
<replaceable>ADDRESS</replaceable></option></arg>
111
<arg choice="plain"><option>-e
112
<replaceable>ADDRESS</replaceable></option></arg>
116
<arg choice="plain"><option>--comment
117
<replaceable>TEXT</replaceable></option></arg>
118
<arg choice="plain"><option>-c
119
<replaceable>TEXT</replaceable></option></arg>
123
<arg choice="plain"><option>--expire
124
<replaceable>TIME</replaceable></option></arg>
125
<arg choice="plain"><option>-x
126
<replaceable>TIME</replaceable></option></arg>
130
<arg choice="plain"><option>--tls-keytype
131
<replaceable>KEYTYPE</replaceable></option></arg>
132
<arg choice="plain"><option>-T
133
<replaceable>KEYTYPE</replaceable></option></arg>
113
137
<arg choice="plain"><option>--force</option></arg>
117
<command>&COMMANDNAME;</command>
119
<arg choice="plain"><option>-d</option>
120
<replaceable>directory</replaceable></arg>
123
<arg choice="plain"><option>-t</option>
124
<replaceable>type</replaceable></arg>
127
<arg choice="plain"><option>-l</option>
128
<replaceable>bits</replaceable></arg>
131
<arg choice="plain"><option>-s</option>
132
<replaceable>type</replaceable></arg>
135
<arg choice="plain"><option>-L</option>
136
<replaceable>bits</replaceable></arg>
139
<arg choice="plain"><option>-n</option>
140
<replaceable>NAME</replaceable></arg>
143
<arg choice="plain"><option>-e</option>
144
<replaceable>EMAIL</replaceable></arg>
147
<arg choice="plain"><option>-c</option>
148
<replaceable>COMMENT</replaceable></arg>
151
<arg choice="plain"><option>-x</option>
152
<replaceable>TIME</replaceable></arg>
155
138
<arg choice="plain"><option>-f</option></arg>
159
142
<command>&COMMANDNAME;</command>
160
143
<group choice="req">
144
<arg choice="plain"><option>--password</option></arg>
145
<arg choice="plain"><option>-p</option></arg>
146
<arg choice="plain"><option>--passfile
147
<replaceable>FILE</replaceable></option></arg>
148
<arg choice="plain"><option>-F</option>
149
<replaceable>FILE</replaceable></arg>
153
<arg choice="plain"><option>--dir
154
<replaceable>DIRECTORY</replaceable></option></arg>
155
<arg choice="plain"><option>-d
156
<replaceable>DIRECTORY</replaceable></option></arg>
160
<arg choice="plain"><option>--name
161
<replaceable>NAME</replaceable></option></arg>
162
<arg choice="plain"><option>-n
163
<replaceable>NAME</replaceable></option></arg>
166
<arg choice="plain"><option>--no-ssh</option></arg>
167
<arg choice="plain"><option>-S</option></arg>
171
<command>&COMMANDNAME;</command>
173
<arg choice="plain"><option>--help</option></arg>
161
174
<arg choice="plain"><option>-h</option></arg>
162
<arg choice="plain"><option>--help</option></arg>
166
178
<command>&COMMANDNAME;</command>
167
179
<group choice="req">
180
<arg choice="plain"><option>--version</option></arg>
168
181
<arg choice="plain"><option>-v</option></arg>
169
<arg choice="plain"><option>--version</option></arg>
172
184
</refsynopsisdiv>
174
186
<refsect1 id="description">
175
187
<title>DESCRIPTION</title>
177
189
<command>&COMMANDNAME;</command> is a program to generate the
179
<citerefentry><refentrytitle>password-request</refentrytitle>
190
TLS and OpenPGP keys used by
191
<citerefentry><refentrytitle>mandos-client</refentrytitle>
180
192
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
181
193
normally written to /etc/mandos for later installation into the
182
initrd image, but this, like most things, can be changed with
183
command line options.
194
initrd image, but this, and most other things, can be changed
195
with command line options.
198
This program can also be used with the
199
<option>--password</option> or <option>--passfile</option>
200
options to generate a ready-made section for
201
<filename>clients.conf</filename> (see
202
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
203
<manvolnum>5</manvolnum></citerefentry>).
187
207
<refsect1 id="purpose">
188
208
<title>PURPOSE</title>
191
210
The purpose of this is to enable <emphasis>remote and unattended
192
211
rebooting</emphasis> of client host computer with an
193
212
<emphasis>encrypted root file system</emphasis>. See <xref
194
213
linkend="overview"/> for details.
199
217
<refsect1 id="options">
200
218
<title>OPTIONS</title>
204
<term><literal>-h</literal>, <literal>--help</literal></term>
222
<term><option>--help</option></term>
223
<term><option>-h</option></term>
207
226
Show a help message and exit
213
<term><literal>-d</literal>, <literal>--dir
214
<replaceable>directory</replaceable></literal></term>
217
Target directory for key files.
223
<term><literal>-t</literal>, <literal>--type
224
<replaceable>type</replaceable></literal></term>
227
Key type. Default is <quote>DSA</quote>.
233
<term><literal>-l</literal>, <literal>--length
234
<replaceable>bits</replaceable></literal></term>
237
Key length in bits. Default is 1024.
243
<term><literal>-s</literal>, <literal>--subtype
244
<replaceable>type</replaceable></literal></term>
247
Subkey type. Default is <quote>ELG-E</quote> (Elgamal
254
<term><literal>-L</literal>, <literal>--sublength
255
<replaceable>bits</replaceable></literal></term>
258
Subkey length in bits. Default is 2048.
264
<term><literal>-e</literal>, <literal>--email</literal>
265
<replaceable>address</replaceable></term>
233
<replaceable>DIRECTORY</replaceable></option></term>
235
<replaceable>DIRECTORY</replaceable></option></term>
238
Target directory for key files. Default is
239
<filename class="directory">/etc/mandos</filename>.
246
<replaceable>TYPE</replaceable></option></term>
248
<replaceable>TYPE</replaceable></option></term>
251
OpenPGP key type. Default is <quote>RSA</quote>.
257
<term><option>--length
258
<replaceable>BITS</replaceable></option></term>
260
<replaceable>BITS</replaceable></option></term>
263
OpenPGP key length in bits. Default is 4096.
269
<term><option>--subtype
270
<replaceable>KEYTYPE</replaceable></option></term>
272
<replaceable>KEYTYPE</replaceable></option></term>
275
OpenPGP subkey type. Default is <quote>RSA</quote>
281
<term><option>--sublength
282
<replaceable>BITS</replaceable></option></term>
284
<replaceable>BITS</replaceable></option></term>
287
OpenPGP subkey length in bits. Default is 4096.
293
<term><option>--email
294
<replaceable>ADDRESS</replaceable></option></term>
296
<replaceable>ADDRESS</replaceable></option></term>
268
299
Email address of key. Default is empty.
274
<term><literal>-c</literal>, <literal>--comment</literal>
275
<replaceable>comment</replaceable></term>
305
<term><option>--comment
306
<replaceable>TEXT</replaceable></option></term>
308
<replaceable>TEXT</replaceable></option></term>
278
Comment field for key. The default value is
279
<quote><literal>Mandos client key</literal></quote>.
311
Comment field for key. Default is empty.
285
<term><literal>-x</literal>, <literal>--expire</literal>
286
<replaceable>time</replaceable></term>
317
<term><option>--expire
318
<replaceable>TIME</replaceable></option></term>
320
<replaceable>TIME</replaceable></option></term>
289
323
Key expire time. Default is no expiration. See
297
<term><literal>-f</literal>, <literal>--force</literal></term>
300
Force overwriting old keys.
331
<term><option>--tls-keytype
332
<replaceable>KEYTYPE</replaceable></option></term>
334
<replaceable>KEYTYPE</replaceable></option></term>
337
TLS key type. Default is <quote>ed25519</quote>
343
<term><option>--force</option></term>
344
<term><option>-f</option></term>
347
Force overwriting old key.
352
<term><option>--password</option></term>
353
<term><option>-p</option></term>
356
Prompt for a password and encrypt it with the key already
357
present in either <filename>/etc/mandos</filename> or the
358
directory specified with the <option>--dir</option>
359
option. Outputs, on standard output, a section suitable
360
for inclusion in <citerefentry><refentrytitle
361
>mandos-clients.conf</refentrytitle><manvolnum
362
>8</manvolnum></citerefentry>. The host name or the name
363
specified with the <option>--name</option> option is used
364
for the section header. All other options are ignored,
365
and no key is created.
370
<term><option>--passfile
371
<replaceable>FILE</replaceable></option></term>
373
<replaceable>FILE</replaceable></option></term>
376
The same as <option>--password</option>, but read from
377
<replaceable>FILE</replaceable>, not the terminal.
382
<term><option>--no-ssh</option></term>
383
<term><option>-S</option></term>
386
When <option>--password</option> or
387
<option>--passfile</option> is given, this option will
388
prevent <command>&COMMANDNAME;</command> from calling
389
<command>ssh-keyscan</command> to get an SSH fingerprint
390
for this host and, if successful, output suitable config
391
options to use this fingerprint as a
392
<option>checker</option> option in the output. This is
393
otherwise the default behavior.
307
400
<refsect1 id="overview">
308
401
<title>OVERVIEW</title>
309
402
<xi:include href="overview.xml"/>
311
This program is a small utility to generate new OpenPGP keys for
404
This program is a small utility to generate new TLS and OpenPGP
405
keys for new Mandos clients, and to generate sections for
406
inclusion in <filename>clients.conf</filename> on the server.
316
410
<refsect1 id="exit_status">
317
411
<title>EXIT STATUS</title>
319
The exit status will be 0 if new keys were successfully created,
413
The exit status will be 0 if a new key (or password, if the
414
<option>--password</option> option was used) was successfully
415
created, otherwise not.
389
498
Normal invocation needs no options:
392
<userinput>mandos-keygen</userinput>
501
<userinput>&COMMANDNAME;</userinput>
394
503
</informalexample>
395
504
<informalexample>
397
Create keys in another directory and of another type. Force
506
Create key in another directory and of another type. Force
398
507
overwriting old key files:
402
511
<!-- do not wrap this line -->
403
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
512
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
518
Prompt for a password, encrypt it with the key in <filename
519
class="directory">/etc/mandos</filename> and output a section
520
suitable for <filename>clients.conf</filename>.
523
<userinput>&COMMANDNAME; --password</userinput>
528
Prompt for a password, encrypt it with the key in the
529
<filename>client-key</filename> directory and output a section
530
suitable for <filename>clients.conf</filename>.
534
<!-- do not wrap this line -->
535
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
406
538
</informalexample>
409
541
<refsect1 id="security">
410
542
<title>SECURITY</title>
412
544
The <option>--type</option>, <option>--length</option>,
413
545
<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.
546
options can be used to create keys of low security. If in
547
doubt, leave them to the default values.
418
The key expire time is not guaranteed to be honored by
419
<citerefentry><refentrytitle>mandos</refentrytitle>
550
The key expire time is <emphasis>not</emphasis> guaranteed to be
551
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
420
552
<manvolnum>8</manvolnum></citerefentry>.
424
556
<refsect1 id="see_also">
425
557
<title>SEE ALSO</title>
427
<citerefentry><refentrytitle>password-request</refentrytitle>
559
<citerefentry><refentrytitle>intro</refentrytitle>
428
560
<manvolnum>8mandos</manvolnum></citerefentry>,
561
<citerefentry><refentrytitle>gpg</refentrytitle>
562
<manvolnum>1</manvolnum></citerefentry>,
563
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
564
<manvolnum>5</manvolnum></citerefentry>,
429
565
<citerefentry><refentrytitle>mandos</refentrytitle>
430
566
<manvolnum>8</manvolnum></citerefentry>,
431
<citerefentry><refentrytitle>gpg</refentrytitle>
567
<citerefentry><refentrytitle>mandos-client</refentrytitle>
568
<manvolnum>8mandos</manvolnum></citerefentry>,
569
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
432
570
<manvolnum>1</manvolnum></citerefentry>
575
<!-- Local Variables: -->
576
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
577
<!-- time-stamp-end: "[\"']>" -->
578
<!-- time-stamp-format: "%:y-%02m-%02d" -->