/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

  • Committer: Teddy Hogeborn
  • Date: 2025-06-27 19:49:05 UTC
  • mto: This revision was merged to the branch mainline in revision 414.
  • Revision ID: teddy@recompile.se-20250627194905-ijufqn8ytzdgkf34
Update copyright year

* dracut-module/ask-password-mandos.service: Update copyright year to
  2024.
* dracut-module/password-agent.c: Update copyright year to 2023.
* initramfs-unpack: Update copyright year to 2024.
* mandos: - '' -
* mandos-clients.conf.xml: Update copyright year to 2023.
* mandos-ctl: Update copyright year to 2024.
* mandos-keygen: - '' -
* mandos-monitor: - '' -
* mandos.conf.xml: - '' -
* mandos.xml: Update copyright year to 2022.
* plugin-runner.xml: Update copyright year to 2024.
* plugins.d/mandos-client.xml: - '' -
* plugins.d/plymouth.c: - '' -

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 "2009-02-15">
 
5
<!ENTITY TIMESTAMP "2025-06-27">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
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
      <year>2020</year>
 
47
      <year>2021</year>
 
48
      <year>2022</year>
36
49
      <holder>Teddy Hogeborn</holder>
37
50
      <holder>Björn Påhlsson</holder>
38
51
    </copyright>
86
99
      <sbr/>
87
100
      <arg><option>--debug</option></arg>
88
101
      <sbr/>
 
102
      <arg><option>--debuglevel
 
103
      <replaceable>LEVEL</replaceable></option></arg>
 
104
      <sbr/>
89
105
      <arg><option>--no-dbus</option></arg>
90
106
      <sbr/>
91
107
      <arg><option>--no-ipv6</option></arg>
 
108
      <sbr/>
 
109
      <arg><option>--no-restore</option></arg>
 
110
      <sbr/>
 
111
      <arg><option>--statedir
 
112
      <replaceable>DIRECTORY</replaceable></option></arg>
 
113
      <sbr/>
 
114
      <arg><option>--socket
 
115
      <replaceable>FD</replaceable></option></arg>
 
116
      <sbr/>
 
117
      <arg><option>--foreground</option></arg>
 
118
      <sbr/>
 
119
      <arg><option>--no-zeroconf</option></arg>
92
120
    </cmdsynopsis>
93
121
    <cmdsynopsis>
94
122
      <command>&COMMANDNAME;</command>
111
139
    <title>DESCRIPTION</title>
112
140
    <para>
113
141
      <command>&COMMANDNAME;</command> is a server daemon which
114
 
      handles incoming request for passwords for a pre-defined list of
115
 
      client host computers.  The Mandos server uses Zeroconf to
116
 
      announce itself on the local network, and uses TLS to
117
 
      communicate securely with and to authenticate the clients.  The
118
 
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
119
 
      link-local addresses, since the clients will probably not have
120
 
      any other addresses configured (see <xref linkend="overview"/>).
121
 
      Any authenticated client is then given the stored pre-encrypted
122
 
      password for that specific client.
 
142
      handles incoming requests for passwords for a pre-defined list
 
143
      of client host computers. For an introduction, see
 
144
      <citerefentry><refentrytitle>intro</refentrytitle>
 
145
      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
 
146
      uses Zeroconf to announce itself on the local network, and uses
 
147
      TLS to communicate securely with and to authenticate the
 
148
      clients.  The Mandos server uses IPv6 to allow Mandos clients to
 
149
      use IPv6 link-local addresses, since the clients will probably
 
150
      not have any other addresses configured (see <xref
 
151
      linkend="overview"/>).  Any authenticated client is then given
 
152
      the stored pre-encrypted password for that specific client.
123
153
    </para>
124
154
  </refsect1>
125
155
  
194
224
      </varlistentry>
195
225
      
196
226
      <varlistentry>
 
227
        <term><option>--debuglevel
 
228
        <replaceable>LEVEL</replaceable></option></term>
 
229
        <listitem>
 
230
          <para>
 
231
            Set the debugging log level.
 
232
            <replaceable>LEVEL</replaceable> is a string, one of
 
