77
54
<command>&COMMANDNAME;</command>
78
<arg choice='opt'>--connect<arg choice='plain'>IP</arg></arg>
79
<arg choice='opt'>--keydir<arg choice='plain'>KEYDIR</arg></arg>
80
<arg choice='opt'>--interface<arg choice='plain'>INTERFACE</arg></arg>
81
<arg choice='opt'>--pubkey<arg choice='plain'>PUBKEY</arg></arg>
82
<arg choice='opt'>--seckey<arg choice='plain'>SECKEY</arg></arg>
83
<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
84
<arg choice='opt'>--dh-bits<arg choice='plain'>BITS</arg></arg>
85
<arg choice='opt'>--debug</arg>
88
<command>&COMMANDNAME;</command>
89
<arg choice='plain'>--help</arg>
92
<command>&COMMANDNAME;</command>
93
<arg choice='plain'>--usage</arg>
96
<command>&COMMANDNAME;</command>
97
<arg choice='plain'>--version</arg>
56
<arg choice="plain"><option>--connect
57
<replaceable>IPADDR</replaceable><literal>:</literal
58
><replaceable>PORT</replaceable></option></arg>
59
<arg choice="plain"><option>-c
60
<replaceable>IPADDR</replaceable><literal>:</literal
61
><replaceable>PORT</replaceable></option></arg>
65
<arg choice="plain"><option>--keydir
66
<replaceable>DIRECTORY</replaceable></option></arg>
67
<arg choice="plain"><option>-d
68
<replaceable>DIRECTORY</replaceable></option></arg>
72
<arg choice="plain"><option>--interface
73
<replaceable>NAME</replaceable></option></arg>
74
<arg choice="plain"><option>-i
75
<replaceable>NAME</replaceable></option></arg>
79
<arg choice="plain"><option>--pubkey
80
<replaceable>FILE</replaceable></option></arg>
81
<arg choice="plain"><option>-p
82
<replaceable>FILE</replaceable></option></arg>
86
<arg choice="plain"><option>--seckey
87
<replaceable>FILE</replaceable></option></arg>
88
<arg choice="plain"><option>-s
89
<replaceable>FILE</replaceable></option></arg>
93
<option>--priority <replaceable>STRING</replaceable></option>
97
<option>--dh-bits <replaceable>BITS</replaceable></option>
101
<option>--debug</option>
105
<command>&COMMANDNAME;</command>
107
<arg choice="plain"><option>--help</option></arg>
108
<arg choice="plain"><option>-?</option></arg>
112
<command>&COMMANDNAME;</command>
113
<arg choice="plain"><option>--usage</option></arg>
116
<command>&COMMANDNAME;</command>
118
<arg choice="plain"><option>--version</option></arg>
119
<arg choice="plain"><option>-V</option></arg>
101
124
<refsect1 id="description">
102
125
<title>DESCRIPTION</title>
104
<command>&COMMANDNAME;</command> is a mandos plugin that works
105
like a client program that through avahi detects mandos servers,
106
sets up a gnutls connect and request a encrypted password. Any
107
passwords given is automaticly decrypted and passed to
127
<command>&COMMANDNAME;</command> is a client program that
128
communicates with <citerefentry><refentrytitle
129
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
130
to get a password. It uses IPv6 link-local addresses to get
131
network connectivity, Zeroconf to find servers, and TLS with an
132
OpenPGP key to ensure authenticity and confidentiality. It
133
keeps running, trying all servers on the network, until it
134
receives a satisfactory reply or a TERM signal is recieved.
137
This program is not meant to be run directly; it is really meant
138
to run as a plugin of the <application>Mandos</application>
139
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
140
<manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
141
initial <acronym>RAM</acronym> disk environment because it is
142
specified as a <quote>keyscript</quote> in the <citerefentry>
143
<refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
144
</citerefentry> file.
148
<refsect1 id="purpose">
149
<title>PURPOSE</title>
151
The purpose of this is to enable <emphasis>remote and unattended
152
rebooting</emphasis> of client host computer with an
153
<emphasis>encrypted root file system</emphasis>. See <xref
154
linkend="overview"/> for details.
112
158
<refsect1 id="options">
113
159
<title>OPTIONS</title>
115
Commonly not invoked as command lines but from configuration
116
file of plugin runner.
161
This program is commonly not invoked from the command line; it
162
is normally started by the <application>Mandos</application>
163
plugin runner, see <citerefentry><refentrytitle
164
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
165
</citerefentry>. Any command line options this program accepts
166
are therefore normally provided by the plugin runner, and not
121
<term><literal>-c</literal>, <literal>--connect=<replaceable>
122
IP</replaceable></literal></term>
125
Connect directly to a specified mandos server
131
<term><literal>-d</literal>, <literal>--keydir=<replaceable>
132
KEYDIR</replaceable></literal></term>
135
Directory where the openpgp keyring is
141
<term><literal>-i</literal>, <literal>--interface=
142
<replaceable>INTERFACE</replaceable></literal></term>
145
Interface that Avahi will conntect through
151
<term><literal>-p</literal>, <literal>--pubkey=<replaceable>
152
PUBKEY</replaceable></literal></term>
155
Public openpgp key for gnutls authentication
161
<term><literal>-s</literal>, <literal>--seckey=<replaceable>
162
SECKEY</replaceable></literal></term>
165
Secret openpgp key for gnutls authentication
171
<term><literal>--priority=<replaceable>PRIORITY</replaceable>
181
<term><literal>--dh-bits=<replaceable>BITS</replaceable>
185
dh-bits to use in gnutls communication
191
<term><literal>--debug</literal></term>
200
<term><literal>-?</literal>, <literal>--help</literal></term>
209
<term><literal>--usage</literal></term>
212
Gives a short usage message
218
<term><literal>-V</literal>, <literal>--version</literal></term>
221
Prints the program version
172
<term><option>--connect=<replaceable
173
>ADDRESS</replaceable><literal>:</literal><replaceable
174
>PORT</replaceable></option></term>
176
<replaceable>ADDRESS</replaceable><literal>:</literal
177
><replaceable>PORT</replaceable></option></term>
180
Do not use Zeroconf to locate servers. Connect directly
181
to only one specified <application>Mandos</application>
182
server. Note that an IPv6 address has colon characters in
183
it, so the <emphasis>last</emphasis> colon character is
184
assumed to separate the address from the port number.
187
This option is normally only useful for testing and
194
<term><option>--keydir=<replaceable
195
>DIRECTORY</replaceable></option></term>
197
<replaceable>DIRECTORY</replaceable></option></term>
200
Directory to read the OpenPGP key files
201
<filename>pubkey.txt</filename> and
202
<filename>seckey.txt</filename> from. The default is
203
<filename>/conf/conf.d/mandos</filename> (in the initial
204
<acronym>RAM</acronym> disk environment).
210
<term><option>--interface=
211
<replaceable>NAME</replaceable></option></term>
213
<replaceable>NAME</replaceable></option></term>
216
Network interface that will be brought up and scanned for
217
Mandos servers to connect to. The default it
218
<quote><literal>eth0</literal></quote>.
221
If the <option>--connect</option> option is used, this
222
specifies the interface to use to connect to the address
229
<term><option>--pubkey=<replaceable
230
>FILE</replaceable></option></term>
232
<replaceable>FILE</replaceable></option></term>
235
OpenPGP public key file base name. This will be combined
236
with the directory from the <option>--keydir</option>
237
option to form an absolute file name. The default name is
238
<quote><literal>pubkey.txt</literal></quote>.
244
<term><option>--seckey=<replaceable
245
>FILE</replaceable></option></term>
247
<replaceable>FILE</replaceable></option></term>
250
OpenPGP secret key file base name. This will be combined
251
with the directory from the <option>--keydir</option>
252
option to form an absolute file name. The default name is
253
<quote><literal>seckey.txt</literal></quote>.
259
<term><option>--priority=<replaceable
260
>STRING</replaceable></option></term>
262
<xi:include href="../mandos-options.xml"
263
xpointer="priority"/>
268
<term><option>--dh-bits=<replaceable
269
>BITS</replaceable></option></term>
272
Sets the number of bits to use for the prime number in the
273
TLS Diffie-Hellman key exchange. Default is 1024.
279
<term><option>--debug</option></term>
282
Enable debug mode. This will enable a lot of output to
283
standard error about what the program is doing. The
284
program will still perform all other functions normally.
287
It will also enable debug mode in the Avahi and GnuTLS
288
libraries, making them print large amounts of debugging
295
<term><option>--help</option></term>
296
<term><option>-?</option></term>
299
Gives a help message about options and their meanings.
305
<term><option>--usage</option></term>
308
Gives a short usage message.
314
<term><option>--version</option></term>
315
<term><option>-V</option></term>
318
Prints the program version.
325
<refsect1 id="overview">
326
<title>OVERVIEW</title>
327
<xi:include href="../overview.xml"/>
329
This program is the client part. It is a plugin started by
330
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
331
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
332
an initial <acronym>RAM</acronym> disk environment.
335
This program could, theoretically, be used as a keyscript in
336
<filename>/etc/crypttab</filename>, but it would then be
337
impossible to enter a password for the encrypted root disk at
338
the console, since this program does not read from the console
339
at all. This is why a separate plugin (<citerefentry>
340
<refentrytitle>password-prompt</refentrytitle>
341
<manvolnum>8mandos</manvolnum></citerefentry>) does that, which
342
will be run in parallell to this one by the plugin runner.
228
346
<refsect1 id="exit_status">
229
347
<title>EXIT STATUS</title>
349
This program will exit with a successful (zero) exit status if a
350
server could be found and the password received from it could be
351
successfully decrypted and output on standard output. The
352
program will exit with a non-zero exit status only if a critical
353
error occurs. Otherwise, it will forever connect to new
354
<application>Mandos</application> servers as they appear, trying
355
to get a decryptable password.
234
359
<refsect1 id="environment">
235
360
<title>ENVIRONMENT</title>
362
This program does not use any environment variables, not even
363
the ones provided by <citerefentry><refentrytitle
364
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
240
369
<refsect1 id="file">
241
370
<title>FILES</title>
373
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
375
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
379
OpenPGP public and private key files, in <quote>ASCII
380
Armor</quote> format. These are the default file names,
381
they can be changed with the <option>--pubkey</option> and
382
<option>--seckey</option> options.
389
<!-- <refsect1 id="bugs"> -->
390
<!-- <title>BUGS</title> -->
252
395
<refsect1 id="example">
253
396
<title>EXAMPLE</title>
398
Note that normally, command line options will not be given
399
directly, but via options for the Mandos <citerefentry
400
><refentrytitle>plugin-runner</refentrytitle>
401
<manvolnum>8mandos</manvolnum></citerefentry>.
405
Normal invocation needs no options, if the network interface
406
is <quote>eth0</quote>:
409
<userinput>&COMMANDNAME;</userinput>
414
Search for Mandos servers on another interface:
417
<!-- do not wrap this line -->
418
<userinput>&COMMANDNAME; --interface eth1</userinput>
423
Run in debug mode, and use a custom key directory:
426
<!-- do not wrap this line -->
427
<userinput>&COMMANDNAME; --debug --keydir keydir</userinput>
432
Run in debug mode, with a custom key directory, and do not use
433
Zeroconf to locate a server; connect directly to the IPv6
434
address <quote><systemitem class="ipaddress"
435
>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
436
port 4711, using interface eth2:
440
<!-- do not wrap this line -->
441
<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
258
447
<refsect1 id="security">
259
448
<title>SECURITY</title>
450
This program is set-uid to root, but will switch back to the
451
original (and presumably non-privileged) user and group after
452
bringing up the network interface.
455
To use this program for its intended purpose (see <xref
456
linkend="purpose"/>), the password for the root file system will
457
have to be given out to be stored in a server computer, after
458
having been encrypted using an OpenPGP key. This encrypted data
459
which will be stored in a server can only be decrypted by the
460
OpenPGP key, and the data will only be given out to those
461
clients who can prove they actually have that key. This key,
462
however, is stored unencrypted on the client side in its initial
463
<acronym>RAM</acronym> disk image file system. This is normally
464
readable by all, but this is normally fixed during installation
465
of this program; file permissions are set so that no-one is able
469
The only remaining weak point is that someone with physical
470
access to the client hard drive might turn off the client
471
computer, read the OpenPGP keys directly from the hard drive,
472
and communicate with the server. The defense against this is
473
that the server is supposed to notice the client disappearing
474
and will stop giving out the encrypted data. Therefore, it is
475
important to set the timeout and checker interval values tightly
476
on the server. See <citerefentry><refentrytitle
477
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
480
It will also help if the checker program on the server is
481
configured to request something from the client which can not be
482
spoofed by someone else on the network, unlike unencrypted
483
<acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.
486
<emphasis>Note</emphasis>: This makes it completely insecure to
487
have <application >Mandos</application> clients which dual-boot
488
to another operating system which is <emphasis>not</emphasis>
489
trusted to keep the initial <acronym>RAM</acronym> disk image
264
494
<refsect1 id="see_also">
265
495
<title>SEE ALSO</title>
268
<citerefentry><refentrytitle>mandos</refentrytitle>
269
<manvolnum>8</manvolnum></citerefentry>
273
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
274
<manvolnum>8mandos</manvolnum></citerefentry>
278
<citerefentry><refentrytitle>password-prompt</refentrytitle>
279
<manvolnum>8mandos</manvolnum></citerefentry>
283
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
287
<ulink url="http://www.avahi.org/">Avahi</ulink>
292
url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
297
url="http://www.gnupg.org/related_software/gpgme/">
302
<citation>RFC 4880: <citetitle>OpenPGP Message
303
Format</citetitle></citation>
307
<citation>RFC 5081: <citetitle>Using OpenPGP Keys for
308
Transport Layer Security</citetitle></citation>
312
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
313
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
314
Unicast Addresses</citation>
497
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
498
<manvolnum>8</manvolnum></citerefentry>,
499
<citerefentry><refentrytitle>crypttab</refentrytitle>
500
<manvolnum>5</manvolnum></citerefentry>,
501
<citerefentry><refentrytitle>mandos</refentrytitle>
502
<manvolnum>8</manvolnum></citerefentry>,
503
<citerefentry><refentrytitle>password-prompt</refentrytitle>
504
<manvolnum>8mandos</manvolnum></citerefentry>,
505
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
506
<manvolnum>8mandos</manvolnum></citerefentry>
511
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
515
Zeroconf is the network protocol standard used for finding
516
Mandos servers on the local network.
522
<ulink url="http://www.avahi.org/">Avahi</ulink>
526
Avahi is the library this program calls to find Zeroconf
533
<ulink url="http://www.gnu.org/software/gnutls/"
538
GnuTLS is the library this client uses to implement TLS for
539
communicating securely with the server, and at the same time
540
send the public OpenPGP key to the server.
546
<ulink url="http://www.gnupg.org/related_software/gpgme/"
551
GPGME is the library used to decrypt the OpenPGP data sent
558
RFC 4291: <citetitle>IP Version 6 Addressing
559
Architecture</citetitle>
564
<term>Section 2.2: <citetitle>Text Representation of
565
Addresses</citetitle></term>
566
<listitem><para/></listitem>
569
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
570
Address</citetitle></term>
571
<listitem><para/></listitem>
574
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
575
Addresses</citetitle></term>
578
This client uses IPv6 link-local addresses, which are
579
immediately usable since a link-local addresses is
580
automatically assigned to a network interfaces when it
590
RFC 4346: <citetitle>The Transport Layer Security (TLS)
591
Protocol Version 1.1</citetitle>
595
TLS 1.1 is the protocol implemented by GnuTLS.
601
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
605
The data received from the server is binary encrypted
612
RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
617
This is implemented by GnuTLS and used by this program so
618
that OpenPGP keys can be used.