1
<?xml version="1.0" encoding="UTF-8"?>
1
<?xml version='1.0' encoding='UTF-8'?>
2
<?xml-stylesheet type="text/xsl"
3
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
2
4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
5
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
6
<!ENTITY VERSION "1.0">
4
7
<!ENTITY COMMANDNAME "mandos-keygen">
5
<!ENTITY TIMESTAMP "2011-10-03">
6
<!ENTITY % common SYSTEM "common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
12
<title>&COMMANDNAME;</title>
13
<!-- NWalsh's docbook scripts use this to generate the footer: -->
14
<productname>&COMMANDNAME;</productname>
15
<productnumber>&VERSION;</productnumber>
19
18
<firstname>Björn</firstname>
20
19
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
21
<email>belorn@fukt.bsnet.se</email>
26
25
<firstname>Teddy</firstname>
27
26
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
28
<email>teddy@fukt.bsnet.se</email>
37
<holder>Teddy Hogeborn</holder>
38
<holder>Björn Påhlsson</holder>
34
<holder>Teddy Hogeborn & Björn Påhlsson</holder>
40
<xi:include href="legalnotice.xml"/>
38
This manual page is free software: you can redistribute it
39
and/or modify it under the terms of the GNU General Public
40
License as published by the Free Software Foundation,
41
either version 3 of the License, or (at your option) any
46
This manual page is distributed in the hope that it will
47
be useful, but WITHOUT ANY WARRANTY; without even the
48
implied warranty of MERCHANTABILITY or FITNESS FOR A
49
PARTICULAR PURPOSE. See the GNU General Public License
54
You should have received a copy of the GNU General Public
55
License along with this program; If not, see
56
<ulink url="http://www.gnu.org/licenses/"/>.
44
62
<refentrytitle>&COMMANDNAME;</refentrytitle>
45
63
<manvolnum>8</manvolnum>
49
67
<refname><command>&COMMANDNAME;</command></refname>
51
Generate key and password for Mandos client and server.
69
Generate keys for <citerefentry><refentrytitle>password-request
70
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
57
76
<command>&COMMANDNAME;</command>
59
<arg choice="plain"><option>--dir
60
<replaceable>DIRECTORY</replaceable></option></arg>
61
<arg choice="plain"><option>-d
62
<replaceable>DIRECTORY</replaceable></option></arg>
66
<arg choice="plain"><option>--type
67
<replaceable>KEYTYPE</replaceable></option></arg>
68
<arg choice="plain"><option>-t
69
<replaceable>KEYTYPE</replaceable></option></arg>
73
<arg choice="plain"><option>--length
74
<replaceable>BITS</replaceable></option></arg>
75
<arg choice="plain"><option>-l
76
<replaceable>BITS</replaceable></option></arg>
80
<arg choice="plain"><option>--subtype
81
<replaceable>KEYTYPE</replaceable></option></arg>
82
<arg choice="plain"><option>-s
83
<replaceable>KEYTYPE</replaceable></option></arg>
87
<arg choice="plain"><option>--sublength
88
<replaceable>BITS</replaceable></option></arg>
89
<arg choice="plain"><option>-L
90
<replaceable>BITS</replaceable></option></arg>
94
<arg choice="plain"><option>--name
95
<replaceable>NAME</replaceable></option></arg>
96
<arg choice="plain"><option>-n
97
<replaceable>NAME</replaceable></option></arg>
101
<arg choice="plain"><option>--email
102
<replaceable>ADDRESS</replaceable></option></arg>
103
<arg choice="plain"><option>-e
104
<replaceable>ADDRESS</replaceable></option></arg>
108
<arg choice="plain"><option>--comment
109
<replaceable>TEXT</replaceable></option></arg>
110
<arg choice="plain"><option>-c
111
<replaceable>TEXT</replaceable></option></arg>
115
<arg choice="plain"><option>--expire
116
<replaceable>TIME</replaceable></option></arg>
117
<arg choice="plain"><option>-x
118
<replaceable>TIME</replaceable></option></arg>
121
<arg><option>--force</option></arg>
124
<command>&COMMANDNAME;</command>
126
<arg choice="plain"><option>--password</option></arg>
127
<arg choice="plain"><option>-p</option></arg>
128
<arg choice="plain"><option>--passfile
129
<replaceable>FILE</replaceable></option></arg>
130
<arg choice="plain"><option>-F</option>
131
<replaceable>FILE</replaceable></arg>
135
<arg choice="plain"><option>--dir
136
<replaceable>DIRECTORY</replaceable></option></arg>
137
<arg choice="plain"><option>-d
138
<replaceable>DIRECTORY</replaceable></option></arg>
142
<arg choice="plain"><option>--name
143
<replaceable>NAME</replaceable></option></arg>
144
<arg choice="plain"><option>-n
145
<replaceable>NAME</replaceable></option></arg>
149
<command>&COMMANDNAME;</command>
151
<arg choice="plain"><option>--help</option></arg>
152
<arg choice="plain"><option>-h</option></arg>
156
<command>&COMMANDNAME;</command>
158
<arg choice="plain"><option>--version</option></arg>
159
<arg choice="plain"><option>-v</option></arg>
78
<arg choice="plain"><option>--dir</option>
79
<replaceable>directory</replaceable></arg>
82
<arg choice="plain"><option>--type</option>
83
<replaceable>type</replaceable></arg>
86
<arg choice="plain"><option>--length</option>
87
<replaceable>bits</replaceable></arg>
90
<arg choice="plain"><option>--name</option>
91
<replaceable>NAME</replaceable></arg>
94
<arg choice="plain"><option>--email</option>
95
<replaceable>EMAIL</replaceable></arg>
98
<arg choice="plain"><option>--comment</option>
99
<replaceable>COMMENT</replaceable></arg>
102
<arg choice="plain"><option>--expire</option>
103
<replaceable>TIME</replaceable></arg>
106
<arg choice="plain"><option>--force</option></arg>
110
<command>&COMMANDNAME;</command>
112
<arg choice="plain"><option>-d</option>
113
<replaceable>directory</replaceable></arg>
116
<arg choice="plain"><option>-t</option>
117
<replaceable>type</replaceable></arg>
120
<arg choice="plain"><option>-l</option>
121
<replaceable>bits</replaceable></arg>
124
<arg choice="plain"><option>-n</option>
125
<replaceable>NAME</replaceable></arg>
128
<arg choice="plain"><option>-e</option>
129
<replaceable>EMAIL</replaceable></arg>
132
<arg choice="plain"><option>-c</option>
133
<replaceable>COMMENT</replaceable></arg>
136
<arg choice="plain"><option>-x</option>
137
<replaceable>TIME</replaceable></arg>
140
<arg choice="plain"><option>-f</option></arg>
144
<command>&COMMANDNAME;</command>
146
<arg choice='plain'><option>-h</option></arg>
147
<arg choice='plain'><option>--help</option></arg>
151
<command>&COMMANDNAME;</command>
153
<arg choice='plain'><option>-v</option></arg>
154
<arg choice='plain'><option>--version</option></arg>
162
157
</refsynopsisdiv>
164
159
<refsect1 id="description">
165
160
<title>DESCRIPTION</title>
167
162
<command>&COMMANDNAME;</command> is a program to generate the
169
<citerefentry><refentrytitle>mandos-client</refentrytitle>
170
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
164
<citerefentry><refentrytitle>password-request</refentrytitle>
165
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
171
166
normally written to /etc/mandos for later installation into the
172
initrd image, but this, and most other things, can be changed
173
with command line options.
176
This program can also be used with the
177
<option>--password</option> or <option>--passfile</option>
178
options to generate a ready-made section for
179
<filename>clients.conf</filename> (see
180
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
181
<manvolnum>5</manvolnum></citerefentry>).
185
<refsect1 id="purpose">
186
<title>PURPOSE</title>
188
The purpose of this is to enable <emphasis>remote and unattended
189
rebooting</emphasis> of client host computer with an
190
<emphasis>encrypted root file system</emphasis>. See <xref
191
linkend="overview"/> for details.
167
initrd image, but this, like most things, can be changed with
168
command line options.
195
172
<refsect1 id="options">
196
173
<title>OPTIONS</title>
200
<term><option>--help</option></term>
201
<term><option>-h</option></term>
177
<term><literal>-h</literal>, <literal>--help</literal></term>
204
180
Show a help message and exit
211
<replaceable>DIRECTORY</replaceable></option></term>
213
<replaceable>DIRECTORY</replaceable></option></term>
216
Target directory for key files. Default is
217
<filename>/etc/mandos</filename>.
224
<replaceable>TYPE</replaceable></option></term>
226
<replaceable>TYPE</replaceable></option></term>
229
Key type. Default is <quote>DSA</quote>.
235
<term><option>--length
236
<replaceable>BITS</replaceable></option></term>
238
<replaceable>BITS</replaceable></option></term>
241
Key length in bits. Default is 2048.
247
<term><option>--subtype
248
<replaceable>KEYTYPE</replaceable></option></term>
250
<replaceable>KEYTYPE</replaceable></option></term>
253
Subkey type. Default is <quote>ELG-E</quote> (Elgamal
260
<term><option>--sublength
261
<replaceable>BITS</replaceable></option></term>
263
<replaceable>BITS</replaceable></option></term>
266
Subkey length in bits. Default is 2048.
272
<term><option>--email
273
<replaceable>ADDRESS</replaceable></option></term>
275
<replaceable>ADDRESS</replaceable></option></term>
186
<term><literal>-d</literal>, <literal>--dir
187
<replaceable>directory</replaceable></literal></term>
190
Target directory for key files.
196
<term><literal>-t</literal>, <literal>--type
197
<replaceable>type</replaceable></literal></term>
200
Key type. Default is DSA.
206
<term><literal>-l</literal>, <literal>--length
207
<replaceable>bits</replaceable></literal></term>
210
Key length in bits. Default is 1024.
216
<term><literal>-e</literal>, <literal>--email</literal>
217
<replaceable>address</replaceable></term>
278
220
Email address of key. Default is empty.
284
<term><option>--comment
285
<replaceable>TEXT</replaceable></option></term>
287
<replaceable>TEXT</replaceable></option></term>
226
<term><literal>-c</literal>, <literal>--comment</literal>
227
<replaceable>comment</replaceable></term>
290
230
Comment field for key. The default value is
291
<quote><literal>Mandos client key</literal></quote>.
231
"<literal>Mandos client key</literal>".
297
<term><option>--expire
298
<replaceable>TIME</replaceable></option></term>
300
<replaceable>TIME</replaceable></option></term>
237
<term><literal>-x</literal>, <literal>--expire</literal>
238
<replaceable>time</replaceable></term>
303
241
Key expire time. Default is no expiration. See
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.
249
<term><literal>-f</literal>, <literal>--force</literal></term>
252
Force overwriting old keys.
352
<refsect1 id="overview">
353
<title>OVERVIEW</title>
354
<xi:include href="overview.xml"/>
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.
362
259
<refsect1 id="exit_status">
363
260
<title>EXIT STATUS</title>
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.
371
<refsect1 id="environment">
372
<title>ENVIRONMENT</title>
375
<term><envar>TMPDIR</envar></term>
378
If set, temporary files will be created here. See
379
<citerefentry><refentrytitle>mktemp</refentrytitle>
380
<manvolnum>1</manvolnum></citerefentry>.
387
<refsect1 id="files">
388
266
<title>FILES</title>
390
Use the <option>--dir</option> option to change where
391
<command>&COMMANDNAME;</command> will write the key files. The
392
default file names are shown here.
396
<term><filename>/etc/mandos/seckey.txt</filename></term>
399
OpenPGP secret key file which will be created or
405
<term><filename>/etc/mandos/pubkey.txt</filename></term>
408
OpenPGP public key file which will be created or
414
<term><filename>/tmp</filename></term>
417
Temporary files will be written here if
418
<varname>TMPDIR</varname> is not set.
425
<!-- <refsect1 id="bugs"> -->
426
<!-- <title>BUGS</title> -->
431
<refsect1 id="example">
432
<title>EXAMPLE</title>
435
Normal invocation needs no options:
438
<userinput>&COMMANDNAME;</userinput>
443
Create key in another directory and of another type. Force
444
overwriting old key files:
448
<!-- do not wrap this line -->
449
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
455
Prompt for a password, encrypt it with the key in
456
<filename>/etc/mandos</filename> and output a section suitable
457
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>
277
<refsect1 id="examples">
278
<title>EXAMPLES</title>
478
283
<refsect1 id="security">
479
284
<title>SECURITY</title>
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.
487
The key expire time is <emphasis>not</emphasis> guaranteed to be
488
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
489
<manvolnum>8</manvolnum></citerefentry>.
493
289
<refsect1 id="see_also">
494
290
<title>SEE ALSO</title>
496
<citerefentry><refentrytitle>intro</refentrytitle>
292
<citerefentry><refentrytitle>password-request</refentrytitle>
497
293
<manvolnum>8mandos</manvolnum></citerefentry>,
294
<citerefentry><refentrytitle>mandos</refentrytitle>
295
<manvolnum>8</manvolnum></citerefentry>, and
498
296
<citerefentry><refentrytitle>gpg</refentrytitle>
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>
297
<manvolnum>1</manvolnum></citerefentry>
510
<!-- Local Variables: -->
511
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
512
<!-- time-stamp-end: "[\"']>" -->
513
<!-- time-stamp-format: "%:y-%02m-%02d" -->