233
            <quote><literal>CRITICAL</literal></quote>,
 
234
            <quote><literal>ERROR</literal></quote>,
 
235
            <quote><literal>WARNING</literal></quote>,
 
236
            <quote><literal>INFO</literal></quote>, or
 
237
            <quote><literal>DEBUG</literal></quote>, in order of
 
238
            increasing verbosity.  The default level is
 
239
            <quote><literal>WARNING</literal></quote>.
 
240
          </para>
 
241
        </listitem>
 
242
      </varlistentry>
 
243
      
 
244
      <varlistentry>
197
245
        <term><option>--priority <replaceable>
198
246
        PRIORITY</replaceable></option></term>
199
247
        <listitem>
250
298
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
251
299
        </listitem>
252
300
      </varlistentry>
 
301
      
 
302
      <varlistentry>
 
303
        <term><option>--no-restore</option></term>
 
304
        <listitem>
 
305
          <xi:include href="mandos-options.xml" xpointer="restore"/>
 
306
          <para>
 
307
            See also <xref linkend="persistent_state"/>.
 
308
          </para>
 
309
        </listitem>
 
310
      </varlistentry>
 
311
      
 
312
      <varlistentry>
 
313
        <term><option>--statedir
 
314
        <replaceable>DIRECTORY</replaceable></option></term>
 
315
        <listitem>
 
316
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
 
317
        </listitem>
 
318
      </varlistentry>
 
319
      
 
320
      <varlistentry>
 
321
        <term><option>--socket
 
322
        <replaceable>FD</replaceable></option></term>
 
323
        <listitem>
 
324
          <xi:include href="mandos-options.xml" xpointer="socket"/>
 
325
        </listitem>
 
326
      </varlistentry>
 
327
      
 
328
      <varlistentry>
 
329
        <term><option>--foreground</option></term>
 
330
        <listitem>
 
331
          <xi:include href="mandos-options.xml"
 
332
                      xpointer="foreground"/>
 
333
        </listitem>
 
334
      </varlistentry>
 
335
      
 
336
      <varlistentry>
 
337
        <term><option>--no-zeroconf</option></term>
 
338
        <listitem>
 
339
          <xi:include href="mandos-options.xml" xpointer="zeroconf"/>
 
340
        </listitem>
 
341
      </varlistentry>
 
342
      
253
343
    </variablelist>
254
344
  </refsect1>
255
345
  
275
365
      start a TLS protocol handshake with a slight quirk: the Mandos
276
366
      server program acts as a TLS <quote>client</quote> while the
277
367
      connecting Mandos client acts as a TLS <quote>server</quote>.
278
 
      The Mandos client must supply an OpenPGP certificate, and the
279
 
      fingerprint of this certificate is used by the Mandos server to
280
 
      look up (in a list read from <filename>clients.conf</filename>
281
 
      at start time) which binary blob to give the client.  No other
282
 
      authentication or authorization is done by the server.
 
368
      The Mandos client must supply a TLS public key, and the key ID
 
369
      of this public key is used by the Mandos server to look up (in a
 
370
      list read from <filename>clients.conf</filename> at start time)
 
371
      which binary blob to give the client.  No other authentication
 
372
      or authorization is done by the server.
283
373
    </para>
284
374
    <table>
285
375
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
305
395
        </emphasis></entry>
306
396
      </row>
307
397
      <row>
308
 
        <entry>OpenPGP public key (part of TLS handshake)</entry>
 
398
        <entry>Public key (part of TLS handshake)</entry>
309
399
        <entry>-><!-- &rarr; --></entry>
310
400
      </row>
311
401
      <row>
327
417
      The server will, by default, continually check that the clients
328
418
      are still up.  If a client has not been confirmed as being up
329
419
      for some time, the client is assumed to be compromised and is no
330
 
      longer eligible to receive the encrypted password.  The timeout,
331
 
      checker program, and interval between checks can be configured
332
 
      both globally and per client; see <citerefentry>
 
420
      longer eligible to receive the encrypted password.  (Manual
 
421
      intervention is required to re-enable a client.)  The timeout,
 
