diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
commit | 3b9b6d0b8e7f798023c9d109c490449d528fde80 (patch) | |
tree | 2e1c188dd7b8d7475cd163de9ae02c428343669b /doc/arm/tsig.inc.rst | |
parent | Initial commit. (diff) | |
download | bind9-upstream.tar.xz bind9-upstream.zip |
Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/arm/tsig.inc.rst')
-rw-r--r-- | doc/arm/tsig.inc.rst | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/doc/arm/tsig.inc.rst b/doc/arm/tsig.inc.rst new file mode 100644 index 0000000..6840692 --- /dev/null +++ b/doc/arm/tsig.inc.rst @@ -0,0 +1,165 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. _tsig: + +TSIG +---- + +TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS +messages, originally specified in :rfc:`2845`. It allows DNS messages to be +cryptographically signed using a shared secret. TSIG can be used in any +DNS transaction, as a way to restrict access to certain server functions +(e.g., recursive queries) to authorized clients when IP-based access +control is insufficient or needs to be overridden, or as a way to ensure +message authenticity when it is critical to the integrity of the server, +such as with dynamic UPDATE messages or zone transfers from a primary to +a secondary server. + +This section is a guide to setting up TSIG in BIND. It describes the +configuration syntax and the process of creating TSIG keys. + +:iscman:`named` supports TSIG for server-to-server communication, and some of +the tools included with BIND support it for sending messages to +:iscman:`named`: + + * :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. + * :ref:`man_dig` supports TSIG via the :option:`-k <dig -k>` and :option:`-y <dig -y>` command-line options. + +Generating a Shared Key +~~~~~~~~~~~~~~~~~~~~~~~ + +TSIG keys can be generated using the :iscman:`tsig-keygen` command; the output +of the command is a ``key`` directive suitable for inclusion in +:iscman:`named.conf`. The key name, algorithm, and size can be specified by +command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and +256 bits, respectively. + +Any string which is a valid DNS name can be used as a key name. For +example, a key to be shared between servers called ``host1`` and ``host2`` +could be called "host1-host2.", and this key can be generated using: + +:: + + $ tsig-keygen host1-host2. > host1-host2.key + +This key may then be copied to both hosts. The key name and secret must +be identical on both hosts. (Note: copying a shared secret from one +server to another is beyond the scope of the DNS. A secure transport +mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted +email, etc.) + +:iscman:`tsig-keygen` can also be run as :iscman:`ddns-confgen`, in which case its +output includes additional configuration text for setting up dynamic DNS +in :iscman:`named`. See :ref:`man_ddns-confgen` for details. + +Loading a New Key +~~~~~~~~~~~~~~~~~ + +For a key shared between servers called ``host1`` and ``host2``, the +following could be added to each server's :iscman:`named.conf` file: + +:: + + key "host1-host2." { + algorithm hmac-sha256; + secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY="; + }; + +(This is the same key generated above using :iscman:`tsig-keygen`.) + +Since this text contains a secret, it is recommended that either +:iscman:`named.conf` not be world-readable, or that the ``key`` directive be +stored in a file which is not world-readable and which is included in +:iscman:`named.conf` via the ``include`` directive. + +Once a key has been added to :iscman:`named.conf` and the server has been +restarted or reconfigured, the server can recognize the key. If the +server receives a message signed by the key, it is able to verify +the signature. If the signature is valid, the response is signed +using the same key. + +TSIG keys that are known to a server can be listed using the command +:option:`rndc tsig-list`. + +Instructing the Server to Use a Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A server sending a request to another server must be told whether to use +a key, and if so, which key to use. + +For example, a key may be specified for each server in the :any:`primaries` +statement in the definition of a secondary zone; in this case, all SOA QUERY +messages, NOTIFY messages, and zone transfer requests (AXFR or IXFR) +are signed using the specified key. Keys may also be specified in +the :any:`also-notify` statement of a primary or secondary zone, causing NOTIFY +messages to be signed using the specified key. + +Keys can also be specified in a :namedconf:ref:`server` directive. Adding the +following on ``host1``, if the IP address of ``host2`` is 10.1.2.3, would +cause *all* requests from ``host1`` to ``host2``, including normal DNS +queries, to be signed using the ``host1-host2.`` key: + +:: + + server 10.1.2.3 { + keys { host1-host2. ;}; + }; + +Multiple keys may be present in the :any:`keys` statement, but only the +first one is used. As this directive does not contain secrets, it can be +used in a world-readable file. + +Requests sent by ``host2`` to ``host1`` would *not* be signed, unless a +similar ``server`` directive were in ``host2``'s configuration file. + +When any server sends a TSIG-signed DNS request, it expects the +response to be signed with the same key. If a response is not signed, or +if the signature is not valid, the response is rejected. + +TSIG-Based Access Control +~~~~~~~~~~~~~~~~~~~~~~~~~ + +TSIG keys may be specified in ACL definitions and ACL directives such as +:any:`allow-query`, :any:`allow-transfer`, and :any:`allow-update`. The above key +would be denoted in an ACL element as ``key host1-host2.`` + +Here is an example of an :any:`allow-update` directive using a TSIG key: + +:: + + allow-update { !{ !localnets; any; }; key host1-host2. ;}; + +This allows dynamic updates to succeed only if the UPDATE request comes +from an address in ``localnets``, *and* if it is signed using the +``host1-host2.`` key. + +See :ref:`dynamic_update_policies` for a +discussion of the more flexible :any:`update-policy` statement. + +Errors +~~~~~~ + +Processing of TSIG-signed messages can result in several errors: + +- If a TSIG-aware server receives a message signed by an unknown key, + the response will be unsigned, with the TSIG extended error code set + to BADKEY. +- If a TSIG-aware server receives a message from a known key but with + an invalid signature, the response will be unsigned, with the TSIG + extended error code set to BADSIG. +- If a TSIG-aware server receives a message with a time outside of the + allowed range, the response will be signed but the TSIG extended + error code set to BADTIME, and the time values will be adjusted so + that the response can be successfully verified. + +In all of the above cases, the server returns a response code of +NOTAUTH (not authenticated). |