1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _tsig: 13 14TSIG 15---- 16 17TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS 18messages, originally specified in :rfc:`2845`. It allows DNS messages to be 19cryptographically signed using a shared secret. TSIG can be used in any 20DNS transaction, as a way to restrict access to certain server functions 21(e.g., recursive queries) to authorized clients when IP-based access 22control is insufficient or needs to be overridden, or as a way to ensure 23message authenticity when it is critical to the integrity of the server, 24such as with dynamic UPDATE messages or zone transfers from a primary to 25a secondary server. 26 27This section is a guide to setting up TSIG in BIND. It describes the 28configuration syntax and the process of creating TSIG keys. 29 30:iscman:`named` supports TSIG for server-to-server communication, and some of 31the tools included with BIND support it for sending messages to 32:iscman:`named`: 33 34 * :ref:`man_nsupdate` supports TSIG via the :option:`-k <nsupdate -k>`, :option:`-l <nsupdate -l>`, and :option:`-y <nsupdate -y>` command-line options, or via the ``key`` command when running interactively. 35 * :ref:`man_dig` supports TSIG via the :option:`-k <dig -k>` and :option:`-y <dig -y>` command-line options. 36 37Generating a Shared Key 38~~~~~~~~~~~~~~~~~~~~~~~ 39 40TSIG keys can be generated using the :iscman:`tsig-keygen` command; the output 41of the command is a ``key`` directive suitable for inclusion in 42:iscman:`named.conf`. The key name, algorithm, and size can be specified by 43command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and 44256 bits, respectively. 45 46Any string which is a valid DNS name can be used as a key name. For 47example, a key to be shared between servers called ``host1`` and ``host2`` 48could be called "host1-host2.", and this key can be generated using: 49 50:: 51 52 $ tsig-keygen host1-host2. > host1-host2.key 53 54This key may then be copied to both hosts. The key name and secret must 55be identical on both hosts. (Note: copying a shared secret from one 56server to another is beyond the scope of the DNS. A secure transport 57mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted 58email, etc.) 59 60:iscman:`tsig-keygen` can also be run as :iscman:`ddns-confgen`, in which case its 61output includes additional configuration text for setting up dynamic DNS 62in :iscman:`named`. See :ref:`man_ddns-confgen` for details. 63 64Loading a New Key 65~~~~~~~~~~~~~~~~~ 66 67For a key shared between servers called ``host1`` and ``host2``, the 68following could be added to each server's :iscman:`named.conf` file: 69 70:: 71 72 key "host1-host2." { 73 algorithm hmac-sha256; 74 secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY="; 75 }; 76 77(This is the same key generated above using :iscman:`tsig-keygen`.) 78 79Since this text contains a secret, it is recommended that either 80:iscman:`named.conf` not be world-readable, or that the ``key`` directive be 81stored in a file which is not world-readable and which is included in 82:iscman:`named.conf` via the ``include`` directive. 83 84Once a key has been added to :iscman:`named.conf` and the server has been 85restarted or reconfigured, the server can recognize the key. If the 86server receives a message signed by the key, it is able to verify 87the signature. If the signature is valid, the response is signed 88using the same key. 89 90Instructing the Server to Use a Key 91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 93A server sending a request to another server must be told whether to use 94a key, and if so, which key to use. 95 96For example, a key may be specified for each server in the :any:`primaries` 97statement in the definition of a secondary zone; in this case, all SOA QUERY 98messages, NOTIFY messages, and zone transfer requests (AXFR or IXFR) 99are signed using the specified key. Keys may also be specified in 100the :any:`also-notify` statement of a primary or secondary zone, causing NOTIFY 101messages to be signed using the specified key. 102 103Keys can also be specified in a :namedconf:ref:`server` directive. Adding the 104following on ``host1``, if the IP address of ``host2`` is 10.1.2.3, would 105cause *all* requests from ``host1`` to ``host2``, including normal DNS 106queries, to be signed using the ``host1-host2.`` key: 107 108:: 109 110 server 10.1.2.3 { 111 keys { host1-host2. ;}; 112 }; 113 114Multiple keys may be present in the :any:`keys` statement, but only the 115first one is used. As this directive does not contain secrets, it can be 116used in a world-readable file. 117 118Requests sent by ``host2`` to ``host1`` would *not* be signed, unless a 119similar ``server`` directive were in ``host2``'s configuration file. 120 121When any server sends a TSIG-signed DNS request, it expects the 122response to be signed with the same key. If a response is not signed, or 123if the signature is not valid, the response is rejected. 124 125TSIG-Based Access Control 126~~~~~~~~~~~~~~~~~~~~~~~~~ 127 128TSIG keys may be specified in ACL definitions and ACL directives such as 129:any:`allow-query`, :any:`allow-transfer`, and :any:`allow-update`. The above key 130would be denoted in an ACL element as ``key host1-host2.`` 131 132Here is an example of an :any:`allow-update` directive using a TSIG key: 133 134:: 135 136 allow-update { !{ !localnets; any; }; key host1-host2. ;}; 137 138This allows dynamic updates to succeed only if the UPDATE request comes 139from an address in ``localnets``, *and* if it is signed using the 140``host1-host2.`` key. 141 142See :ref:`dynamic_update_policies` for a 143discussion of the more flexible :any:`update-policy` statement. 144 145Errors 146~~~~~~ 147 148Processing of TSIG-signed messages can result in several errors: 149 150- If a TSIG-aware server receives a message signed by an unknown key, 151 the response will be unsigned, with the TSIG extended error code set 152 to BADKEY. 153- If a TSIG-aware server receives a message from a known key but with 154 an invalid signature, the response will be unsigned, with the TSIG 155 extended error code set to BADSIG. 156- If a TSIG-aware server receives a message with a time outside of the 157 allowed range, the response will be signed but the TSIG extended 158 error code set to BADTIME, and the time values will be adjusted so 159 that the response can be successfully verified. 160 161In all of the above cases, the server returns a response code of 162NOTAUTH (not authenticated). 163