422
      extended timeout, checker program, and interval between checks
 
423
      can be configured both globally and per client; see
 
424
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
425
      <manvolnum>5</manvolnum></citerefentry>.
 
426
    </para>
 
427
  </refsect1>
 
428
  
 
429
  <refsect1 id="approval">
 
430
    <title>APPROVAL</title>
 
431
    <para>
 
432
      The server can be configured to require manual approval for a
 
433
      client before it is sent its secret.  The delay to wait for such
 
434
      approval and the default action (approve or deny) can be
 
435
      configured both globally and per client; see <citerefentry>
333
436
      <refentrytitle>mandos-clients.conf</refentrytitle>
334
 
      <manvolnum>5</manvolnum></citerefentry>.
335
 
    </para>
 
437
      <manvolnum>5</manvolnum></citerefentry>.  By default all clients
 
438
      will be approved immediately without delay.
 
439
    </para>
 
440
    <para>
 
441
      This can be used to deny a client its secret if not manually
 
442
      approved within a specified time.  It can also be used to make
 
443
      the server delay before giving a client its secret, allowing
 
444
      optional manual denying of this specific client.
 
445
    </para>
 
446
    
336
447
  </refsect1>
337
448
  
338
449
  <refsect1 id="logging">
339
450
    <title>LOGGING</title>
340
451
    <para>
341
452
      The server will send log message with various severity levels to
342
 
      <filename>/dev/log</filename>.  With the
 
453
      <filename class="devicefile">/dev/log</filename>.  With the
343
454
      <option>--debug</option> option, it will log even more messages,
344
455
      and also show them on the console.
345
456
    </para>
346
457
  </refsect1>
347
458
  
 
459
  <refsect1 id="persistent_state">
 
460
    <title>PERSISTENT STATE</title>
 
461
    <para>
 
462
      Client settings, initially read from
 
463
      <filename>clients.conf</filename>, are persistent across
 
464
      restarts, and run-time changes will override settings in
 
465
      <filename>clients.conf</filename>.  However, if a setting is
 
466
      <emphasis>changed</emphasis> (or a client added, or removed) in
 
467
      <filename>clients.conf</filename>, this will take precedence.
 
468
    </para>
 
469
  </refsect1>
 
470
  
348
471
  <refsect1 id="dbus_interface">
349
472
    <title>D-BUS INTERFACE</title>
350
473
    <para>
351
474
      The server will by default provide a D-Bus system bus interface.
352
475
      This interface will only be accessible by the root user or a
353
 
      Mandos-specific user, if such a user exists.
354
 
      <!-- XXX -->
 
476
      Mandos-specific user, if such a user exists.  For documentation
 
477
      of the D-Bus API, see the file <filename>DBUS-API</filename>.
355
478
    </para>
356
479
  </refsect1>
357
480
  
412
535
        </listitem>
413
536
      </varlistentry>
414
537
      <varlistentry>
415
 
        <term><filename>/var/run/mandos.pid</filename></term>
416
 
        <listitem>
417
 
          <para>
418
 
            The file containing the process id of
419
 
            <command>&COMMANDNAME;</command>.
420
 
          </para>
421
 
        </listitem>
422
 
      </varlistentry>
423
 
      <varlistentry>
424
 
        <term><filename>/dev/log</filename></term>
 
538
        <term><filename>/run/mandos.pid</filename></term>
 
539
        <listitem>
 
540
          <para>
 
541
            The file containing the process id of the
 
542
            <command>&COMMANDNAME;</command> process started last.
 
543
            <emphasis >Note:</emphasis> If the <filename
 
544
            class="directory">/run</filename> directory does not
 
545
            exist, <filename>/var/run/mandos.pid</filename> will be
 
546
            used instead.
 
547
          </para>
 
548
        </listitem>
 
549
      </varlistentry>
 
550
      <varlistentry>
 
551
        <term><filename
 
552
        class="directory">/var/lib/mandos</filename></term>
 
553
        <listitem>
 
554
          <para>
 
555
            Directory where persistent state will be saved.  Change
 
556
            this with the <option>--statedir</option> option.  See
 
