docs/tsig.rst

   1 TSIG
   2 ====
   3
   4 TSIG, as defined in :rfc:`2845`,
   5 is a method for signing DNS messages using shared secrets. Each TSIG
   6 shared secret has a name, and PowerDNS can be told to allow zone
   7 transfer of a domain if the request is signed with an authorized name.
   8
   9 In PowerDNS, TSIG shared secrets are stored by the various backends. In
  10 case of the :doc:`backends/generic-sql`, they
  11 can be found in the 'tsigkeys' table. The name can be chosen freely, but
  12 the algorithm name will typically be 'hmac-md5'. Other supported
  13 algorithms are 'hmac-sha1', 'hmac-shaX' where X is 224, 256, 384 or 512.
  14 The content is a Base64-encoded secret.
  15
  16 .. note::
  17   Most backends require DNSSEC support enabled to support TSIG.
  18   For the Generic SQL Backend make sure to use the DNSSEC enabled schema
  19   and to turn on the relevant '-dnssec' flag (for example,
  20   ``gmysql-dnssec``)!
  21
  22 Provisioning outbound AXFR access
  23 ---------------------------------
  24
  25 To actually provision a named secret permission to AXFR a zone, set a
  26 metadata item in the 'domainmetadata' table called ``TSIG-ALLOW-AXFR``
  27 with the key name in the content field. For example::
  28
  29     insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=');
  30     select id from domains where name='powerdnssec.org';
  31     5
  32     insert into domainmetadata (domain_id, kind, content) values (5, 'TSIG-ALLOW-AXFR', 'test');
  33
  34     $ dig -t axfr powerdnssec.org @127.0.0.1 -y 'test:kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='
  35
  36 Another of importing and activating TSIG keys into the database is using
  37 :doc:`pdnsutil <manpages/pdnsutil.1>`:
  38
  39 .. code-block:: shell
  40
  41     pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='
  42     pdnsutil activate-tsig-key powerdnssec.org test master
  43
  44 To ease interoperability, the equivalent configuration above in BIND
  45 would look like this::
  46
  47     key test. {
  48             algorithm hmac-md5;
  49             secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=";
  50     };
  51
  52     zone "powerdnssec.org" {
  53         type master;
  54         file "powerdnssec.org";
  55         allow-transfer {  key test.; };
  56     };
  57
  58 A packet authorized and authenticated by a TSIG signature will gain
  59 access to a zone even if the remote IP address is not otherwise allowed
  60 to AXFR a zone.
  61
  62 .. _tsig-provision-signed-notify-axfr:
  63
  64 Provisioning signed notification and AXFR requests
  65 --------------------------------------------------
  66
  67 To configure PowerDNS to send out TSIG signed AXFR requests for a zone
  68 to its master(s), set the ``AXFR-MASTER-TSIG`` metadata item for the
  69 relevant domain to the key that must be used.
  70
  71 The actual TSIG key must also be provisioned, as outlined in the
  72 previous section.
  73
  74 For the Generic SQL backends, configuring the use of TSIG for AXFR
  75 requests could be achieved as follows::
  76
  77     insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=');
  78     select id from domains where name='powerdnssec.org';
  79     5
  80     insert into domainmetadata (domain_id, kind, content) values (5, 'AXFR-MASTER-TSIG', 'test');
  81
  82 This can also be done using
  83 :doc:`/manpages/pdnsutil.1`:
  84
  85 .. code-block:: shell
  86
  87     pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='
  88     pdnsutil activate-tsig-key powerdnssec.org test slave
  89
  90 This setup corresponds to the ``TSIG-ALLOW-AXFR`` access rule defined in
  91 the previous section.
  92
  93 In the interest of interoperability, the configuration above is (not
  94 quite) similar to the following BIND statements::
  95
  96     key test. {
  97             algorithm hmac-md5;
  98             secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=";
  99     };
 100
 101     server 127.0.0.1 {
 102             keys { test.; };
 103     };
 104
 105     zone "powerdnssec.org" {
 106      type slave;
 107      masters { 127.0.0.1; };
 108      file "powerdnssec.org";
 109     };
 110
 111 Except that in this case, TSIG will be used for all communications with
 112 the master, not just those about AXFR requests.
 113
 114 .. _tsig-gss-tsig:
 115
 116 GSS-TSIG support
 117 ----------------
 118
 119 GSS-TSIG allows authentication and authorization of DNS updates or AXFR
 120 using Kerberos with TSIG signatures.
 121
 122 .. note::
 123   This feature is experimental and subject to change in future releases.
 124
 125 Prerequisites
 126 ~~~~~~~~~~~~~
 127
 128 -  Working Kerberos environment. Please refer to your Kerberos vendor
 129    documentation on how to setup it.
 130 -  Principal (such as ``DNS/<your.dns.server.name>@REALM``) in either
 131    per-user keytab or system keytab.
 132
 133 In particular, if something does not work, read logs and ensure that
 134 your kerberos environment is ok before filing an issue. Most common
 135 problems are time synchronization or changes done to the principal.
 136
 137 Setting up
 138 ~~~~~~~~~~
 139
 140 To allow AXFR / DNS update to work, you need to configure
 141 ``GSS-ACCEPTOR-PRINCIPAL`` in
 142 :doc:`domainmetadata`. This will define the
 143 principal that is used to accept any GSS context requests. This *must*
 144 match to your keytab. Next you need to define one or more
 145 ``GSS-ALLOW-AXFR-PRINCIPAL`` entries for AXFR, or
 146 ``TSIG-ALLOW-DNSUPDATE`` entries for DNS update. These must be set to
 147 the exact initiator principal names you intend to use. No wildcards
 148 accepted.