100
128
<command>&COMMANDNAME;</command>
101
129
<group choice="req">
102
<arg choice="plain"><option>--help</option></arg>
103
<arg choice="plain"><option>-?</option></arg>
130
<arg choice='plain'><option>-?</option></arg>
131
<arg choice='plain'><option>--help</option></arg>
107
135
<command>&COMMANDNAME;</command>
108
<arg choice="plain"><option>--usage</option></arg>
136
<arg choice='plain'><option>--usage</option></arg>
111
139
<command>&COMMANDNAME;</command>
112
140
<group choice="req">
113
<arg choice="plain"><option>--version</option></arg>
114
<arg choice="plain"><option>-V</option></arg>
141
<arg choice='plain'><option>-V</option></arg>
142
<arg choice='plain'><option>--version</option></arg>
117
145
</refsynopsisdiv>
119
147
<refsect1 id="description">
120
148
<title>DESCRIPTION</title>
122
<command>&COMMANDNAME;</command> is a client program that
123
communicates with <citerefentry><refentrytitle
124
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
125
to get a password. In slightly more detail, this client program
126
brings up a network interface, uses the interface’s IPv6
127
link-local address to get network connectivity, uses Zeroconf to
128
find servers on the local network, and communicates with servers
129
using TLS with an OpenPGP key to ensure authenticity and
130
confidentiality. This client program keeps running, trying all
131
servers on the network, until it receives a satisfactory reply
132
or a TERM signal is received. If no servers are found, or after
133
all servers have been tried, it waits indefinitely for new
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.
150
<command>&COMMANDNAME;</command> is a mandos plugin that works
151
like a client program that through avahi detects mandos servers,
152
sets up a gnutls connect and request a encrypted password. Any
153
passwords given is automaticly decrypted and passed to
158
158
<refsect1 id="options">
159
159
<title>OPTIONS</title>
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
161
Commonly not invoked as command lines but from configuration
162
file of plugin runner.
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>--interface=
195
<replaceable>NAME</replaceable></option></term>
197
<replaceable>NAME</replaceable></option></term>
200
Network interface that will be brought up and scanned for
201
Mandos servers to connect to. The default it
202
<quote><literal>eth0</literal></quote>.
205
If the <option>--connect</option> option is used, this
206
specifies the interface to use to connect to the address
210
Note that since this program will normally run in the
211
initial RAM disk environment, the interface must be an
212
interface which exists at that stage. Thus, the interface
213
can not be a pseudo-interface such as <quote>br0</quote>
214
or <quote>tun0</quote>; such interfaces will not exist
215
until much later in the boot process, and can not be used
222
<term><option>--pubkey=<replaceable
223
>FILE</replaceable></option></term>
225
<replaceable>FILE</replaceable></option></term>
228
OpenPGP public key file name. The default name is
229
<quote><filename>/conf/conf.d/mandos/pubkey.txt</filename
236
<term><option>--seckey=<replaceable
237
>FILE</replaceable></option></term>
239
<replaceable>FILE</replaceable></option></term>
242
OpenPGP secret key file name. The default name is
243
<quote><filename>/conf/conf.d/mandos/seckey.txt</filename
250
<term><option>--priority=<replaceable
251
>STRING</replaceable></option></term>
253
<xi:include href="../mandos-options.xml"
254
xpointer="priority"/>
259
<term><option>--dh-bits=<replaceable
260
>BITS</replaceable></option></term>
263
Sets the number of bits to use for the prime number in the
264
TLS Diffie-Hellman key exchange. Default is 1024.
270
<term><option>--debug</option></term>
273
Enable debug mode. This will enable a lot of output to
274
standard error about what the program is doing. The
275
program will still perform all other functions normally.
278
It will also enable debug mode in the Avahi and GnuTLS
279
libraries, making them print large amounts of debugging
286
<term><option>--help</option></term>
287
<term><option>-?</option></term>
290
Gives a help message about options and their meanings.
296
<term><option>--usage</option></term>
299
Gives a short usage message.
305
<term><option>--version</option></term>
306
<term><option>-V</option></term>
309
Prints the program version.
167
<term><literal>-c</literal>, <literal>--connect=<replaceable>
168
IP</replaceable></literal></term>
171
Connect directly to a specified mandos server
177
<term><literal>-d</literal>, <literal>--keydir=<replaceable>
178
KEYDIR</replaceable></literal></term>
181
Directory where the openpgp keyring is
187
<term><literal>-i</literal>, <literal>--interface=
188
<replaceable>INTERFACE</replaceable></literal></term>
191
Interface that Avahi will conntect through
197
<term><literal>-p</literal>, <literal>--pubkey=<replaceable>
198
PUBKEY</replaceable></literal></term>
201
Public openpgp key for gnutls authentication
207
<term><literal>-s</literal>, <literal>--seckey=<replaceable>
208
SECKEY</replaceable></literal></term>
211
Secret openpgp key for gnutls authentication
217
<term><literal>--priority=<replaceable>PRIORITY</replaceable>
227
<term><literal>--dh-bits=<replaceable>BITS</replaceable>
231
dh-bits to use in gnutls communication
237
<term><literal>--debug</literal></term>
246
<term><literal>-?</literal>, <literal>--help</literal></term>
255
<term><literal>--usage</literal></term>
258
Gives a short usage message
264
<term><literal>-V</literal>, <literal>--version</literal></term>
267
Prints the program version
316
<refsect1 id="overview">
317
<title>OVERVIEW</title>
318
<xi:include href="../overview.xml"/>
320
This program is the client part. It is a plugin started by
321
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
322
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
323
an initial <acronym>RAM</acronym> disk environment.
326
This program could, theoretically, be used as a keyscript in
327
<filename>/etc/crypttab</filename>, but it would then be
328
impossible to enter a password for the encrypted root disk at
329
the console, since this program does not read from the console
330
at all. This is why a separate plugin runner (<citerefentry>
331
<refentrytitle>plugin-runner</refentrytitle>
332
<manvolnum>8mandos</manvolnum></citerefentry>) is used to run
333
both this program and others in in parallel,
334
<emphasis>one</emphasis> of which will prompt for passwords on
339
274
<refsect1 id="exit_status">
340
275
<title>EXIT STATUS</title>
342
This program will exit with a successful (zero) exit status if a
343
server could be found and the password received from it could be
344
successfully decrypted and output on standard output. The
345
program will exit with a non-zero exit status only if a critical
346
error occurs. Otherwise, it will forever connect to new
347
<application>Mandos</application> servers as they appear, trying
348
to get a decryptable password and print it.
352
280
<refsect1 id="environment">
353
281
<title>ENVIRONMENT</title>
355
This program does not use any environment variables, not even
356
the ones provided by <citerefentry><refentrytitle
357
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
362
<refsect1 id="files">
363
287
<title>FILES</title>
366
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
368
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
372
OpenPGP public and private key files, in <quote>ASCII
373
Armor</quote> format. These are the default file names,
374
they can be changed with the <option>--pubkey</option> and
375
<option>--seckey</option> options.
382
<!-- <refsect1 id="bugs"> -->
383
<!-- <title>BUGS</title> -->
388
298
<refsect1 id="example">
389
299
<title>EXAMPLE</title>
391
Note that normally, command line options will not be given
392
directly, but via options for the Mandos <citerefentry
393
><refentrytitle>plugin-runner</refentrytitle>
394
<manvolnum>8mandos</manvolnum></citerefentry>.
398
Normal invocation needs no options, if the network interface
399
is <quote>eth0</quote>:
402
<userinput>&COMMANDNAME;</userinput>
407
Search for Mandos servers (and connect to them) using another
411
<!-- do not wrap this line -->
412
<userinput>&COMMANDNAME; --interface eth1</userinput>
417
Run in debug mode, and use a custom key:
421
<!-- do not wrap this line -->
422
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
428
Run in debug mode, with a custom key, and do not use Zeroconf
429
to locate a server; connect directly to the IPv6 address
430
<quote><systemitem class="ipaddress"
431
>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
432
port 4711, using interface eth2:
436
<!-- do not wrap this line -->
437
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
443
304
<refsect1 id="security">
444
305
<title>SECURITY</title>
446
This program is set-uid to root, but will switch back to the
447
original (and presumably non-privileged) user and group after
448
bringing up the network interface.
451
To use this program for its intended purpose (see <xref
452
linkend="purpose"/>), the password for the root file system will
453
have to be given out to be stored in a server computer, after
454
having been encrypted using an OpenPGP key. This encrypted data
455
which will be stored in a server can only be decrypted by the
456
OpenPGP key, and the data will only be given out to those
457
clients who can prove they actually have that key. This key,
458
however, is stored unencrypted on the client side in its initial
459
<acronym>RAM</acronym> disk image file system. This is normally
460
readable by all, but this is normally fixed during installation
461
of this program; file permissions are set so that no-one is able
465
The only remaining weak point is that someone with physical
466
access to the client hard drive might turn off the client
467
computer, read the OpenPGP keys directly from the hard drive,
468
and communicate with the server. To safeguard against this, the
469
server is supposed to notice the client disappearing and stop
470
giving out the encrypted data. Therefore, it is important to
471
set the timeout and checker interval values tightly on the
472
server. See <citerefentry><refentrytitle
473
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
476
It will also help if the checker program on the server is
477
configured to request something from the client which can not be
478
spoofed by someone else on the network, unlike unencrypted
479
<acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.
482
<emphasis>Note</emphasis>: This makes it completely insecure to
483
have <application >Mandos</application> clients which dual-boot
484
to another operating system which is <emphasis>not</emphasis>
485
trusted to keep the initial <acronym>RAM</acronym> disk image
490
310
<refsect1 id="see_also">
491
311
<title>SEE ALSO</title>
493
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
494
<manvolnum>8</manvolnum></citerefentry>,
495
<citerefentry><refentrytitle>crypttab</refentrytitle>
496
<manvolnum>5</manvolnum></citerefentry>,
497
313
<citerefentry><refentrytitle>mandos</refentrytitle>
498
314
<manvolnum>8</manvolnum></citerefentry>,
499
315
<citerefentry><refentrytitle>password-prompt</refentrytitle>
501
317
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
502
318
<manvolnum>8mandos</manvolnum></citerefentry>
507
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
511
Zeroconf is the network protocol standard used for finding
512
Mandos servers on the local network.
518
<ulink url="http://www.avahi.org/">Avahi</ulink>
522
Avahi is the library this program calls to find Zeroconf
529
<ulink url="http://www.gnu.org/software/gnutls/"
534
GnuTLS is the library this client uses to implement TLS for
535
communicating securely with the server, and at the same time
536
send the public OpenPGP key to the server.
542
<ulink url="http://www.gnupg.org/related_software/gpgme/"
547
GPGME is the library used to decrypt the OpenPGP data sent
554
RFC 4291: <citetitle>IP Version 6 Addressing
555
Architecture</citetitle>
560
<term>Section 2.2: <citetitle>Text Representation of
561
Addresses</citetitle></term>
562
<listitem><para/></listitem>
565
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
566
Address</citetitle></term>
567
<listitem><para/></listitem>
570
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
571
Addresses</citetitle></term>
574
This client uses IPv6 link-local addresses, which are
575
immediately usable since a link-local addresses is
576
automatically assigned to a network interfaces when it
586
RFC 4346: <citetitle>The Transport Layer Security (TLS)
587
Protocol Version 1.1</citetitle>
591
TLS 1.1 is the protocol implemented by GnuTLS.
597
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
601
The data received from the server is binary encrypted
608
RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
613
This is implemented by GnuTLS and used by this program so
614
that OpenPGP keys can be used.
322
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
326
<ulink url="http://www.avahi.org/">Avahi</ulink>
331
url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
336
url="http://www.gnupg.org/related_software/gpgme/">
341
<citation>RFC 4880: <citetitle>OpenPGP Message
342
Format</citetitle></citation>
346
<citation>RFC 5081: <citetitle>Using OpenPGP Keys for
347
Transport Layer Security</citetitle></citation>
351
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
352
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
353
Unicast Addresses</citation>
622
359
<!-- Local Variables: -->
623
360
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
624
361
<!-- time-stamp-end: "[\"']>" -->