/mandos/release

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

« back to all changes in this revision

Viewing changes to mandos.xml

Merge from release branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.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">
5
 
<!ENTITY TIMESTAMP "2019-07-24">
 
5
<!ENTITY TIMESTAMP "2012-01-01">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
36
36
      <year>2010</year>
37
37
      <year>2011</year>
38
38
      <year>2012</year>
39
 
      <year>2013</year>
40
 
      <year>2014</year>
41
 
      <year>2015</year>
42
 
      <year>2016</year>
43
 
      <year>2017</year>
44
 
      <year>2018</year>
45
 
      <year>2019</year>
46
39
      <holder>Teddy Hogeborn</holder>
47
40
      <holder>Björn Påhlsson</holder>
48
41
    </copyright>
107
100
      <sbr/>
108
101
      <arg><option>--statedir
109
102
      <replaceable>DIRECTORY</replaceable></option></arg>
110
 
      <sbr/>
111
 
      <arg><option>--socket
112
 
      <replaceable>FD</replaceable></option></arg>
113
 
      <sbr/>
114
 
      <arg><option>--foreground</option></arg>
115
 
      <sbr/>
116
 
      <arg><option>--no-zeroconf</option></arg>
117
103
    </cmdsynopsis>
118
104
    <cmdsynopsis>
119
105
      <command>&COMMANDNAME;</command>
313
299
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
314
300
        </listitem>
315
301
      </varlistentry>
316
 
      
317
 
      <varlistentry>
318
 
        <term><option>--socket
319
 
        <replaceable>FD</replaceable></option></term>
320
 
        <listitem>
321
 
          <xi:include href="mandos-options.xml" xpointer="socket"/>
322
 
        </listitem>
323
 
      </varlistentry>
324
 
      
325
 
      <varlistentry>
326
 
        <term><option>--foreground</option></term>
327
 
        <listitem>
328
 
          <xi:include href="mandos-options.xml"
329
 
                      xpointer="foreground"/>
330
 
        </listitem>
331
 
      </varlistentry>
332
 
      
333
 
      <varlistentry>
334
 
        <term><option>--no-zeroconf</option></term>
335
 
        <listitem>
336
 
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
337
 
        </listitem>
338
 
      </varlistentry>
339
 
      
340
302
    </variablelist>
341
303
  </refsect1>
342
304
  
362
324
      start a TLS protocol handshake with a slight quirk: the Mandos
363
325
      server program acts as a TLS <quote>client</quote> while the
364
326
      connecting Mandos client acts as a TLS <quote>server</quote>.
365
 
      The Mandos client must supply a TLS public key, and the key ID
366
 
      of this public key is used by the Mandos server to look up (in a
367
 
      list read from <filename>clients.conf</filename> at start time)
368
 
      which binary blob to give the client.  No other authentication
369
 
      or authorization is done by the server.
 
327
      The Mandos client must supply an OpenPGP certificate, and the
 
328
      fingerprint of this certificate is used by the Mandos server to
 
329
      look up (in a list read from <filename>clients.conf</filename>
 
330
      at start time) which binary blob to give the client.  No other
 
331
      authentication or authorization is done by the server.
370
332
    </para>
371
333
    <table>
372
334
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
392
354
        </emphasis></entry>
393
355
      </row>
394
356
      <row>
395
 
        <entry>Public key (part of TLS handshake)</entry>
 
357
        <entry>OpenPGP public key (part of TLS handshake)</entry>
396
358
        <entry>-><!-- &rarr; --></entry>
397
359
      </row>
398
360
      <row>
419
381
      extended timeout, checker program, and interval between checks
420
382
      can be configured both globally and per client; see
421
383
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
422
 
      <manvolnum>5</manvolnum></citerefentry>.
 
384
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
 
385
      receiving its password will also be treated as a successful
 
386
      checker run.
423
387
    </para>
424
388
  </refsect1>
425
389
  
532
496
        </listitem>
533
497
      </varlistentry>
534
498
      <varlistentry>
535
 
        <term><filename>/run/mandos.pid</filename></term>
 
499
        <term><filename>/var/run/mandos.pid</filename></term>
536
500
        <listitem>
537
501
          <para>
538
502
            The file containing the process id of the
539
503
            <command>&COMMANDNAME;</command> process started last.
540
 
            <emphasis >Note:</emphasis> If the <filename
541
 
            class="directory">/run</filename> directory does not
542
 
            exist, <filename>/var/run/mandos.pid</filename> will be
543
 
            used instead.
544
504
          </para>
545
505
        </listitem>
546
506
      </varlistentry>
547
507
      <varlistentry>
 
508
        <term><filename class="devicefile">/dev/log</filename></term>
 
509
      </varlistentry>
 
510
      <varlistentry>
