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 "2013-10-22">
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>
38
<holder>Teddy Hogeborn</holder>
39
<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/"/>.
41
<xi:include href="legalnotice.xml"/>
60
45
<refentrytitle>&COMMANDNAME;</refentrytitle>
61
46
<manvolnum>8</manvolnum>
65
50
<refname><command>&COMMANDNAME;</command></refname>
67
Generate keys for <citerefentry><refentrytitle>password-request
68
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
52
Generate key and password for Mandos client and server.
74
58
<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>
104
<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
<arg choice="plain"><option>-f</option></arg>
142
<command>&COMMANDNAME;</command>
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>
60
<arg choice="plain"><option>--dir
61
<replaceable>DIRECTORY</replaceable></option></arg>
62
<arg choice="plain"><option>-d
63
<replaceable>DIRECTORY</replaceable></option></arg>
67
<arg choice="plain"><option>--type
68
<replaceable>KEYTYPE</replaceable></option></arg>
69
<arg choice="plain"><option>-t
70
<replaceable>KEYTYPE</replaceable></option></arg>
74
<arg choice="plain"><option>--length
75
<replaceable>BITS</replaceable></option></arg>
76
<arg choice="plain"><option>-l
77
<replaceable>BITS</replaceable></option></arg>
81
<arg choice="plain"><option>--subtype
82
<replaceable>KEYTYPE</replaceable></option></arg>
83
<arg choice="plain"><option>-s
84
<replaceable>KEYTYPE</replaceable></option></arg>
88
<arg choice="plain"><option>--sublength
89
<replaceable>BITS</replaceable></option></arg>
90
<arg choice="plain"><option>-L
91
<replaceable>BITS</replaceable></option></arg>
95
<arg choice="plain"><option>--name
96
<replaceable>NAME</replaceable></option></arg>
97
<arg choice="plain"><option>-n
98
<replaceable>NAME</replaceable></option></arg>
102
<arg choice="plain"><option>--email
103
<replaceable>ADDRESS</replaceable></option></arg>
104
<arg choice="plain"><option>-e
105
<replaceable>ADDRESS</replaceable></option></arg>
109
<arg choice="plain"><option>--comment
110
<replaceable>TEXT</replaceable></option></arg>
111
<arg choice="plain"><option>-c
112
<replaceable>TEXT</replaceable></option></arg>
116
<arg choice="plain"><option>--expire
117
<replaceable>TIME</replaceable></option></arg>
118
<arg choice="plain"><option>-x
119
<replaceable>TIME</replaceable></option></arg>
122
<arg><option>--force</option></arg>
125
<command>&COMMANDNAME;</command>
127
<arg choice="plain"><option>--password</option></arg>
128
<arg choice="plain"><option>-p</option></arg>
129
<arg choice="plain"><option>--passfile
130
<replaceable>FILE</replaceable></option></arg>
131
<arg choice="plain"><option>-F</option>
132
<replaceable>FILE</replaceable></arg>
136
<arg choice="plain"><option>--dir
137
<replaceable>DIRECTORY</replaceable></option></arg>
138
<arg choice="plain"><option>-d
139
<replaceable>DIRECTORY</replaceable></option></arg>
143
<arg choice="plain"><option>--name
144
<replaceable>NAME</replaceable></option></arg>
145
<arg choice="plain"><option>-n
146
<replaceable>NAME</replaceable></option></arg>
150
<command>&COMMANDNAME;</command>
152
<arg choice="plain"><option>--help</option></arg>
153
<arg choice="plain"><option>-h</option></arg>
157
<command>&COMMANDNAME;</command>
159
<arg choice="plain"><option>--version</option></arg>
160
<arg choice="plain"><option>-v</option></arg>
155
163
</refsynopsisdiv>
157
165
<refsect1 id="description">
158
166
<title>DESCRIPTION</title>
160
168
<command>&COMMANDNAME;</command> is a program to generate the
162
<citerefentry><refentrytitle>password-request</refentrytitle>
163
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
170
<citerefentry><refentrytitle>mandos-client</refentrytitle>
171
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
164
172
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.
173
initrd image, but this, and most other things, can be changed
174
with command line options.
177
This program can also be used with the
178
<option>--password</option> or <option>--passfile</option>
179
options to generate a ready-made section for
180
<filename>clients.conf</filename> (see
181
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
182
<manvolnum>5</manvolnum></citerefentry>).
170
186
<refsect1 id="purpose">
171
187
<title>PURPOSE</title>
174
189
The purpose of this is to enable <emphasis>remote and unattended
175
190
rebooting</emphasis> of client host computer with an
176
191
<emphasis>encrypted root file system</emphasis>. See <xref
177
192
linkend="overview"/> for details.
182
196
<refsect1 id="options">
183
197
<title>OPTIONS</title>
187
<term><literal>-h</literal>, <literal>--help</literal></term>
201
<term><option>--help</option></term>
202
<term><option>-h</option></term>
190
205
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>
212
<replaceable>DIRECTORY</replaceable></option></term>
214
<replaceable>DIRECTORY</replaceable></option></term>
217
Target directory for key files. Default is
218
<filename class="directory">/etc/mandos</filename>.
225
<replaceable>TYPE</replaceable></option></term>
227
<replaceable>TYPE</replaceable></option></term>
230
Key type. Default is <quote>RSA</quote>.
236
<term><option>--length
237
<replaceable>BITS</replaceable></option></term>
239
<replaceable>BITS</replaceable></option></term>
242
Key length in bits. Default is 4096.
248
<term><option>--subtype
249
<replaceable>KEYTYPE</replaceable></option></term>
251
<replaceable>KEYTYPE</replaceable></option></term>
254
Subkey type. Default is <quote>RSA</quote> (Elgamal
261
<term><option>--sublength
262
<replaceable>BITS</replaceable></option></term>
264
<replaceable>BITS</replaceable></option></term>
267
Subkey length in bits. Default is 4096.
273
<term><option>--email
274
<replaceable>ADDRESS</replaceable></option></term>
276
<replaceable>ADDRESS</replaceable></option></term>
230
279
Email address of key. Default is empty.
236
<term><literal>-c</literal>, <literal>--comment</literal>
237
<replaceable>comment</replaceable></term>
285
<term><option>--comment
286
<replaceable>TEXT</replaceable></option></term>
288
<replaceable>TEXT</replaceable></option></term>
240
Comment field for key. The default value is
241
"<literal>Mandos client key</literal>".
291
Comment field for key. Default is empty.
247
<term><literal>-x</literal>, <literal>--expire</literal>
248
<replaceable>time</replaceable></term>
297
<term><option>--expire
298
<replaceable>TIME</replaceable></option></term>
300
<replaceable>TIME</replaceable></option></term>
251
303
Key expire time. Default is no expiration. See
259
<term><literal>-f</literal>, <literal>--force</literal></term>
262
Force overwriting old keys.
311
<term><option>--force</option></term>
312
<term><option>-f</option></term>
315
Force overwriting old key.
320
<term><option>--password</option></term>
321
<term><option>-p</option></term>
324
Prompt for a password and encrypt it with the key already
325
present in either <filename>/etc/mandos</filename> or the
326
directory specified with the <option>--dir</option>
327
option. Outputs, on standard output, a section suitable
328
for inclusion in <citerefentry><refentrytitle
329
>mandos-clients.conf</refentrytitle><manvolnum
330
>8</manvolnum></citerefentry>. The host name or the name
331
specified with the <option>--name</option> option is used
332
for the section header. All other options are ignored,
333
and no key is created.
338
<term><option>--passfile
339
<replaceable>FILE</replaceable></option></term>
341
<replaceable>FILE</replaceable></option></term>
344
The same as <option>--password</option>, but read from
345
<replaceable>FILE</replaceable>, not the terminal.
269
352
<refsect1 id="overview">
270
353
<title>OVERVIEW</title>
271
354
<xi:include href="overview.xml"/>
273
This program is a small program to generate new OpenPGP keys for
356
This program is a small utility to generate new OpenPGP keys for
357
new Mandos clients, and to generate sections for inclusion in
358
<filename>clients.conf</filename> on the server.
278
362
<refsect1 id="exit_status">
279
363
<title>EXIT STATUS</title>
281
The exit status will be 0 if new keys were successfully created,
365
The exit status will be 0 if a new key (or password, if the
366
<option>--password</option> option was used) was successfully
367
created, otherwise not.
351
435
Normal invocation needs no options:
354
<userinput>mandos-keygen</userinput>
438
<userinput>&COMMANDNAME;</userinput>
356
440
</informalexample>
357
441
<informalexample>
359
Create keys in another directory and of another type. Force
443
Create key in another directory and of another type. Force
360
444
overwriting old key files:
364
448
<!-- do not wrap this line -->
365
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
449
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
455
Prompt for a password, encrypt it with the key in <filename
456
class="directory">/etc/mandos</filename> and output a section
457
suitable for <filename>clients.conf</filename>.
460
<userinput>&COMMANDNAME; --password</userinput>
465
Prompt for a password, encrypt it with the key in the
466
<filename>client-key</filename> directory and output a section
467
suitable for <filename>clients.conf</filename>.
471
<!-- do not wrap this line -->
472
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
368
475
</informalexample>
371
478
<refsect1 id="security">
372
479
<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.
481
The <option>--type</option>, <option>--length</option>,
482
<option>--subtype</option>, and <option>--sublength</option>
483
options can be used to create keys of low security. If in
484
doubt, leave them to the default values.
379
The key expire time is not guaranteed to be honored by
380
<citerefentry><refentrytitle>mandos</refentrytitle>
487
The key expire time is <emphasis>not</emphasis> guaranteed to be
488
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
381
489
<manvolnum>8</manvolnum></citerefentry>.
385
493
<refsect1 id="see_also">
386
494
<title>SEE ALSO</title>
388
<citerefentry><refentrytitle>password-request</refentrytitle>
496
<citerefentry><refentrytitle>intro</refentrytitle>
389
497
<manvolnum>8mandos</manvolnum></citerefentry>,
390
<citerefentry><refentrytitle>mandos</refentrytitle>
391
<manvolnum>8</manvolnum></citerefentry>, and
392
498
<citerefentry><refentrytitle>gpg</refentrytitle>
393
<manvolnum>1</manvolnum></citerefentry>
499
<manvolnum>1</manvolnum></citerefentry>,
500
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
501
<manvolnum>5</manvolnum></citerefentry>,
502
<citerefentry><refentrytitle>mandos</refentrytitle>
503
<manvolnum>8</manvolnum></citerefentry>,
504
<citerefentry><refentrytitle>mandos-client</refentrytitle>
505
<manvolnum>8mandos</manvolnum></citerefentry>
510
<!-- Local Variables: -->
511
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
512
<!-- time-stamp-end: "[\"']>" -->
513
<!-- time-stamp-format: "%:y-%02m-%02d" -->