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 "2016-03-05">
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>
43
<holder>Teddy Hogeborn</holder>
44
<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/"/>.
46
<xi:include href="legalnotice.xml"/>
61
50
<refentrytitle>&COMMANDNAME;</refentrytitle>
62
51
<manvolnum>8</manvolnum>
66
55
<refname><command>&COMMANDNAME;</command></refname>
68
Generate keys for <citerefentry><refentrytitle>password-request
69
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
57
Generate key and password for Mandos client and server.
75
63
<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>
65
<arg choice="plain"><option>--dir
66
<replaceable>DIRECTORY</replaceable></option></arg>
67
<arg choice="plain"><option>-d
68
<replaceable>DIRECTORY</replaceable></option></arg>
72
<arg choice="plain"><option>--type
73
<replaceable>KEYTYPE</replaceable></option></arg>
74
<arg choice="plain"><option>-t
75
<replaceable>KEYTYPE</replaceable></option></arg>
79
<arg choice="plain"><option>--length
80
<replaceable>BITS</replaceable></option></arg>
81
<arg choice="plain"><option>-l
82
<replaceable>BITS</replaceable></option></arg>
86
<arg choice="plain"><option>--subtype
87
<replaceable>KEYTYPE</replaceable></option></arg>
88
<arg choice="plain"><option>-s
89
<replaceable>KEYTYPE</replaceable></option></arg>
93
<arg choice="plain"><option>--sublength
94
<replaceable>BITS</replaceable></option></arg>
95
<arg choice="plain"><option>-L
96
<replaceable>BITS</replaceable></option></arg>
100
<arg choice="plain"><option>--name
101
<replaceable>NAME</replaceable></option></arg>
102
<arg choice="plain"><option>-n
103
<replaceable>NAME</replaceable></option></arg>
107
<arg choice="plain"><option>--email
108
<replaceable>ADDRESS</replaceable></option></arg>
109
<arg choice="plain"><option>-e
110
<replaceable>ADDRESS</replaceable></option></arg>
114
<arg choice="plain"><option>--comment
115
<replaceable>TEXT</replaceable></option></arg>
116
<arg choice="plain"><option>-c
117
<replaceable>TEXT</replaceable></option></arg>
121
<arg choice="plain"><option>--expire
122
<replaceable>TIME</replaceable></option></arg>
123
<arg choice="plain"><option>-x
124
<replaceable>TIME</replaceable></option></arg>
105
128
<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
129
<arg choice="plain"><option>-f</option></arg>
143
133
<command>&COMMANDNAME;</command>
144
134
<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>
135
<arg choice="plain"><option>--password</option></arg>
136
<arg choice="plain"><option>-p</option></arg>
137
<arg choice="plain"><option>--passfile
138
<replaceable>FILE</replaceable></option></arg>
139
<arg choice="plain"><option>-F</option>
140
<replaceable>FILE</replaceable></arg>
144
<arg choice="plain"><option>--dir
145
<replaceable>DIRECTORY</replaceable></option></arg>
146
<arg choice="plain"><option>-d
147
<replaceable>DIRECTORY</replaceable></option></arg>
151
<arg choice="plain"><option>--name
152
<replaceable>NAME</replaceable></option></arg>
153
<arg choice="plain"><option>-n
154
<replaceable>NAME</replaceable></option></arg>
157
<arg choice="plain"><option>--no-ssh</option></arg>
158
<arg choice="plain"><option>-S</option></arg>
162
<command>&COMMANDNAME;</command>
164
<arg choice="plain"><option>--help</option></arg>
165
<arg choice="plain"><option>-h</option></arg>
169
<command>&COMMANDNAME;</command>
171
<arg choice="plain"><option>--version</option></arg>
172
<arg choice="plain"><option>-v</option></arg>
156
175
</refsynopsisdiv>
158
177
<refsect1 id="description">
159
178
<title>DESCRIPTION</title>
161
180
<command>&COMMANDNAME;</command> is a program to generate the
163
<citerefentry><refentrytitle>password-request</refentrytitle>
164
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
182
<citerefentry><refentrytitle>mandos-client</refentrytitle>
183
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
165
184
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.
185
initrd image, but this, and most other things, can be changed
186
with command line options.
189
This program can also be used with the
190
<option>--password</option> or <option>--passfile</option>
191
options to generate a ready-made section for
192
<filename>clients.conf</filename> (see
193
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
<manvolnum>5</manvolnum></citerefentry>).
171
198
<refsect1 id="purpose">
172
199
<title>PURPOSE</title>
175
201
The purpose of this is to enable <emphasis>remote and unattended
176
202
rebooting</emphasis> of client host computer with an
177
203
<emphasis>encrypted root file system</emphasis>. See <xref
178
204
linkend="overview"/> for details.
183
208
<refsect1 id="options">
184
209
<title>OPTIONS</title>
188
<term><literal>-h</literal>, <literal>--help</literal></term>
213
<term><option>--help</option></term>
214
<term><option>-h</option></term>
191
217
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>
224
<replaceable>DIRECTORY</replaceable></option></term>
226
<replaceable>DIRECTORY</replaceable></option></term>
229
Target directory for key files. Default is
230
<filename class="directory">/etc/mandos</filename>.
237
<replaceable>TYPE</replaceable></option></term>
239
<replaceable>TYPE</replaceable></option></term>
242
Key type. Default is <quote>RSA</quote>.
248
<term><option>--length
249
<replaceable>BITS</replaceable></option></term>
251
<replaceable>BITS</replaceable></option></term>
254
Key length in bits. Default is 4096.
260
<term><option>--subtype
261
<replaceable>KEYTYPE</replaceable></option></term>
263
<replaceable>KEYTYPE</replaceable></option></term>
266
Subkey type. Default is <quote>RSA</quote> (Elgamal
273
<term><option>--sublength
274
<replaceable>BITS</replaceable></option></term>
276
<replaceable>BITS</replaceable></option></term>
279
Subkey length in bits. Default is 4096.
285
<term><option>--email
286
<replaceable>ADDRESS</replaceable></option></term>
288
<replaceable>ADDRESS</replaceable></option></term>
231
291
Email address of key. Default is empty.
237
<term><literal>-c</literal>, <literal>--comment</literal>
238
<replaceable>comment</replaceable></term>
297
<term><option>--comment
298
<replaceable>TEXT</replaceable></option></term>
300
<replaceable>TEXT</replaceable></option></term>
241
Comment field for key. The default value is
242
"<literal>Mandos client key</literal>".
303
Comment field for key. Default is empty.
248
<term><literal>-x</literal>, <literal>--expire</literal>
249
<replaceable>time</replaceable></term>
309
<term><option>--expire
310
<replaceable>TIME</replaceable></option></term>
312
<replaceable>TIME</replaceable></option></term>
252
315
Key expire time. Default is no expiration. See
260
<term><literal>-f</literal>, <literal>--force</literal></term>
263
Force overwriting old keys.
323
<term><option>--force</option></term>
324
<term><option>-f</option></term>
327
Force overwriting old key.
332
<term><option>--password</option></term>
333
<term><option>-p</option></term>
336
Prompt for a password and encrypt it with the key already
337
present in either <filename>/etc/mandos</filename> or the
338
directory specified with the <option>--dir</option>
339
option. Outputs, on standard output, a section suitable
340
for inclusion in <citerefentry><refentrytitle
341
>mandos-clients.conf</refentrytitle><manvolnum
342
>8</manvolnum></citerefentry>. The host name or the name
343
specified with the <option>--name</option> option is used
344
for the section header. All other options are ignored,
345
and no key is created.
350
<term><option>--passfile
351
<replaceable>FILE</replaceable></option></term>
353
<replaceable>FILE</replaceable></option></term>
356
The same as <option>--password</option>, but read from
357
<replaceable>FILE</replaceable>, not the terminal.
362
<term><option>--no-ssh</option></term>
363
<term><option>-S</option></term>
366
When <option>--password</option> or
367
<option>--passfile</option> is given, this option will
368
prevent <command>&COMMANDNAME;</command> from calling
369
<command>ssh-keyscan</command> to get an SSH fingerprint
370
for this host and, if successful, output suitable config
371
options to use this fingerprint as a
372
<option>checker</option> option in the output. This is
373
otherwise the default behavior.
270
380
<refsect1 id="overview">
271
381
<title>OVERVIEW</title>
382
<xi:include href="overview.xml"/>
274
This program is a small program to generate new OpenPGP keys for
384
This program is a small utility to generate new OpenPGP keys for
385
new Mandos clients, and to generate sections for inclusion in
386
<filename>clients.conf</filename> on the server.
279
390
<refsect1 id="exit_status">
280
391
<title>EXIT STATUS</title>
393
The exit status will be 0 if a new key (or password, if the
394
<option>--password</option> option was used) was successfully
395
created, otherwise not.
399
<refsect1 id="environment">
400
<title>ENVIRONMENT</title>
403
<term><envar>TMPDIR</envar></term>
406
If set, temporary files will be created here. See
407
<citerefentry><refentrytitle>mktemp</refentrytitle>
408
<manvolnum>1</manvolnum></citerefentry>.
415
<refsect1 id="files">
286
416
<title>FILES</title>
418
Use the <option>--dir</option> option to change where
419
<command>&COMMANDNAME;</command> will write the key files. The
420
default file names are shown here.
424
<term><filename>/etc/mandos/seckey.txt</filename></term>
427
OpenPGP secret key file which will be created or
433
<term><filename>/etc/mandos/pubkey.txt</filename></term>
436
OpenPGP public key file which will be created or
442
<term><filename class="directory">/tmp</filename></term>
445
Temporary files will be written here if
446
<varname>TMPDIR</varname> is not set.
291
453
<refsect1 id="bugs">
292
454
<title>BUGS</title>
455
<xi:include href="bugs.xml"/>
297
458
<refsect1 id="example">
298
459
<title>EXAMPLE</title>
462
Normal invocation needs no options:
465
<userinput>&COMMANDNAME;</userinput>
470
Create key in another directory and of another type. Force
471
overwriting old key files:
475
<!-- do not wrap this line -->
476
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
482
Prompt for a password, encrypt it with the key in <filename
483
class="directory">/etc/mandos</filename> and output a section
484
suitable for <filename>clients.conf</filename>.
487
<userinput>&COMMANDNAME; --password</userinput>
492
Prompt for a password, encrypt it with the key in the
493
<filename>client-key</filename> directory and output a section
494
suitable for <filename>clients.conf</filename>.
498
<!-- do not wrap this line -->
499
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
303
505
<refsect1 id="security">
304
506
<title>SECURITY</title>
508
The <option>--type</option>, <option>--length</option>,
509
<option>--subtype</option>, and <option>--sublength</option>
510
options can be used to create keys of low security. If in
511
doubt, leave them to the default values.
514
The key expire time is <emphasis>not</emphasis> guaranteed to be
515
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
516
<manvolnum>8</manvolnum></citerefentry>.
309
520
<refsect1 id="see_also">
310
521
<title>SEE ALSO</title>
312
<citerefentry><refentrytitle>password-request</refentrytitle>
523
<citerefentry><refentrytitle>intro</refentrytitle>
313
524
<manvolnum>8mandos</manvolnum></citerefentry>,
525
<citerefentry><refentrytitle>gpg</refentrytitle>
526
<manvolnum>1</manvolnum></citerefentry>,
527
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
528
<manvolnum>5</manvolnum></citerefentry>,
314
529
<citerefentry><refentrytitle>mandos</refentrytitle>
315
<manvolnum>8</manvolnum></citerefentry>, and
316
<citerefentry><refentrytitle>gpg</refentrytitle>
530
<manvolnum>8</manvolnum></citerefentry>,
531
<citerefentry><refentrytitle>mandos-client</refentrytitle>
532
<manvolnum>8mandos</manvolnum></citerefentry>,
533
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
317
534
<manvolnum>1</manvolnum></citerefentry>
539
<!-- Local Variables: -->
540
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
541
<!-- time-stamp-end: "[\"']>" -->
542
<!-- time-stamp-format: "%:y-%02m-%02d" -->