140
122
</refsynopsisdiv>
142
124
<refsect1 id="description">
143
125
<title>DESCRIPTION</title>
145
127
<command>&COMMANDNAME;</command> is a client program that
146
128
communicates with <citerefentry><refentrytitle
147
129
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
148
to get a password. In slightly more detail, this client program
149
brings up network interfaces, uses the interfaces’ IPv6
150
link-local addresses to get network connectivity, uses Zeroconf
151
to find servers on the local network, and communicates with
152
servers using TLS with an OpenPGP key to ensure authenticity and
153
confidentiality. This client program keeps running, trying all
154
servers on the network, until it receives a satisfactory reply
155
or a TERM signal. After all servers have been tried, all
156
servers are periodically retried. If no servers are found it
157
will wait indefinitely for new servers to appear.
160
The network interfaces are selected like this: If any interfaces
161
are specified using the <option>--interface</option> option,
162
those interface are used. Otherwise,
163
<command>&COMMANDNAME;</command> will use all interfaces that
164
are not loopback interfaces, are not point-to-point interfaces,
165
are capable of broadcasting and do not have the NOARP flag (see
166
<citerefentry><refentrytitle>netdevice</refentrytitle>
167
<manvolnum>7</manvolnum></citerefentry>). (If the
168
<option>--connect</option> option is used, point-to-point
169
interfaces and non-broadcast interfaces are accepted.) If any
170
used interfaces are not up and running, they are first taken up
171
(and later taken down again on program exit).
174
Before network interfaces are selected, all <quote>network
175
hooks</quote> are run; see <xref linkend="network-hooks"/>.
130
to get a password. It uses IPv6 link-local addresses to get
131
network connectivity, Zeroconf to find the server, and TLS with
132
an OpenPGP key to ensure authenticity and confidentiality. It
133
keeps running, trying all servers on the network, until it
134
receives a satisfactory reply.
178
137
This program is not meant to be run directly; it is really meant
225
184
assumed to separate the address from the port number.
228
Normally, Zeroconf would be used to locate Mandos servers,
229
in which case this option would only be used when testing
187
This option is normally only useful for testing and
236
<term><option>--interface=<replaceable
237
>NAME</replaceable><arg rep='repeat'>,<replaceable
238
>NAME</replaceable></arg></option></term>
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>
240
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
241
>NAME</replaceable></arg></option></term>
213
<replaceable>NAME</replaceable></option></term>
244
Comma separated list of network interfaces that will be
245
brought up and scanned for Mandos servers to connect to.
246
The default is the empty string, which will automatically
247
use all appropriate interfaces.
250
If the <option>--connect</option> option is used, and
251
exactly one interface name is specified (except
252
<quote><literal>none</literal></quote>), this specifies
253
the interface to use to connect to the address given.
256
Note that since this program will normally run in the
257
initial RAM disk environment, the interface must be an
258
interface which exists at that stage. Thus, the interface
259
can normally not be a pseudo-interface such as
260
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
261
will not exist until much later in the boot process, and
262
can not be used by this program, unless created by a
263
<quote>network hook</quote> — see <xref
264
linkend="network-hooks"/>.
267
<replaceable>NAME</replaceable> can be the string
268
<quote><literal>none</literal></quote>; this will make
269
<command>&COMMANDNAME;</command> only bring up interfaces
270
specified <emphasis>before</emphasis> this string. This
271
is not recommended, and only meant for advanced users.
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>.
309
258
xpointer="priority"/>
314
263
<term><option>--dh-bits=<replaceable
315
264
>BITS</replaceable></option></term>
318
267
Sets the number of bits to use for the prime number in the
319
TLS Diffie-Hellman key exchange. The default value is
320
selected automatically based on the OpenPGP key. Note
321
that if the <option>--dh-params</option> option is used,
322
the values from that file will be used instead.
328
<term><option>--dh-params=<replaceable
329
>FILE</replaceable></option></term>
332
Specifies a PEM-encoded PKCS#3 file to read the parameters
333
needed by the TLS Diffie-Hellman key exchange from. If
334
this option is not given, or if the file for some reason
335
could not be used, the parameters will be generated on
336
startup, which will take some time and processing power.
337
Those using servers running under time, power or processor
338
constraints may want to generate such a file in advance
345
<term><option>--delay=<replaceable
346
>SECONDS</replaceable></option></term>
349
After bringing a network interface up, the program waits
350
for the interface to arrive in a <quote>running</quote>
351
state before proceeding. During this time, the kernel log
352
level will be lowered to reduce clutter on the system
353
console, alleviating any other plugins which might be
354
using the system console. This option sets the upper
355
limit of seconds to wait. The default is 2.5 seconds.
361
<term><option>--retry=<replaceable
362
>SECONDS</replaceable></option></term>
365
All Mandos servers are tried repeatedly until a password
366
is received. This value specifies, in seconds, how long
367
between each successive try <emphasis>for the same
368
server</emphasis>. The default is 10 seconds.
374
<term><option>--network-hook-dir=<replaceable
375
>DIR</replaceable></option></term>
378
Network hook directory. The default directory is
379
<quote><filename class="directory"
380
>/lib/mandos/network-hooks.d</filename></quote>.
268
TLS Diffie-Hellman key exchange. Default is 1024.
461
343
server could be found and the password received from it could be
462
344
successfully decrypted and output on standard output. The
463
345
program will exit with a non-zero exit status only if a critical
464
error occurs. Otherwise, it will forever connect to any
465
discovered <application>Mandos</application> servers, trying to
466
get a decryptable password and print it.
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.
470
352
<refsect1 id="environment">
471
353
<title>ENVIRONMENT</title>
474
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
477
This environment variable will be assumed to contain the
478
directory containing any helper executables. The use and
479
nature of these helper executables, if any, is
480
purposefully not documented.
486
This program does not use any other environment variables, not
487
even the ones provided by <citerefentry><refentrytitle
355
This program does not use any environment variables, not even
356
the ones provided by <citerefentry><refentrytitle
488
357
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
493
<refsect1 id="network-hooks">
494
<title>NETWORK HOOKS</title>
496
If a network interface like a bridge or tunnel is required to
497
find a Mandos server, this requires the interface to be up and
498
running before <command>&COMMANDNAME;</command> starts looking
499
for Mandos servers. This can be accomplished by creating a
500
<quote>network hook</quote> program, and placing it in a special
504
Before the network is used (and again before program exit), any
505
runnable programs found in the network hook directory are run
506
with the argument <quote><literal>start</literal></quote> or
507
<quote><literal>stop</literal></quote>. This should bring up or
508
down, respectively, any network interface which
509
<command>&COMMANDNAME;</command> should use.
511
<refsect2 id="hook-requirements">
512
<title>REQUIREMENTS</title>
514
A network hook must be an executable file, and its name must
515
consist entirely of upper and lower case letters, digits,
516
underscores, periods, and hyphens.
519
A network hook will receive one argument, which can be one of
524
<term><literal>start</literal></term>
527
This should make the network hook create (if necessary)
528
and bring up a network interface.
533
<term><literal>stop</literal></term>
536
This should make the network hook take down a network
537
interface, and delete it if it did not exist previously.
542
<term><literal>files</literal></term>
545
This should make the network hook print, <emphasis>one
546
file per line</emphasis>, all the files needed for it to
547
run. (These files will be copied into the initial RAM
548
filesystem.) Typical use is for a network hook which is
549
a shell script to print its needed binaries.
552
It is not necessary to print any non-executable files
553
already in the network hook directory, these will be
554
copied implicitly if they otherwise satisfy the name
560
<term><literal>modules</literal></term>
563
This should make the network hook print, <emphasis>on
564
separate lines</emphasis>, all the kernel modules needed
565
for it to run. (These modules will be copied into the
566
initial RAM filesystem.) For instance, a tunnel
568
<quote><literal>tun</literal></quote> module.
574
The network hook will be provided with a number of environment
579
<term><envar>MANDOSNETHOOKDIR</envar></term>
582
The network hook directory, specified to
583
<command>&COMMANDNAME;</command> by the
584
<option>--network-hook-dir</option> option. Note: this
585
should <emphasis>always</emphasis> be used by the
586
network hook to refer to itself or any files in the hook
587
directory it may require.
592
<term><envar>DEVICE</envar></term>
595
The network interfaces, as specified to
596
<command>&COMMANDNAME;</command> by the
597
<option>--interface</option> option, combined to one
598
string and separated by commas. If this is set, and
599
does not contain the interface a hook will bring up,
600
there is no reason for a hook to continue.
605
<term><envar>MODE</envar></term>
608
This will be the same as the first argument;
609
i.e. <quote><literal>start</literal></quote>,
610
<quote><literal>stop</literal></quote>,
611
<quote><literal>files</literal></quote>, or
612
<quote><literal>modules</literal></quote>.
617
<term><envar>VERBOSITY</envar></term>
620
This will be the <quote><literal>1</literal></quote> if
621
the <option>--debug</option> option is passed to
622
<command>&COMMANDNAME;</command>, otherwise
623
<quote><literal>0</literal></quote>.
628
<term><envar>DELAY</envar></term>
631
This will be the same as the <option>--delay</option>
632
option passed to <command>&COMMANDNAME;</command>. Is
633
only set if <envar>MODE</envar> is
634
<quote><literal>start</literal></quote> or
635
<quote><literal>stop</literal></quote>.
640
<term><envar>CONNECT</envar></term>
643
This will be the same as the <option>--connect</option>
644
option passed to <command>&COMMANDNAME;</command>. Is
645
only set if <option>--connect</option> is passed and
646
<envar>MODE</envar> is
647
<quote><literal>start</literal></quote> or
648
<quote><literal>stop</literal></quote>.
654
A hook may not read from standard input, and should be
655
restrictive in printing to standard output or standard error
656
unless <varname>VERBOSITY</varname> is
657
<quote><literal>1</literal></quote>.
662
<refsect1 id="files">
663
363
<title>FILES</title>
666
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
668
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
672
OpenPGP public and private key files, in <quote>ASCII
673
Armor</quote> format. These are the default file names,
674
they can be changed with the <option>--pubkey</option> and
675
<option>--seckey</option> options.
681
class="directory">/lib/mandos/network-hooks.d</filename></term>
684
Directory where network hooks are located. Change this
685
with the <option>--network-hook-dir</option> option. See
686
<xref linkend="network-hooks"/>.
693
<!-- <refsect1 id="bugs"> -->
694
<!-- <title>BUGS</title> -->
699
374
<refsect1 id="example">
700
375
<title>EXAMPLE</title>
702
Note that normally, command line options will not be given
703
directly, but via options for the Mandos <citerefentry
704
><refentrytitle>plugin-runner</refentrytitle>
705
<manvolnum>8mandos</manvolnum></citerefentry>.
709
Normal invocation needs no options, if the network interfaces
710
can be automatically determined:
713
<userinput>&COMMANDNAME;</userinput>
718
Search for Mandos servers (and connect to them) using one
722
<!-- do not wrap this line -->
723
<userinput>&COMMANDNAME; --interface eth1</userinput>
728
Run in debug mode, and use a custom key:
732
<!-- do not wrap this line -->
733
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
739
Run in debug mode, with a custom key, and do not use Zeroconf
740
to locate a server; connect directly to the IPv6 link-local
741
address <quote><systemitem class="ipaddress"
742
>fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
743
using interface eth2:
747
<!-- do not wrap this line -->
748
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
754
380
<refsect1 id="security">
755
381
<title>SECURITY</title>
757
This program is set-uid to root, but will switch back to the
758
original (and presumably non-privileged) user and group after
759
bringing up the network interface.
762
To use this program for its intended purpose (see <xref
763
linkend="purpose"/>), the password for the root file system will
764
have to be given out to be stored in a server computer, after
765
having been encrypted using an OpenPGP key. This encrypted data
766
which will be stored in a server can only be decrypted by the
767
OpenPGP key, and the data will only be given out to those
768
clients who can prove they actually have that key. This key,
769
however, is stored unencrypted on the client side in its initial
770
<acronym>RAM</acronym> disk image file system. This is normally
771
readable by all, but this is normally fixed during installation
772
of this program; file permissions are set so that no-one is able
776
The only remaining weak point is that someone with physical
777
access to the client hard drive might turn off the client
778
computer, read the OpenPGP keys directly from the hard drive,
779
and communicate with the server. To safeguard against this, the
780
server is supposed to notice the client disappearing and stop
781
giving out the encrypted data. Therefore, it is important to
782
set the timeout and checker interval values tightly on the
783
server. See <citerefentry><refentrytitle
784
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
787
It will also help if the checker program on the server is
788
configured to request something from the client which can not be
789
spoofed by someone else on the network, like SSH server key
790
fingerprints, and unlike unencrypted <acronym>ICMP</acronym>
791
echo (<quote>ping</quote>) replies.
794
<emphasis>Note</emphasis>: This makes it completely insecure to
795
have <application >Mandos</application> clients which dual-boot
796
to another operating system which is <emphasis>not</emphasis>
797
trusted to keep the initial <acronym>RAM</acronym> disk image
802
386
<refsect1 id="see_also">
803
387
<title>SEE ALSO</title>
805
<citerefentry><refentrytitle>intro</refentrytitle>
806
<manvolnum>8mandos</manvolnum></citerefentry>,
807
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
808
<manvolnum>8</manvolnum></citerefentry>,
809
<citerefentry><refentrytitle>crypttab</refentrytitle>
810
<manvolnum>5</manvolnum></citerefentry>,
811
389
<citerefentry><refentrytitle>mandos</refentrytitle>
812
390
<manvolnum>8</manvolnum></citerefentry>,
813
391
<citerefentry><refentrytitle>password-prompt</refentrytitle>
815
393
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
816
394
<manvolnum>8mandos</manvolnum></citerefentry>
821
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
825
Zeroconf is the network protocol standard used for finding
826
Mandos servers on the local network.
832
<ulink url="http://www.avahi.org/">Avahi</ulink>
836
Avahi is the library this program calls to find Zeroconf
843
<ulink url="http://www.gnu.org/software/gnutls/"
848
GnuTLS is the library this client uses to implement TLS for
849
communicating securely with the server, and at the same time
850
send the public OpenPGP key to the server.
856
<ulink url="http://www.gnupg.org/related_software/gpgme/"
861
GPGME is the library used to decrypt the OpenPGP data sent
868
RFC 4291: <citetitle>IP Version 6 Addressing
869
Architecture</citetitle>
874
<term>Section 2.2: <citetitle>Text Representation of
875
Addresses</citetitle></term>
876
<listitem><para/></listitem>
879
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
880
Address</citetitle></term>
881
<listitem><para/></listitem>
884
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
885
Addresses</citetitle></term>
888
This client uses IPv6 link-local addresses, which are
889
immediately usable since a link-local addresses is
890
automatically assigned to a network interface when it
900
RFC 4346: <citetitle>The Transport Layer Security (TLS)
901
Protocol Version 1.1</citetitle>
905
TLS 1.1 is the protocol implemented by GnuTLS.
911
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
915
The data received from the server is binary encrypted
922
RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
927
This is implemented by GnuTLS and used by this program so
928
that OpenPGP keys can be used.
398
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
402
<ulink url="http://www.avahi.org/">Avahi</ulink>
407
url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
412
url="http://www.gnupg.org/related_software/gpgme/"
417
<citation>RFC 4880: <citetitle>OpenPGP Message
418
Format</citetitle></citation>
422
<citation>RFC 5081: <citetitle>Using OpenPGP Keys for
423
Transport Layer Security</citetitle></citation>
427
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
428
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
429
Unicast Addresses</citation>
936
435
<!-- Local Variables: -->
937
436
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
938
437
<!-- time-stamp-end: "[\"']>" -->