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