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">
5
<!ENTITY TIMESTAMP "2017-02-23">
6
<!ENTITY % common SYSTEM "common.ent">
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
<title>&COMMANDNAME;</title>
11
<!-- NWalsh's docbook scripts use this to generate the footer: -->
12
<productname>&COMMANDNAME;</productname>
13
<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>
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
<holder>Teddy Hogeborn & Björn Påhlsson</holder>
44
<holder>Teddy Hogeborn</holder>
45
<holder>Björn Påhlsson</holder>
36
This manual page is free software: you can redistribute it
37
and/or modify it under the terms of the GNU General Public
38
License as published by the Free Software Foundation,
39
either version 3 of the License, or (at your option) any
44
This manual page is distributed in the hope that it will
45
be useful, but WITHOUT ANY WARRANTY; without even the
46
implied warranty of MERCHANTABILITY or FITNESS FOR A
47
PARTICULAR PURPOSE. See the GNU General Public License
52
You should have received a copy of the GNU General Public
53
License along with this program; If not, see
54
<ulink url="http://www.gnu.org/licenses/"/>.
47
<xi:include href="legalnotice.xml"/>
60
51
<refentrytitle>&COMMANDNAME;</refentrytitle>
61
52
<manvolnum>8</manvolnum>
65
56
<refname><command>&COMMANDNAME;</command></refname>
67
Generate keys for <citerefentry><refentrytitle>password-request
68
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
58
Generate key and password for Mandos client and server.
74
64
<command>&COMMANDNAME;</command>
76
<arg choice="plain"><option>--dir</option>
77
<replaceable>directory</replaceable></arg>
80
<arg choice="plain"><option>--type</option>
81
<replaceable>type</replaceable></arg>
84
<arg choice="plain"><option>--length</option>
85
<replaceable>bits</replaceable></arg>
88
<arg choice="plain"><option>--name</option>
89
<replaceable>NAME</replaceable></arg>
92
<arg choice="plain"><option>--email</option>
93
<replaceable>EMAIL</replaceable></arg>
96
<arg choice="plain"><option>--comment</option>
97
<replaceable>COMMENT</replaceable></arg>
100
<arg choice="plain"><option>--expire</option>
101
<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>
104
129
<arg choice="plain"><option>--force</option></arg>
108
<command>&COMMANDNAME;</command>
110
<arg choice="plain"><option>-d</option>
111
<replaceable>directory</replaceable></arg>
114
<arg choice="plain"><option>-t</option>
115
<replaceable>type</replaceable></arg>
118
<arg choice="plain"><option>-l</option>
119
<replaceable>bits</replaceable></arg>
122
<arg choice="plain"><option>-n</option>
123
<replaceable>NAME</replaceable></arg>
126
<arg choice="plain"><option>-e</option>
127
<replaceable>EMAIL</replaceable></arg>
130
<arg choice="plain"><option>-c</option>
131
<replaceable>COMMENT</replaceable></arg>
134
<arg choice="plain"><option>-x</option>
135
<replaceable>TIME</replaceable></arg>
138
130
<arg choice="plain"><option>-f</option></arg>
142
134
<command>&COMMANDNAME;</command>
143
135
<group choice="req">
144
<arg choice='plain'><option>-h</option></arg>
145
<arg choice='plain'><option>--help</option></arg>
149
<command>&COMMANDNAME;</command>
151
<arg choice='plain'><option>-v</option></arg>
152
<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>
155
176
</refsynopsisdiv>
157
178
<refsect1 id="description">
158
179
<title>DESCRIPTION</title>
160
181
<command>&COMMANDNAME;</command> is a program to generate the
162
<citerefentry><refentrytitle>password-request</refentrytitle>
163
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
183
<citerefentry><refentrytitle>mandos-client</refentrytitle>
184
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
164
185
normally written to /etc/mandos for later installation into the
165
initrd image, but this, like most things, can be changed with
166
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>).
170
199
<refsect1 id="purpose">
171
200
<title>PURPOSE</title>
174
202
The purpose of this is to enable <emphasis>remote and unattended
175
203
rebooting</emphasis> of client host computer with an
176
204
<emphasis>encrypted root file system</emphasis>. See <xref
177
205
linkend="overview"/> for details.
182
209
<refsect1 id="options">
183
210
<title>OPTIONS</title>
187
<term><literal>-h</literal>, <literal>--help</literal></term>
214
<term><option>--help</option></term>
215
<term><option>-h</option></term>
190
218
Show a help message and exit
196
<term><literal>-d</literal>, <literal>--dir
197
<replaceable>directory</replaceable></literal></term>
200
Target directory for key files.
206
<term><literal>-t</literal>, <literal>--type
207
<replaceable>type</replaceable></literal></term>
210
Key type. Default is DSA.
216
<term><literal>-l</literal>, <literal>--length
217
<replaceable>bits</replaceable></literal></term>
220
Key length in bits. Default is 1024.
226
<term><literal>-e</literal>, <literal>--email</literal>
227
<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>
230
292
Email address of key. Default is empty.
236
<term><literal>-c</literal>, <literal>--comment</literal>
237
<replaceable>comment</replaceable></term>
298
<term><option>--comment
299
<replaceable>TEXT</replaceable></option></term>
301
<replaceable>TEXT</replaceable></option></term>
240
Comment field for key. The default value is
241
"<literal>Mandos client key</literal>".
304
Comment field for key. Default is empty.
247
<term><literal>-x</literal>, <literal>--expire</literal>
248
<replaceable>time</replaceable></term>
310
<term><option>--expire
311
<replaceable>TIME</replaceable></option></term>
313
<replaceable>TIME</replaceable></option></term>
251
316
Key expire time. Default is no expiration. See
259
<term><literal>-f</literal>, <literal>--force</literal></term>
262
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.
269
381
<refsect1 id="overview">
270
382
<title>OVERVIEW</title>
271
383
<xi:include href="overview.xml"/>
273
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.
278
391
<refsect1 id="exit_status">
279
392
<title>EXIT STATUS</title>
281
The exit status will be 0 if new keys were successfully created,
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.
351
463
Normal invocation needs no options:
354
<userinput>mandos-keygen</userinput>
466
<userinput>&COMMANDNAME;</userinput>
356
468
</informalexample>
357
469
<informalexample>
359
Create keys in another directory and of another type. Force
471
Create key in another directory and of another type. Force
360
472
overwriting old key files:
364
476
<!-- do not wrap this line -->
365
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
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>
368
503
</informalexample>
371
506
<refsect1 id="security">
372
507
<title>SECURITY</title>
374
The <option>--type</option> and <option>--length</option>
375
options can be used to create keys of insufficient security. If
376
in doubt, leave them to the default values.
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.
379
The key expire time is not guaranteed to be honored by
380
<citerefentry><refentrytitle>mandos</refentrytitle>
515
The key expire time is <emphasis>not</emphasis> guaranteed to be
516
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
381
517
<manvolnum>8</manvolnum></citerefentry>.
385
521
<refsect1 id="see_also">
386
522
<title>SEE ALSO</title>
388
<citerefentry><refentrytitle>password-request</refentrytitle>
524
<citerefentry><refentrytitle>intro</refentrytitle>
389
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>,
390
530
<citerefentry><refentrytitle>mandos</refentrytitle>
391
531
<manvolnum>8</manvolnum></citerefentry>,
392
<citerefentry><refentrytitle>gpg</refentrytitle>
532
<citerefentry><refentrytitle>mandos-client</refentrytitle>
533
<manvolnum>8mandos</manvolnum></citerefentry>,
534
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
393
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" -->