]>
Commit | Line | Data |
---|---|---|
0e2063c3 PL |
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 | |
633489be GD |
37 | :doc:`pdnsutil <manpages/pdnsutil.1>`: |
38 | ||
39 | .. code-block:: shell | |
0e2063c3 PL |
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 | |
633489be | 75 | requests could be achieved as follows:: |
0e2063c3 PL |
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 | ||
633489be | 85 | .. code-block:: shell |
0e2063c3 PL |
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 | |
633489be | 94 | quite) similar to the following BIND statements:: |
0e2063c3 PL |
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. |