557
            also the <option>--no-restore</option> option.
 
558
          </para>
 
559
        </listitem>
 
560
      </varlistentry>
 
561
      <varlistentry>
 
562
        <term><filename class="devicefile">/dev/log</filename></term>
425
563
        <listitem>
426
564
          <para>
427
565
            The Unix domain socket to where local syslog messages are
450
588
      backtrace.  This could be considered a feature.
451
589
    </para>
452
590
    <para>
453
 
      Currently, if a client is declared <quote>invalid</quote> due to
454
 
      having timed out, the server does not record this fact onto
455
 
      permanent storage.  This has some security implications, see
456
 
      <xref linkend="clients"/>.
457
 
    </para>
458
 
    <para>
459
 
      There is currently no way of querying the server of the current
460
 
      status of clients, other than analyzing its <systemitem
461
 
      class="service">syslog</systemitem> output.
462
 
    </para>
463
 
    <para>
464
591
      There is no fine-grained control over logging and debug output.
465
592
    </para>
466
 
    <para>
467
 
      Debug mode is conflated with running in the foreground.
468
 
    </para>
469
 
    <para>
470
 
      The console log messages do not show a time stamp.
471
 
    </para>
472
 
    <para>
473
 
      This server does not check the expire time of clients’ OpenPGP
474
 
      keys.
475
 
    </para>
 
593
    <xi:include href="bugs.xml"/>
476
594
  </refsect1>
477
595
  
478
596
  <refsect1 id="example">
488
606
    <informalexample>
489
607
      <para>
490
608
        Run the server in debug mode, read configuration files from
491
 
        the <filename>~/mandos</filename> directory, and use the
492
 
        Zeroconf service name <quote>Test</quote> to not collide with
493
 
        any other official Mandos server on this host:
 
609
        the <filename class="directory">~/mandos</filename> directory,
 
610
        and use the Zeroconf service name <quote>Test</quote> to not
 
611
        collide with any other official Mandos server on this host:
494
612
      </para>
495
613
      <para>
496
614
 
528
646
      <title>CLIENTS</title>
529
647
      <para>
530
648
        The server only gives out its stored data to clients which
531
 
        does have the OpenPGP key of the stored fingerprint.  This is
532
 
        guaranteed by the fact that the client sends its OpenPGP
533
 
        public key in the TLS handshake; this ensures it to be
534
 
        genuine.  The server computes the fingerprint of the key
535
 
        itself and looks up the fingerprint in its list of
