]>
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 | |
37 | :doc:`pdnsutil <manpages/pdnsutil.1>`:: | |
38 | ||
39 | pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' | |
40 | pdnsutil activate-tsig-key powerdnssec.org test master | |
41 | ||
42 | To ease interoperability, the equivalent configuration above in BIND | |
43 | would look like this:: | |
44 | ||
45 | key test. { | |
46 | algorithm hmac-md5; | |
47 | secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; | |
48 | }; | |
49 | ||
50 | zone "powerdnssec.org" { | |
51 | type master; | |
52 | file "powerdnssec.org"; | |
53 | allow-transfer { key test.; }; | |
54 | }; | |
55 | ||
56 | A packet authorized and authenticated by a TSIG signature will gain | |
57 | access to a zone even if the remote IP address is not otherwise allowed | |
58 | to AXFR a zone. | |
59 | ||
60 | .. _tsig-provision-signed-notify-axfr: | |
61 | ||
62 | Provisioning signed notification and AXFR requests | |
63 | -------------------------------------------------- | |
64 | ||
65 | To configure PowerDNS to send out TSIG signed AXFR requests for a zone | |
66 | to its master(s), set the ``AXFR-MASTER-TSIG`` metadata item for the | |
67 | relevant domain to the key that must be used. | |
68 | ||
69 | The actual TSIG key must also be provisioned, as outlined in the | |
70 | previous section. | |
71 | ||
72 | For the Generic SQL backends, configuring the use of TSIG for AXFR | |
73 | requests could be achieved as follows: | |
74 | ||
75 | :: | |
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 | :: | |
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 | :: | |
97 | ||
98 | key test. { | |
99 | algorithm hmac-md5; | |
100 | secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; | |
101 | }; | |
102 | ||
103 | server 127.0.0.1 { | |
104 | keys { test.; }; | |
105 | }; | |
106 | ||
107 | zone "powerdnssec.org" { | |
108 | type slave; | |
109 | masters { 127.0.0.1; }; | |
110 | file "powerdnssec.org"; | |
111 | }; | |
112 | ||
113 | Except that in this case, TSIG will be used for all communications with | |
114 | the master, not just those about AXFR requests. | |
115 | ||
116 | .. _tsig-gss-tsig: | |
117 | ||
118 | GSS-TSIG support | |
119 | ---------------- | |
120 | ||
121 | GSS-TSIG allows authentication and authorization of DNS updates or AXFR | |
122 | using Kerberos with TSIG signatures. | |
123 | ||
124 | .. note:: | |
125 | This feature is experimental and subject to change in future releases. | |
126 | ||
127 | Prerequisites | |
128 | ~~~~~~~~~~~~~ | |
129 | ||
130 | - Working Kerberos environment. Please refer to your Kerberos vendor | |
131 | documentation on how to setup it. | |
132 | - Principal (such as ``DNS/<your.dns.server.name>@REALM``) in either | |
133 | per-user keytab or system keytab. | |
134 | ||
135 | In particular, if something does not work, read logs and ensure that | |
136 | your kerberos environment is ok before filing an issue. Most common | |
137 | problems are time synchronization or changes done to the principal. | |
138 | ||
139 | Setting up | |
140 | ~~~~~~~~~~ | |
141 | ||
142 | To allow AXFR / DNS update to work, you need to configure | |
143 | ``GSS-ACCEPTOR-PRINCIPAL`` in | |
144 | :doc:`domainmetadata`. This will define the | |
145 | principal that is used to accept any GSS context requests. This *must* | |
146 | match to your keytab. Next you need to define one or more | |
147 | ``GSS-ALLOW-AXFR-PRINCIPAL`` entries for AXFR, or | |
148 | ``TSIG-ALLOW-DNSUPDATE`` entries for DNS update. These must be set to | |
149 | the exact initiator principal names you intend to use. No wildcards | |
150 | accepted. |