1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY COMMANDNAME "mandos-keygen">
5
<!ENTITY TIMESTAMP "2019-07-18">
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>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
46
<holder>Teddy Hogeborn</holder>
47
<holder>Björn Påhlsson</holder>
49
<xi:include href="legalnotice.xml"/>
53
<refentrytitle>&COMMANDNAME;</refentrytitle>
54
<manvolnum>8</manvolnum>
58
<refname><command>&COMMANDNAME;</command></refname>
60
Generate key and password for Mandos client and server.
66
<command>&COMMANDNAME;</command>
68
<arg choice="plain"><option>--dir
69
<replaceable>DIRECTORY</replaceable></option></arg>
70
<arg choice="plain"><option>-d
71
<replaceable>DIRECTORY</replaceable></option></arg>
75
<arg choice="plain"><option>--type
76
<replaceable>KEYTYPE</replaceable></option></arg>
77
<arg choice="plain"><option>-t
78
<replaceable>KEYTYPE</replaceable></option></arg>
82
<arg choice="plain"><option>--length
83
<replaceable>BITS</replaceable></option></arg>
84
<arg choice="plain"><option>-l
85
<replaceable>BITS</replaceable></option></arg>
89
<arg choice="plain"><option>--subtype
90
<replaceable>KEYTYPE</replaceable></option></arg>
91
<arg choice="plain"><option>-s
92
<replaceable>KEYTYPE</replaceable></option></arg>
96
<arg choice="plain"><option>--sublength
97
<replaceable>BITS</replaceable></option></arg>
98
<arg choice="plain"><option>-L
99
<replaceable>BITS</replaceable></option></arg>
103
<arg choice="plain"><option>--name
104
<replaceable>NAME</replaceable></option></arg>
105
<arg choice="plain"><option>-n
106
<replaceable>NAME</replaceable></option></arg>
110
<arg choice="plain"><option>--email
111
<replaceable>ADDRESS</replaceable></option></arg>
112
<arg choice="plain"><option>-e
113
<replaceable>ADDRESS</replaceable></option></arg>
117
<arg choice="plain"><option>--comment
118
<replaceable>TEXT</replaceable></option></arg>
119
<arg choice="plain"><option>-c
120
<replaceable>TEXT</replaceable></option></arg>
124
<arg choice="plain"><option>--expire
125
<replaceable>TIME</replaceable></option></arg>
126
<arg choice="plain"><option>-x
127
<replaceable>TIME</replaceable></option></arg>
131
<arg choice="plain"><option>--tls-keytype
132
<replaceable>KEYTYPE</replaceable></option></arg>
133
<arg choice="plain"><option>-T
134
<replaceable>KEYTYPE</replaceable></option></arg>
138
<arg choice="plain"><option>--force</option></arg>
139
<arg choice="plain"><option>-f</option></arg>
143
<command>&COMMANDNAME;</command>
145
<arg choice="plain"><option>--password</option></arg>
146
<arg choice="plain"><option>-p</option></arg>
147
<arg choice="plain"><option>--passfile
148
<replaceable>FILE</replaceable></option></arg>
149
<arg choice="plain"><option>-F</option>
150
<replaceable>FILE</replaceable></arg>
154
<arg choice="plain"><option>--dir
155
<replaceable>DIRECTORY</replaceable></option></arg>
156
<arg choice="plain"><option>-d
157
<replaceable>DIRECTORY</replaceable></option></arg>
161
<arg choice="plain"><option>--name
162
<replaceable>NAME</replaceable></option></arg>
163
<arg choice="plain"><option>-n
164
<replaceable>NAME</replaceable></option></arg>
167
<arg choice="plain"><option>--no-ssh</option></arg>
168
<arg choice="plain"><option>-S</option></arg>
172
<command>&COMMANDNAME;</command>
174
<arg choice="plain"><option>--help</option></arg>
175
<arg choice="plain"><option>-h</option></arg>
179
<command>&COMMANDNAME;</command>
181
<arg choice="plain"><option>--version</option></arg>
182
<arg choice="plain"><option>-v</option></arg>
187
<refsect1 id="description">
188
<title>DESCRIPTION</title>
190
<command>&COMMANDNAME;</command> is a program to generate the
191
TLS and OpenPGP keys used by
192
<citerefentry><refentrytitle>mandos-client</refentrytitle>
193
<manvolnum>8mandos</manvolnum></citerefentry>. The keys are
194
normally written to /etc/keys/mandos for later installation into
195
the initrd image, but this, and most other things, can be
196
changed with command line options.
199
This program can also be used with the
200
<option>--password</option> or <option>--passfile</option>
201
options to generate a ready-made section for
202
<filename>clients.conf</filename> (see
203
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
204
<manvolnum>5</manvolnum></citerefentry>).
208
<refsect1 id="purpose">
209
<title>PURPOSE</title>
211
The purpose of this is to enable <emphasis>remote and unattended
212
rebooting</emphasis> of client host computer with an
213
<emphasis>encrypted root file system</emphasis>. See <xref
214
linkend="overview"/> for details.
218
<refsect1 id="options">
219
<title>OPTIONS</title>
223
<term><option>--help</option></term>
224
<term><option>-h</option></term>
227
Show a help message and exit
234
<replaceable>DIRECTORY</replaceable></option></term>
236
<replaceable>DIRECTORY</replaceable></option></term>
239
Target directory for key files. Default is <filename
240
class="directory">/etc/keys/mandos</filename>.
247
<replaceable>TYPE</replaceable></option></term>
249
<replaceable>TYPE</replaceable></option></term>
252
OpenPGP key type. Default is <quote>RSA</quote>.
258
<term><option>--length
259
<replaceable>BITS</replaceable></option></term>
261
<replaceable>BITS</replaceable></option></term>
264
OpenPGP key length in bits. Default is 4096.
270
<term><option>--subtype
271
<replaceable>KEYTYPE</replaceable></option></term>
273
<replaceable>KEYTYPE</replaceable></option></term>
276
OpenPGP subkey type. Default is <quote>RSA</quote>
282
<term><option>--sublength
283
<replaceable>BITS</replaceable></option></term>
285
<replaceable>BITS</replaceable></option></term>
288
OpenPGP subkey length in bits. Default is 4096.
294
<term><option>--email
295
<replaceable>ADDRESS</replaceable></option></term>
297
<replaceable>ADDRESS</replaceable></option></term>
300
Email address of key. Default is empty.
306
<term><option>--comment
307
<replaceable>TEXT</replaceable></option></term>
309
<replaceable>TEXT</replaceable></option></term>
312
Comment field for key. Default is empty.
318
<term><option>--expire
319
<replaceable>TIME</replaceable></option></term>
321
<replaceable>TIME</replaceable></option></term>
324
Key expire time. Default is no expiration. See
325
<citerefentry><refentrytitle>gpg</refentrytitle>
326
<manvolnum>1</manvolnum></citerefentry> for syntax.
332
<term><option>--tls-keytype
333
<replaceable>KEYTYPE</replaceable></option></term>
335
<replaceable>KEYTYPE</replaceable></option></term>
338
TLS key type. Default is <quote>ed25519</quote>
344
<term><option>--force</option></term>
345
<term><option>-f</option></term>
348
Force overwriting old key.
353
<term><option>--password</option></term>
354
<term><option>-p</option></term>
357
Prompt for a password and encrypt it with the key already
358
present in either <filename>/etc/keys/mandos</filename> or
359
the directory specified with the <option>--dir</option>
360
option. Outputs, on standard output, a section suitable
361
for inclusion in <citerefentry><refentrytitle
362
>mandos-clients.conf</refentrytitle><manvolnum
363
>8</manvolnum></citerefentry>. The host name or the name
364
specified with the <option>--name</option> option is used
365
for the section header. All other options are ignored,
366
and no key is created. Note: white space is stripped from
367
the beginning and from the end of the password; See <xref
373
<term><option>--passfile
374
<replaceable>FILE</replaceable></option></term>
376
<replaceable>FILE</replaceable></option></term>
379
The same as <option>--password</option>, but read from
380
<replaceable>FILE</replaceable>, not the terminal, and
381
white space is not stripped from the password in any way.
386
<term><option>--no-ssh</option></term>
387
<term><option>-S</option></term>
390
When <option>--password</option> or
391
<option>--passfile</option> is given, this option will
392
prevent <command>&COMMANDNAME;</command> from calling
393
<command>ssh-keyscan</command> to get an SSH fingerprint
394
for this host and, if successful, output suitable config
395
options to use this fingerprint as a
396
<option>checker</option> option in the output. This is
397
otherwise the default behavior.
404
<refsect1 id="overview">
405
<title>OVERVIEW</title>
406
<xi:include href="overview.xml"/>
408
This program is a small utility to generate new TLS and OpenPGP
409
keys for new Mandos clients, and to generate sections for
410
inclusion in <filename>clients.conf</filename> on the server.
414
<refsect1 id="exit_status">
415
<title>EXIT STATUS</title>
417
The exit status will be 0 if a new key (or password, if the
418
<option>--password</option> option was used) was successfully
419
created, otherwise not.
423
<refsect1 id="environment">
424
<title>ENVIRONMENT</title>
427
<term><envar>TMPDIR</envar></term>
430
If set, temporary files will be created here. See
431
<citerefentry><refentrytitle>mktemp</refentrytitle>
432
<manvolnum>1</manvolnum></citerefentry>.
439
<refsect1 id="files">
442
Use the <option>--dir</option> option to change where
443
<command>&COMMANDNAME;</command> will write the key files. The
444
default file names are shown here.
448
<term><filename>/etc/keys/mandos/seckey.txt</filename></term>
451
OpenPGP secret key file which will be created or
457
<term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
460
OpenPGP public key file which will be created or
466
<term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
469
Private key file which will be created or overwritten.
474
<term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
477
Public key file which will be created or overwritten.
482
<term><filename class="directory">/tmp</filename></term>
485
Temporary files will be written here if
486
<varname>TMPDIR</varname> is not set.
496
The <option>--password</option>/<option>-p</option> option
497
strips white space from the start and from the end of the
498
password before using it. If this is a problem, use the
499
<option>--passfile</option> option instead, which does not do
502
<xi:include href="bugs.xml"/>
505
<refsect1 id="example">
506
<title>EXAMPLE</title>
509
Normal invocation needs no options:
512
<userinput>&COMMANDNAME;</userinput>
517
Create key in another directory and of another type. Force
518
overwriting old key files:
522
<!-- do not wrap this line -->
523
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
529
Prompt for a password, encrypt it with the keys in <filename
530
class="directory">/etc/keys/mandos</filename> and output a
531
section suitable for <filename>clients.conf</filename>.
534
<userinput>&COMMANDNAME; --password</userinput>
539
Prompt for a password, encrypt it with the keys in the
540
<filename>client-key</filename> directory and output a section
541
suitable for <filename>clients.conf</filename>.
545
<!-- do not wrap this line -->
546
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
552
<refsect1 id="security">
553
<title>SECURITY</title>
555
The <option>--type</option>, <option>--length</option>,
556
<option>--subtype</option>, and <option>--sublength</option>
557
options can be used to create keys of low security. If in
558
doubt, leave them to the default values.
561
The key expire time is <emphasis>not</emphasis> guaranteed to be
562
honored by <citerefentry><refentrytitle>mandos</refentrytitle>
563
<manvolnum>8</manvolnum></citerefentry>.
567
<refsect1 id="see_also">
568
<title>SEE ALSO</title>
570
<citerefentry><refentrytitle>intro</refentrytitle>
571
<manvolnum>8mandos</manvolnum></citerefentry>,
572
<citerefentry><refentrytitle>gpg</refentrytitle>
573
<manvolnum>1</manvolnum></citerefentry>,
574
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
575
<manvolnum>5</manvolnum></citerefentry>,
576
<citerefentry><refentrytitle>mandos</refentrytitle>
577
<manvolnum>8</manvolnum></citerefentry>,
578
<citerefentry><refentrytitle>mandos-client</refentrytitle>
579
<manvolnum>8mandos</manvolnum></citerefentry>,
580
<citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
581
<manvolnum>1</manvolnum></citerefentry>
586
<!-- Local Variables: -->
587
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
588
<!-- time-stamp-end: "[\"']>" -->
589
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
mandos-keygen.xml
