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