/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: 2019-02-09 23:23:26 UTC
  • Revision ID: teddy@recompile.se-20190209232326-z1z2kzpgfixz7iaj
Add support for using raw public keys in TLS (RFC 7250)

Since GnuTLS removed support for OpenPGP keys in TLS (RFC 6091), and
no other library supports it, we have to change the protocol to use
something else.  We choose to use "raw public keys" (RFC 7250).  Since
we still use OpenPGP keys to decrypt the secret password, this means
that each client will have two keys: One OpenPGP key and one TLS
public/private key, and the key ID of the latter key is used to
identify clients instead of the fingerprint of the OpenPGP key.

Note that this code is still compatible with GnuTLS before version
3.6.0 (when OpenPGP key support was removed).  This commit merely adds
support for using raw pulic keys instead with GnuTLS 3.6.6. or later.

* DBUS-API (Signals/ClientNotFound): Change name of first parameter
                                     from "Fingerprint" to "KeyID".
  (Mandos Client Interface/Properties/KeyID): New.
* INSTALL: Document conflict with GnuTLS 3.6.0 (which removed OpenPGP
           key support) up until 3.6.6, when support for raw public
           keys was added.  Also document new dependency of client on
           "gnutls-bin" package (for certtool).
* Makefile (run-client): Depend on TLS key files, and also pass them
                         as arguments to client.
  (keydir/tls-privkey.pem, keydir/tls-pubkey.pem): New.
  (confdir/clients.conf): Add dependency on TLS public key.
  (purge-client): Add removal of TLS key files.
* clients.conf ([foo]/key_id, [bar]/key_id): New.
* debian/control (Source: mandos/Build-Depends): Also allow
                                                 libgnutls30 (>= 3.6.6)
  (Package: mandos/Depends): - '' -
  (Package: mandos/Description): Alter description to match new
                                 design.
  (Package: mandos-client/Description): - '' -
  (Package: mandos-client/Depends): Move "gnutls-bin | openssl" to
                                    here from "Recommends".
* debian/mandos-client.README.Debian: Add --tls-privkey and
                                      --tls-pubkey options to test
                                      command.
* debian/mandos-client.postinst (create_key): Renamed to "create_keys"
                                             (all callers changed),
                                             and also create TLS key.
* debian/mandos-client.postrm (purge): Also remove TLS key files.
* intro.xml (DESCRIPTION): Describe new dual-key design.
* mandos (GnuTLS): Define different functions depending on whether
                   support for raw public keys is detected.
  (Client.key_id): New attribute.
  (ClientDBus.KeyID_dbus_property): New method.
  (ProxyClient.__init__): Take new "key_id" parameter.
  (ClientHandler.handle): Use key IDs when using raw public keys and
                          use fingerprints when using OpenPGP keys.
  (ClientHandler.peer_certificate): Also handle raw public keys.
  (ClientHandler.key_id): New.
  (MandosServer.handle_ipc): Pass key ID over the pipe IPC.  Also
                             check for key ID matches when looking up
                             clients.
  (main): Default GnuTLS priority string depends on whether we are
          using raw public keys or not.  When unpickling clients, set
          key_id if not set in the pickle.
  (main/MandosDBusService.ClientNotFound): Change name of first
                                           parameter from
                                           "Fingerprint" to "KeyID".
* mandos-clients.conf.xml (OPTIONS): Document new "key_id" option.
  (OPTIONS/secret): Mention new key ID matchning.
  (EXPANSION/RUNTIME EXPANSION): Add new "key_id" option.
  (EXAMPLE): - '' -
* mandos-ctl (tablewords, main/keywords): Add new "KeyID" property.
* mandos-keygen: Create TLS key files.  New "--tls-keytype" (-T)
                 option.  Alter help text to be more clear about key
                 types.  When in password mode, also output "key_id"
                 option.
* mandos-keygen.xml (SYNOPSIS): Add new "--tls-keytype" (-T) option.
  (DESCRIPTION): Alter to match new dual-key design.
  (OVERVIEW): - '' -
  (FILES): Add TLS key files.