548
511
        <term><filename
549
512
        class="directory">/var/lib/mandos</filename></term>
550
513
        <listitem>
556
519
        </listitem>
557
520
      </varlistentry>
558
521
      <varlistentry>
559
 
        <term><filename class="devicefile">/dev/log</filename></term>
 
522
        <term><filename>/dev/log</filename></term>
560
523
        <listitem>
561
524
          <para>
562
525
            The Unix domain socket to where local syslog messages are
587
550
    <para>
588
551
      There is no fine-grained control over logging and debug output.
589
552
    </para>
590
 
    <xi:include href="bugs.xml"/>
 
553
    <para>
 
554
      Debug mode is conflated with running in the foreground.
 
555
    </para>
 
556
    <para>
 
557
      This server does not check the expire time of clients’ OpenPGP
 
558
      keys.
 
559
    </para>
591
560
  </refsect1>
592
561
  
593
562
  <refsect1 id="example">
643
612
      <title>CLIENTS</title>
644
613
      <para>
645
614
        The server only gives out its stored data to clients which
646
 
        does have the correct key ID of the stored key ID.  This is
647
 
        guaranteed by the fact that the client sends its public key in
648
 
        the TLS handshake; this ensures it to be genuine.  The server
649
 
        computes the key ID of the key itself and looks up the key ID
650
 
        in its list of clients. The <filename>clients.conf</filename>
651
 
        file (see
 
615
        does have the OpenPGP key of the stored fingerprint.  This is
 
616
        guaranteed by the fact that the client sends its OpenPGP
 
617
        public key in the TLS handshake; this ensures it to be
 
618
        genuine.  The server computes the fingerprint of the key
 
619
        itself and looks up the fingerprint in its list of
 
620
        clients. The <filename>clients.conf</filename> file (see
652
621
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
653
622
        <manvolnum>5</manvolnum></citerefentry>)
654
623
        <emphasis>must</emphasis> be made non-readable by anyone
695
664
      </varlistentry>
696
665
      <varlistentry>
697
666
        <term>
698
 
          <ulink url="https://www.avahi.org/">Avahi</ulink>
 
667
          <ulink url="http://www.avahi.org/">Avahi</ulink>
699
668
        </term>
700
669
      <listitem>
701
670
        <para>
706
675
      </varlistentry>
707
676
      <varlistentry>
708
677
        <term>
709
 
          <ulink url="https://gnutls.org/">GnuTLS</ulink>
 
678
          <ulink url="http://www.gnu.org/software/gnutls/"
 
679
          >GnuTLS</ulink>
710
680
        </term>
711
681
      <listitem>
712
682
        <para>
713
683
          GnuTLS is the library this server uses to implement TLS for
714
684
          communicating securely with the client, and at the same time
715
 
          confidently get the client’s public key.
 
685
          confidently get the client’s public OpenPGP key.
716
686
        </para>
717
687
      </listitem>
718
688
      </varlistentry>
750
720
      </varlistentry>
751
721
      <varlistentry>
752
722
        <term>
753
 
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
754
 
          Protocol Version 1.2</citetitle>
 
723
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
 
724
          Protocol Version 1.1</citetitle>
755
725
        </term>
756
726
      <listitem>
757
727
        <para>
758
 
          TLS 1.2 is the protocol implemented by GnuTLS.
 
728
          TLS 1.1 is the protocol implemented by GnuTLS.
759
729
        </para>
760
730
      </listitem>
761
731
      </varlistentry>
771
741
      </varlistentry>
772
742
      <varlistentry>
773
743
        <term>
774
 
          RFC 7250: <citetitle>Using Raw Public Keys in Transport
775
 
          Layer Security (TLS) and Datagram Transport Layer Security
776
 
          (DTLS)</citetitle>
777
 
        </term>
778
 
      <listitem>
779
 
        <para>
780
 
          This is implemented by GnuTLS version 3.6.6 and is, if
781
 
          present, used by this server so that raw public keys can be
782
 
          used.
783
 
        </para>
784
 
      </listitem>
785
 
      </varlistentry>
786
 
      <varlistentry>
787
 
        <term>
788
 
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
789
 
          Security (TLS) Authentication</citetitle>
790
 
        </term>
791
 
      <listitem>
792
 
        <para>
793
 
          This is implemented by GnuTLS before version 3.6.0 and is,
794
 
          if present, used by this server so that OpenPGP keys can be
795
 
          used.
 
744
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
 
745
          Security</citetitle>
 
746
        </term>
 
747
      <listitem>
 
748
        <para>
 
749
          This is implemented by GnuTLS and used by this server so
 
750
          that OpenPGP keys can be used.
796
751
        </para>
797
752
      </listitem>
798
753
      </varlistentry>