diff --git a/doc/arm/dnssec.inc.rst b/doc/arm/dnssec.inc.rst index 4f5dddb700..98c70e0c49 100644 --- a/doc/arm/dnssec.inc.rst +++ b/doc/arm/dnssec.inc.rst @@ -235,123 +235,6 @@ should be referenced by :iscman:`named.conf` as the input file for the zone. to provide the parent zone administrators with the ``DNSKEYs`` (or their corresponding ``DS`` records) that are the secure entry point to the zone. -.. _dnssec_config: - -DNSSEC Validation -~~~~~~~~~~~~~~~~~ - -To enable :iscman:`named` to validate answers received from other servers, the -``dnssec-validation`` option must be set to either ``yes`` or ``auto``. - -When ``dnssec-validation`` is set to ``auto``, a trust anchor for the -DNS root zone is automatically used. This trust anchor is provided -as part of BIND and is kept up to date using :rfc:`5011` key management. - -When ``dnssec-validation`` is set to ``yes``, DNSSEC validation -only occurs if at least one trust anchor has been explicitly configured -in :iscman:`named.conf`, using a ``trust-anchors`` statement (or the -``managed-keys`` and ``trusted-keys`` statements, both deprecated). - -When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not -occur. - -The default is ``auto`` unless BIND is built with -``configure --disable-auto-validation``, in which case the default is -``yes``. - -The keys specified in ``trust-anchors`` are copies of ``DNSKEY`` RRs for zones -that are used to form the first link in the cryptographic chain of trust. Keys -configured with the keyword ``static-key`` or ``static-ds`` are loaded directly -into the table of trust anchors, and can only be changed by altering the -configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used -to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date -automatically after the first time :iscman:`named` runs. - -``trust-anchors`` is described in more detail later in this document. - -BIND 9 does not verify signatures on load, so zone keys -for authoritative zones do not need to be specified in the configuration -file. - -After DNSSEC is established, a typical DNSSEC configuration looks -something like the following. It has one or more public keys for the -root, which allows answers from outside the organization to be validated. -It also has several keys for parts of the namespace that the -organization controls. These are here to ensure that :iscman:`named` is immune -to compromised security in the DNSSEC components of parent zones. - -:: - - trust-anchors { - /* Root Key */ - "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS - JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh - aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy - 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg - hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp - 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke - g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq - 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ - 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ - dgxbcDTClU0CRBdiieyLMNzXG3"; - /* Key for our organization's forward zone */ - example.com. static-ds 54135 5 2 "8EF922C97F1D07B23134440F19682E7519ADDAE180E20B1B1EC52E7F58B2831D" - - /* Key for our reverse zone. */ - 2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc - xOdNax071L18QqZnQQQAVVr+i - LhGTnNGp3HoWQLUIzKrJVZ3zg - gy3WwNT6kZo6c0tszYqbtvchm - gQC8CzKojM/W16i6MG/eafGU3 - siaOdS0yOI6BgPsw+YZdzlYMa - IJGf4M4dyoKIhzdZyQ2bYQrjy - Q4LB0lC7aOnsMyYKHHYeRvPxj - IQXmdqgOJGq+vsevG06zW+1xg - YJh9rCIfnm1GX/KMgxLPG2vXT - D/RnLX+D3T3UL7HJYHJhAZD5L - 59VvjSPsZJHeDCUyWYrvPZesZ - DIRvhDD52SKvbheeTJUm6Ehkz - ytNN2SN96QRk8j/iI8ib"; - }; - - options { - ... - dnssec-validation yes; - }; - -.. - -.. note:: - - None of the keys listed in this example are valid. In particular, the - root key is not valid. - -When DNSSEC validation is enabled and properly configured, the resolver -rejects any answers from signed, secure zones which fail to -validate, and returns SERVFAIL to the client. - -Responses may fail to validate for any of several reasons, including -missing, expired, or invalid signatures, a key which does not match the -DS RRset in the parent zone, or an insecure response from a zone which, -according to its parent, should have been secure. - -.. note:: - - When the validator receives a response from an unsigned zone that has - a signed parent, it must confirm with the parent that the zone was - intentionally left unsigned. It does this by verifying, via signed - and validated NSEC/NSEC3 records, that the parent zone contains no DS - records for the child. - - If the validator *can* prove that the zone is insecure, then the - response is accepted. However, if it cannot, the validator must assume an - insecure response to be a forgery; it rejects the response and logs - an error. - - The logged error reads "insecurity proof failed" and "got insecure - response; parent indicates it should be secure." - - .. _dnssec_dynamic_zones: Dynamic Zones @@ -559,3 +442,118 @@ This requires the ``dnssec-secure-to-insecure`` option to be set to ``yes`` in In addition, if the ``auto-dnssec maintain`` or a ``dnssec-policy`` is used, it should be removed or changed to ``allow`` instead; otherwise it will re-sign. + + +DNSSEC Validation +~~~~~~~~~~~~~~~~~ + +To enable :iscman:`named` to validate answers received from other servers, the +``dnssec-validation`` option must be set to either ``yes`` or ``auto``. + +When ``dnssec-validation`` is set to ``auto``, a trust anchor for the +DNS root zone is automatically used. This trust anchor is provided +as part of BIND and is kept up to date using :rfc:`5011` key management. + +When ``dnssec-validation`` is set to ``yes``, DNSSEC validation +only occurs if at least one trust anchor has been explicitly configured +in :iscman:`named.conf`, using a ``trust-anchors`` statement (or the +``managed-keys`` and ``trusted-keys`` statements, both deprecated). + +When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not +occur. + +The default is ``auto`` unless BIND is built with +``configure --disable-auto-validation``, in which case the default is +``yes``. + +The keys specified in ``trust-anchors`` are copies of ``DNSKEY`` RRs for zones +that are used to form the first link in the cryptographic chain of trust. Keys +configured with the keyword ``static-key`` or ``static-ds`` are loaded directly +into the table of trust anchors, and can only be changed by altering the +configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used +to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date +automatically after the first time :iscman:`named` runs. + +``trust-anchors`` is described in more detail later in this document. + +BIND 9 does not verify signatures on load, so zone keys +for authoritative zones do not need to be specified in the configuration +file. + +After DNSSEC is established, a typical DNSSEC configuration looks +something like the following. It has one or more public keys for the +root, which allows answers from outside the organization to be validated. +It also has several keys for parts of the namespace that the +organization controls. These are here to ensure that :iscman:`named` is immune +to compromised security in the DNSSEC components of parent zones. + +:: + + trust-anchors { + /* Root Key */ + "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS + JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh + aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy + 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg + hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp + 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke + g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq + 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ + 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ + dgxbcDTClU0CRBdiieyLMNzXG3"; + /* Key for our organization's forward zone */ + example.com. static-ds 54135 5 2 "8EF922C97F1D07B23134440F19682E7519ADDAE180E20B1B1EC52E7F58B2831D" + + /* Key for our reverse zone. */ + 2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + xOdNax071L18QqZnQQQAVVr+i + LhGTnNGp3HoWQLUIzKrJVZ3zg + gy3WwNT6kZo6c0tszYqbtvchm + gQC8CzKojM/W16i6MG/eafGU3 + siaOdS0yOI6BgPsw+YZdzlYMa + IJGf4M4dyoKIhzdZyQ2bYQrjy + Q4LB0lC7aOnsMyYKHHYeRvPxj + IQXmdqgOJGq+vsevG06zW+1xg + YJh9rCIfnm1GX/KMgxLPG2vXT + D/RnLX+D3T3UL7HJYHJhAZD5L + 59VvjSPsZJHeDCUyWYrvPZesZ + DIRvhDD52SKvbheeTJUm6Ehkz + ytNN2SN96QRk8j/iI8ib"; + }; + + options { + ... + dnssec-validation yes; + }; + +.. + +.. note:: + + None of the keys listed in this example are valid. In particular, the + root key is not valid. + +When DNSSEC validation is enabled and properly configured, the resolver +rejects any answers from signed, secure zones which fail to +validate, and returns SERVFAIL to the client. + +Responses may fail to validate for any of several reasons, including +missing, expired, or invalid signatures; a key which does not match the +DS RRset in the parent zone; or an insecure response from a zone which, +according to its parent, should have been secure. + +.. note:: + + When the validator receives a response from an unsigned zone that has + a signed parent, it must confirm with the parent that the zone was + intentionally left unsigned. It does this by verifying, via signed + and validated NSEC/NSEC3 records, that the parent zone contains no DS + records for the child. + + If the validator *can* prove that the zone is insecure, then the + response is accepted. However, if it cannot, the validator must assume an + insecure response to be a forgery; it rejects the response and logs + an error. + + The logged error reads "insecurity proof failed" and "got insecure + response; parent indicates it should be secure."