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">
4
5
<!ENTITY COMMANDNAME "mandos-keygen">
5
<!ENTITY TIMESTAMP "2012-01-01">
6
<!ENTITY % common SYSTEM "common.ent">
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
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>
11
<title>&COMMANDNAME;</title>
12
<!-- NWalsh's docbook scripts use this to generate the footer: -->
13
<productname>&COMMANDNAME;</productname>
14
<productnumber>&VERSION;</productnumber>
19
17
<firstname>Björn</firstname>
20
18
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
20
<email>belorn@fukt.bsnet.se</email>
26
24
<firstname>Teddy</firstname>
27
25
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
27
<email>teddy@fukt.bsnet.se</email>
38
<holder>Teddy Hogeborn</holder>
39
<holder>Björn Påhlsson</holder>
33
<holder>Teddy Hogeborn & Björn Påhlsson</holder>
41
<xi:include href="legalnotice.xml"/>
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/"/>.
45
61
<refentrytitle>&COMMANDNAME;</refentrytitle>
46
62
<manvolnum>8</manvolnum>
50
66
<refname><command>&COMMANDNAME;</command></refname>
52
Generate key and password for Mandos client and server.
68
Generate keys for <citerefentry><refentrytitle>password-request
69
</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
58
75
<command>&COMMANDNAME;</command>
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>
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>
105
<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
<arg choice="plain"><option>-f</option></arg>
143
<command>&COMMANDNAME;</command>
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>
163
156
</refsynopsisdiv>
165
158
<refsect1 id="description">
166
159
<title>DESCRIPTION</title>
168
161
<command>&COMMANDNAME;</command> is a program to generate the
170
<citerefentry><refentrytitle>mandos-client</refentrytitle>
171
<manvolnum>8mandos</manvolnum></citerefentry>. The key is
163
<citerefentry><refentrytitle>password-request</refentrytitle>
164
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
172
165
normally written to /etc/mandos for later installation into the
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>).
166
initrd image, but this, like most things, can be changed with
167
command line options.
186
171
<refsect1 id="purpose">
187
172
<title>PURPOSE</title>
189
175
The purpose of this is to enable <emphasis>remote and unattended
190
176
rebooting</emphasis> of client host computer with an
191
177
<emphasis>encrypted root file system</emphasis>. See <xref
192
178
linkend="overview"/> for details.
196
183
<refsect1 id="options">
197
184
<title>OPTIONS</title>
201
<term><option>--help</option></term>
202
<term><option>-h</option></term>
188
<term><literal>-h</literal>, <literal>--help</literal></term>
205
191
Show a help message and exit
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>DSA</quote>.
236
<term><option>--length
237
<replaceable>BITS</replaceable></option></term>
239
<replaceable>BITS</replaceable></option></term>
242
Key length in bits. Default is 2048.
248
<term><option>--subtype
249
<replaceable>KEYTYPE</replaceable></option></term>
251
<replaceable>KEYTYPE</replaceable></option></term>
254
Subkey type. Default is <quote>ELG-E</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 2048.
273
<term><option>--email
274
<replaceable>ADDRESS</replaceable></option></term>
276
<replaceable>ADDRESS</replaceable></option></term>
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>
279
231
Email address of key. Default is empty.
285
<term><option>--comment
286
<replaceable>TEXT</replaceable></option></term>
288
<replaceable>TEXT</replaceable></option></term>
237
<term><literal>-c</literal>, <literal>--comment</literal>
238
<replaceable>comment</replaceable></term>
291
241
Comment field for key. The default value is
292
<quote><literal>Mandos client key</literal></quote>.
242
"<literal>Mandos client key</literal>".
298
<term><option>--expire
299
<replaceable>TIME</replaceable></option></term>
301
<replaceable>TIME</replaceable></option></term>
248
<term><literal>-x</literal>, <literal>--expire</literal>
249
<replaceable>time</replaceable></term>
304
252
Key expire time. Default is no expiration. See
312
<term><option>--force</option></term>
313
<term><option>-f</option></term>
316
Force overwriting old key.
321
<term><option>--password</option></term>
322
<term><option>-p</option></term>
325
Prompt for a password and encrypt it with the key already
326
present in either <filename>/etc/mandos</filename> or the
327
directory specified with the <option>--dir</option>
328
option. Outputs, on standard output, a section suitable
329
for inclusion in <citerefentry><refentrytitle
330
>mandos-clients.conf</refentrytitle><manvolnum
331
>8</manvolnum></citerefentry>. The host name or the name
332
specified with the <option>--name</option> option is used
333
for the section header. All other options are ignored,
334
and no key is created.
339
<term><option>--passfile
340
<replaceable>FILE</replaceable></option></term>
342
<replaceable>FILE</replaceable></option></term>
345
The same as <option>--password</option>, but read from
346
<replaceable>FILE</replaceable>, not the terminal.
260
<term><literal>-f</literal>, <literal>--force</literal></term>
263
Force overwriting old keys.
353
270
<refsect1 id="overview">
354
271
<title>OVERVIEW</title>
355
<xi:include href="overview.xml"/>
357
This program is a small utility to generate new OpenPGP keys for
358
new Mandos clients, and to generate sections for inclusion in
359
<filename>clients.conf</filename> on the server.
274
This program is a small program to generate new OpenPGP keys for
363
279
<refsect1 id="exit_status">
364
280
<title>EXIT STATUS</title>
366
The exit status will be 0 if a new key (or password, if the
367
<option>--password</option> option was used) was successfully
368
created, otherwise not.
372
<refsect1 id="environment">
373
<title>ENVIRONMENT</title>
376
<term><envar>TMPDIR</envar></term>
379
If set, temporary files will be created here. See
380
<citerefentry><refentrytitle>mktemp</refentrytitle>
381
<manvolnum>1</manvolnum></citerefentry>.
388
<refsect1 id="files">
389
286
<title>FILES</title>
391
Use the <option>--dir</option> option to change where
392
<command>&COMMANDNAME;</command> will write the key files. The
393
default file names are shown here.
397
<term><filename>/etc/mandos/seckey.txt</filename></term>
400
OpenPGP secret key file which will be created or
406
<term><filename>/etc/mandos/pubkey.txt</filename></term>
409
OpenPGP public key file which will be created or
415
<term><filename class="directory">/tmp</filename></term>
418
Temporary files will be written here if
419
<varname>TMPDIR</varname> is not set.
426
<!-- <refsect1 id="bugs"> -->
427
<!-- <title>BUGS</title> -->
432
297
<refsect1 id="example">
433
298
<title>EXAMPLE</title>
436
Normal invocation needs no options:
439
<userinput>&COMMANDNAME;</userinput>
444
Create key in another directory and of another type. Force
445
overwriting old key files:
449
<!-- do not wrap this line -->
450
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
456
Prompt for a password, encrypt it with the key in <filename
457
class="directory">/etc/mandos</filename> and output a section
458
suitable for <filename>clients.conf</filename>.
461
<userinput>&COMMANDNAME; --password</userinput>
466
Prompt for a password, encrypt it with the key in the
467
<filename>client-key</filename> directory and output a section
468
suitable for <filename>clients.conf</filename>.
472
<!-- do not wrap this line -->
473
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
479
303
<refsect1 id="security">
480
304
<title>SECURITY</title>
482
The <option>--type</option>, <option>--length</option>,
483
<option>--subtype</option>, and <option>--sublength</option>
484
options can be used to create keys of low security. If in
485
doubt, leave them to the default values.
488
The key expire time is <emphasis>not</emphasis> guaranteed to be
489
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
490
<manvolnum>8</manvolnum></citerefentry>.
494
309
<refsect1 id="see_also">
495
310
<title>SEE ALSO</title>
497
<citerefentry><refentrytitle>intro</refentrytitle>
312
<citerefentry><refentrytitle>password-request</refentrytitle>
498
313
<manvolnum>8mandos</manvolnum></citerefentry>,
314
<citerefentry><refentrytitle>mandos</refentrytitle>
315
<manvolnum>8</manvolnum></citerefentry>, and
499
316
<citerefentry><refentrytitle>gpg</refentrytitle>
500
<manvolnum>1</manvolnum></citerefentry>,
501
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
<manvolnum>5</manvolnum></citerefentry>,
503
<citerefentry><refentrytitle>mandos</refentrytitle>
504
<manvolnum>8</manvolnum></citerefentry>,
505
<citerefentry><refentrytitle>mandos-client</refentrytitle>
506
<manvolnum>8mandos</manvolnum></citerefentry>
317
<manvolnum>1</manvolnum></citerefentry>
511
<!-- Local Variables: -->
512
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
513
<!-- time-stamp-end: "[\"']>" -->
514
<!-- time-stamp-format: "%:y-%02m-%02d" -->