/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to plugins.d/mandos-client.xml

  • Committer: Teddy Hogeborn
  • Date: 2015-07-06 20:29:34 UTC
  • mfrom: (738.1.6 route-external)
  • Revision ID: teddy@recompile.se-20150706202934-09j06jm2fiw1bn80
Merge change to add local route when network is "unreachable".

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/mandos-client.xml
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY COMMANDNAME "mandos-client">
5
 
<!ENTITY TIMESTAMP "2019-02-09">
 
5
<!ENTITY TIMESTAMP "2015-07-06">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
36
 
      <year>2010</year>
37
 
      <year>2011</year>
38
36
      <year>2012</year>
39
37
      <year>2013</year>
40
38
      <year>2014</year>
41
39
      <year>2015</year>
42
 
      <year>2016</year>
43
 
      <year>2017</year>
44
 
      <year>2018</year>
45
40
      <holder>Teddy Hogeborn</holder>
46
41
      <holder>Björn Påhlsson</holder>
47
42
    </copyright>
95
90
        <replaceable>FILE</replaceable></option></arg>
96
91
      </group>
97
92
      <sbr/>
98
 
      <group>
99
 
        <arg choice="plain"><option>--tls-privkey
100
 
        <replaceable>FILE</replaceable></option></arg>
101
 
        <arg choice="plain"><option>-t
102
 
        <replaceable>FILE</replaceable></option></arg>
103
 
      </group>
104
 
      <sbr/>
105
 
      <group>
106
 
        <arg choice="plain"><option>--tls-pubkey
107
 
        <replaceable>FILE</replaceable></option></arg>
108
 
        <arg choice="plain"><option>-T
109
 
        <replaceable>FILE</replaceable></option></arg>
110
 
      </group>
111
 
      <sbr/>
112
93
      <arg>
113
94
        <option>--priority <replaceable>STRING</replaceable></option>
114
95
      </arg>
118
99
      </arg>
119
100
      <sbr/>
120
101
      <arg>
121
 
        <option>--dh-params <replaceable>FILE</replaceable></option>
122
 
      </arg>
123
 
      <sbr/>
124
 
      <arg>
125
102
        <option>--delay <replaceable>SECONDS</replaceable></option>
126
103
      </arg>
127
104
      <sbr/>
168
145
      brings up network interfaces, uses the interfaces’ IPv6
169
146
      link-local addresses to get network connectivity, uses Zeroconf
170
147
      to find servers on the local network, and communicates with
171
 
      servers using TLS with a raw public key to ensure authenticity
172
 
      and confidentiality.  This client program keeps running, trying
173
 
      all servers on the network, until it receives a satisfactory
174
 
      reply or a TERM signal.  After all servers have been tried, all
 
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
175
152
      servers are periodically retried.  If no servers are found it
176
153
      will wait indefinitely for new servers to appear.
177
154
    </para>
321
298
      </varlistentry>
322
299
      
323
300
      <varlistentry>
324
 
        <term><option>--tls-pubkey=<replaceable
325
 
        >FILE</replaceable></option></term>
326
 
        <term><option>-T
327
 
        <replaceable>FILE</replaceable></option></term>
328
 
        <listitem>
329
 
          <para>
330
 
            TLS raw public key file name.  The default name is
331
 
            <quote><filename>/conf/conf.d/mandos/tls-pubkey.pem</filename
332
 
            ></quote>.
333
 
          </para>
334
 
        </listitem>
335
 
      </varlistentry>
336
 
 
337
 
      <varlistentry>
338
 
        <term><option>--tls-privkey=<replaceable
339
 
        >FILE</replaceable></option></term>
340
 
        <term><option>-t
341
 
        <replaceable>FILE</replaceable></option></term>
342
 
        <listitem>
343
 
          <para>
344
 
            TLS secret key file name.  The default name is
345
 
            <quote><filename>/conf/conf.d/mandos/tls-privkey.pem</filename
346
 
            ></quote>.
347
 
          </para>
348
 
        </listitem>
349
 
      </varlistentry>
350
 
 
351
 
      <varlistentry>
352
301
        <term><option>--priority=<replaceable
353
302
        >STRING</replaceable></option></term>
354
303
        <listitem>
364
313
          <para>
365
314
            Sets the number of bits to use for the prime number in the
366
315
            TLS Diffie-Hellman key exchange.  The default value is
367
 
            selected automatically based on the GnuTLS security
368
 
            profile set in its priority string.  Note that if the
369
 
            <option>--dh-params</option> option is used, the values
370
 
            from that file will be used instead.
371
 
          </para>
372
 
        </listitem>
373
 
      </varlistentry>
374
 
      
375
 
      <varlistentry>
376
 
        <term><option>--dh-params=<replaceable
377
 
        >FILE</replaceable></option></term>
378
 
        <listitem>
379
 
          <para>
380
 
            Specifies a PEM-encoded PKCS#3 file to read the parameters
381
 
            needed by the TLS Diffie-Hellman key exchange from.  If
382
 
            this option is not given, or if the file for some reason
383
 
            could not be used, the parameters will be generated on
384
 
            startup, which will take some time and processing power.
385
 
            Those using servers running under time, power or processor
386
 
            constraints may want to generate such a file in advance
387
 
            and use this option.
 
316
            selected automatically based on the OpenPGP key.
388
317
          </para>
389
318
        </listitem>
390
319
      </varlistentry>
725
654
        </listitem>
726
655
      </varlistentry>
727
656
      <varlistentry>
728
 
        <term><filename>/conf/conf.d/mandos/tls-pubkey.pem</filename
729
 
        ></term>
730
 
        <term><filename>/conf/conf.d/mandos/tls-privkey.pem</filename
731
 
        ></term>
