1
<?xml version='1.0' encoding='UTF-8'?>
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">
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
5
<!ENTITY TIMESTAMP "2017-02-23">
6
<!ENTITY % common SYSTEM "common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
<title>&COMMANDNAME;</title>
12
<!-- NWalsh's docbook scripts use this to generate the footer: -->
13
<productname>&COMMANDNAME;</productname>
14
<productnumber>&VERSION;</productnumber>
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
19
<firstname>Björn</firstname>
18
20
<surname>Påhlsson</surname>
20
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
24
26
<firstname>Teddy</firstname>
25
27
<surname>Hogeborn</surname>
27
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
33
<holder>Teddy Hogeborn & Björn Påhlsson</holder>
44
<holder>Teddy Hogeborn</holder>
45
<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/"/>.
47
<xi:include href="legalnotice.xml"/>
61
51
<refentrytitle>&COMMANDNAME;</refentrytitle>
62
52
<manvolnum>8</manvolnum>
66
56
<refname><command>&COMMANDNAME;</command></refname>
68
Generate keys for <citerefentry><refentrytitle>password-request
69
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
58
Generate key and password for Mandos client and server.
75
64
<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>--name</option>
90
<replaceable>NAME</replaceable></arg>
93
<arg choice="plain"><option>--email</option>
94
<replaceable>EMAIL</replaceable></arg>
97
<arg choice="plain"><option>--comment</option>
98
<replaceable>COMMENT</replaceable></arg>
101
<arg choice="plain"><option>--expire</option>
102
<replaceable>TIME</replaceable></arg>
66
<arg choice="plain"><option>--dir
67
<replaceable>DIRECTORY</replaceable></option></arg>
68
<arg choice="plain"><option>-d
69
<replaceable>DIRECTORY</replaceable></option></arg>
73
<arg choice="plain"><option>--type
74
<replaceable>KEYTYPE</replaceable></option></arg>
75
<arg choice="plain"><option>-t
76
<replaceable>KEYTYPE</replaceable></option></arg>
80
<arg choice="plain"><option>--length
81
<replaceable>BITS</replaceable></option></arg>
82
<arg choice="plain"><option>-l
83
<replaceable>BITS</replaceable></option></arg>
87
<arg choice="plain"><option>--subtype
88
<replaceable>KEYTYPE</replaceable></option></arg>
89
<arg choice="plain"><option>-s
90
<replaceable>KEYTYPE</replaceable></option></arg>
94
<arg choice="plain"><option>--sublength
95
<replaceable>BITS</replaceable></option></arg>
96
<arg choice="plain"><option>-L
97
<replaceable>BITS</replaceable></option></arg>
101
<arg choice="plain"><option>--name
102
<replaceable>NAME</replaceable></option></arg>
103
<arg choice="plain"><option>-n
104
<replaceable>NAME</replaceable></option></arg>
108
<arg choice="plain"><option>--email
109
<replaceable>ADDRESS</replaceable></option></arg>
110
<arg choice="plain"><option>-e
111
<replaceable>ADDRESS</replaceable></option></arg>
115
<arg choice="plain"><option>--comment
116
<replaceable>TEXT</replaceable></option></arg>
117
<arg choice="plain"><option>-c
118
<replaceable>TEXT</replaceable></option></arg>
122
<arg choice="plain"><option>--expire
123
<replaceable>TIME</replaceable></option></arg>
124
<arg choice="plain"><option>-x
125
<replaceable>TIME</replaceable></option></arg>
105
129
<arg choice="plain"><option>--force</option></arg>
109
<command>&COMMANDNAME;</command>
111
<arg choice="plain"><option>-d</option>
112
<replaceable>directory</replaceable></arg>
115
<arg choice="plain"><option>-t</option>
116
<replaceable>type</replaceable></arg>
119
<arg choice="plain"><option>-l</option>
120
<replaceable>bits</replaceable></arg>
123
<arg choice="plain"><option>-n</option>
124
<replaceable>NAME</replaceable></arg>
127
<arg choice="plain"><option>-e</option>
128
<replaceable>EMAIL</replaceable></arg>
131
<arg choice="plain"><option>-c</option>
132
<replaceable>COMMENT</replaceable></arg>
135
<arg choice="plain"><option>-x</option>
136
<replaceable>TIME</replaceable></arg>
139
130
<arg choice="plain"><option>-f</option></arg>
143
134
<command>&COMMANDNAME;</command>
144
135
<group choice="req">
145
<arg choice='plain'><option>-h</option></arg>
146
<arg choice='plain'><option>--help</option></arg>
150
<command>&COMMANDNAME;</command>
152
<arg choice='plain'><option>-v</option></arg>
153
<arg choice='plain'><option>--version</option></arg>
136
<arg choice="plain"><option>--password</option></arg>
137
<arg choice="plain"><option>-p</option></arg>
138
<arg choice="plain"><option>--passfile
139
<replaceable>FILE</replaceable></option></arg>
140
<arg choice="plain"><option>-F</option>
141
<replaceable>FILE</replaceable></arg>
145
<arg choice="plain"><option>--dir
146
<replaceable>DIRECTORY</replaceable></option></arg>
147
<arg choice="plain"><option>-d
148
<replaceable>DIRECTORY</replaceable></option></arg>
152
<arg choice="plain"><option>--name
153
<replaceable>NAME</replaceable></option></arg>
154
<arg choice="plain"><option>-n
155
<replaceable>NAME</replaceable></option></arg>
158
<arg choice="plain"><option>--no-ssh</option></arg>
159
<arg choice="plain"><option>-S</option></arg>
163
<command>&COMMANDNAME;</command>
165
<arg choice="plain"><option>--help</option></arg>
166
<arg choice="plain"><option>-h</option></arg>
170
<command>&COMMANDNAME;</command>
172
<arg choice="plain"><option>--version</option></arg>
173
<arg choice="plain"><option>-v</option></arg>
156
176
</refsynopsisdiv>
158
178
<refsect1 id="description">
159
179
<title>DESCRIPTION</title>
161
181
<command>&COMMANDNAME;</command> is a program to generate the
163
<citerefentry><refentrytitle>password-request</refentrytitle>
164
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
183
<citerefentry><refentrytitle>mandos-client</refentrytitle>
184
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
165
185
normally written to /etc/mandos for later installation into the
166
initrd image, but this, like most things, can be changed with
167
command line options.
186
initrd image, but this, and most other things, can be changed
187
with command line options.
190
This program can also be used with the
191
<option>--password</option> or <option>--passfile</option>
192
options to generate a ready-made section for
193
<filename>clients.conf</filename> (see
194
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
<manvolnum>5</manvolnum></citerefentry>).
171
199
<refsect1 id="purpose">
172
200
<title>PURPOSE</title>
175
202
The purpose of this is to enable <emphasis>remote and unattended
176
203
rebooting</emphasis> of client host computer with an
177
204
<emphasis>encrypted root file system</emphasis>. See <xref
178
205
linkend="overview"/> for details.
183
209
<refsect1 id="options">
184
210
<title>OPTIONS</title>
188
<term><literal>-h</literal>, <literal>--help</literal></term>
214
<term><option>--help</option></term>
215
<term><option>-h</option></term>
191
218
Show a help message and exit
197
<term><literal>-d</literal>, <literal>--dir
198
<replaceable>directory</replaceable></literal></term>
201
Target directory for key files.
207
<term><literal>-t</literal>, <literal>--type
208
<replaceable>type</replaceable></literal></term>
211
Key type. Default is DSA.
217
<term><literal>-l</literal>, <literal>--length
218
<replaceable>bits</replaceable></literal></term>
221
Key length in bits. Default is 1024.
227
<term><literal>-e</literal>, <literal>--email</literal>
228
<replaceable>address</replaceable></term>
225
<replaceable>DIRECTORY</replaceable></option></term>
227
<replaceable>DIRECTORY</replaceable></option></term>
230
Target directory for key files. Default is
231
<filename class="directory">/etc/mandos</filename>.
238
<replaceable>TYPE</replaceable></option></term>
240
<replaceable>TYPE</replaceable></option></term>
243
Key type. Default is <quote>RSA</quote>.
249
<term><option>--length
250
<replaceable>BITS</replaceable></option></term>
252
<replaceable>BITS</replaceable></option></term>
255
Key length in bits. Default is 4096.
261
<term><option>--subtype
262
<replaceable>KEYTYPE</replaceable></option></term>
264
<replaceable>KEYTYPE</replaceable></option></term>
267
Subkey type. Default is <quote>RSA</quote> (Elgamal
274
<term><option>--sublength
275
<replaceable>BITS</replaceable></option></term>
277
<replaceable>BITS</replaceable></option></term>
280
Subkey length in bits. Default is 4096.
286
<term><option>--email
287
<replaceable>ADDRESS</replaceable></option></term>
289
<replaceable>ADDRESS</replaceable></option></term>
231
292
Email address of key. Default is empty.
237
<term><literal>-c</literal>, <literal>--comment</literal>
238
<replaceable>comment</replaceable></term>
298
<term><option>--comment
299
<replaceable>TEXT</replaceable></option></term>
301
<replaceable>TEXT</replaceable></option></term>
241
Comment field for key. The default value is
242
"<literal>Mandos client key</literal>".
304
Comment field for key. Default is empty.
248
<term><literal>-x</literal>, <literal>--expire</literal>
249
<replaceable>time</replaceable></term>
310
<term><option>--expire
311
<replaceable>TIME</replaceable></option></term>
313
<replaceable>TIME</replaceable></option></term>
252
316
Key expire time. Default is no expiration. See
260
<term><literal>-f</literal>, <literal>--force</literal></term>
263
Force overwriting old keys.
324
<term><option>--force</option></term>
325
<term><option>-f</option></term>
328
Force overwriting old key.
333
<term><option>--password</option></term>
334
<term><option>-p</option></term>
337
Prompt for a password and encrypt it with the key already
338
present in either <filename>/etc/mandos</filename> or the
339
directory specified with the <option>--dir</option>
340
option. Outputs, on standard output, a section suitable
341
for inclusion in <citerefentry><refentrytitle
342
>mandos-clients.conf</refentrytitle><manvolnum
343
>8</manvolnum></citerefentry>. The host name or the name
344
specified with the <option>--name</option> option is used
345
for the section header. All other options are ignored,
346
and no key is created.
351
<term><option>--passfile
352
<replaceable>FILE</replaceable></option></term>
354
<replaceable>FILE</replaceable></option></term>
357
The same as <option>--password</option>, but read from
358
<replaceable>FILE</replaceable>, not the terminal.
363
<term><option>--no-ssh</option></term>
364
<term><option>-S</option></term>
367
When <option>--password</option> or
368
<option>--passfile</option> is given, this option will
369
prevent <command>&COMMANDNAME;</command> from calling
370
<command>ssh-keyscan</command> to get an SSH fingerprint
371
for this host and, if successful, output suitable config
372
options to use this fingerprint as a
373
<option>checker</option> option in the output. This is
374
otherwise the default behavior.
270
381
<refsect1 id="overview">
271
382
<title>OVERVIEW</title>
383
<xi:include href="overview.xml"/>
274
This program is a small program to generate new OpenPGP keys for
385
This program is a small utility to generate new OpenPGP keys for
386
new Mandos clients, and to generate sections for inclusion in
387
<filename>clients.conf</filename> on the server.
279
391
<refsect1 id="exit_status">
280
392
<title>EXIT STATUS</title>
394
The exit status will be 0 if a new key (or password, if the
395
<option>--password</option> option was used) was successfully
396
created, otherwise not.
400
<refsect1 id="environment">
401
<title>ENVIRONMENT</title>
404
<term><envar>TMPDIR</envar></term>
407
If set, temporary files will be created here. See
408
<citerefentry><refentrytitle>mktemp</refentrytitle>
409
<manvolnum>1</manvolnum></citerefentry>.
416
<refsect1 id="files">
286
417
<title>FILES</title>
419
Use the <option>--dir</option> option to change where
420
<command>&COMMANDNAME;</command> will write the key files. The
421
default file names are shown here.
425
<term><filename>/etc/mandos/seckey.txt</filename></term>
428
OpenPGP secret key file which will be created or
434
<term><filename>/etc/mandos/pubkey.txt</filename></term>
437
OpenPGP public key file which will be created or
443
<term><filename class="directory">/tmp</filename></term>
446
Temporary files will be written here if
447
<varname>TMPDIR</varname> is not set.
291
454
<refsect1 id="bugs">
292
455
<title>BUGS</title>
456
<xi:include href="bugs.xml"/>
297
459
<refsect1 id="example">
298
460
<title>EXAMPLE</title>
463
Normal invocation needs no options:
466
<userinput>&COMMANDNAME;</userinput>
471
Create key in another directory and of another type. Force
472
overwriting old key files:
476
<!-- do not wrap this line -->
477
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
483
Prompt for a password, encrypt it with the key in <filename
484
class="directory">/etc/mandos</filename> and output a section
485
suitable for <filename>clients.conf</filename>.
488
<userinput>&COMMANDNAME; --password</userinput>
493
Prompt for a password, encrypt it with the key in the
494
<filename>client-key</filename> directory and output a section
495
suitable for <filename>clients.conf</filename>.
499
<!-- do not wrap this line -->
500
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
303
506
<refsect1 id="security">
304
507
<title>SECURITY</title>
509
The <option>--type</option>, <option>--length</option>,
510
<option>--subtype</option>, and <option>--sublength</option>
511
options can be used to create keys of low security. If in
512
doubt, leave them to the default values.
515
The key expire time is <emphasis>not</emphasis> guaranteed to be
516
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
517
<manvolnum>8</manvolnum></citerefentry>.
309
521
<refsect1 id="see_also">
310
522
<title>SEE ALSO</title>
312
<citerefentry><refentrytitle>password-request</refentrytitle>
524
<citerefentry><refentrytitle>intro</refentrytitle>
313
525
<manvolnum>8mandos</manvolnum></citerefentry>,
526
<citerefentry><refentrytitle>gpg</refentrytitle>
527
<manvolnum>1</manvolnum></citerefentry>,
528
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
529
<manvolnum>5</manvolnum></citerefentry>,
314
530
<citerefentry><refentrytitle>mandos</refentrytitle>
315
<manvolnum>8</manvolnum></citerefentry>, and
316
<citerefentry><refentrytitle>gpg</refentrytitle>
531
<manvolnum>8</manvolnum></citerefentry>,
532
<citerefentry><refentrytitle>mandos-client</refentrytitle>
533
<manvolnum>8mandos</manvolnum></citerefentry>,
534
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
317
535
<manvolnum>1</manvolnum></citerefentry>
540
<!-- Local Variables: -->
541
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
542
<!-- time-stamp-end: "[\"']>" -->
543
<!-- time-stamp-format: "%:y-%02m-%02d" -->