isc-hmac-fixup.docbook revision 9a769d8b16eb4e3d088ba1e5bd6ccb65504e1c9e
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen - Copyright (C) 2010, 2013-2017 Internet Systems Consortium, Inc. ("ISC")
b44650b0f48a4b5f0dc240ed836833a00b643b9fTimo Sirainen - This Source Code Form is subject to the terms of the Mozilla Public
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen - License, v. 2.0. If a copy of the MPL was not distributed with this
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen - file, You can obtain one at http://mozilla.org/MPL/2.0/.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen<!-- Converted by db4-upgrade version 1.0 -->
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.isc-hmac-fixup">
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refentryinfo>
c1ebcdad1b4d950eb22219704dd9d64a89d0568fTimo Sirainen <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
c1ebcdad1b4d950eb22219704dd9d64a89d0568fTimo Sirainen </refentryinfo>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refentrytitle><application>isc-hmac-fixup</application></refentrytitle>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refname><application>isc-hmac-fixup</application></refname>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refpurpose>fixes HMAC keys generated by older versions of BIND</refpurpose>
c1ebcdad1b4d950eb22219704dd9d64a89d0568fTimo Sirainen </refnamediv>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refsynopsisdiv>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <arg choice="req" rep="norepeat"><replaceable class="parameter">algorithm</replaceable></arg>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <arg choice="req" rep="norepeat"><replaceable class="parameter">secret</replaceable></arg>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen </cmdsynopsis>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen </refsynopsisdiv>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refsection><info><title>DESCRIPTION</title></info>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen Versions of BIND 9 up to and including BIND 9.6 had a bug causing
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen HMAC-SHA* TSIG keys which were longer than the digest length of the
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen hash algorithm (i.e., SHA1 keys longer than 160 bits, SHA256 keys
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen longer than 256 bits, etc) to be used incorrectly, generating a
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen message authentication code that was incompatible with other DNS
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen implementations.
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen This bug was fixed in BIND 9.7. However, the fix may
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen cause incompatibility between older and newer versions of
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen BIND, when using long keys. <command>isc-hmac-fixup</command>
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen modifies those keys to restore compatibility.
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen To modify a key, run <command>isc-hmac-fixup</command> and
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen specify the key's algorithm and secret on the command line. If the
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen secret is longer than the digest length of the algorithm (64 bytes
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen for SHA1 through SHA256, or 128 bytes for SHA384 and SHA512), then a
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen new secret will be generated consisting of a hash digest of the old
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen secret. (If the secret did not require conversion, then it will be
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen printed without modification.)
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen </refsection>
4376643cd2c7110e752c09f838f2c4eee6ed8ac6Timo Sirainen <refsection><info><title>SECURITY CONSIDERATIONS</title></info>
4376643cd2c7110e752c09f838f2c4eee6ed8ac6Timo Sirainen Secrets that have been converted by <command>isc-hmac-fixup</command>
4376643cd2c7110e752c09f838f2c4eee6ed8ac6Timo Sirainen are shortened, but as this is how the HMAC protocol works in
4376643cd2c7110e752c09f838f2c4eee6ed8ac6Timo Sirainen operation anyway, it does not affect security. RFC 2104 notes,
4376643cd2c7110e752c09f838f2c4eee6ed8ac6Timo Sirainen "Keys longer than [the digest length] are acceptable but the
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen extra length would not significantly increase the function
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen </refsection>
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen <refsection><info><title>SEE ALSO</title></info>
47bb4a7615c85f212f061499f04f121d6d625387Timo Sirainen <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen </refsection>