* mandos-options.xml (priority): Document new default priority string
                                 when using raw public keys.
* mandos.xml (NETWORK PROTOCOL): Describe new protocol using key ID.
  (BUGS): Remove issue about checking expire times of OpenPGP keys,
          since TLS public keys do not have expiration times.
  (SECURITY/CLIENT): Alter description to match new design.
  (SEE ALSO/GnuTLS): - '' -
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.
* overview.xml: Alter text to match new design.
* plugin-runner.xml (EXAMPLE): Add --tls-pubkey and --tls-privkey
                               options to mandos-client options.
* plugins.d/mandos-client.c: Use raw public keys when compiling with
                             supporting GnuTLS versions. Add new
                             "--tls-pubkey" and "--tls-privkey"
                             options (which do nothing if GnuTLS
                             library does not support raw public
                             keys).  Alter text throughout to reflect
                             new design.  Only generate new DH
                             parameters (based on size of OpenPGP key)
                             when using OpenPGP in TLS.  Default
                             GnuTLS priority string depends on whether
                             we are using raw public keys or not.
* plugins.d/mandos-client.xml (SYNOPSIS): Add new "--tls-privkey" (-t)
                                          and "--tls-pubkey" (-T)
                                          options.
  (DESCRIPTION): Describe new dual-key design.
  (OPTIONS): Document new "--tls-privkey" (-t) and "--tls-pubkey" (-T)
             options.
  (OPTIONS/--dh-bits): No longer necessarily depends on OpenPGP key
                       size.
  (FILES): Add default locations for TLS public and private key files.
  (EXAMPLE): Use new --tls-pubkey and --tls-privkey options.
  (SECURITY): Alter wording slightly to reflect new dual-key design.
  (SEE ALSO/GnuTLS): Alter description to match new design.
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 "2025-06-27">
 
5
<!ENTITY TIMESTAMP "2019-02-09">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
42
42
      <year>2016</year>
43
43
      <year>2017</year>
44
44
      <year>2018</year>
45
 
      <year>2019</year>
46
 
      <year>2020</year>
47
 
      <year>2021</year>
48
 
      <year>2022</year>
49
 
      <year>2023</year>
50
 
      <year>2024</year>
51
45
      <holder>Teddy Hogeborn</holder>
52
46
      <holder>Björn Påhlsson</holder>
53
47
    </copyright>
201
195
    </para>
202
196
    <para>
203
197
      This program is not meant to be run directly; it is really meant
204
 
      to be run by other programs in the initial
205
 
      <acronym>RAM</acronym> disk environment; see <xref
206
 
      linkend="overview"/>.
 
198
      to run as a plugin of the <application>Mandos</application>
 
199
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
200
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
 
201
      initial <acronym>RAM</acronym> disk environment because it is
 
202
      specified as a <quote>keyscript</quote> in the <citerefentry>
 
203
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
 
204
      </citerefentry> file.
207
205
    </para>
208
206
  </refsect1>
209
207
  
221
219
    <title>OPTIONS</title>
222
220
    <para>
223
221
      This program is commonly not invoked from the command line; it
224
 
      is normally started by another program as described in <xref
225
 
      linkend="description"/>.  Any command line options this program
226
 
      accepts are therefore normally provided by the invoking program,
227
 
      and not directly.
 
222
      is normally started by the <application>Mandos</application>
 
223
      plugin runner, see <citerefentry><refentrytitle
 
224
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
 
225
      </citerefentry>.  Any command line options this program accepts
 
226
      are therefore normally provided by the plugin runner, and not
 
227
      directly.
228
228
    </para>
229
229
    
230
230
    <variablelist>
481
481
    <title>OVERVIEW</title>
482
482
    <xi:include href="../overview.xml"/>
483
483
    <para>
484
 
      This program is the client part.  It is run automatically in an
485
 
      initial <acronym>RAM</acronym> disk environment.
486
 
    </para>
487
 
    <para>
488
 
      In an initial <acronym>RAM</acronym> disk environment using
489
 
      <citerefentry><refentrytitle>systemd</refentrytitle>