536
 
        clients. The <filename>clients.conf</filename> file (see
 
649
        does have the correct key ID of the stored key ID.  This is
 
650
        guaranteed by the fact that the client sends its public key in
 
651
        the TLS handshake; this ensures it to be genuine.  The server
 
652
        computes the key ID of the key itself and looks up the key ID
 
653
        in its list of clients. The <filename>clients.conf</filename>
 
654
        file (see
537
655
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
538
656
        <manvolnum>5</manvolnum></citerefentry>)
539
657
        <emphasis>must</emphasis> be made non-readable by anyone
545
663
        compromised if they are gone for too long.
546
664
      </para>
547
665
      <para>
548
 
        If a client is compromised, its downtime should be duly noted
549
 
        by the server which would therefore declare the client
550
 
        invalid.  But if the server was ever restarted, it would
551
 
        re-read its client list from its configuration file and again
552
 
        regard all clients therein as valid, and hence eligible to
553
 
        receive their passwords.  Therefore, be careful when
554
 
        restarting servers if it is suspected that a client has, in
555
 
        fact, been compromised by parties who may now be running a
556
 
        fake Mandos client with the keys from the non-encrypted
557
 
        initial <acronym>RAM</acronym> image of the client host.  What
558
 
        should be done in that case (if restarting the server program
559
 
        really is necessary) is to stop the server program, edit the
560
 
        configuration file to omit any suspect clients, and restart
561
 
        the server program.
562
 
      </para>
563
 
      <para>
564
666
        For more details on client-side security, see
565
667
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
566
668
        <manvolnum>8mandos</manvolnum></citerefentry>.
571
673
  <refsect1 id="see_also">
572
674
    <title>SEE ALSO</title>
573
675
    <para>
574
 
      <citerefentry>
575
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
576
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
577
 
        <refentrytitle>mandos.conf</refentrytitle>
578
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
579
 
        <refentrytitle>mandos-client</refentrytitle>
580
 
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
581
 
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
582
 
      </citerefentry>
 
676
      <citerefentry><refentrytitle>intro</refentrytitle>
 
677
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
678
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
679
      <manvolnum>5</manvolnum></citerefentry>,
 
680
      <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
681
      <manvolnum>5</manvolnum></citerefentry>,
 
682
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
683
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
684
      <citerefentry><refentrytitle>sh</refentrytitle>
 
685
      <manvolnum>1</manvolnum></citerefentry>
583
686
    </para>
584
687
    <variablelist>
585
688
      <varlistentry>
595
698
      </varlistentry>
596
699
      <varlistentry>
597
700
        <term>
598
 
          <ulink url="http://www.avahi.org/">Avahi</ulink>
 
701
          <ulink url="https://www.avahi.org/">Avahi</ulink>
599
702
        </term>
600
703
      <listitem>
601
704
        <para>
606
709
      </varlistentry>
607
710
      <varlistentry>
608
711
        <term>
609
 
          <ulink url="http://www.gnu.org/software/gnutls/"
610
 
          >GnuTLS</ulink>
 
712
          <ulink url="https://gnutls.org/">GnuTLS</ulink>
611
713
        </term>
612
714
      <listitem>
613
715
        <para>
614
716
          GnuTLS is the library this server uses to implement TLS for
615
717
          communicating securely with the client, and at the same time
616
 
          confidently get the client’s public OpenPGP key.
 
718
          confidently get the client’s public key.
617
719
        </para>
618
720
      </listitem>
619
721
      </varlistentry>
640
742
            <listitem>
641
743
              <para>
642
744
                The clients use IPv6 link-local addresses, which are
643
 
                immediately usable since a link-local addresses is
 
745
                immediately usable since a link-local address is
644
746
                automatically assigned to a network interfaces when it
645
747
                is brought up.
646
748
              </para>
651
753
      </varlistentry>
652
754
      <varlistentry>
653
755
        <term>
654
 
          RFC 4346: <citetitle>The Transport Layer Security (TLS)
655
 
          Protocol Version 1.1</citetitle>
 
756
          RFC 5246: <citetitle>The Transport Layer Security (TLS)
 
757
          Protocol Version 1.2</citetitle>
656
758
        </term>
657
759
      <listitem>
658
760
        <para>
659
 
          TLS 1.1 is the protocol implemented by GnuTLS.
 
761
          TLS 1.2 is the protocol implemented by GnuTLS.
660
762
        </para>
661
763
      </listitem>
662
764
      </varlistentry>
672
774
      </varlistentry>
673
775
      <varlistentry>
674
776
        <term>
675
 
          RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
676
 
          Security</citetitle>
677
 
        </term>
678
 
      <listitem>
679
 
        <para>
680
 
          This is implemented by GnuTLS and used by this server so
681
 
          that OpenPGP keys can be used.
 
777
          RFC 7250: <citetitle>Using Raw Public Keys in Transport
 
778
          Layer Security (TLS) and Datagram Transport Layer Security
 
779
          (DTLS)</citetitle>
 
780
        </term>
 
781
      <listitem>
 
782
        <para>
 
783
          This is implemented by GnuTLS version 3.6.6 and is, if
 
784
          present, used by this server so that raw public keys can be
 
785
          used.
 
786
        </para>
 
787
      </listitem>
 
788
      </varlistentry>
 
789
      <varlistentry>
 
790
        <term>
 
791
          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
 
792
          Security (TLS) Authentication</citetitle>
 
793
        </term>
 
794
      <listitem>
 
795
        <para>
 
796
          This is implemented by GnuTLS before version 3.6.0 and is,
 
797
          if present, used by this server so that OpenPGP keys can be
 
798
          used.
682
799
        </para>
683
800
      </listitem>
684
801
      </varlistentry>