122
136
</refsynopsisdiv>
124
138
<refsect1 id="description">
125
139
<title>DESCRIPTION</title>
127
<command>&COMMANDNAME;</command> is a mandos plugin that works
128
like a client program that through avahi detects mandos servers,
129
sets up a gnutls connect and request a encrypted password. Any
130
passwords given is automaticly decrypted and passed to
141
<command>&COMMANDNAME;</command> is a client program that
142
communicates with <citerefentry><refentrytitle
143
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
144
to get a password. In slightly more detail, this client program
145
brings up network interfaces, uses the interfaces’ IPv6
146
link-local addresses to get network connectivity, uses Zeroconf
147
to find servers on the local network, and communicates with
148
servers using TLS with an OpenPGP key to ensure authenticity and
149
confidentiality. This client program keeps running, trying all
150
servers on the network, until it receives a satisfactory reply
151
or a TERM signal. After all servers have been tried, all
152
servers are periodically retried. If no servers are found it
153
will wait indefinitely for new servers to appear.
156
The network interfaces are selected like this: If any interfaces
157
are specified using the <option>--interface</option> option,
158
those interface are used. Otherwise,
159
<command>&COMMANDNAME;</command> will use all interfaces that
160
are not loopback interfaces, are not point-to-point interfaces,
161
are capable of broadcasting and do not have the NOARP flag (see
162
<citerefentry><refentrytitle>netdevice</refentrytitle>
163
<manvolnum>7</manvolnum></citerefentry>). (If the
164
<option>--connect</option> option is used, point-to-point
165
interfaces and non-broadcast interfaces are accepted.) If any
166
used interfaces are not up and running, they are first taken up
167
(and later taken down again on program exit).
170
Before network interfaces are selected, all <quote>network
171
hooks</quote> are run; see <xref linkend="network-hooks"/>.
174
This program is not meant to be run directly; it is really meant
175
to run as a plugin of the <application>Mandos</application>
176
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
177
<manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
178
initial <acronym>RAM</acronym> disk environment because it is
179
specified as a <quote>keyscript</quote> in the <citerefentry>
180
<refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
181
</citerefentry> file.
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.
135
195
<refsect1 id="options">
136
196
<title>OPTIONS</title>
138
Commonly not invoked as command lines but from configuration
139
file of plugin runner.
198
This program is commonly not invoked from the command line; it
199
is normally started by the <application>Mandos</application>
200
plugin runner, see <citerefentry><refentrytitle
201
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
202
</citerefentry>. Any command line options this program accepts
203
are therefore normally provided by the plugin runner, and not
144
209
<term><option>--connect=<replaceable
145
>IPADDR</replaceable><literal>:</literal><replaceable
210
>ADDRESS</replaceable><literal>:</literal><replaceable
146
211
>PORT</replaceable></option></term>
148
<replaceable>IPADDR</replaceable><literal>:</literal
213
<replaceable>ADDRESS</replaceable><literal>:</literal
149
214
><replaceable>PORT</replaceable></option></term>
152
Connect directly to a specified mandos server
217
Do not use Zeroconf to locate servers. Connect directly
218
to only one specified <application>Mandos</application>
219
server. Note that an IPv6 address has colon characters in
220
it, so the <emphasis>last</emphasis> colon character is
221
assumed to separate the address from the port number.
158
<term><option>--keydir=<replaceable
159
>DIRECTORY</replaceable></option></term>
161
<replaceable>DIRECTORY</replaceable></option></term>
164
Directory where the openpgp keyring is
224
Normally, Zeroconf would be used to locate Mandos servers,
225
in which case this option would only be used when testing
170
<term><option>--interface=
171
<replaceable>NAME</replaceable></option></term>
232
<term><option>--interface=<replaceable
233
>NAME</replaceable><arg rep='repeat'>,<replaceable
234
>NAME</replaceable></arg></option></term>
173
<replaceable>NAME</replaceable></option></term>
236
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
237
>NAME</replaceable></arg></option></term>
176
Interface that Avahi will connect through
240
Comma separated list of network interfaces that will be
241
brought up and scanned for Mandos servers to connect to.
242
The default is the empty string, which will automatically
243
use all appropriate interfaces.
246
If the <option>--connect</option> option is used, and
247
exactly one interface name is specified (except
248
<quote><literal>none</literal></quote>), this specifies
249
the interface to use to connect to the address given.
252
Note that since this program will normally run in the
253
initial RAM disk environment, the interface must be an
254
interface which exists at that stage. Thus, the interface
255
can normally not be a pseudo-interface such as
256
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
257
will not exist until much later in the boot process, and
258
can not be used by this program, unless created by a
259
<quote>network hook</quote> — see <xref
260
linkend="network-hooks"/>.
263
<replaceable>NAME</replaceable> can be the string
264
<quote><literal>none</literal></quote>; this will make
265
<command>&COMMANDNAME;</command> only bring up interfaces
266
specified <emphasis>before</emphasis> this string. This
267
is not recommended, and only meant for advanced users.
182
273
<term><option>--pubkey=<replaceable
183
274
>FILE</replaceable></option></term>
245
388
<term><option>--usage</option></term>
248
Gives a short usage message
391
Gives a short usage message.
254
397
<term><option>--version</option></term>
255
398
<term><option>-V</option></term>
258
Prints the program version
401
Prints the program version.
408
<refsect1 id="overview">
409
<title>OVERVIEW</title>
410
<xi:include href="../overview.xml"/>
412
This program is the client part. It is a plugin started by
413
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
414
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
415
an initial <acronym>RAM</acronym> disk environment.
418
This program could, theoretically, be used as a keyscript in
419
<filename>/etc/crypttab</filename>, but it would then be
420
impossible to enter a password for the encrypted root disk at
421
the console, since this program does not read from the console
422
at all. This is why a separate plugin runner (<citerefentry>
423
<refentrytitle>plugin-runner</refentrytitle>
424
<manvolnum>8mandos</manvolnum></citerefentry>) is used to run
425
both this program and others in in parallel,
426
<emphasis>one</emphasis> of which (<citerefentry>
427
<refentrytitle>password-prompt</refentrytitle>
428
<manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
429
passwords on the system console.
265
433
<refsect1 id="exit_status">
266
434
<title>EXIT STATUS</title>
436
This program will exit with a successful (zero) exit status if a
437
server could be found and the password received from it could be
438
successfully decrypted and output on standard output. The
439
program will exit with a non-zero exit status only if a critical
440
error occurs. Otherwise, it will forever connect to any
441
discovered <application>Mandos</application> servers, trying to
442
get a decryptable password and print it.
271
446
<refsect1 id="environment">
272
447
<title>ENVIRONMENT</title>
450
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
453
This environment variable will be assumed to contain the
454
directory containing any helper executables. The use and
455
nature of these helper executables, if any, is
456
purposefully not documented.
462
This program does not use any other environment variables, not
463
even the ones provided by <citerefentry><refentrytitle
464
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
469
<refsect1 id="network-hooks">
470
<title>NETWORK HOOKS</title>
472
If a network interface like a bridge or tunnel is required to
473
find a Mandos server, this requires the interface to be up and
474
running before <command>&COMMANDNAME;</command> starts looking
475
for Mandos servers. This can be accomplished by creating a
476
<quote>network hook</quote> program, and placing it in a special
480
Before the network is used (and again before program exit), any
481
runnable programs found in the network hook directory are run
482
with the argument <quote><literal>start</literal></quote> or
483
<quote><literal>stop</literal></quote>. This should bring up or
484
down, respectively, any network interface which
485
<command>&COMMANDNAME;</command> should use.
487
<refsect2 id="hook-requirements">
488
<title>REQUIREMENTS</title>
490
A network hook must be an executable file, and its name must
491
consist entirely of upper and lower case letters, digits,
492
underscores, periods, and hyphens.
495
A network hook will receive one argument, which can be one of
500
<term><literal>start</literal></term>
503
This should make the network hook create (if necessary)
504
and bring up a network interface.
509
<term><literal>stop</literal></term>
512
This should make the network hook take down a network
513
interface, and delete it if it did not exist previously.
518
<term><literal>files</literal></term>
521
This should make the network hook print, <emphasis>one
522
file per line</emphasis>, all the files needed for it to
523
run. (These files will be copied into the initial RAM
524
filesystem.) Typical use is for a network hook which is
525
a shell script to print its needed binaries.
528
It is not necessary to print any non-executable files
529
already in the network hook directory, these will be
530
copied implicitly if they otherwise satisfy the name
536
<term><literal>modules</literal></term>
539
This should make the network hook print, <emphasis>on
540
separate lines</emphasis>, all the kernel modules needed
541
for it to run. (These modules will be copied into the
542
initial RAM filesystem.) For instance, a tunnel
544
<quote><literal>tun</literal></quote> module.
550
The network hook will be provided with a number of environment
555
<term><envar>MANDOSNETHOOKDIR</envar></term>
558
The network hook directory, specified to
559
<command>&COMMANDNAME;</command> by the
560
<option>--network-hook-dir</option> option. Note: this
561
should <emphasis>always</emphasis> be used by the
562
network hook to refer to itself or any files in the hook
563
directory it may require.
568
<term><envar>DEVICE</envar></term>
571
The network interfaces, as specified to
572
<command>&COMMANDNAME;</command> by the
573
<option>--interface</option> option, combined to one
574
string and separated by commas. If this is set, and
575
does not contain the interface a hook will bring up,
576
there is no reason for a hook to continue.
581
<term><envar>MODE</envar></term>
584
This will be the same as the first argument;
585
i.e. <quote><literal>start</literal></quote>,
586
<quote><literal>stop</literal></quote>,
587
<quote><literal>files</literal></quote>, or
588
<quote><literal>modules</literal></quote>.
593
<term><envar>VERBOSITY</envar></term>
596
This will be the <quote><literal>1</literal></quote> if
597
the <option>--debug</option> option is passed to
598
<command>&COMMANDNAME;</command>, otherwise
599
<quote><literal>0</literal></quote>.
604
<term><envar>DELAY</envar></term>
607
This will be the same as the <option>--delay</option>
608
option passed to <command>&COMMANDNAME;</command>. Is
609
only set if <envar>MODE</envar> is
610
<quote><literal>start</literal></quote> or
611
<quote><literal>stop</literal></quote>.
616
<term><envar>CONNECT</envar></term>
619
This will be the same as the <option>--connect</option>
620
option passed to <command>&COMMANDNAME;</command>. Is
621
only set if <option>--connect</option> is passed and
622
<envar>MODE</envar> is
623
<quote><literal>start</literal></quote> or
624
<quote><literal>stop</literal></quote>.
630
A hook may not read from standard input, and should be
631
restrictive in printing to standard output or standard error
632
unless <varname>VERBOSITY</varname> is
633
<quote><literal>1</literal></quote>.
638
<refsect1 id="files">
278
639
<title>FILES</title>
642
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
644
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
648
OpenPGP public and private key files, in <quote>ASCII
649
Armor</quote> format. These are the default file names,
650
they can be changed with the <option>--pubkey</option> and
651
<option>--seckey</option> options.
657
class="directory">/lib/mandos/network-hooks.d</filename></term>
660
Directory where network hooks are located. Change this
661
with the <option>--network-hook-dir</option> option. See
662
<xref linkend="network-hooks"/>.
669
<!-- <refsect1 id="bugs"> -->
670
<!-- <title>BUGS</title> -->
289
675
<refsect1 id="example">
290
676
<title>EXAMPLE</title>
678
Note that normally, command line options will not be given
679
directly, but via options for the Mandos <citerefentry
680
><refentrytitle>plugin-runner</refentrytitle>
681
<manvolnum>8mandos</manvolnum></citerefentry>.
685
Normal invocation needs no options, if the network interfaces
686
can be automatically determined:
689
<userinput>&COMMANDNAME;</userinput>
694
Search for Mandos servers (and connect to them) using one
698
<!-- do not wrap this line -->
699
<userinput>&COMMANDNAME; --interface eth1</userinput>
704
Run in debug mode, and use a custom key:
708
<!-- do not wrap this line -->
709
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
715
Run in debug mode, with a custom key, and do not use Zeroconf
716
to locate a server; connect directly to the IPv6 link-local
717
address <quote><systemitem class="ipaddress"
718
>fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
719
using interface eth2:
723
<!-- do not wrap this line -->
724
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
295
730
<refsect1 id="security">
296
731
<title>SECURITY</title>
733
This program is set-uid to root, but will switch back to the
734
original (and presumably non-privileged) user and group after
735
bringing up the network interface.
738
To use this program for its intended purpose (see <xref
739
linkend="purpose"/>), the password for the root file system will
740
have to be given out to be stored in a server computer, after
741
having been encrypted using an OpenPGP key. This encrypted data
742
which will be stored in a server can only be decrypted by the
743
OpenPGP key, and the data will only be given out to those
744
clients who can prove they actually have that key. This key,
745
however, is stored unencrypted on the client side in its initial
746
<acronym>RAM</acronym> disk image file system. This is normally
747
readable by all, but this is normally fixed during installation
748
of this program; file permissions are set so that no-one is able
752
The only remaining weak point is that someone with physical
753
access to the client hard drive might turn off the client
754
computer, read the OpenPGP keys directly from the hard drive,
755
and communicate with the server. To safeguard against this, the
756
server is supposed to notice the client disappearing and stop
757
giving out the encrypted data. Therefore, it is important to
758
set the timeout and checker interval values tightly on the
759
server. See <citerefentry><refentrytitle
760
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
763
It will also help if the checker program on the server is
764
configured to request something from the client which can not be
765
spoofed by someone else on the network, like SSH server key
766
fingerprints, and unlike unencrypted <acronym>ICMP</acronym>
767
echo (<quote>ping</quote>) replies.
770
<emphasis>Note</emphasis>: This makes it completely insecure to
771
have <application >Mandos</application> clients which dual-boot
772
to another operating system which is <emphasis>not</emphasis>
773
trusted to keep the initial <acronym>RAM</acronym> disk image
301
778
<refsect1 id="see_also">
302
779
<title>SEE ALSO</title>
781
<citerefentry><refentrytitle>intro</refentrytitle>
782
<manvolnum>8mandos</manvolnum></citerefentry>,
783
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
784
<manvolnum>8</manvolnum></citerefentry>,
785
<citerefentry><refentrytitle>crypttab</refentrytitle>
786
<manvolnum>5</manvolnum></citerefentry>,
304
787
<citerefentry><refentrytitle>mandos</refentrytitle>
305
788
<manvolnum>8</manvolnum></citerefentry>,
306
789
<citerefentry><refentrytitle>password-prompt</refentrytitle>
308
791
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
309
792
<manvolnum>8mandos</manvolnum></citerefentry>
313
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
317
<ulink url="http://www.avahi.org/">Avahi</ulink>
322
url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
327
url="http://www.gnupg.org/related_software/gpgme/">
332
<citation>RFC 4880: <citetitle>OpenPGP Message
333
Format</citetitle></citation>
337
<citation>RFC 5081: <citetitle>Using OpenPGP Keys for
338
Transport Layer Security</citetitle></citation>
342
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
343
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
344
Unicast Addresses</citation>
797
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
801
Zeroconf is the network protocol standard used for finding
802
Mandos servers on the local network.
808
<ulink url="http://www.avahi.org/">Avahi</ulink>
812
Avahi is the library this program calls to find Zeroconf
819
<ulink url="http://www.gnu.org/software/gnutls/"
824
GnuTLS is the library this client uses to implement TLS for
825
communicating securely with the server, and at the same time
826
send the public OpenPGP key to the server.
832
<ulink url="http://www.gnupg.org/related_software/gpgme/"
837
GPGME is the library used to decrypt the OpenPGP data sent
844
RFC 4291: <citetitle>IP Version 6 Addressing
845
Architecture</citetitle>
850
<term>Section 2.2: <citetitle>Text Representation of
851
Addresses</citetitle></term>
852
<listitem><para/></listitem>
855
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
856
Address</citetitle></term>
857
<listitem><para/></listitem>
860
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
861
Addresses</citetitle></term>
864
This client uses IPv6 link-local addresses, which are
865
immediately usable since a link-local addresses is
866
automatically assigned to a network interface when it
876
RFC 4346: <citetitle>The Transport Layer Security (TLS)
877
Protocol Version 1.1</citetitle>
881
TLS 1.1 is the protocol implemented by GnuTLS.
887
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
891
The data received from the server is binary encrypted
898
RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
903
This is implemented by GnuTLS and used by this program so
904
that OpenPGP keys can be used.
350
912
<!-- Local Variables: -->
351
913
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
352
914
<!-- time-stamp-end: "[\"']>" -->