732
 
        <listitem>
733
 
          <para>
734
 
            Public and private raw key files, in <quote>PEM</quote>
735
 
            format.  These are the default file names, they can be
736
 
            changed with the <option>--tls-pubkey</option> and
737
 
            <option>--tls-privkey</option> options.
738
 
          </para>
739
 
        </listitem>
740
 
      </varlistentry>
741
 
      <varlistentry>
742
657
        <term><filename
743
658
        class="directory">/lib/mandos/network-hooks.d</filename></term>
744
659
        <listitem>
752
667
    </variablelist>
753
668
  </refsect1>
754
669
  
755
 
  <refsect1 id="bugs">
756
 
    <title>BUGS</title>
757
 
    <xi:include href="../bugs.xml"/>
758
 
  </refsect1>
 
670
<!--   <refsect1 id="bugs"> -->
 
671
<!--     <title>BUGS</title> -->
 
672
<!--     <para> -->
 
673
<!--     </para> -->
 
674
<!--   </refsect1> -->
759
675
  
760
676
  <refsect1 id="example">
761
677
    <title>EXAMPLE</title>
786
702
    </informalexample>
787
703
    <informalexample>
788
704
      <para>
789
 
        Run in debug mode, and use custom keys:
 
705
        Run in debug mode, and use a custom key:
790
706
      </para>
791
707
      <para>
792
708
 
793
709
<!-- do not wrap this line -->
794
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --tls-pubkey keydir/tls-pubkey.pem --tls-privkey keydir/tls-privkey.pem</userinput>
 
710
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
795
711
 
796
712
      </para>
797
713
    </informalexample>
798
714
    <informalexample>
799
715
      <para>
800
 
        Run in debug mode, with custom keys, and do not use Zeroconf
 
716
        Run in debug mode, with a custom key, and do not use Zeroconf
801
717
        to locate a server; connect directly to the IPv6 link-local
802
718
        address <quote><systemitem class="ipaddress"
803
719
        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
806
722
      <para>
807
723
 
808
724
<!-- do not wrap this line -->
809
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --tls-pubkey keydir/tls-pubkey.pem --tls-privkey keydir/tls-privkey.pem --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
 
725
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
810
726
 
811
727
      </para>
812
728
    </informalexample>
836
752
    <para>
837
753
      The only remaining weak point is that someone with physical
838
754
      access to the client hard drive might turn off the client
839
 
      computer, read the OpenPGP and TLS keys directly from the hard
840
 
      drive, and communicate with the server.  To safeguard against
841
 
      this, the server is supposed to notice the client disappearing
842
 
      and stop giving out the encrypted data.  Therefore, it is
843
 
      important to set the timeout and checker interval values tightly
844
 
      on the server.  See <citerefentry><refentrytitle
 
755
      computer, read the OpenPGP keys directly from the hard drive,
 
756
      and communicate with the server.  To safeguard against this, the
 
757
      server is supposed to notice the client disappearing and stop
 
758
      giving out the encrypted data.  Therefore, it is important to
 
759
      set the timeout and checker interval values tightly on the
 
760
      server.  See <citerefentry><refentrytitle
845
761
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
846
762
    </para>
847
763
    <para>
901
817
      </varlistentry>
902
818
      <varlistentry>
903
819
        <term>
904
 
          <ulink url="https://www.gnutls.org/">GnuTLS</ulink>
 
820
          <ulink url="http://www.gnu.org/software/gnutls/"
 
821
          >GnuTLS</ulink>
905
822
        </term>
906
823
      <listitem>
907
824
        <para>
908
825
          GnuTLS is the library this client uses to implement TLS for
909
826
          communicating securely with the server, and at the same time
910
 
          send the public key to the server.
 
827
          send the public OpenPGP key to the server.
911
828
        </para>
912
829
      </listitem>
913
830
      </varlistentry>
914
831
      <varlistentry>
915
832
        <term>
916
 
          <ulink url="https://www.gnupg.org/related_software/gpgme/"
 
833
          <ulink url="http://www.gnupg.org/related_software/gpgme/"
917
834
                 >GPGME</ulink>
918
835
        </term>
919
836
        <listitem>
957
874
      </varlistentry>
958
875
      <varlistentry>
959
876
        <term>
960
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
961
 
          Protocol Version 1.2</citetitle>
 
877
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
878
          Protocol Version 1.1</citetitle>
962
879
        </term>
963
880
      <listitem>
964
881
        <para>
965
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
882
          TLS 1.1 is the protocol implemented by GnuTLS.
966
883
        </para>
967
884
      </listitem>
968
885
      </varlistentry>
979
896
      </varlistentry>
980
897
      <varlistentry>
981
898
        <term>
982
 
          RFC 7250: <citetitle>Using Raw Public Keys in Transport
983
 
          Layer Security (TLS) and Datagram Transport Layer Security
984
 
          (DTLS)</citetitle>
985
 
        </term>
986
 
      <listitem>
987
 
        <para>
988
 
          This is implemented by GnuTLS in version 3.6.6 and is, if
989
 
          present, used by this program so that raw public keys can be
990
 
          used.
991
 
        </para>
992
 
      </listitem>
993
 
      </varlistentry>
994
 
      <varlistentry>
995
 
        <term>
996
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
 
899
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
997
900
          Security</citetitle>
998
901
        </term>
999
902
      <listitem>
1000
903
        <para>
1001
 
          This is implemented by GnuTLS before version 3.6.0 and is,
1002
 
          if present, used by this program so that OpenPGP keys can be
1003
 
          used.
 
904
          This is implemented by GnuTLS and used by this program so
 
905
          that OpenPGP keys can be used.
1004
906
        </para>
1005
907
      </listitem>
1006
908
      </varlistentry>