490
 
      <manvolnum>1</manvolnum></citerefentry>, this program is started
491
 
      by the <application>Mandos</application> <citerefentry>
492
 
      <refentrytitle>password-agent</refentrytitle>
493
 
      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn is
494
 
      started automatically by the <citerefentry>
495
 
      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
496
 
      </citerefentry> <quote>Password Agent</quote> system.
497
 
    </para>
498
 
    <para>
499
 
      In the case of a non-<citerefentry>
500
 
      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
501
 
      </citerefentry> environment, this program is started as a plugin
502
 
      of the <application>Mandos</application> <citerefentry>
503
 
      <refentrytitle>plugin-runner</refentrytitle>
504
 
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
505
 
      initial <acronym>RAM</acronym> disk environment because it is
506
 
      specified as a <quote>keyscript</quote> in the <citerefentry>
507
 
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
508
 
      </citerefentry> file.
 
484
      This program is the client part.  It is a plugin started by
 
485
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
486
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
 
487
      an initial <acronym>RAM</acronym> disk environment.
509
488
    </para>
510
489
    <para>
511
490
      This program could, theoretically, be used as a keyscript in
512
491
      <filename>/etc/crypttab</filename>, but it would then be
513
492
      impossible to enter a password for the encrypted root disk at
514
493
      the console, since this program does not read from the console
515
 
      at all.
 
494
      at all.  This is why a separate plugin runner (<citerefentry>
 
495
      <refentrytitle>plugin-runner</refentrytitle>
 
496
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
 
497
      both this program and others in in parallel,
 
498
      <emphasis>one</emphasis> of which (<citerefentry>
 
499
      <refentrytitle>password-prompt</refentrytitle>
 
500
      <manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
 
501
      passwords on the system console.
516
502
    </para>
517
503
  </refsect1>
518
504
  
538
524
          <para>
539
525
            This environment variable will be assumed to contain the
540
526
            directory containing any helper executables.  The use and
541
 
            nature of these helper executables, if any, is purposely
542
 
            not documented.
 
527
            nature of these helper executables, if any, is
 
528
            purposefully not documented.
543
529
        </para>
544
530
        </listitem>
545
531
      </varlistentry>
775
761
    <title>EXAMPLE</title>
776
762
    <para>
777
763
      Note that normally, command line options will not be given
778
 
      directly, but passed on via the program responsible for starting
779
 
      this program; see <xref linkend="overview"/>.
 
764
      directly, but via options for the Mandos <citerefentry
 
765
      ><refentrytitle>plugin-runner</refentrytitle>
 
766
      <manvolnum>8mandos</manvolnum></citerefentry>.
780
767
    </para>
781
768
    <informalexample>
782
769
      <para>
828
815
  <refsect1 id="security">
829
816
    <title>SECURITY</title>
830
817
    <para>
831
 
      This program assumes that it is set-uid to root, and will switch
832
 
      back to the original (and presumably non-privileged) user and
833
 
      group after bringing up the network interface.
 
818
      This program is set-uid to root, but will switch back to the
 
819
      original (and presumably non-privileged) user and group after
 
820
      bringing up the network interface.
834
821
    </para>
835
822
    <para>
836
823
      To use this program for its intended purpose (see <xref
884
871
      <manvolnum>5</manvolnum></citerefentry>,
885
872
      <citerefentry><refentrytitle>mandos</refentrytitle>
886
873
      <manvolnum>8</manvolnum></citerefentry>,
887
 
      <citerefentry><refentrytitle>password-agent</refentrytitle>
 
874
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
888
875
      <manvolnum>8mandos</manvolnum></citerefentry>,
889
876
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
890
877
      <manvolnum>8mandos</manvolnum></citerefentry>
903
890
      </varlistentry>
904
891
      <varlistentry>
905
892
        <term>
906
 
          <ulink url="https://www.avahi.org/">Avahi</ulink>
 
893
          <ulink url="http://www.avahi.org/">Avahi</ulink>
907
894
        </term>
908
895
      <listitem>
909
896
        <para>