From: cvs2git Date: Tue, 6 Mar 2007 07:05:52 +0000 (+0000) Subject: This commit was manufactured by cvs2git to create tag 'v9_3_3rc3'. X-Git-Tag: v9.3.3rc3^0 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d357463397993657166fd1bdb5ddfc72ea60a798;p=thirdparty%2Fbind9.git This commit was manufactured by cvs2git to create tag 'v9_3_3rc3'. --- d357463397993657166fd1bdb5ddfc72ea60a798 diff --cc doc/draft/draft-ietf-dnsext-dnssec-experiments-03.txt index c8db70916fc,c8db70916fc..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-dnssec-experiments-03.txt +++ /dev/null @@@ -1,840 -1,840 +1,0 @@@ -- -- -- --DNSEXT D. Blacka --Internet-Draft VeriSign, Inc. --Intended status: Standards Track April 7, 2006 --Expires: October 9, 2006 -- -- -- DNSSEC Experiments -- draft-ietf-dnsext-dnssec-experiments-03 -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on October 9, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 1] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --Abstract -- -- This document describes a methodology for deploying alternate, non- -- backwards-compatible, DNSSEC methodologies in an experimental fashion -- without disrupting the deployment of standard DNSSEC. -- -- --Table of Contents -- -- 1. Definitions and Terminology . . . . . . . . . . . . . . . . . 3 -- 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 -- 3. Experiments . . . . . . . . . . . . . . . . . . . . . . . . . 5 -- 4. Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 -- 5. Defining an Experiment . . . . . . . . . . . . . . . . . . . . 8 -- 6. Considerations . . . . . . . . . . . . . . . . . . . . . . . . 9 -- 7. Use in Non-Experiments . . . . . . . . . . . . . . . . . . . . 10 -- 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 -- 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 -- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 -- 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 -- 10.2. Informative References . . . . . . . . . . . . . . . . . 13 -- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 -- Intellectual Property and Copyright Statements . . . . . . . . . . 15 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 2] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --1. Definitions and Terminology -- -- Throughout this document, familiarity with the DNS system (RFC 1035 -- [5]) and the DNS security extensions ([2], [3], and [4] is assumed. -- -- The key words "MUST, "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY, and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119 [1]. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 3] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --2. Overview -- -- Historically, experimentation with DNSSEC alternatives has been a -- problematic endeavor. There has typically been a desire to both -- introduce non-backwards-compatible changes to DNSSEC and to try these -- changes on real zones in the public DNS. This creates a problem when -- the change to DNSSEC would make all or part of the zone using those -- changes appear bogus (bad) or otherwise broken to existing security- -- aware resolvers. -- -- This document describes a standard methodology for setting up DNSSEC -- experiments. This methodology addresses the issue of co-existence -- with standard DNSSEC and DNS by using unknown algorithm identifiers -- to hide the experimental DNSSEC protocol modifications from standard -- security-aware resolvers. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 4] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --3. Experiments -- -- When discussing DNSSEC experiments, it is necessary to classify these -- experiments into two broad categories: -- -- Backwards-Compatible: describes experimental changes that, while not -- strictly adhering to the DNSSEC standard, are nonetheless -- interoperable with clients and servers that do implement the -- DNSSEC standard. -- -- Non-Backwards-Compatible: describes experiments that would cause a -- standard security-aware resolver to (incorrectly) determine that -- all or part of a zone is bogus, or to otherwise not interoperate -- with standard DNSSEC clients and servers. -- -- Not included in these terms are experiments with the core DNS -- protocol itself. -- -- The methodology described in this document is not necessary for -- backwards-compatible experiments, although it certainly may be used -- if desired. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 5] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --4. Method -- -- The core of the methodology is the use of strictly unknown algorithm -- identifiers when signing the experimental zone, and more importantly, -- having only unknown algorithm identifiers in the DS records for the -- delegation to the zone at the parent. -- -- This technique works because of the way DNSSEC-compliant validators -- are expected to work in the presence of a DS set with only unknown -- algorithm identifiers. From [4], Section 5.2: -- -- If the validator does not support any of the algorithms listed in -- an authenticated DS RRset, then the resolver has no supported -- authentication path leading from the parent to the child. The -- resolver should treat this case as it would the case of an -- authenticated NSEC RRset proving that no DS RRset exists, as -- described above. -- -- And further: -- -- If the resolver does not support any of the algorithms listed in -- an authenticated DS RRset, then the resolver will not be able to -- verify the authentication path to the child zone. In this case, -- the resolver SHOULD treat the child zone as if it were unsigned. -- -- While this behavior isn't strictly mandatory (as marked by MUST), it -- is likely that a validator would implement this behavior, or, more to -- the point, it would handle this situation in a safe way (see below -- (Section 6).) -- -- Because we are talking about experiments, it is RECOMMENDED that -- private algorithm numbers be used (see [3], appendix A.1.1. Note -- that secure handling of private algorithms requires special handing -- by the validator logic. See [6] for further details.) Normally, -- instead of actually inventing new signing algorithms, the recommended -- path is to create alternate algorithm identifiers that are aliases -- for the existing, known algorithms. While, strictly speaking, it is -- only necessary to create an alternate identifier for the mandatory -- algorithms, it is suggested that all optional defined algorithms be -- aliased as well. -- -- It is RECOMMENDED that for a particular DNSSEC experiment, a -- particular domain name base is chosen for all new algorithms, then -- the algorithm number (or name) is prepended to it. For example, for -- experiment A, the base name of "dnssec-experiment-a.example.com" is -- chosen. Then, aliases for algorithms 3 (DSA) and 5 (RSASHA1) are -- defined to be "3.dnssec-experiment-a.example.com" and -- "5.dnssec-experiment-a.example.com". However, any unique identifier -- -- -- --Blacka Expires October 9, 2006 [Page 6] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- -- will suffice. -- -- Using this method, resolvers (or, more specifically, DNSSEC -- validators) essentially indicate their ability to understand the -- DNSSEC experiment's semantics by understanding what the new algorithm -- identifiers signify. -- -- This method creates two classes of security-aware servers and -- resolvers: servers and resolvers that are aware of the experiment -- (and thus recognize the experiment's algorithm identifiers and -- experimental semantics), and servers and resolvers that are unaware -- of the experiment. -- -- This method also precludes any zone from being both in an experiment -- and in a classic DNSSEC island of security. That is, a zone is -- either in an experiment and only experimentally validatable, or it is -- not. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 7] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --5. Defining an Experiment -- -- The DNSSEC experiment MUST define the particular set of (previously -- unknown) algorithm identifiers that identify the experiment, and -- define what each unknown algorithm identifier means. Typically, -- unless the experiment is actually experimenting with a new DNSSEC -- algorithm, this will be a mapping of private algorithm identifiers to -- existing, known algorithms. -- -- Normally the experiment will choose a DNS name as the algorithm -- identifier base. This DNS name SHOULD be under the control of the -- authors of the experiment. Then the experiment will define a mapping -- between known mandatory and optional algorithms into this private -- algorithm identifier space. Alternately, the experiment MAY use the -- OID private algorithm space instead (using algorithm number 254), or -- MAY choose non-private algorithm numbers, although this would require -- an IANA allocation. -- -- For example, an experiment might specify in its description the DNS -- name "dnssec-experiment-a.example.com" as the base name, and declare -- that "3.dnssec-experiment-a.example.com" is an alias of DNSSEC -- algorithm 3 (DSA), and that "5.dnssec-experiment-a.example.com" is an -- alias of DNSSEC algorithm 5 (RSASHA1). -- -- Resolvers MUST only recognize the experiment's semantics when present -- in a zone signed by one or more of these algorithm identifiers. This -- is necessary to isolate the semantics of one experiment from any -- others that the resolver might understand. -- -- In general, resolvers involved in the experiment are expected to -- understand both standard DNSSEC and the defined experimental DNSSEC -- protocol, although this isn't required. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 8] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --6. Considerations -- -- There are a number of considerations with using this methodology. -- -- 1. Under some circumstances, it may be that the experiment will not -- be sufficiently masked by this technique and may cause resolution -- problem for resolvers not aware of the experiment. For instance, -- the resolver may look at a non-validatable response and conclude -- that the response is bogus, either due to local policy or -- implementation details. This is not expected to be a common -- case, however. -- -- 2. It will not be possible for security-aware resolvers unaware of -- the experiment to build a chain of trust through an experimental -- zone. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 9] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --7. Use in Non-Experiments -- -- This general methodology MAY be used for non-backwards compatible -- DNSSEC protocol changes that start out as or become standards. In -- this case: -- -- o The protocol change SHOULD use public IANA allocated algorithm -- identifiers instead of private algorithm identifiers. This will -- help identify the protocol change as a standard, rather than an -- experiment. -- -- o Resolvers MAY recognize the protocol change in zones not signed -- (or not solely signed) using the new algorithm identifiers. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 10] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --8. Security Considerations -- -- Zones using this methodology will be considered insecure by all -- resolvers except those aware of the experiment. It is not generally -- possible to create a secure delegation from an experimental zone that -- will be followed by resolvers unaware of the experiment. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 11] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --9. IANA Considerations -- -- This document has no IANA actions. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 12] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --10. References -- --10.1. Normative References -- -- [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- [2] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, -- March 2005. -- -- [3] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- [4] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", -- RFC 4035, March 2005. -- --10.2. Informative References -- -- [5] Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- -- [6] Austein, R. and S. Weiler, "Clarifications and Implementation -- Notes for DNSSECbis", draft-ietf-dnsext-dnssec-bis-updates-02 -- (work in progress), January 2006. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 13] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --Author's Address -- -- David Blacka -- VeriSign, Inc. -- 21355 Ridgetop Circle -- Dulles, VA 20166 -- US -- -- Phone: +1 703 948 3200 -- Email: davidb@verisign.com -- URI: http://www.verisignlabs.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 14] -- --Internet-Draft DNSSEC Experiments April 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- --Blacka Expires October 9, 2006 [Page 15] -- diff --cc doc/draft/draft-ietf-dnsext-dnssec-online-signing-02.txt index 7503c66ab31,7503c66ab31..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-dnssec-online-signing-02.txt +++ /dev/null @@@ -1,616 -1,616 +1,0 @@@ -- -- -- --Network Working Group S. Weiler --Internet-Draft SPARTA, Inc --Updates: 4034, 4035 (if approved) J. Ihren --Expires: July 24, 2006 Autonomica AB -- January 20, 2006 -- -- -- Minimally Covering NSEC Records and DNSSEC On-line Signing -- draft-ietf-dnsext-dnssec-online-signing-02 -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on July 24, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document describes how to construct DNSSEC NSEC resource records -- that cover a smaller range of names than called for by RFC4034. By -- generating and signing these records on demand, authoritative name -- servers can effectively stop the disclosure of zone contents -- otherwise made possible by walking the chain of NSEC records in a -- signed zone. -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 1] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --Changes from ietf-01 to ietf-02 -- -- Clarified that a generated NSEC RR's type bitmap MUST have the RRSIG -- and NSEC bits set, to be consistent with DNSSECbis -- previous text -- said SHOULD. -- -- Made the applicability statement a little less oppressive. -- --Changes from ietf-00 to ietf-01 -- -- Added an applicability statement, making reference to ongoing work on -- NSEC3. -- -- Added the phrase "epsilon functions", which has been commonly used to -- describe the technique and already appeared in the header of each -- page, in place of "increment and decrement functions". Also added an -- explanatory sentence. -- -- Corrected references from 4034 section 6.2 to section 6.1. -- -- Fixed an out-of-date reference to [-bis] and other typos. -- -- Replaced IANA Considerations text. -- -- Escaped close parentheses in examples. -- -- Added some more acknowledgements. -- --Changes from weiler-01 to ietf-00 -- -- Inserted RFC numbers for 4033, 4034, and 4035. -- -- Specified contents of bitmap field in synthesized NSEC RR's, pointing -- out that this relaxes a constraint in 4035. Added 4035 to the -- Updates header. -- --Changes from weiler-00 to weiler-01 -- -- Clarified that this updates RFC4034 by relaxing requirements on the -- next name field. -- -- Added examples covering wildcard names. -- -- In the 'better functions' section, reiterated that perfect functions -- aren't needed. -- -- Added a reference to RFC 2119. -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 2] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --Table of Contents -- -- 1. Introduction and Terminology . . . . . . . . . . . . . . . . . 4 -- 2. Applicability of This Technique . . . . . . . . . . . . . . . 4 -- 3. Minimally Covering NSEC Records . . . . . . . . . . . . . . . 5 -- 4. Better Epsilon Functions . . . . . . . . . . . . . . . . . . . 6 -- 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 -- 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 -- 7. Normative References . . . . . . . . . . . . . . . . . . . . . 8 -- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 8 -- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 -- Intellectual Property and Copyright Statements . . . . . . . . . . 11 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 3] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --1. Introduction and Terminology -- -- With DNSSEC [1], an NSEC record lists the next instantiated name in -- its zone, proving that no names exist in the "span" between the -- NSEC's owner name and the name in the "next name" field. In this -- document, an NSEC record is said to "cover" the names between its -- owner name and next name. -- -- Through repeated queries that return NSEC records, it is possible to -- retrieve all of the names in the zone, a process commonly called -- "walking" the zone. Some zone owners have policies forbidding zone -- transfers by arbitrary clients; this side-effect of the NSEC -- architecture subverts those policies. -- -- This document presents a way to prevent zone walking by constructing -- NSEC records that cover fewer names. These records can make zone -- walking take approximately as many queries as simply asking for all -- possible names in a zone, making zone walking impractical. Some of -- these records must be created and signed on demand, which requires -- on-line private keys. Anyone contemplating use of this technique is -- strongly encouraged to review the discussion of the risks of on-line -- signing in Section 6. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119 [4]. -- -- --2. Applicability of This Technique -- -- The technique presented here may be useful to a zone owner that wants -- to use DNSSEC, is concerned about exposure of its zone contents via -- zone walking, and is willing to bear the costs of on-line signing. -- -- As discussed in Section 6, on-line signing has several security -- risks, including an increased likelihood of private keys being -- disclosed and an increased risk of denial of service attack. Anyone -- contemplating use of this technique is strongly encouraged to review -- the discussion of the risks of on-line signing in Section 6. -- -- Furthermore, at the time this document was published, the DNSEXT -- working group was actively working on a mechanism to prevent zone -- walking that does not require on-line signing (tentatively called -- NSEC3). The new mechanism is likely to expose slightly more -- information about the zone than this technique (e.g. the number of -- instantiated names), but it may be preferable to this technique. -- -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 4] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --3. Minimally Covering NSEC Records -- -- This mechanism involves changes to NSEC records for instantiated -- names, which can still be generated and signed in advance, as well as -- the on-demand generation and signing of new NSEC records whenever a -- name must be proven not to exist. -- -- In the 'next name' field of instantiated names' NSEC records, rather -- than list the next instantiated name in the zone, list any name that -- falls lexically after the NSEC's owner name and before the next -- instantiated name in the zone, according to the ordering function in -- RFC4034 [2] section 6.1. This relaxes the requirement in section -- 4.1.1 of RFC4034 that the 'next name' field contains the next owner -- name in the zone. This change is expected to be fully compatible -- with all existing DNSSEC validators. These NSEC records are returned -- whenever proving something specifically about the owner name (e.g. -- that no resource records of a given type appear at that name). -- -- Whenever an NSEC record is needed to prove the non-existence of a -- name, a new NSEC record is dynamically produced and signed. The new -- NSEC record has an owner name lexically before the QNAME but -- lexically following any existing name and a 'next name' lexically -- following the QNAME but before any existing name. -- -- The generated NSEC record's type bitmap MUST have the RRSIG and NSEC -- bits set and SHOULD NOT have any other bits set. This relaxes the -- requirement in Section 2.3 of RFC4035 that NSEC RRs not appear at -- names that did not exist before the zone was signed. -- -- The functions to generate the lexically following and proceeding -- names need not be perfect nor consistent, but the generated NSEC -- records must not cover any existing names. Furthermore, this -- technique works best when the generated NSEC records cover as few -- names as possible. In this document, the functions that generate the -- nearby names are called 'epsilon' functions, a reference to the -- mathematical convention of using the greek letter epsilon to -- represent small deviations. -- -- An NSEC record denying the existence of a wildcard may be generated -- in the same way. Since the NSEC record covering a non-existent -- wildcard is likely to be used in response to many queries, -- authoritative name servers using the techniques described here may -- want to pregenerate or cache that record and its corresponding RRSIG. -- -- For example, a query for an A record at the non-instantiated name -- example.com might produce the following two NSEC records, the first -- denying the existence of the name example.com and the second denying -- the existence of a wildcard: -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 5] -- --Internet-Draft NSEC Epsilon January 2006 -- -- -- exampld.com 3600 IN NSEC example-.com ( RRSIG NSEC ) -- -- \).com 3600 IN NSEC +.com ( RRSIG NSEC ) -- -- Before answering a query with these records, an authoritative server -- must test for the existence of names between these endpoints. If the -- generated NSEC would cover existing names (e.g. exampldd.com or -- *bizarre.example.com), a better epsilon function may be used or the -- covered name closest to the QNAME could be used as the NSEC owner -- name or next name, as appropriate. If an existing name is used as -- the NSEC owner name, that name's real NSEC record MUST be returned. -- Using the same example, assuming an exampldd.com delegation exists, -- this record might be returned from the parent: -- -- exampldd.com 3600 IN NSEC example-.com ( NS DS RRSIG NSEC ) -- -- Like every authoritative record in the zone, each generated NSEC -- record MUST have corresponding RRSIGs generated using each algorithm -- (but not necessarily each DNSKEY) in the zone's DNSKEY RRset, as -- described in RFC4035 [3] section 2.2. To minimize the number of -- signatures that must be generated, a zone may wish to limit the -- number of algorithms in its DNSKEY RRset. -- -- --4. Better Epsilon Functions -- -- Section 6.1 of RFC4034 defines a strict ordering of DNS names. -- Working backwards from that definition, it should be possible to -- define epsilon functions that generate the immediately following and -- preceding names, respectively. This document does not define such -- functions. Instead, this section presents functions that come -- reasonably close to the perfect ones. As described above, an -- authoritative server should still ensure than no generated NSEC -- covers any existing name. -- -- To increment a name, add a leading label with a single null (zero- -- value) octet. -- -- To decrement a name, decrement the last character of the leftmost -- label, then fill that label to a length of 63 octets with octets of -- value 255. To decrement a null (zero-value) octet, remove the octet -- -- if an empty label is left, remove the label. Defining this -- function numerically: fill the left-most label to its maximum length -- with zeros (numeric, not ASCII zeros) and subtract one. -- -- In response to a query for the non-existent name foo.example.com, -- these functions produce NSEC records of: -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 6] -- --Internet-Draft NSEC Epsilon January 2006 -- -- -- fon\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255.example.com 3600 IN NSEC \000.foo.example.com ( NSEC RRSIG ) -- -- \)\255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255.example.com 3600 IN NSEC \000.*.example.com ( NSEC RRSIG ) -- -- The first of these NSEC RRs proves that no exact match for -- foo.example.com exists, and the second proves that there is no -- wildcard in example.com. -- -- Both of these functions are imperfect: they don't take into account -- constraints on number of labels in a name nor total length of a name. -- As noted in the previous section, though, this technique does not -- depend on the use of perfect epsilon functions: it is sufficient to -- test whether any instantiated names fall into the span covered by the -- generated NSEC and, if so, substitute those instantiated owner names -- for the NSEC owner name or next name, as appropriate. -- -- --5. IANA Considerations -- -- This document specifies no IANA Actions. -- -- --6. Security Considerations -- -- This approach requires on-demand generation of RRSIG records. This -- creates several new vulnerabilities. -- -- First, on-demand signing requires that a zone's authoritative servers -- have access to its private keys. Storing private keys on well-known -- internet-accessible servers may make them more vulnerable to -- unintended disclosure. -- -- Second, since generation of digital signatures tends to be -- computationally demanding, the requirement for on-demand signing -- makes authoritative servers vulnerable to a denial of service attack. -- -- Lastly, if the epsilon functions are predictable, on-demand signing -- may enable a chosen-plaintext attack on a zone's private keys. Zones -- using this approach should attempt to use cryptographic algorithms -- that are resistant to chosen-plaintext attacks. It's worth noting -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 7] -- --Internet-Draft NSEC Epsilon January 2006 -- -- -- that while DNSSEC has a "mandatory to implement" algorithm, that is a -- requirement on resolvers and validators -- there is no requirement -- that a zone be signed with any given algorithm. -- -- The success of using minimally covering NSEC record to prevent zone -- walking depends greatly on the quality of the epsilon functions -- chosen. An increment function that chooses a name obviously derived -- from the next instantiated name may be easily reverse engineered, -- destroying the value of this technique. An increment function that -- always returns a name close to the next instantiated name is likewise -- a poor choice. Good choices of epsilon functions are the ones that -- produce the immediately following and preceding names, respectively, -- though zone administrators may wish to use less perfect functions -- that return more human-friendly names than the functions described in -- Section 4 above. -- -- Another obvious but misguided concern is the danger from synthesized -- NSEC records being replayed. It's possible for an attacker to replay -- an old but still validly signed NSEC record after a new name has been -- added in the span covered by that NSEC, incorrectly proving that -- there is no record at that name. This danger exists with DNSSEC as -- defined in [3]. The techniques described here actually decrease the -- danger, since the span covered by any NSEC record is smaller than -- before. Choosing better epsilon functions will further reduce this -- danger. -- --7. Normative References -- -- [1] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, -- March 2005. -- -- [2] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- [3] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", -- RFC 4035, March 2005. -- -- [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- --Appendix A. Acknowledgments -- -- Many individuals contributed to this design. They include, in -- addition to the authors of this document, Olaf Kolkman, Ed Lewis, -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 8] -- --Internet-Draft NSEC Epsilon January 2006 -- -- -- Peter Koch, Matt Larson, David Blacka, Suzanne Woolf, Jaap Akkerhuis, -- Jakob Schlyter, Bill Manning, and Joao Damas. -- -- In addition, the editors would like to thank Ed Lewis, Scott Rose, -- and David Blacka for their careful review of the document. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 9] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --Authors' Addresses -- -- Samuel Weiler -- SPARTA, Inc -- 7075 Samuel Morse Drive -- Columbia, Maryland 21046 -- US -- -- Email: weiler@tislabs.com -- -- -- Johan Ihren -- Autonomica AB -- Bellmansgatan 30 -- Stockholm SE-118 47 -- Sweden -- -- Email: johani@autonomica.se -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 10] -- --Internet-Draft NSEC Epsilon January 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- --Weiler & Ihren Expires July 24, 2006 [Page 11] -- diff --cc doc/draft/draft-ietf-dnsext-ds-sha256-05.txt index 2460cb619b6,2460cb619b6..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-ds-sha256-05.txt +++ /dev/null @@@ -1,504 -1,504 +1,0 @@@ -- -- -- --Network Working Group W. Hardaker --Internet-Draft Sparta --Expires: August 25, 2006 February 21, 2006 -- -- -- Use of SHA-256 in DNSSEC Delegation Signer (DS) Resource Records (RRs) -- draft-ietf-dnsext-ds-sha256-05.txt -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on August 25, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document specifies how to use the SHA-256 digest type in DNS -- Delegation Signer (DS) Resource Records (RRs). DS records, when -- stored in a parent zone, point to key signing DNSKEY key(s) in a -- child zone. -- -- -- -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 1] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- --Table of Contents -- -- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 -- 2. Implementing the SHA-256 algorithm for DS record support . . . 3 -- 2.1. DS record field values . . . . . . . . . . . . . . . . . . 3 -- 2.2. DS Record with SHA-256 Wire Format . . . . . . . . . . . . 3 -- 2.3. Example DS Record Using SHA-256 . . . . . . . . . . . . . . 4 -- 3. Implementation Requirements . . . . . . . . . . . . . . . . . . 4 -- 4. Deployment Considerations . . . . . . . . . . . . . . . . . . . 4 -- 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 -- 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 -- 6.1. Potential Digest Type Downgrade Attacks . . . . . . . . . . 5 -- 6.2. SHA-1 vs SHA-256 Considerations for DS Records . . . . . . 6 -- 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 6 -- 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 -- 8.1. Normative References . . . . . . . . . . . . . . . . . . . 7 -- 8.2. Informative References . . . . . . . . . . . . . . . . . . 7 -- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 -- Intellectual Property and Copyright Statements . . . . . . . . . . 9 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 2] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- --1. Introduction -- -- The DNSSEC [RFC4033] [RFC4034] [RFC4035] DS RR is published in parent -- zones to distribute a cryptographic digest of a child's Key Signing -- Key (KSK) DNSKEY RR. The DS RRset is signed by at least one of the -- parent zone's private zone data signing keys for each algorithm in -- use by the parent. Each signature is published in an RRSIG resource -- record, owned by the same domain as the DS RRset and with a type -- covered of DS. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [RFC2119]. -- -- --2. Implementing the SHA-256 algorithm for DS record support -- -- This document specifies that the digest type code [XXX: To be -- assigned by IANA; likely 2] is to be assigned to SHA-256 [SHA256] -- [SHA256CODE] for use within DS records. The results of the digest -- algorithm MUST NOT be truncated and the entire 32 byte digest result -- is to be published in the DS record. -- --2.1. DS record field values -- -- Using the SHA-256 digest algorithm within a DS record will make use -- of the following DS-record fields: -- -- Digest type: [XXX: To be assigned by IANA; likely 2] -- -- Digest: A SHA-256 bit digest value calculated by using the following -- formula ("|" denotes concatenation). The resulting value is not -- truncated and the entire 32 byte result is to used in the -- resulting DS record and related calculations. -- -- digest = SHA_256(DNSKEY owner name | DNSKEY RDATA) -- -- where DNSKEY RDATA is defined by [RFC4034] as: -- -- DNSKEY RDATA = Flags | Protocol | Algorithm | Public Key -- -- The Key Tag field and Algorithm fields remain unchanged by this -- document and are specified in the [RFC4034] specification. -- --2.2. DS Record with SHA-256 Wire Format -- -- The resulting on-the-wire format for the resulting DS record will be -- [XXX: IANA assignment should replace the 2 below]: -- -- -- --Hardaker Expires August 25, 2006 [Page 3] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- -- 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 -- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | Key Tag | Algorithm | DigestType=2 | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- / / -- / Digest (length for SHA-256 is 32 bytes) / -- / / -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| -- --2.3. Example DS Record Using SHA-256 -- -- The following is an example DNSKEY and matching DS record. This -- DNSKEY record comes from the example DNSKEY/DS records found in -- section 5.4 of [RFC4034]. -- -- The DNSKEY record: -- -- dskey.example.com. 86400 IN DNSKEY 256 3 5 ( AQOeiiR0GOMYkDshWoSKz9Xz -- fwJr1AYtsmx3TGkJaNXVbfi/ -- 2pHm822aJ5iI9BMzNXxeYCmZ -- DRD99WYwYqUSdjMmmAphXdvx -- egXd/M5+X7OrzKBaMbCVdFLU -- Uh6DhweJBjEVv5f2wwjM9Xzc -- nOf+EPbtG9DMBmADjFDc2w/r -- ljwvFw== -- ) ; key id = 60485 -- -- The resulting DS record covering the above DNSKEY record using a SHA- -- 256 digest: [RFC Editor: please replace XXX with the assigned digest -- type (likely 2):] -- -- dskey.example.com. 86400 IN DS 60485 5 XXX ( D4B7D520E7BB5F0F67674A0C -- CEB1E3E0614B93C4F9E99B83 -- 83F6A1E4469DA50A ) -- -- --3. Implementation Requirements -- -- Implementations MUST support the use of the SHA-256 algorithm in DS -- RRs. Validator implementations SHOULD ignore DS RRs containing SHA-1 -- digests if DS RRs with SHA-256 digests are present in the DS RRset. -- -- --4. Deployment Considerations -- -- If a validator does not support the SHA-256 digest type and no other -- DS RR exists in a zone's DS RRset with a supported digest type, then -- -- -- --Hardaker Expires August 25, 2006 [Page 4] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- -- the validator has no supported authentication path leading from the -- parent to the child. The resolver should treat this case as it would -- the case of an authenticated NSEC RRset proving that no DS RRset -- exists, as described in [RFC4035], section 5.2. -- -- Because zone administrators can not control the deployment speed of -- support for SHA-256 in validators that may be referencing any of -- their zones, zone operators should consider deploying both SHA-1 and -- SHA-256 based DS records. This should be done for every DNSKEY for -- which DS records are being generated. Whether to make use of both -- digest types and for how long is a policy decision that extends -- beyond the scope of this document. -- -- --5. IANA Considerations -- -- Only one IANA action is required by this document: -- -- The Digest Type to be used for supporting SHA-256 within DS records -- needs to be assigned by IANA. This document requests that the Digest -- Type value of 2 be assigned to the SHA-256 digest algorithm. -- -- At the time of this writing, the current digest types assigned for -- use in DS records are as follows: -- -- VALUE Digest Type Status -- 0 Reserved - -- 1 SHA-1 MANDATORY -- 2 SHA-256 MANDATORY -- 3-255 Unassigned - -- -- --6. Security Considerations -- --6.1. Potential Digest Type Downgrade Attacks -- -- A downgrade attack from a stronger digest type to a weaker one is -- possible if all of the following are true: -- -- o A zone includes multiple DS records for a given child's DNSKEY, -- each of which use a different digest type. -- -- o A validator accepts a weaker digest even if a stronger one is -- present but invalid. -- -- For example, if the following conditions are all true: -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 5] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- -- o Both SHA-1 and SHA-256 based digests are published in DS records -- within a parent zone for a given child zone's DNSKEY. -- -- o The DS record with the SHA-1 digest matches the digest computed -- using the child zone's DNSKEY. -- -- o The DS record with the SHA-256 digest fails to match the digest -- computed using the child zone's DNSKEY. -- -- Then if the validator accepts the above situation as secure then this -- can be used as a downgrade attack since the stronger SHA-256 digest -- is ignored. -- --6.2. SHA-1 vs SHA-256 Considerations for DS Records -- -- Users of DNSSEC are encouraged to deploy SHA-256 as soon as software -- implementations allow for it. SHA-256 is widely believed to be more -- resilient to attack than SHA-1, and confidence in SHA-1's strength is -- being eroded by recently-announced attacks. Regardless of whether or -- not the attacks on SHA-1 will affect DNSSEC, it is believed (at the -- time of this writing) that SHA-256 is the better choice for use in DS -- records. -- -- At the time of this publication, the SHA-256 digest algorithm is -- considered sufficiently strong for the immediate future. It is also -- considered sufficient for use in DNSSEC DS RRs for the immediate -- future. However, future published attacks may weaken the usability -- of this algorithm within the DS RRs. It is beyond the scope of this -- document to speculate extensively on the cryptographic strength of -- the SHA-256 digest algorithm. -- -- Likewise, it is also beyond the scope of this document to specify -- whether or for how long SHA-1 based DS records should be -- simultaneously published alongside SHA-256 based DS records. -- -- --7. Acknowledgments -- -- This document is a minor extension to the existing DNSSEC documents -- and those authors are gratefully appreciated for the hard work that -- went into the base documents. -- -- The following people contributed to portions of this document in some -- fashion: Mark Andrews, Roy Arends, Olafur Gudmundsson, Paul Hoffman, -- Olaf M. Kolkman, Edward Lewis, Scott Rose, Stuart E. Schechter, Sam -- Weiler. -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 6] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- --8. References -- --8.1. Normative References -- -- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- -- [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "DNS Security Introduction and Requirements", -- RFC 4033, March 2005. -- -- [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Resource Records for the DNS Security Extensions", -- RFC 4034, March 2005. -- -- [RFC4035] Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Protocol Modifications for the DNS Security -- Extensions", RFC 4035, March 2005. -- -- [SHA256] National Institute of Standards and Technology, "Secure -- Hash Algorithm. NIST FIPS 180-2", August 2002. -- --8.2. Informative References -- -- [SHA256CODE] -- Eastlake, D., "US Secure Hash Algorithms (SHA)", -- June 2005. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 7] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- --Author's Address -- -- Wes Hardaker -- Sparta -- P.O. Box 382 -- Davis, CA 95617 -- US -- -- Email: hardaker@tislabs.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Hardaker Expires August 25, 2006 [Page 8] -- --Internet-Draft Use of SHA-256 in DNSSEC DS RRs February 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- --Hardaker Expires August 25, 2006 [Page 9] -- diff --cc doc/draft/draft-ietf-dnsext-mdns-46.txt index 63d0b23af67,63d0b23af67..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-mdns-46.txt +++ /dev/null @@@ -1,1801 -1,1801 +1,0 @@@ -- -- -- -- -- -- --DNSEXT Working Group Bernard Aboba --INTERNET-DRAFT Dave Thaler --Category: Standards Track Levon Esibov -- Microsoft Corporation --16 April 2006 -- -- Linklocal Multicast Name Resolution (LLMNR) -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on October 15, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society 2006. -- --Abstract -- -- The goal of Link-Local Multicast Name Resolution (LLMNR) is to enable -- name resolution in scenarios in which conventional DNS name -- resolution is not possible. LLMNR supports all current and future -- DNS formats, types and classes, while operating on a separate port -- from DNS, and with a distinct resolver cache. Since LLMNR only -- operates on the local link, it cannot be considered a substitute for -- DNS. -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 1] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --Table of Contents -- --1. Introduction .......................................... 3 -- 1.1 Requirements .................................... 4 -- 1.2 Terminology ..................................... 4 --2. Name Resolution Using LLMNR ........................... 4 -- 2.1 LLMNR Packet Format ............................. 5 -- 2.2 Sender Behavior ................................. 8 -- 2.3 Responder Behavior .............................. 8 -- 2.4 Unicast Queries and Responses ................... 11 -- 2.5 Off-link Detection .............................. 11 -- 2.6 Responder Responsibilities ...................... 12 -- 2.7 Retransmission and Jitter ....................... 13 -- 2.8 DNS TTL ......................................... 14 -- 2.9 Use of the Authority and Additional Sections .... 14 --3. Usage model ........................................... 15 -- 3.1 LLMNR Configuration ............................. 16 --4. Conflict Resolution ................................... 18 -- 4.1 Uniqueness Verification ......................... 18 -- 4.2 Conflict Detection and Defense .................. 19 -- 4.3 Considerations for Multiple Interfaces .......... 20 -- 4.4 API issues ...................................... 22 --5. Security Considerations ............................... 22 -- 5.1 Denial of Service ............................... 22 -- 5.2 Spoofing ...............,........................ 23 -- 5.3 Authentication .................................. 24 -- 5.4 Cache and Port Separation ....................... 24 --6. IANA considerations ................................... 25 --7. Constants ............................................. 25 --8. References ............................................ 26 -- 8.1 Normative References ............................ 26 -- 8.2 Informative References .......................... 26 --Acknowledgments .............................................. 28 --Authors' Addresses ........................................... 28 --Intellectual Property Statement .............................. 29 --Disclaimer of Validity ....................................... 29 --Copyright Statement .......................................... 29 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 2] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --1. Introduction -- -- This document discusses Link Local Multicast Name Resolution (LLMNR), -- which is based on the DNS packet format and supports all current and -- future DNS formats, types and classes. LLMNR operates on a separate -- port from the Domain Name System (DNS), with a distinct resolver -- cache. -- -- Since LLMNR only operates on the local link, it cannot be considered -- a substitute for DNS. Link-scope multicast addresses are used to -- prevent propagation of LLMNR traffic across routers, potentially -- flooding the network. LLMNR queries can also be sent to a unicast -- address, as described in Section 2.4. -- -- Propagation of LLMNR packets on the local link is considered -- sufficient to enable name resolution in small networks. In such -- networks, if a network has a gateway, then typically the network is -- able to provide DNS server configuration. Configuration issues are -- discussed in Section 3.1. -- -- In the future, it may be desirable to consider use of multicast name -- resolution with multicast scopes beyond the link-scope. This could -- occur if LLMNR deployment is successful, the need arises for -- multicast name resolution beyond the link-scope, or multicast routing -- becomes ubiquitous. For example, expanded support for multicast name -- resolution might be required for mobile ad-hoc networks. -- -- Once we have experience in LLMNR deployment in terms of -- administrative issues, usability and impact on the network, it will -- be possible to reevaluate which multicast scopes are appropriate for -- use with multicast name resolution. IPv4 administratively scoped -- multicast usage is specified in "Administratively Scoped IP -- Multicast" [RFC2365]. -- -- Service discovery in general, as well as discovery of DNS servers -- using LLMNR in particular, is outside of the scope of this document, -- as is name resolution over non-multicast capable media. -- --1.1. Requirements -- -- In this document, several words are used to signify the requirements -- of the specification. The key words "MUST", "MUST NOT", "REQUIRED", -- "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", -- and "OPTIONAL" in this document are to be interpreted as described in -- [RFC2119]. -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 3] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --1.2. Terminology -- -- This document assumes familiarity with DNS terminology defined in -- [RFC1035]. Other terminology used in this document includes: -- --Routable Address -- An address other than a Link-Local address. This includes globally -- routable addresses, as well as private addresses. -- --Reachable -- An LLMNR responder considers one of its addresses reachable over a -- link if it will respond to an ARP or Neighbor Discovery query for -- that address received on that link. -- --Responder -- A host that listens to LLMNR queries, and responds to those for -- which it is authoritative. -- --Sender -- A host that sends an LLMNR query. -- --UNIQUE -- There are some scenarios when multiple responders may respond to -- the same query. There are other scenarios when only one responder -- may respond to a query. Names for which only a single responder is -- anticipated are referred to as UNIQUE. Name uniqueness is -- configured on the responder, and therefore uniqueness verification -- is the responder's responsibility. -- --2. Name Resolution Using LLMNR -- -- LLMNR queries are sent to and received on port 5355. The IPv4 link- -- scope multicast address a given responder listens to, and to which a -- sender sends queries, is 224.0.0.252. The IPv6 link-scope multicast -- address a given responder listens to, and to which a sender sends all -- queries, is FF02:0:0:0:0:0:1:3. -- -- Typically a host is configured as both an LLMNR sender and a -- responder. A host MAY be configured as a sender, but not a -- responder. However, a host configured as a responder MUST act as a -- sender, if only to verify the uniqueness of names as described in -- Section 4. This document does not specify how names are chosen or -- configured. This may occur via any mechanism, including DHCPv4 -- [RFC2131] or DHCPv6 [RFC3315]. -- -- A typical sequence of events for LLMNR usage is as follows: -- -- [a] An LLMNR sender sends an LLMNR query to the link-scope -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 4] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- multicast address(es), unless a unicast query is indicated, -- as specified in Section 2.4. -- -- [b] A responder responds to this query only if it is authoritative -- for the name in the query. A responder responds to a -- multicast query by sending a unicast UDP response to the sender. -- Unicast queries are responded to as indicated in Section 2.4. -- -- [c] Upon reception of the response, the sender processes it. -- -- The sections that follow provide further details on sender and -- responder behavior. -- --2.1. LLMNR Packet Format -- -- LLMNR is based on the DNS packet format defined in [RFC1035] Section -- 4 for both queries and responses. LLMNR implementations SHOULD send -- UDP queries and responses only as large as are known to be -- permissible without causing fragmentation. When in doubt a maximum -- packet size of 512 octets SHOULD be used. LLMNR implementations MUST -- accept UDP queries and responses as large as the smaller of the link -- MTU or 9194 octets (Ethernet jumbo frame size of 9KB (9216) minus 22 -- octets for the header, VLAN tag and CRC). -- --2.1.1. LLMNR Header Format -- -- LLMNR queries and responses utilize the DNS header format defined in -- [RFC1035] with exceptions noted below: -- -- 1 1 1 1 1 1 -- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- | ID | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- |QR| Opcode | C|TC| T| Z| Z| Z| Z| RCODE | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- | QDCOUNT | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- | ANCOUNT | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- | NSCOUNT | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- | ARCOUNT | -- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -- -- where: -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 5] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --ID A 16 bit identifier assigned by the program that generates any kind -- of query. This identifier is copied from the query to the response -- and can be used by the sender to match responses to outstanding -- queries. The ID field in a query SHOULD be set to a pseudo-random -- value. For advice on generation of pseudo-random values, please -- consult [RFC1750]. -- --QR Query/Response. A one bit field, which if set indicates that the -- message is an LLMNR response; if clear then the message is an LLMNR -- query. -- --OPCODE -- A four bit field that specifies the kind of query in this message. -- This value is set by the originator of a query and copied into the -- response. This specification defines the behavior of standard -- queries and responses (opcode value of zero). Future -- specifications may define the use of other opcodes with LLMNR. -- LLMNR senders and responders MUST support standard queries (opcode -- value of zero). LLMNR queries with unsupported OPCODE values MUST -- be silently discarded by responders. -- --C Conflict. When set within a request, the 'C'onflict bit indicates -- that a sender has received multiple LLMNR responses to this query. -- In an LLMNR response, if the name is considered UNIQUE, then the -- 'C' bit is clear, otherwise it is set. LLMNR senders do not -- retransmit queries with the 'C' bit set. Responders MUST NOT -- respond to LLMNR queries with the 'C' bit set, but may start the -- uniqueness verification process, as described in Section 4.2. -- --TC TrunCation - specifies that this message was truncated due to -- length greater than that permitted on the transmission channel. -- The TC bit MUST NOT be set in an LLMNR query and if set is ignored -- by an LLMNR responder. If the TC bit is set in an LLMNR response, -- then the sender SHOULD resend the LLMNR query over TCP using the -- unicast address of the responder as the destination address. If -- the sender receives a response to the TCP query, then it SHOULD -- discard the UDP response with the TC bit set. See [RFC2181] and -- Section 2.4 of this specification for further discussion of the TC -- bit. -- --T Tentative. The 'T'entative bit is set in a response if the -- responder is authoritative for the name, but has not yet verified -- the uniqueness of the name. A responder MUST ignore the 'T' bit in -- a query, if set. A response with the 'T' bit set is silently -- discarded by the sender, except if it is a uniqueness query, in -- which case a conflict has been detected and a responder MUST -- resolve the conflict as described in Section 4.1. -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 6] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --Z Reserved for future use. Implementations of this specification -- MUST set these bits to zero in both queries and responses. If -- these bits are set in a LLMNR query or response, implementations of -- this specification MUST ignore them. Since reserved bits could -- conceivably be used for different purposes than in DNS, -- implementors are advised not to enable processing of these bits in -- an LLMNR implementation starting from a DNS code base. -- --RCODE -- Response code -- this 4 bit field is set as part of LLMNR -- responses. In an LLMNR query, the sender MUST set RCODE to zero; -- the responder ignores the RCODE and assumes it to be zero. The -- response to a multicast LLMNR query MUST have RCODE set to zero. A -- sender MUST silently discard an LLMNR response with a non-zero -- RCODE sent in response to a multicast query. -- -- If an LLMNR responder is authoritative for the name in a multicast -- query, but an error is encountered, the responder SHOULD send an -- LLMNR response with an RCODE of zero, no RRs in the answer section, -- and the TC bit set. This will cause the query to be resent using -- TCP, and allow the inclusion of a non-zero RCODE in the response to -- the TCP query. Responding with the TC bit set is preferable to not -- sending a response, since it enables errors to be diagnosed. This -- may be required, for example, when an LLMNR query includes a TSIG -- RR in the additional section, and the responder encounters a -- problem that requires returning a non-zero RCODE. TSIG error -- conditions defined in [RFC2845] include a TSIG RR in an -- unacceptable position (RCODE=1) or a TSIG RR which does not -- validate (RCODE=9 with TSIG ERROR 17 (BADKEY) or 16 (BADSIG)). -- -- Since LLMNR responders only respond to LLMNR queries for names for -- which they are authoritative, LLMNR responders MUST NOT respond -- with an RCODE of 3; instead, they should not respond at all. -- -- LLMNR implementations MUST support EDNS0 [RFC2671] and extended -- RCODE values. -- --QDCOUNT -- An unsigned 16 bit integer specifying the number of entries in the -- question section. A sender MUST place only one question into the -- question section of an LLMNR query. LLMNR responders MUST silently -- discard LLMNR queries with QDCOUNT not equal to one. LLMNR senders -- MUST silently discard LLMNR responses with QDCOUNT not equal to -- one. -- --ANCOUNT -- An unsigned 16 bit integer specifying the number of resource -- records in the answer section. LLMNR responders MUST silently -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 7] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- discard LLMNR queries with ANCOUNT not equal to zero. -- --NSCOUNT -- An unsigned 16 bit integer specifying the number of name server -- resource records in the authority records section. Authority -- record section processing is described in Section 2.9. LLMNR -- responders MUST silently discard LLMNR queries with NSCOUNT not -- equal to zero. -- --ARCOUNT -- An unsigned 16 bit integer specifying the number of resource -- records in the additional records section. Additional record -- section processing is described in Section 2.9. -- --2.2. Sender Behavior -- -- A sender MAY send an LLMNR query for any legal resource record type -- (e.g., A, AAAA, PTR, SRV, etc.) to the link-scope multicast address. -- As described in Section 2.4, a sender MAY also send a unicast query. -- -- The sender MUST anticipate receiving no replies to some LLMNR -- queries, in the event that no responders are available within the -- link-scope. If no response is received, a resolver treats it as a -- response that the name does not exist (RCODE=3 is returned). A -- sender can handle duplicate responses by discarding responses with a -- source IP address and ID field that duplicate a response already -- received. -- -- When multiple valid LLMNR responses are received with the 'C' bit -- set, they SHOULD be concatenated and treated in the same manner that -- multiple RRs received from the same DNS server would be. However, -- responses with the 'C' bit set SHOULD NOT be concatenated with -- responses with the 'C' bit clear; instead, only the responses with -- the 'C' bit set SHOULD be returned. If valid LLMNR response(s) are -- received along with error response(s), then the error responses are -- silently discarded. -- -- Since the responder may order the RRs in the response so as to -- indicate preference, the sender SHOULD preserve ordering in the -- response to the querying application. -- --2.3. Responder Behavior -- -- An LLMNR response MUST be sent to the sender via unicast. -- -- Upon configuring an IP address, responders typically will synthesize -- corresponding A, AAAA and PTR RRs so as to be able to respond to -- LLMNR queries for these RRs. An SOA RR is synthesized only when a -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 8] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- responder has another RR in addition to the SOA RR; the SOA RR MUST -- NOT be the only RR that a responder has. However, in general whether -- RRs are manually or automatically created is an implementation -- decision. -- -- For example, a host configured to have computer name "host1" and to -- be a member of the "example.com" domain, and with IPv4 address -- 192.0.2.1 and IPv6 address 2001:0DB8::1:2:3:FF:FE:4:5:6 might be -- authoritative for the following records: -- -- host1. IN A 192.0.2.1 -- IN AAAA 2001:0DB8::1:2:3:FF:FE:4:5:6 -- -- host1.example.com. IN A 192.0.2.1 -- IN AAAA 2001:0DB8::1:2:3:FF:FE:4:5:6 -- -- 1.2.0.192.in-addr.arpa. IN PTR host1. -- IN PTR host1.example.com. -- -- 6.0.5.0.4.0.E.F.F.F.3.0.2.0.1.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2. -- ip6.arpa IN PTR host1. (line split for formatting reasons) -- IN PTR host1.example.com. -- -- An LLMNR responder might be further manually configured with the name -- of a local mail server with an MX RR included in the "host1." and -- "host1.example.com." records. -- -- In responding to queries: -- --[a] Responders MUST listen on UDP port 5355 on the link-scope multicast -- address(es) defined in Section 2, and on TCP port 5355 on the -- unicast address(es) that could be set as the source address(es) -- when the responder responds to the LLMNR query. -- --[b] Responders MUST direct responses to the port from which the query -- was sent. When queries are received via TCP this is an inherent -- part of the transport protocol. For queries received by UDP the -- responder MUST take note of the source port and use that as the -- destination port in the response. Responses MUST always be sent -- from the port to which they were directed. -- --[c] Responders MUST respond to LLMNR queries for names and addresses -- they are authoritative for. This applies to both forward and -- reverse lookups, with the exception of queries with the 'C' bit -- set, which do not elicit a response. -- --[d] Responders MUST NOT respond to LLMNR queries for names they are not -- authoritative for. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 9] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --[e] Responders MUST NOT respond using data from the LLMNR or DNS -- resolver cache. -- --[f] If a DNS server is running on a host that supports LLMNR, the DNS -- server MUST respond to LLMNR queries only for the RRSets relating -- to the host on which the server is running, but MUST NOT respond -- for other records for which the server is authoritative. DNS -- servers also MUST NOT send LLMNR queries in order to resolve DNS -- queries. -- --[g] If a responder is authoritative for a name, it MUST respond with -- RCODE=0 and an empty answer section, if the type of query does not -- match a RR that the responder has. -- -- As an example, a host configured to respond to LLMNR queries for the -- name "foo.example.com." is authoritative for the name -- "foo.example.com.". On receiving an LLMNR query for an A RR with the -- name "foo.example.com." the host authoritatively responds with A -- RR(s) that contain IP address(es) in the RDATA of the resource -- record. If the responder has a AAAA RR, but no A RR, and an A RR -- query is received, the responder would respond with RCODE=0 and an -- empty answer section. -- -- In conventional DNS terminology a DNS server authoritative for a zone -- is authoritative for all the domain names under the zone apex except -- for the branches delegated into separate zones. Contrary to -- conventional DNS terminology, an LLMNR responder is authoritative -- only for the zone apex. -- -- For example the host "foo.example.com." is not authoritative for the -- name "child.foo.example.com." unless the host is configured with -- multiple names, including "foo.example.com." and -- "child.foo.example.com.". As a result, "foo.example.com." cannot -- reply to an LLMNR query for "child.foo.example.com." with RCODE=3 -- (authoritative name error). The purpose of limiting the name -- authority scope of a responder is to prevent complications that could -- be caused by coexistence of two or more hosts with the names -- representing child and parent (or grandparent) nodes in the DNS tree, -- for example, "foo.example.com." and "child.foo.example.com.". -- -- Without the restriction on authority an LLMNR query for an A resource -- record for the name "child.foo.example.com." would result in two -- authoritative responses: RCODE=3 (authoritative name error) received -- from "foo.example.com.", and a requested A record - from -- "child.foo.example.com.". To prevent this ambiguity, LLMNR enabled -- hosts could perform a dynamic update of the parent (or grandparent) -- zone with a delegation to a child zone; for example a host -- "child.foo.example.com." could send a dynamic update for the NS and -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 10] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- glue A record to "foo.example.com.". However, this approach -- significantly complicates implementation of LLMNR and would not be -- acceptable for lightweight hosts. -- --2.4. Unicast Queries and Responses -- -- Unicast queries SHOULD be sent when: -- -- [a] A sender repeats a query after it received a response -- with the TC bit set to the previous LLMNR multicast query, or -- -- [b] The sender queries for a PTR RR of a fully formed IP address -- within the "in-addr.arpa" or "ip6.arpa" zones. -- -- Unicast LLMNR queries MUST be done using TCP and the responses MUST -- be sent using the same TCP connection as the query. Senders MUST -- support sending TCP queries, and responders MUST support listening -- for TCP queries. If the sender of a TCP query receives a response to -- that query not using TCP, the response MUST be silently discarded. -- -- Unicast UDP queries MUST be silently discarded. -- -- A unicast PTR RR query for an off-link address will not elicit a -- response, but instead an ICMP TTL or Hop Limit exceeded message will -- be received. An implementation receiving an ICMP message in response -- to a TCP connection setup attempt can return immediately, treating -- this as a response that no such name exists (RCODE=3 is returned). -- An implementation that cannot process ICMP messages MAY send -- multicast UDP queries for PTR RRs. Since TCP implementations will -- not retransmit prior to RTOmin, a considerable period will elapse -- before TCP retransmits multiple times, resulting in a long timeout -- for TCP PTR RR queries sent to an off-link destination. -- --2.5. "Off link" Detection -- -- A sender MUST select a source address for LLMNR queries that is -- assigned on the interface on which the query is sent. The -- destination address of an LLMNR query MUST be a link-scope multicast -- address or a unicast address. -- -- A responder MUST select a source address for responses that is -- assigned on the interface on which the query was received. The -- destination address of an LLMNR response MUST be a unicast address. -- -- On receiving an LLMNR query, the responder MUST check whether it was -- sent to a LLMNR multicast addresses defined in Section 2. If it was -- sent to another multicast address, then the query MUST be silently -- discarded. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 11] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- Section 2.4 discusses use of TCP for LLMNR queries and responses. In -- composing an LLMNR query using TCP, the sender MUST set the Hop Limit -- field in the IPv6 header and the TTL field in the IPv4 header of the -- response to one (1). The responder SHOULD set the TTL or Hop Limit -- settings on the TCP listen socket to one (1) so that SYN-ACK packets -- will have TTL (IPv4) or Hop Limit (IPv6) set to one (1). This -- prevents an incoming connection from off-link since the sender will -- not receive a SYN-ACK from the responder. -- -- For UDP queries and responses, the Hop Limit field in the IPv6 header -- and the TTL field in the IPV4 header MAY be set to any value. -- However, it is RECOMMENDED that the value 255 be used for -- compatibility with early implementations of [RFC3927]. -- -- Implementation note: -- -- In the sockets API for IPv4 [POSIX], the IP_TTL and -- IP_MULTICAST_TTL socket options are used to set the TTL of -- outgoing unicast and multicast packets. The IP_RECVTTL socket -- option is available on some platforms to retrieve the IPv4 TTL of -- received packets with recvmsg(). [RFC2292] specifies similar -- options for setting and retrieving the IPv6 Hop Limit. -- --2.6. Responder Responsibilities -- -- It is the responsibility of the responder to ensure that RRs returned -- in LLMNR responses MUST only include values that are valid on the -- local interface, such as IPv4 or IPv6 addresses valid on the local -- link or names defended using the mechanism described in Section 4. -- IPv4 Link-Local addresses are defined in [RFC3927]. IPv6 Link-Local -- addresses are defined in [RFC2373]. In particular: -- -- [a] If a link-scope IPv6 address is returned in a AAAA RR, -- that address MUST be valid on the local link over which -- LLMNR is used. -- -- [b] If an IPv4 address is returned, it MUST be reachable -- through the link over which LLMNR is used. -- -- [c] If a name is returned (for example in a CNAME, MX -- or SRV RR), the name MUST be resolvable on the local -- link over which LLMNR is used. -- -- Where multiple addresses represent valid responses to a query, the -- order in which the addresses are returned is as follows: -- -- [d] If the source address of the query is a link-scope address, -- then the responder SHOULD include a link-scope address first -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 12] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- in the response, if available. -- -- [e] If the source address of the query is a routable address, -- then the responder MUST include a routable address first -- in the response, if available. -- --2.7. Retransmission and Jitter -- -- An LLMNR sender uses the timeout interval LLMNR_TIMEOUT to determine -- when to retransmit an LLMNR query. An LLMNR sender SHOULD either -- estimate the LLMNR_TIMEOUT for each interface, or set a reasonably -- high initial timeout. Suggested constants are described in Section -- 7. -- -- If an LLMNR query sent over UDP is not resolved within LLMNR_TIMEOUT, -- then a sender SHOULD repeat the transmission of the query in order to -- assure that it was received by a host capable of responding to it. -- An LLMNR query SHOULD NOT be sent more than three times. -- -- Where LLMNR queries are sent using TCP, retransmission is handled by -- the transport layer. Queries with the 'C' bit set MUST be sent using -- multicast UDP and MUST NOT be retransmitted. -- -- An LLMNR sender cannot know in advance if a query sent using -- multicast will receive no response, one response, or more than one -- response. An LLMNR sender MUST wait for LLMNR_TIMEOUT if no response -- has been received, or if it is necessary to collect all potential -- responses, such as if a uniqueness verification query is being made. -- Otherwise an LLMNR sender SHOULD consider a multicast query answered -- after the first response is received, if that response has the 'C' -- bit clear. -- -- However, if the first response has the 'C' bit set, then the sender -- SHOULD wait for LLMNR_TIMEOUT + JITTER_INTERVAL in order to collect -- all possible responses. When multiple valid answers are received, -- they may first be concatenated, and then treated in the same manner -- that multiple RRs received from the same DNS server would. A unicast -- query sender considers the query answered after the first response is -- received. -- -- Since it is possible for a response with the 'C' bit clear to be -- followed by a response with the 'C' bit set, an LLMNR sender SHOULD -- be prepared to process additional responses for the purposes of -- conflict detection, even after it has considered a query answered. -- -- In order to avoid synchronization, the transmission of each LLMNR -- query and response SHOULD delayed by a time randomly selected from -- the interval 0 to JITTER_INTERVAL. This delay MAY be avoided by -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 13] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- responders responding with names which they have previously -- determined to be UNIQUE (see Section 4 for details). -- --2.8. DNS TTL -- -- The responder should insert a pre-configured TTL value in the records -- returned in an LLMNR response. A default value of 30 seconds is -- RECOMMENDED. In highly dynamic environments (such as mobile ad-hoc -- networks), the TTL value may need to be reduced. -- -- Due to the TTL minimalization necessary when caching an RRset, all -- TTLs in an RRset MUST be set to the same value. -- --2.9. Use of the Authority and Additional Sections -- -- Unlike the DNS, LLMNR is a peer-to-peer protocol and does not have a -- concept of delegation. In LLMNR, the NS resource record type may be -- stored and queried for like any other type, but it has no special -- delegation semantics as it does in the DNS. Responders MAY have NS -- records associated with the names for which they are authoritative, -- but they SHOULD NOT include these NS records in the authority -- sections of responses. -- -- Responders SHOULD insert an SOA record into the authority section of -- a negative response, to facilitate negative caching as specified in -- [RFC2308]. The TTL of this record is set from the minimum of the -- MINIMUM field of the SOA record and the TTL of the SOA itself, and -- indicates how long a resolver may cache the negative answer. The -- owner name of the SOA record (MNAME) MUST be set to the query name. -- The RNAME, SERIAL, REFRESH, RETRY and EXPIRE values MUST be ignored -- by senders. Negative responses without SOA records SHOULD NOT be -- cached. -- -- In LLMNR, the additional section is primarily intended for use by -- EDNS0, TSIG and SIG(0). As a result, unless the 'C' bit is set, -- senders MAY only include pseudo RR-types in the additional section of -- a query; unless the 'C' bit is set, responders MUST ignore the -- additional section of queries containing other RR types. -- -- In queries where the 'C' bit is set, the sender SHOULD include the -- conflicting RRs in the additional section. Since conflict -- notifications are advisory, responders SHOULD log information from -- the additional section, but otherwise MUST ignore the additional -- section. -- -- Senders MUST NOT cache RRs from the authority or additional section -- of a response as answers, though they may be used for other purposes -- such as negative caching. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 14] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --3. Usage Model -- -- LLMNR is a peer-to-peer name resolution protocol that is not intended -- as a replacement for DNS; rather, it enables name resolution in -- scenarios in which conventional DNS name resolution is not possible. -- This includes situations in which hosts are not configured with the -- address of a DNS server; where the DNS server is unavailable or -- unreachable; where there is no DNS server authoritative for the name -- of a host, or where the authoritative DNS server does not have the -- desired RRs. -- -- By default, an LLMNR sender SHOULD send LLMNR queries only for -- single-label names. In order to reduce unnecessary DNS queries, stub -- resolvers supporting both DNS and LLMNR SHOULD avoid sending DNS -- queries for single-label names. An LLMNR sender SHOULD NOT be -- enabled to send a query for any name, except where security -- mechanisms (described in Section 5.3) can be utilized. -- -- Regardless of whether security mechanisms can be utilized, LLMNR -- queries SHOULD NOT be sent unless one of the following conditions are -- met: -- -- [1] No manual or automatic DNS configuration has been performed. -- If DNS server address(es) have been configured, a -- host SHOULD attempt to reach DNS servers over all protocols -- on which DNS server address(es) are configured, prior to sending -- LLMNR queries. For dual stack hosts configured with DNS server -- address(es) for one protocol but not another, this implies that -- DNS queries SHOULD be sent over the protocol configured with -- a DNS server, prior to sending LLMNR queries. -- -- [2] All attempts to resolve the name via DNS on all interfaces -- have failed after exhausting the searchlist. This can occur -- because DNS servers did not respond, or because they -- responded to DNS queries with RCODE=3 (Authoritative Name -- Error) or RCODE=0, and an empty answer section. Where a -- single resolver call generates DNS queries for A and AAAA RRs, -- an implementation MAY choose not to send LLMNR queries if any -- of the DNS queries is successful. An LLMNR query SHOULD only -- be sent for the originally requested name; a searchlist -- is not used to form additional LLMNR queries. -- -- Since LLMNR is a secondary name resolution mechanism, its usage is in -- part determined by the behavior of DNS implementations. In general, -- robust DNS resolver implementations are more likely to avoid -- unnecessary LLMNR queries. -- -- As noted in [DNSPerf], even when DNS servers are configured, a -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 15] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- significant fraction of DNS queries do not receive a response, or -- result in negative responses due to missing inverse mappings or NS -- records that point to nonexistent or inappropriate hosts. This has -- the potential to result in a large number of unnecessary LLMNR -- queries. -- -- [RFC1536] describes common DNS implementation errors and fixes. If -- the proposed fixes are implemented, unnecessary LLMNR queries will be -- reduced substantially, and so implementation of [RFC1536] is -- recommended. -- -- For example, [RFC1536] Section 1 describes issues with retransmission -- and recommends implementation of a retransmission policy based on -- round trip estimates, with exponential back-off. [RFC1536] Section 4 -- describes issues with failover, and recommends that resolvers try -- another server when they don't receive a response to a query. These -- policies are likely to avoid unnecessary LLMNR queries. -- -- [RFC1536] Section 3 describes zero answer bugs, which if addressed -- will also reduce unnecessary LLMNR queries. -- -- [RFC1536] Section 6 describes name error bugs and recommended -- searchlist processing that will reduce unnecessary RCODE=3 -- (authoritative name) errors, thereby also reducing unnecessary LLMNR -- queries. -- -- If error responses are received from both DNS and LLMNR, then the -- lowest RCODE value should be returned. For example, if either DNS or -- LLMNR receives a response with RCODE=0, then this should returned to -- the caller. -- --3.1. LLMNR Configuration -- -- LLMNR usage MAY be configured manually or automatically on a per -- interface basis. By default, LLMNR responders SHOULD be enabled on -- all interfaces, at all times. Enabling LLMNR for use in situations -- where a DNS server has been configured will result in a change in -- default behavior without a simultaneous update to configuration -- information. Where this is considered undesirable, LLMNR SHOULD NOT -- be enabled by default, so that hosts will neither listen on the link- -- scope multicast address, nor will they send queries to that address. -- -- Since IPv4 and IPv6 utilize distinct configuration mechanisms, it is -- possible for a dual stack host to be configured with the address of a -- DNS server over IPv4, while remaining unconfigured with a DNS server -- suitable for use over IPv6. -- -- In these situations, a dual stack host will send AAAA queries to the -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 16] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- configured DNS server over IPv4. However, an IPv6-only host -- unconfigured with a DNS server suitable for use over IPv6 will be -- unable to resolve names using DNS. Automatic IPv6 DNS configuration -- mechanisms (such as [RFC3315] and [DNSDisc]) are not yet widely -- deployed, and not all DNS servers support IPv6. Therefore lack of -- IPv6 DNS configuration may be a common problem in the short term, and -- LLMNR may prove useful in enabling link-local name resolution over -- IPv6. -- -- Where a DHCPv4 server is available but not a DHCPv6 server [RFC3315], -- IPv6-only hosts may not be configured with a DNS server. Where there -- is no DNS server authoritative for the name of a host or the -- authoritative DNS server does not support dynamic client update over -- IPv6 or DHCPv6-based dynamic update, then an IPv6-only host will not -- be able to do DNS dynamic update, and other hosts will not be able to -- resolve its name. -- -- For example, if the configured DNS server responds to a AAAA RR query -- sent over IPv4 or IPv6 with an authoritative name error (RCODE=3) or -- RCODE=0 and an empty answer section, then a AAAA RR query sent using -- LLMNR over IPv6 may be successful in resolving the name of an -- IPv6-only host on the local link. -- -- Similarly, if a DHCPv4 server is available providing DNS server -- configuration, and DNS server(s) exist which are authoritative for -- the A RRs of local hosts and support either dynamic client update -- over IPv4 or DHCPv4-based dynamic update, then the names of local -- IPv4 hosts can be resolved over IPv4 without LLMNR. However, if no -- DNS server is authoritative for the names of local hosts, or the -- authoritative DNS server(s) do not support dynamic update, then LLMNR -- enables linklocal name resolution over IPv4. -- -- Where DHCPv4 or DHCPv6 is implemented, DHCP options can be used to -- configure LLMNR on an interface. The LLMNR Enable Option, described -- in [LLMNREnable], can be used to explicitly enable or disable use of -- LLMNR on an interface. The LLMNR Enable Option does not determine -- whether or in which order DNS itself is used for name resolution. -- The order in which various name resolution mechanisms should be used -- can be specified using the Name Service Search Option (NSSO) for DHCP -- [RFC2937], using the LLMNR Enable Option code carried in the NSSO -- data. -- -- It is possible that DNS configuration mechanisms will go in and out -- of service. In these circumstances, it is possible for hosts within -- an administrative domain to be inconsistent in their DNS -- configuration. -- -- For example, where DHCP is used for configuring DNS servers, one or -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 17] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- more DHCP servers can fail. As a result, hosts configured prior to -- the outage will be configured with a DNS server, while hosts -- configured after the outage will not. Alternatively, it is possible -- for the DNS configuration mechanism to continue functioning while -- configured DNS servers fail. -- -- An outage in the DNS configuration mechanism may result in hosts -- continuing to use LLMNR even once the outage is repaired. Since -- LLMNR only enables linklocal name resolution, this represents a -- degradation in capabilities. As a result, hosts without a configured -- DNS server may wish to periodically attempt to obtain DNS -- configuration if permitted by the configuration mechanism in use. In -- the absence of other guidance, a default retry interval of one (1) -- minute is RECOMMENDED. -- --4. Conflict Resolution -- -- By default, a responder SHOULD be configured to behave as though its -- name is UNIQUE on each interface on which LLMNR is enabled. However, -- it is also possible to configure multiple responders to be -- authoritative for the same name. For example, multiple responders -- MAY respond to a query for an A or AAAA type record for a cluster -- name (assigned to multiple hosts in the cluster). -- -- To detect duplicate use of a name, an administrator can use a name -- resolution utility which employs LLMNR and lists both responses and -- responders. This would allow an administrator to diagnose behavior -- and potentially to intervene and reconfigure LLMNR responders who -- should not be configured to respond to the same name. -- --4.1. Uniqueness Verification -- -- Prior to sending an LLMNR response with the 'T' bit clear, a -- responder configured with a UNIQUE name MUST verify that there is no -- other host within the scope of LLMNR query propagation that is -- authoritative for the same name on that interface. -- -- Once a responder has verified that its name is UNIQUE, if it receives -- an LLMNR query for that name, with the 'C' bit clear, it MUST -- respond, with the 'T' bit clear. Prior to verifying that its name is -- UNIQUE, a responder MUST set the 'T' bit in responses. -- -- Uniqueness verification is carried out when the host: -- -- - starts up or is rebooted -- - wakes from sleep (if the network interface was inactive -- during sleep) -- - is configured to respond to LLMNR queries on an interface -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 18] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- enabled for transmission and reception of IP traffic -- - is configured to respond to LLMNR queries using additional -- UNIQUE resource records -- - verifies the acquisition of a new IP address and configuration -- on an interface -- -- To verify uniqueness, a responder MUST send an LLMNR query with the -- 'C' bit clear, over all protocols on which it responds to LLMNR -- queries (IPv4 and/or IPv6). It is RECOMMENDED that responders verify -- uniqueness of a name by sending a query for the name with type='ANY'. -- -- If no response is received, the sender retransmits the query, as -- specified in Section 2.7. If a response is received, the sender MUST -- check if the source address matches the address of any of its -- interfaces; if so, then the response is not considered a conflict, -- since it originates from the sender. To avoid triggering conflict -- detection, a responder that detects that it is connected to the same -- link on multiple interfaces SHOULD set the 'C' bit in responses. -- -- If a response is received with the 'T' bit clear, the responder MUST -- NOT use the name in response to LLMNR queries received over any -- protocol (IPv4 or IPv6). If a response is received with the 'T' bit -- set, the responder MUST check if the source IP address in the -- response, interpreted as an unsigned integer, is less than the source -- IP address in the query. If so, the responder MUST NOT use the name -- in response to LLMNR queries received over any protocol (IPv4 or -- IPv6). For the purpose of uniqueness verification, the contents of -- the answer section in a response is irrelevant. -- -- Periodically carrying out uniqueness verification in an attempt to -- detect name conflicts is not necessary, wastes network bandwidth, and -- may actually be detrimental. For example, if network links are -- joined only briefly, and are separated again before any new -- communication is initiated, temporary conflicts are benign and no -- forced reconfiguration is required. LLMNR responders SHOULD NOT -- periodically attempt uniqueness verification. -- --4.2. Conflict Detection and Defense -- -- Hosts on disjoint network links may configure the same name for use -- with LLMNR. If these separate network links are later joined or -- bridged together, then there may be multiple hosts which are now on -- the same link, trying to use the same name. -- -- In order to enable ongoing detection of name conflicts, when an LLMNR -- sender receives multiple LLMNR responses to a query, it MUST check if -- the 'C' bit is clear in any of the responses. If so, the sender -- SHOULD send another query for the same name, type and class, this -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 19] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- time with the 'C' bit set, with the potentially conflicting resource -- records included in the additional section. -- -- Queries with the 'C' bit set are considered advisory and responders -- MUST verify the existence of a conflict before acting on it. A -- responder receiving a query with the 'C' bit set MUST NOT respond. -- -- If the query is for a UNIQUE name, then the responder MUST send its -- own query for the same name, type and class, with the 'C' bit clear. -- If a response is received, the sender MUST check if the source -- address matches the address of any of its interfaces; if so, then the -- response is not considered a conflict, since it originates from the -- sender. To avoid triggering conflict detection, a responder that -- detects that it is connected to the same link on multiple interfaces -- SHOULD set the 'C' bit in responses. -- -- An LLMNR responder MUST NOT ignore conflicts once detected and SHOULD -- log them. Upon detecting a conflict, an LLMNR responder MUST -- immediately stop using the conflicting name in response to LLMNR -- queries received over any supported protocol, if the source IP -- address in the response, interpreted as an unsigned integer, is less -- than the source IP address in the uniqueness verification query. -- -- After stopping the use of a name, the responder MAY elect to -- configure a new name. However, since name reconfiguration may be -- disruptive, this is not required, and a responder may have been -- configured to respond to multiple names so that alternative names may -- already be available. A host that has stopped the use of a name may -- attempt uniqueness verification again after the expiration of the TTL -- of the conflicting response. -- --4.3. Considerations for Multiple Interfaces -- -- A multi-homed host may elect to configure LLMNR on only one of its -- active interfaces. In many situations this will be adequate. -- However, should a host need to configure LLMNR on more than one of -- its active interfaces, there are some additional precautions it MUST -- take. Implementers who are not planning to support LLMNR on multiple -- interfaces simultaneously may skip this section. -- -- Where a host is configured to issue LLMNR queries on more than one -- interface, each interface maintains its own independent LLMNR -- resolver cache, containing the responses to LLMNR queries. -- -- A multi-homed host checks the uniqueness of UNIQUE records as -- described in Section 4. The situation is illustrated in figure 1. -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 20] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- ---------- ---------- -- | | | | -- [A] [myhost] [myhost] -- -- Figure 1. Link-scope name conflict -- -- In this situation, the multi-homed myhost will probe for, and defend, -- its host name on both interfaces. A conflict will be detected on one -- interface, but not the other. The multi-homed myhost will not be -- able to respond with a host RR for "myhost" on the interface on the -- right (see Figure 1). The multi-homed host may, however, be -- configured to use the "myhost" name on the interface on the left. -- -- Since names are only unique per-link, hosts on different links could -- be using the same name. If an LLMNR client sends requests over -- multiple interfaces, and receives replies from more than one, the -- result returned to the client is defined by the implementation. The -- situation is illustrated in figure 2. -- -- ---------- ---------- -- | | | | -- [A] [myhost] [A] -- -- -- Figure 2. Off-segment name conflict -- -- If host myhost is configured to use LLMNR on both interfaces, it will -- send LLMNR queries on both interfaces. When host myhost sends a -- query for the host RR for name "A" it will receive a response from -- hosts on both interfaces. -- -- Host myhost cannot distinguish between the situation shown in Figure -- 2, and that shown in Figure 3 where no conflict exists. -- -- [A] -- | | -- ----- ----- -- | | -- [myhost] -- -- Figure 3. Multiple paths to same host -- -- This illustrates that the proposed name conflict resolution mechanism -- does not support detection or resolution of conflicts between hosts -- on different links. This problem can also occur with DNS when a -- multi-homed host is connected to two different networks with -- separated name spaces. It is not the intent of this document to -- address the issue of uniqueness of names within DNS. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 21] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --4.4. API Issues -- -- [RFC2553] provides an API which can partially solve the name -- ambiguity problem for applications written to use this API, since the -- sockaddr_in6 structure exposes the scope within which each scoped -- address exists, and this structure can be used for both IPv4 (using -- v4-mapped IPv6 addresses) and IPv6 addresses. -- -- Following the example in Figure 2, an application on 'myhost' issues -- the request getaddrinfo("A", ...) with ai_family=AF_INET6 and -- ai_flags=AI_ALL|AI_V4MAPPED. LLMNR requests will be sent from both -- interfaces and the resolver library will return a list containing -- multiple addrinfo structures, each with an associated sockaddr_in6 -- structure. This list will thus contain the IPv4 and IPv6 addresses -- of both hosts responding to the name 'A'. Link-local addresses will -- have a sin6_scope_id value that disambiguates which interface is used -- to reach the address. Of course, to the application, Figures 2 and 3 -- are still indistinguishable, but this API allows the application to -- communicate successfully with any address in the list. -- --5. Security Considerations -- -- LLMNR is a peer-to-peer name resolution protocol designed for use on -- the local link. While LLMNR limits the vulnerability of responders -- to off-link senders, it is possible for an off-link responder to -- reach a sender. -- -- In scenarios such as public "hotspots" attackers can be present on -- the same link. These threats are most serious in wireless networks -- such as 802.11, since attackers on a wired network will require -- physical access to the network, while wireless attackers may mount -- attacks from a distance. Link-layer security such as [IEEE-802.11i] -- can be of assistance against these threats if it is available. -- -- This section details security measures available to mitigate threats -- from on and off-link attackers. -- --5.1. Denial of Service -- -- Attackers may take advantage of LLMNR conflict detection by -- allocating the same name, denying service to other LLMNR responders -- and possibly allowing an attacker to receive packets destined for -- other hosts. By logging conflicts, LLMNR responders can provide -- forensic evidence of these attacks. -- -- An attacker may spoof LLMNR queries from a victim's address in order -- to mount a denial of service attack. Responders setting the IPv6 Hop -- Limit or IPv4 TTL field to a value larger than one in an LLMNR UDP -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 22] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- response may be able to reach the victim across the Internet. -- -- While LLMNR responders only respond to queries for which they are -- authoritative and LLMNR does not provide wildcard query support, an -- LLMNR response may be larger than the query, and an attacker can -- generate multiple responses to a query for a name used by multiple -- responders. A sender may protect itself against unsolicited -- responses by silently discarding them as rapidly as possible. -- --5.2. Spoofing -- -- LLMNR is designed to prevent reception of queries sent by an off-link -- attacker. LLMNR requires that responders receiving UDP queries check -- that they are sent to a link-scope multicast address. However, it is -- possible that some routers may not properly implement link-scope -- multicast, or that link-scope multicast addresses may leak into the -- multicast routing system. To prevent successful setup of TCP -- connections by an off-link sender, responders receiving a TCP SYN -- reply with a TCP SYN-ACK with TTL set to one (1). -- -- While it is difficult for an off-link attacker to send an LLMNR query -- to a responder, it is possible for an off-link attacker to spoof a -- response to a query (such as an A or AAAA query for a popular -- Internet host), and by using a TTL or Hop Limit field larger than one -- (1), for the forged response to reach the LLMNR sender. Since the -- forged response will only be accepted if it contains a matching ID -- field, choosing a pseudo-random ID field within queries provides some -- protection against off-link responders. -- -- Since LLMNR queries can be sent when DNS server(s) do not respond, an -- attacker can execute a denial of service attack on the DNS server(s) -- and then poison the LLMNR cache by responding to an LLMNR query with -- incorrect information. As noted in "Threat Analysis of the Domain -- Name System (DNS)" [RFC3833] these threats also exist with DNS, since -- DNS response spoofing tools are available that can allow an attacker -- to respond to a query more quickly than a distant DNS server. -- However, while switched networks or link layer security may make it -- difficult for an on-link attacker to snoop unicast DNS queries, -- multicast LLMNR queries are propagated to all hosts on the link, -- making it possible for an on-link attacker to spoof LLMNR responses -- without having to guess the value of the ID field in the query. -- -- Since LLMNR queries are sent and responded to on the local-link, an -- attacker will need to respond more quickly to provide its own -- response prior to arrival of the response from a legitimate -- responder. If an LLMNR query is sent for an off-link host, spoofing -- a response in a timely way is not difficult, since a legitimate -- response will never be received. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 23] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- This vulnerability can be reduced by limiting use of LLMNR to -- resolution of single-label names as described in Section 3, or by -- implementation of authentication (see Section 5.3). -- --5.3. Authentication -- -- LLMNR is a peer-to-peer name resolution protocol, and as a result, -- it is often deployed in situations where no trust model can be -- assumed. Where a pre-arranged security configuration is possible, -- the following security mechanisms may be used: -- --[a] LLMNR implementations MAY support TSIG [RFC2845] and/or SIG(0) -- [RFC2931] security mechanisms. "DNS Name Service based on Secure -- Multicast DNS for IPv6 Mobile Ad Hoc Networks" [LLMNRSec] describes -- the use of TSIG to secure LLMNR, based on group keys. While group -- keys can be used to demonstrate membership in a group, they do not -- protect against forgery by an attacker that is a member of the -- group. -- --[b] IPsec ESP with a null-transform MAY be used to authenticate unicast -- LLMNR queries and responses or LLMNR responses to multicast -- queries. In a small network without a certificate authority, this -- can be most easily accomplished through configuration of a group -- pre-shared key for trusted hosts. As with TSIG, this does not -- protect against forgery by an attacker with access to the group -- pre-shared key. -- --[c] LLMNR implementations MAY support DNSSEC [RFC4033]. In order to -- support DNSSEC, LLMNR implementations MAY be configured with trust -- anchors, or they MAY make use of keys obtained from DNS queries. -- Since LLMNR does not support "delegated trust" (CD or AD bits), -- LLMNR implementations cannot make use of DNSSEC unless they are -- DNSSEC-aware and support validation. Unlike approaches [a] or [b], -- DNSSEC permits a responder to demonstrate ownership of a name, not -- just membership within a trusted group. As a result, it enables -- protection against forgery. -- --5.4. Cache and Port Separation -- -- In order to prevent responses to LLMNR queries from polluting the DNS -- cache, LLMNR implementations MUST use a distinct, isolated cache for -- LLMNR on each interface. The use of separate caches is most -- effective when LLMNR is used as a name resolution mechanism of last -- resort, since this minimizes the opportunities for poisoning the -- LLMNR cache, and decreases reliance on it. -- -- LLMNR operates on a separate port from DNS, reducing the likelihood -- that a DNS server will unintentionally respond to an LLMNR query. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 24] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- -- If LLMNR is given higher priority than DNS among the enabled name -- resolution mechanisms, a denial of service attack on the DNS server -- would not be necessary in order to poison the LLMNR cache, since -- LLMNR queries would be sent even when the DNS server is available. -- In addition, the LLMNR cache, once poisoned, would take precedence -- over the DNS cache, eliminating the benefits of cache separation. As -- a result, LLMNR SHOULD NOT be used as a primary name resolution -- mechanism. -- --6. IANA Considerations -- -- LLMNR requires allocation of port 5355 for both TCP and UDP. -- -- LLMNR requires allocation of link-scope multicast IPv4 address -- 224.0.0.252, as well as link-scope multicast IPv6 address -- FF02:0:0:0:0:0:1:3. -- -- This specification creates two new name spaces: the LLMNR namespace -- and the reserved bits in the LLMNR header. The reserved bits in the -- LLMNR header are allocated by IETF Consensus, in accordance with BCP -- 26 [RFC2434]. -- -- In order to to avoid creating any new administrative procedures, -- administration of the LLMNR namespace will piggyback on the -- administration of the DNS namespace. -- -- The rights to use a fully qualified domain name (FQDN) within LLMNR -- are obtained coincident with acquiring the rights to use that name -- within DNS. Those wishing to use a FQDN within LLMNR should first -- acquire the rights to use the corresponding FQDN within DNS. Using a -- FQDN within LLMNR without ownership of the corresponding name in DNS -- creates the possibility of conflict and therefore is discouraged. -- -- LLMNR responders may self-allocate a name within the single-label -- name space, first defined in [RFC1001]. Since single-label names are -- not unique, no registration process is required. -- --7. Constants -- -- The following timing constants are used in this protocol; they are -- not intended to be user configurable. -- -- JITTER_INTERVAL 100 ms -- LLMNR_TIMEOUT 1 second (if set statically on all interfaces) -- 100 ms (IEEE 802 media, including IEEE 802.11) -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 25] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --8. References -- --8.1. Normative References -- --[RFC1001] Auerbach, K. and A. Aggarwal, "Protocol Standard for a NetBIOS -- Service on a TCP/UDP Transport: Concepts and Methods", RFC -- 1001, March 1987. -- --[RFC1035] Mockapetris, P., "Domain Names - Implementation and -- Specification", RFC 1035, November 1987. -- --[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- --[RFC2181] Elz, R. and R. Bush, "Clarifications to the DNS -- Specification", RFC 2181, July 1997. -- --[RFC2308] Andrews, M., "Negative Caching of DNS Queries (DNS NCACHE)", -- RFC 2308, March 1998. -- --[RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing -- Architecture", RFC 2373, July 1998. -- --[RFC2434] Alvestrand, H. and T. Narten, "Guidelines for Writing an IANA -- Considerations Section in RFCs", BCP 26, RFC 2434, October -- 1998. -- --[RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC 2671, -- August 1999. -- --[RFC2845] Vixie, P., Gudmundsson, O., Eastlake, D. and B. Wellington, -- "Secret Key Transaction Authentication for DNS (TSIG)", RFC -- 2845, May 2000. -- --[RFC2931] Eastlake, D., "DNS Request and Transaction Signatures -- (SIG(0)s)", RFC 2931, September 2000. -- --8.2. Informative References -- --[DNSPerf] Jung, J., et al., "DNS Performance and the Effectiveness of -- Caching", IEEE/ACM Transactions on Networking, Volume 10, -- Number 5, pp. 589, October 2002. -- --[DNSDisc] Durand, A., Hagino, I. and D. Thaler, "Well known site local -- unicast addresses to communicate with recursive DNS servers", -- Internet draft (work in progress), draft-ietf-ipv6-dns- -- discovery-07.txt, October 2002. -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 26] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --[IEEE-802.11i] -- Institute of Electrical and Electronics Engineers, "Supplement -- to Standard for Telecommunications and Information Exchange -- Between Systems - LAN/MAN Specific Requirements - Part 11: -- Wireless LAN Medium Access Control (MAC) and Physical Layer -- (PHY) Specifications: Specification for Enhanced Security", -- IEEE 802.11i, July 2004. -- --[LLMNREnable] -- Guttman, E., "DHCP LLMNR Enable Option", Internet draft (work -- in progress), draft-guttman-mdns-enable-02.txt, April 2002. -- --[LLMNRSec] -- Jeong, J., Park, J. and H. Kim, "DNS Name Service based on -- Secure Multicast DNS for IPv6 Mobile Ad Hoc Networks", ICACT -- 2004, Phoenix Park, Korea, February 9-11, 2004. -- --[POSIX] IEEE Std. 1003.1-2001 Standard for Information Technology -- -- Portable Operating System Interface (POSIX). Open Group -- Technical Standard: Base Specifications, Issue 6, December -- 2001. ISO/IEC 9945:2002. http://www.opengroup.org/austin -- --[RFC1536] Kumar, A., et. al., "DNS Implementation Errors and Suggested -- Fixes", RFC 1536, October 1993. -- --[RFC1750] Eastlake, D., Crocker, S. and J. Schiller, "Randomness -- Recommendations for Security", RFC 1750, December 1994. -- --[RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, -- March 1997. -- --[RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", -- RFC 2292, February 1998. -- --[RFC2365] Meyer, D., "Administratively Scoped IP Multicast", BCP 23, RFC -- 2365, July 1998. -- --[RFC2553] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic -- Socket Interface Extensions for IPv6", RFC 2553, March 1999. -- --[RFC2937] Smith, C., "The Name Service Search Option for DHCP", RFC -- 2937, September 2000. -- --[RFC3315] Droms, R., et al., "Dynamic Host Configuration Protocol for -- IPv6 (DHCPv6)", RFC 3315, July 2003. -- --[RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain Name -- System (DNS)", RFC 3833, August 2004. -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 27] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --[RFC3927] Cheshire, S., Aboba, B. and E. Guttman, "Dynamic Configuration -- of Link-Local IPv4 Addresses", RFC 3927, October 2004. -- --[RFC4033] Arends, R., Austein, R., Larson, M., Massey, D. and S. Rose, -- "DNS Security Introduction and Requirement", RFC 4033, March -- 2005. -- --Acknowledgments -- -- This work builds upon original work done on multicast DNS by Bill -- Manning and Bill Woodcock. Bill Manning's work was funded under -- DARPA grant #F30602-99-1-0523. The authors gratefully acknowledge -- their contribution to the current specification. Constructive input -- has also been received from Mark Andrews, Rob Austein, Randy Bush, -- Stuart Cheshire, Ralph Droms, Robert Elz, James Gilroy, Olafur -- Gudmundsson, Andreas Gustafsson, Erik Guttman, Myron Hattig, -- Christian Huitema, Olaf Kolkman, Mika Liljeberg, Keith Moore, -- Tomohide Nagashima, Thomas Narten, Erik Nordmark, Markku Savela, Mike -- St. Johns, Sander Van-Valkenburg, and Brian Zill. -- --Authors' Addresses -- -- Bernard Aboba -- Microsoft Corporation -- One Microsoft Way -- Redmond, WA 98052 -- -- Phone: +1 425 706 6605 -- EMail: bernarda@microsoft.com -- -- Dave Thaler -- Microsoft Corporation -- One Microsoft Way -- Redmond, WA 98052 -- -- Phone: +1 425 703 8835 -- EMail: dthaler@microsoft.com -- -- Levon Esibov -- Microsoft Corporation -- One Microsoft Way -- Redmond, WA 98052 -- -- EMail: levone@microsoft.com -- -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 28] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at ietf- -- ipr@ietf.org. -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 29] -- -- -- -- -- --INTERNET-DRAFT LLMNR 16 April 2006 -- -- --Open Issues -- -- Open issues with this specification are tracked on the following web -- site: -- -- http://www.drizzle.com/~aboba/DNSEXT/llmnrissues.html -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Aboba, Thaler & Esibov Standards Track [Page 30] -- -- -- diff --cc doc/draft/draft-ietf-dnsext-nsid-01.txt index 90d1a0609d4,90d1a0609d4..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-nsid-01.txt +++ /dev/null @@@ -1,840 -1,840 +1,0 @@@ -- -- -- --Network Working Group R. Austein --Internet-Draft ISC --Expires: July 15, 2006 January 11, 2006 -- -- -- DNS Name Server Identifier Option (NSID) -- draft-ietf-dnsext-nsid-01 -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on July 15, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- With the increased use of DNS anycast, load balancing, and other -- mechanisms allowing more than one DNS name server to share a single -- IP address, it is sometimes difficult to tell which of a pool of name -- servers has answered a particular query. While existing ad-hoc -- mechanism allow an operator to send follow-up queries when it is -- necessary to debug such a configuration, the only completely reliable -- way to obtain the identity of the name server which responded is to -- have the name server include this information in the response itself. -- This note defines a protocol extension to support this functionality. -- -- -- --Austein Expires July 15, 2006 [Page 1] -- --Internet-Draft DNS NSID January 2006 -- -- --Table of Contents -- -- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 -- 1.1. Reserved Words . . . . . . . . . . . . . . . . . . . . . . 3 -- 2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 -- 2.1. Resolver Behavior . . . . . . . . . . . . . . . . . . . . 4 -- 2.2. Name Server Behavior . . . . . . . . . . . . . . . . . . . 4 -- 2.3. The NSID Option . . . . . . . . . . . . . . . . . . . . . 4 -- 2.4. Presentation Format . . . . . . . . . . . . . . . . . . . 5 -- 3. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 6 -- 3.1. The NSID Payload . . . . . . . . . . . . . . . . . . . . . 6 -- 3.2. NSID Is Not Transitive . . . . . . . . . . . . . . . . . . 8 -- 3.3. User Interface Issues . . . . . . . . . . . . . . . . . . 8 -- 3.4. Truncation . . . . . . . . . . . . . . . . . . . . . . . . 9 -- 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 -- 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 -- 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 -- 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 -- 7.1. Normative References . . . . . . . . . . . . . . . . . . . 13 -- 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 -- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 -- Intellectual Property and Copyright Statements . . . . . . . . . . 15 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 2] -- --Internet-Draft DNS NSID January 2006 -- -- --1. Introduction -- -- With the increased use of DNS anycast, load balancing, and other -- mechanisms allowing more than one DNS name server to share a single -- IP address, it is sometimes difficult to tell which of a pool of name -- servers has answered a particular query. -- -- Existing ad-hoc mechanisms allow an operator to send follow-up -- queries when it is necessary to debug such a configuration, but there -- are situations in which this is not a totally satisfactory solution, -- since anycast routing may have changed, or the server pool in -- question may be behind some kind of extremely dynamic load balancing -- hardware. Thus, while these ad-hoc mechanisms are certainly better -- than nothing (and have the advantage of already being deployed), a -- better solution seems desirable. -- -- Given that a DNS query is an idempotent operation with no retained -- state, it would appear that the only completely reliable way to -- obtain the identity of the name server which responded to a -- particular query is to have that name server include identifying -- information in the response itself. This note defines a protocol -- enhancement to achieve this. -- --1.1. Reserved Words -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [RFC2119]. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 3] -- --Internet-Draft DNS NSID January 2006 -- -- --2. Protocol -- -- This note uses an EDNS [RFC2671] option to signal the resolver's -- desire for information identifying the name server and to hold the -- name server's response, if any. -- --2.1. Resolver Behavior -- -- A resolver signals its desire for information identifying a name -- server by sending an empty NSID option (Section 2.3) in an EDNS OPT -- pseudo-RR in the query message. -- -- The resolver MUST NOT include any NSID payload data in the query -- message. -- -- The semantics of an NSID request are not transitive. That is: the -- presence of an NSID option in a query is a request that the name -- server which receives the query identify itself. If the name server -- side of a recursive name server receives an NSID request, the client -- is asking the recursive name server to identify itself; if the -- resolver side of the recursive name server wishes to receive -- identifying information, it is free to add NSID requests in its own -- queries, but that is a separate matter. -- --2.2. Name Server Behavior -- -- A name server which understands the NSID option and chooses to honor -- a particular NSID request responds by including identifying -- information in a NSID option (Section 2.3) in an EDNS OPT pseudo-RR -- in the response message. -- -- The name server MUST ignore any NSID payload data that might be -- present in the query message. -- -- The NSID option is not transitive. A name server MUST NOT send an -- NSID option back to a resolver which did not request it. In -- particular, while a recursive name server may choose to add an NSID -- option when sending a query, this has no effect on the presence or -- absence of the NSID option in the recursive name server's response to -- the original client. -- -- As stated in Section 2.1, this mechanism is not restricted to -- authoritative name servers; the semantics are intended to be equally -- applicable to recursive name servers. -- --2.3. The NSID Option -- -- The OPTION-CODE for the NSID option is [TBD]. -- -- -- --Austein Expires July 15, 2006 [Page 4] -- --Internet-Draft DNS NSID January 2006 -- -- -- The OPTION-DATA for the NSID option is an opaque byte string the -- semantics of which are deliberately left outside the protocol. See -- Section 3.1 for discussion. -- --2.4. Presentation Format -- -- User interfaces MUST read and write the content of the NSID option as -- a sequence of hexadecimal digits, two digits per payload octet. -- -- The NSID payload is binary data. Any comparison between NSID -- payloads MUST be a comparison of the raw binary data. Copy -- operations MUST NOT assume that the raw NSID payload is null- -- terminated. Any resemblance between raw NSID payload data and any -- form of text is purely a convenience, and does not change the -- underlying nature of the payload data. -- -- See Section 3.3 for discussion. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 5] -- --Internet-Draft DNS NSID January 2006 -- -- --3. Discussion -- -- This section discusses certain aspects of the protocol and explains -- considerations that led to the chosen design. -- --3.1. The NSID Payload -- -- The syntax and semantics of the content of the NSID option is -- deliberately left outside the scope of this specification. This -- section describe some of the kinds of data that server administrators -- might choose to provide as the content of the NSID option, and -- explains the reasoning behind choosing a simple opaque byte string. -- -- There are several possibilities for the payload of the NSID option: -- -- o It could be the "real" name of the specific name server within the -- name server pool. -- -- o It could be the "real" IP address (IPv4 or IPv6) of the name -- server within the name server pool. -- -- o It could be some sort of pseudo-random number generated in a -- predictable fashion somehow using the server's IP address or name -- as a seed value. -- -- o It could be some sort of probabilisticly unique identifier -- initially derived from some sort of random number generator then -- preserved across reboots of the name server. -- -- o It could be some sort of dynamicly generated identifier so that -- only the name server operator could tell whether or not any two -- queries had been answered by the same server. -- -- o It could be a blob of signed data, with a corresponding key which -- might (or might not) be available via DNS lookups. -- -- o It could be a blob of encrypted data, the key for which could be -- restricted to parties with a need to know (in the opinion of the -- server operator). -- -- o It could be an arbitrary string of octets chosen at the discretion -- of the name server operator. -- -- Each of these options has advantages and disadvantages: -- -- o Using the "real" name is simple, but the name server may not have -- a "real" name. -- -- -- -- --Austein Expires July 15, 2006 [Page 6] -- --Internet-Draft DNS NSID January 2006 -- -- -- o Using the "real" address is also simple, and the name server -- almost certainly does have at least one non-anycast IP address for -- maintenance operations, but the operator of the name server may -- not be willing to divulge its non-anycast address. -- -- o Given that one common reason for using anycast DNS techniques is -- an attempt to harden a critical name server against denial of -- service attacks, some name server operators are likely to want an -- identifier other than the "real" name or "real" address of the -- name server instance. -- -- o Using a hash or pseudo-random number can provide a fixed length -- value that the resolver can use to tell two name servers apart -- without necessarily being able to tell where either one of them -- "really" is, but makes debugging more difficult if one happens to -- be in a friendly open environment. Furthermore, hashing might not -- add much value, since a hash based on an IPv4 address still only -- involves a 32-bit search space, and DNS names used for servers -- that operators might have to debug at 4am tend not to be very -- random. -- -- o Probabilisticly unique identifiers have similar properties to -- hashed identifiers, but (given a sufficiently good random number -- generator) are immune to the search space issues. However, the -- strength of this approach is also its weakness: there is no -- algorithmic transformation by which even the server operator can -- associate name server instances with identifiers while debugging, -- which might be annoying. This approach also requires the name -- server instance to preserve the probabilisticly unique identifier -- across reboots, but this does not appear to be a serious -- restriction, since authoritative nameservers almost always have -- some form of nonvolatile storage in any case, and in the rare case -- of a name server that does not have any way to store such an -- identifier, nothing terrible will happen if the name server just -- generates a new identifier every time it reboots. -- -- o Using an arbitrary octet string gives name server operators yet -- another thing to configure, or mis-configure, or forget to -- configure. Having all the nodes in an anycast name server -- constellation identify themselves as "My Name Server" would not be -- particularly useful. -- -- Given all of the issues listed above, there does not appear to be a -- single solution that will meet all needs. Section 2.3 therefore -- defines the NSID payload to be an opaque byte string and leaves the -- choice up to the implementor and name server operator. The following -- guidelines may be useful to implementors and server operators: -- -- -- -- --Austein Expires July 15, 2006 [Page 7] -- --Internet-Draft DNS NSID January 2006 -- -- -- o Operators for whom divulging the unicast address is an issue could -- use the raw binary representation of a probabilisticly unique -- random number. This should probably be the default implementation -- behavior. -- -- o Operators for whom divulging the unicast address is not an issue -- could just use the raw binary representation of a unicast address -- for simplicity. This should only be done via an explicit -- configuration choice by the operator. -- -- o Operators who really need or want the ability to set the NSID -- payload to an arbitrary value could do so, but this should only be -- done via an explicit configuration choice by the operator. -- -- This approach appears to provide enough information for useful -- debugging without unintentionally leaking the maintenance addresses -- of anycast name servers to nogoodniks, while also allowing name -- server operators who do not find such leakage threatening to provide -- more information at their own discretion. -- --3.2. NSID Is Not Transitive -- -- As specified in Section 2.1 and Section 2.2, the NSID option is not -- transitive. This is strictly a hop-by-hop mechanism. -- -- Most of the discussion of name server identification to date has -- focused on identifying authoritative name servers, since the best -- known cases of anycast name servers are a subset of the name servers -- for the root zone. However, given that anycast DNS techniques are -- also applicable to recursive name servers, the mechanism may also be -- useful with recursive name servers. The hop-by-hop semantics support -- this. -- -- While there might be some utility in having a transitive variant of -- this mechanism (so that, for example, a stub resolver could ask a -- recursive server to tell it which authoritative name server provided -- a particular answer to the recursive name server), the semantics of -- such a variant would be more complicated, and are left for future -- work. -- --3.3. User Interface Issues -- -- Given the range of possible payload contents described in -- Section 3.1, it is not possible to define a single presentation -- format for the NSID payload that is efficient, convenient, -- unambiguous, and aesthetically pleasing. In particular, while it is -- tempting to use a presentation format that uses some form of textual -- strings, attempting to support this would significantly complicate -- -- -- --Austein Expires July 15, 2006 [Page 8] -- --Internet-Draft DNS NSID January 2006 -- -- -- what's intended to be a very simple debugging mechanism. -- -- In some cases the content of the NSID payload may be binary data -- meaningful only to the name server operator, and may not be -- meaningful to the user or application, but the user or application -- must be able to capture the entire content anyway in order for it to -- be useful. Thus, the presentation format must support arbitrary -- binary data. -- -- In cases where the name server operator derives the NSID payload from -- textual data, a textual form such as US-ASCII or UTF-8 strings might -- at first glance seem easier for a user to deal with. There are, -- however, a number of complex issues involving internationalized text -- which, if fully addressed here, would require a set of rules -- significantly longer than the rest of this specification. See -- [RFC2277] for an overview of some of these issues. -- -- It is much more important for the NSID payload data to be passed -- unambiguously from server administrator to user and back again than -- it is for the payload data data to be pretty while in transit. In -- particular, it's critical that it be straightforward for a user to -- cut and paste an exact copy of the NSID payload output by a debugging -- tool into other formats such as email messages or web forms without -- distortion. Hexadecimal strings, while ugly, are also robust. -- --3.4. Truncation -- -- In some cases, adding the NSID option to a response message may -- trigger message truncation. This specification does not change the -- rules for DNS message truncation in any way, but implementors will -- need to pay attention to this issue. -- -- Including the NSID option in a response is always optional, so this -- specification never requires name servers to truncate response -- messages. -- -- By definition, a resolver that requests NSID responses also supports -- EDNS, so a resolver that requests NSID responses can also use the -- "sender's UDP payload size" field of the OPT pseudo-RR to signal a -- receive buffer size large enough to make truncation unlikely. -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 9] -- --Internet-Draft DNS NSID January 2006 -- -- --4. IANA Considerations -- -- This mechanism requires allocation of one ENDS option code for the -- NSID option (Section 2.3). -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 10] -- --Internet-Draft DNS NSID January 2006 -- -- --5. Security Considerations -- -- This document describes a channel signaling mechanism, intended -- primarily for debugging. Channel signaling mechanisms are outside -- the scope of DNSSEC per se. Applications that require integrity -- protection for the data being signaled will need to use a channel -- security mechanism such as TSIG [RFC2845]. -- -- Section 3.1 discusses a number of different kinds of information that -- a name server operator might choose to provide as the value of the -- NSID option. Some of these kinds of information are security -- sensitive in some environments. This specification deliberately -- leaves the syntax and semantics of the NSID option content up to the -- implementation and the name server operator. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 11] -- --Internet-Draft DNS NSID January 2006 -- -- --6. Acknowledgements -- -- Joe Abley, Harald Alvestrand, Mark Andrews, Roy Arends, Steve -- Bellovin, Randy Bush, David Conrad, Johan Ihren, Daniel Karrenberg, -- Peter Koch, Mike Patton, Mike StJohns, Paul Vixie, Sam Weiler, and -- Suzanne Woolf. Apologies to anyone inadvertently omitted from the -- above list. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 12] -- --Internet-Draft DNS NSID January 2006 -- -- --7. References -- --7.1. Normative References -- -- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", RFC 2119, BCP 14, March 1997. -- -- [RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", -- RFC 2671, August 1999. -- -- [RFC2845] Vixie, P., Gudmundsson, O., Eastlake 3rd, D., and B. -- Wellington, "Secret Key Transaction Authentication for DNS -- (TSIG)", RFC 2845, May 2000. -- --7.2. Informative References -- -- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and -- Languages", RFC 2277, BCP 18, January 1998. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 13] -- --Internet-Draft DNS NSID January 2006 -- -- --Author's Address -- -- Rob Austein -- ISC -- 950 Charter Street -- Redwood City, CA 94063 -- USA -- -- Email: sra@isc.org -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Austein Expires July 15, 2006 [Page 14] -- --Internet-Draft DNS NSID January 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- --Austein Expires July 15, 2006 [Page 15] -- diff --cc doc/draft/draft-ietf-dnsext-rfc2536bis-dsa-07.txt index e169da86815,e169da86815..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-rfc2536bis-dsa-07.txt +++ /dev/null @@@ -1,464 -1,464 +1,0 @@@ -- --INTERNET-DRAFT DSA Information in the DNS --OBSOLETES: RFC 2536 Donald E. Eastlake 3rd -- Motorola Laboratories --Expires: September 2006 March 2006 -- -- -- DSA Keying and Signature Information in the DNS -- --- ------ --- --------- ----------- -- --- --- -- -- Donald E. Eastlake 3rd -- -- --Status of This Document -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Distribution of this document is unlimited. Comments should be sent -- to the DNS extensions working group mailing list -- . -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/1id-abstracts.html -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html -- -- -- --Abstract -- -- The standard method of encoding US Government Digital Signature -- Algorithm keying and signature information for use in the Domain Name -- System is specified. -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 1] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- --Table of Contents -- -- Status of This Document....................................1 -- Abstract...................................................1 -- -- Table of Contents..........................................2 -- -- 1. Introduction............................................3 -- 2. DSA Keying Information..................................3 -- 3. DSA Signature Information...............................4 -- 4. Performance Considerations..............................4 -- 5. Security Considerations.................................5 -- 6. IANA Considerations.....................................5 -- Copyright, Disclaimer, and Additional IPR Provisions.......5 -- -- Normative References.......................................7 -- Informative References.....................................7 -- -- Author's Address...........................................8 -- Expiration and File Name...................................8 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 2] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- --1. Introduction -- -- The Domain Name System (DNS) is the global hierarchical replicated -- distributed database system for Internet addressing, mail proxy, and -- other information [RFC 1034, 1035]. The DNS has been extended to -- include digital signatures and cryptographic keys as described in -- [RFC 4033, 4034, 4035] and additional work is underway which would -- require the storage of keying and signature information in the DNS. -- -- This document describes how to encode US Government Digital Signature -- Algorithm (DSA) keys and signatures in the DNS. Familiarity with the -- US Digital Signature Algorithm is assumed [FIPS 186-2, Schneier]. -- -- -- --2. DSA Keying Information -- -- When DSA public keys are stored in the DNS, the structure of the -- relevant part of the RDATA part of the RR being used is the fields -- listed below in the order given. -- -- The period of key validity is not included in this data but is -- indicated separately, for example by an RR such as RRSIG which signs -- and authenticates the RR containing the keying information. -- -- Field Size -- ----- ---- -- T 1 octet -- Q 20 octets -- P 64 + T*8 octets -- G 64 + T*8 octets -- Y 64 + T*8 octets -- -- As described in [FIPS 186-2] and [Schneier], T is a key size -- parameter chosen such that 0 <= T <= 8. (The meaning if the T octet -- is greater than 8 is reserved and the remainder of the data may have -- a different format in that case.) Q is a prime number selected at -- key generation time such that 2**159 < Q < 2**160. Thus Q is always -- 20 octets long and, as with all other fields, is stored in "big- -- endian" network order. P, G, and Y are calculated as directed by the -- [FIPS 186-2] key generation algorithm [Schneier]. P is in the range -- 2**(511+64T) < P < 2**(512+64T) and thus is 64 + 8*T octets long. G -- and Y are quantities modulo P and so can be up to the same length as -- P and are allocated fixed size fields with the same number of octets -- as P. -- -- During the key generation process, a random number X must be -- generated such that 1 <= X <= Q-1. X is the private key and is used -- in the final step of public key generation where Y is computed as -- -- -- --D. Eastlake 3rd [Page 3] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- -- Y = G**X mod P -- -- -- --3. DSA Signature Information -- -- The portion of the RDATA area used for US Digital Signature Algorithm -- signature information is shown below with fields in the order they -- are listed and the contents of each multi-octet field in "big-endian" -- network order. -- -- Field Size -- ----- ---- -- T 1 octet -- R 20 octets -- S 20 octets -- -- First, the data signed must be determined. Then the following steps -- are taken, as specified in [FIPS 186-2], where Q, P, G, and Y are as -- specified in the public key [Schneier]: -- -- hash = SHA-1 ( data ) -- -- Generate a random K such that 0 < K < Q. -- -- R = ( G**K mod P ) mod Q -- -- S = ( K**(-1) * (hash + X*R) ) mod Q -- -- For information on the SHA-1 hash function see [FIPS 180-2] and [RFC -- 3174]. -- -- Since Q is 160 bits long, R and S can not be larger than 20 octets, -- which is the space allocated. -- -- T is copied from the public key. It is not logically necessary in -- the SIG but is present so that values of T > 8 can more conveniently -- be used as an escape for extended versions of DSA or other algorithms -- as later standardized. -- -- -- --4. Performance Considerations -- -- General signature generation speeds are roughly the same for RSA [RFC -- 3110] and DSA. With sufficient pre-computation, signature generation -- with DSA is faster than RSA. Key generation is also faster for DSA. -- However, signature verification is an order of magnitude slower than -- RSA when the RSA public exponent is chosen to be small, as is -- recommended for some applications. -- -- --D. Eastlake 3rd [Page 4] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- -- Current DNS implementations are optimized for small transfers, -- typically less than 512 bytes including DNS overhead. Larger -- transfers will perform correctly and extensions have been -- standardized [RFC 2671] to make larger transfers more efficient, it -- is still advisable at this time to make reasonable efforts to -- minimize the size of RR sets containing keying and/or signature -- inforamtion consistent with adequate security. -- -- -- --5. Security Considerations -- -- Keys retrieved from the DNS should not be trusted unless (1) they -- have been securely obtained from a secure resolver or independently -- verified by the user and (2) this secure resolver and secure -- obtainment or independent verification conform to security policies -- acceptable to the user. As with all cryptographic algorithms, -- evaluating the necessary strength of the key is essential and -- dependent on local policy. -- -- The key size limitation of a maximum of 1024 bits ( T = 8 ) in the -- current DSA standard may limit the security of DSA. For particular -- applications, implementors are encouraged to consider the range of -- available algorithms and key sizes. -- -- DSA assumes the ability to frequently generate high quality random -- numbers. See [random] for guidance. DSA is designed so that if -- biased rather than random numbers are used, high bandwidth covert -- channels are possible. See [Schneier] and more recent research. The -- leakage of an entire DSA private key in only two DSA signatures has -- been demonstrated. DSA provides security only if trusted -- implementations, including trusted random number generation, are -- used. -- -- -- --6. IANA Considerations -- -- Allocation of meaning to values of the T parameter that are not -- defined herein (i.e., > 8 ) requires an IETF standards actions. It -- is intended that values unallocated herein be used to cover future -- extensions of the DSS standard. -- -- -- --Copyright, Disclaimer, and Additional IPR Provisions -- -- Copyright (C) The Internet Society (2006). This document is subject to -- the rights, licenses and restrictions contained in BCP 78, and except -- as set forth therein, the authors retain all their rights. -- -- --D. Eastlake 3rd [Page 5] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at ietf- -- ipr@ietf.org. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 6] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- --Normative References -- -- [FIPS 186-2] - U.S. Federal Information Processing Standard: Digital -- Signature Standard, 27 January 2000. -- -- [RFC 4034] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- -- --Informative References -- -- [RFC 1034] - "Domain names - concepts and facilities", P. -- Mockapetris, 11/01/1987. -- -- [RFC 1035] - "Domain names - implementation and specification", P. -- Mockapetris, 11/01/1987. -- -- [RFC 2671] - "Extension Mechanisms for DNS (EDNS0)", P. Vixie, August -- 1999. -- -- [RFC 3110] - "RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System -- (DNS)", D. Eastlake 3rd. May 2001. -- -- [RFC 3174] - "US Secure Hash Algorithm 1 (SHA1)", D. Eastlake, P. -- Jones, September 2001. -- -- [RFC 4033] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "DNS Security Introduction and Requirements", RFC 4033, March -- 2005. -- -- [RFC 4035] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Protocol Modifications for the DNS Security Extensions", RFC -- 4035, March 2005. -- -- [RFC 4086] - Eastlake, D., 3rd, Schiller, J., and S. Crocker, -- "Randomness Requirements for Security", BCP 106, RFC 4086, June 2005. -- -- [Schneier] - "Applied Cryptography Second Edition: protocols, -- algorithms, and source code in C" (second edition), Bruce Schneier, -- 1996, John Wiley and Sons, ISBN 0-471-11709-9. -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 7] -- -- --INTERNET-DRAFT DSA Information in the DNS -- -- --Author's Address -- -- Donald E. Eastlake 3rd -- Motorola Labortories -- 155 Beaver Street -- Milford, MA 01757 USA -- -- Telephone: +1-508-786-7554(w) -- EMail: Donald.Eastlake@motorola.com -- -- -- --Expiration and File Name -- -- This draft expires in September 2006. -- -- Its file name is draft-ietf-dnsext-rfc2536bis-dsa-07.txt. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 8] -- diff --cc doc/draft/draft-ietf-dnsext-rfc2539bis-dhk-07.txt index f6e8588e8cb,f6e8588e8cb..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-rfc2539bis-dhk-07.txt +++ /dev/null @@@ -1,580 -1,580 +1,0 @@@ -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS --OBSOLETES: RFC 2539 Donald E. Eastlake 3rd -- Motorola Laboratories --Expires: September 2006 March 2006 -- -- -- -- -- Storage of Diffie-Hellman Keying Information in the DNS -- ------- -- -------------- ------ ----------- -- --- --- -- -- -- -- --Status of This Document -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Distribution of this document is unlimited. Comments should be sent -- to the DNS extensions working group mailing list -- . -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/1id-abstracts.html -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html -- -- --Abstract -- -- The standard method for encoding Diffie-Hellman keys in the Domain -- Name System is specified. -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 1] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --Acknowledgements -- -- Part of the format for Diffie-Hellman keys and the description -- thereof was taken from a work in progress by Ashar Aziz, Tom Markson, -- and Hemma Prafullchandra. In addition, the following persons -- provided useful comments that were incorporated into the predecessor -- of this document: Ran Atkinson, Thomas Narten. -- -- -- --Table of Contents -- -- Status of This Document....................................1 -- Abstract...................................................1 -- -- Acknowledgements...........................................2 -- Table of Contents..........................................2 -- -- 1. Introduction............................................3 -- 1.1 About This Document....................................3 -- 1.2 About Diffie-Hellman...................................3 -- 2. Encoding Diffie-Hellman Keying Information..............4 -- 3. Performance Considerations..............................5 -- 4. IANA Considerations.....................................5 -- 5. Security Considerations.................................5 -- Copyright, Disclaimer, and Additional IPR Provisions.......5 -- -- Normative References.......................................7 -- Informative Refences.......................................7 -- -- Author's Address...........................................8 -- Expiration and File Name...................................8 -- -- Appendix A: Well known prime/generator pairs...............9 -- A.1. Well-Known Group 1: A 768 bit prime..................9 -- A.2. Well-Known Group 2: A 1024 bit prime.................9 -- A.3. Well-Known Group 3: A 1536 bit prime................10 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 2] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --1. Introduction -- -- The Domain Name System (DNS) is the global hierarchical replicated -- distributed database system for Internet addressing, mail proxy, and -- similar information [RFC 1034, 1035]. The DNS has been extended to -- include digital signatures and cryptographic keys as described in -- [RFC 4033, 4034, 4035] and additonal work is underway which would use -- the storage of keying information in the DNS. -- -- -- --1.1 About This Document -- -- This document describes how to store Diffie-Hellman keys in the DNS. -- Familiarity with the Diffie-Hellman key exchange algorithm is assumed -- [Schneier, RFC 2631]. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119. -- -- -- --1.2 About Diffie-Hellman -- -- Diffie-Hellman requires two parties to interact to derive keying -- information which can then be used for authentication. Thus Diffie- -- Hellman is inherently a key agreement algorithm. As a result, no -- format is defined for Diffie-Hellman "signature information". For -- example, assume that two parties have local secrets "i" and "j". -- Assume they each respectively calculate X and Y as follows: -- -- X = g**i ( mod p ) -- -- Y = g**j ( mod p ) -- -- They exchange these quantities and then each calculates a Z as -- follows: -- -- Zi = Y**i ( mod p ) -- -- Zj = X**j ( mod p ) -- -- Zi and Zj will both be equal to g**(i*j)(mod p) and will be a shared -- secret between the two parties that an adversary who does not know i -- or j will not be able to learn from the exchanged messages (unless -- the adversary can derive i or j by performing a discrete logarithm -- mod p which is hard for strong p and g). -- -- The private key for each party is their secret i (or j). The public -- -- --D. Eastlake 3rd [Page 3] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- -- key is the pair p and g, which is the same for both parties, and -- their individual X (or Y). -- -- For further information about Diffie-Hellman and precautions to take -- in deciding on a p and g, see [RFC 2631]. -- -- -- --2. Encoding Diffie-Hellman Keying Information -- -- When Diffie-Hellman keys appear within the RDATA portion of a RR, -- they are encoded as shown below. -- -- The period of key validity is not included in this data but is -- indicated separately, for example by an RR such as RRSIG which signs -- and authenticates the RR containing the keying information. -- -- 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 -- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | KEY flags | protocol | algorithm=2 | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | prime length (or flag) | prime (p) (or special) / -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- / prime (p) (variable length) | generator length | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | generator (g) (variable length) | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | public value length | public value (variable length)/ -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- / public value (g^i mod p) (variable length) | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- -- Prime length is the length of the Diffie-Hellman prime (p) in bytes -- if it is 16 or greater. Prime contains the binary representation of -- the Diffie-Hellman prime with most significant byte first (i.e., in -- network order). If "prime length" field is 1 or 2, then the "prime" -- field is actually an unsigned index into a table of 65,536 -- prime/generator pairs and the generator length SHOULD be zero. See -- Appedix A for defined table entries and Section 4 for information on -- allocating additional table entries. The meaning of a zero or 3 -- through 15 value for "prime length" is reserved. -- -- Generator length is the length of the generator (g) in bytes. -- Generator is the binary representation of generator with most -- significant byte first. PublicValueLen is the Length of the Public -- Value (g**i (mod p)) in bytes. PublicValue is the binary -- representation of the DH public value with most significant byte -- first. -- -- -- --D. Eastlake 3rd [Page 4] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --3. Performance Considerations -- -- Current DNS implementations are optimized for small transfers, -- typically less than 512 bytes including DNS overhead. Larger -- transfers will perform correctly and extensions have been -- standardized [RFC 2671] to make larger transfers more efficient. But -- it is still advisable at this time to make reasonable efforts to -- minimize the size of RR sets containing keying information consistent -- with adequate security. -- -- -- --4. IANA Considerations -- -- Assignment of meaning to Prime Lengths of 0 and 3 through 15 requires -- an IETF consensus as defined in [RFC 2434]. -- -- Well known prime/generator pairs number 0x0000 through 0x07FF can -- only be assigned by an IETF standards action. [RFC 2539], the -- Proposed Standard predecessor of this document, assigned 0x0001 -- through 0x0002. This document additionally assigns 0x0003. Pairs -- number 0s0800 through 0xBFFF can be assigned based on RFC -- documentation. Pairs number 0xC000 through 0xFFFF are available for -- private use and are not centrally coordinated. Use of such private -- pairs outside of a closed environment may result in conflicts and/or -- security failures. -- -- -- --5. Security Considerations -- -- Keying information retrieved from the DNS should not be trusted -- unless (1) it has been securely obtained from a secure resolver or -- independently verified by the user and (2) this secure resolver and -- secure obtainment or independent verification conform to security -- policies acceptable to the user. As with all cryptographic -- algorithms, evaluating the necessary strength of the key is important -- and dependent on security policy. -- -- In addition, the usual Diffie-Hellman key strength considerations -- apply. (p-1)/2 SHOULD also be prime, g SHOULD be primitive mod p, p -- SHOULD be "large", etc. See [RFC 2631, Schneier]. -- -- -- --Copyright, Disclaimer, and Additional IPR Provisions -- -- Copyright (C) The Internet Society (2006). This document is subject to -- the rights, licenses and restrictions contained in BCP 78, and except -- as set forth therein, the authors retain all their rights. -- -- --D. Eastlake 3rd [Page 5] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at ietf- -- ipr@ietf.org. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 6] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --Normative References -- -- [RFC 2119] - Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- -- [RFC 2434] - "Guidelines for Writing an IANA Considerations Section -- in RFCs", T. Narten, H. Alvestrand, October 1998. -- -- [RFC 2631] - "Diffie-Hellman Key Agreement Method", E. Rescorla, June -- 1999. -- -- [RFC 4034] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- -- --Informative Refences -- -- [RFC 1034] - "Domain names - concepts and facilities", P. -- Mockapetris, November 1987. -- -- [RFC 1035] - "Domain names - implementation and specification", P. -- Mockapetris, November 1987. -- -- [RFC 2539] - "Storage of Diffie-Hellman Keys in the Domain Name -- System (DNS)", D. Eastlake, March 1999, obsoleted by this RFC. -- -- [RFC 2671] - "Extension Mechanisms for DNS (EDNS0)", P. Vixie, August -- 1999. -- -- [RFC 4033] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "DNS Security Introduction and Requirements", RFC 4033, March -- 2005. -- -- [RFC 4035] - Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Protocol Modifications for the DNS Security Extensions", RFC -- 4035, March 2005. -- -- [Schneier] - Bruce Schneier, "Applied Cryptography: Protocols, -- Algorithms, and Source Code in C" (Second Edition), 1996, John Wiley -- and Sons. -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 7] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --Author's Address -- -- Donald E. Eastlake 3rd -- Motorola Laboratories -- 155 Beaver Street -- Milford, MA 01757 USA -- -- Telephone: +1-508-786-7554 -- EMail: Donald.Eastlake@motorola.com -- -- -- --Expiration and File Name -- -- This draft expires in September 2006. -- -- Its file name is draft-ietf-dnsext-rfc2539bis-dhk-07.txt. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 8] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --Appendix A: Well known prime/generator pairs -- -- These numbers are copied from the IPSEC effort where the derivation -- of these values is more fully explained and additional information is -- available. Richard Schroeppel performed all the mathematical and -- computational work for this appendix. -- -- -- --A.1. Well-Known Group 1: A 768 bit prime -- -- The prime is 2^768 - 2^704 - 1 + 2^64 * { [2^638 pi] + 149686 }. Its -- decimal value is -- 155251809230070893513091813125848175563133404943451431320235 -- 119490296623994910210725866945387659164244291000768028886422 -- 915080371891804634263272761303128298374438082089019628850917 -- 0691316593175367469551763119843371637221007210577919 -- -- Prime modulus: Length (32 bit words): 24, Data (hex): -- FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 -- 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD -- EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 -- E485B576 625E7EC6 F44C42E9 A63A3620 FFFFFFFF FFFFFFFF -- -- Generator: Length (32 bit words): 1, Data (hex): 2 -- -- -- --A.2. Well-Known Group 2: A 1024 bit prime -- -- The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. -- Its decimal value is -- 179769313486231590770839156793787453197860296048756011706444 -- 423684197180216158519368947833795864925541502180565485980503 -- 646440548199239100050792877003355816639229553136239076508735 -- 759914822574862575007425302077447712589550957937778424442426 -- 617334727629299387668709205606050270810842907692932019128194 -- 467627007 -- -- Prime modulus: Length (32 bit words): 32, Data (hex): -- FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 -- 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD -- EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 -- E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED -- EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 -- FFFFFFFF FFFFFFFF -- -- Generator: Length (32 bit words): 1, Data (hex): 2 -- -- -- -- --D. Eastlake 3rd [Page 9] -- -- --INTERNET-DRAFT Diffie-Hellman Information in the DNS -- -- --A.3. Well-Known Group 3: A 1536 bit prime -- -- The prime is 2^1536 - 2^1472 - 1 + 2^64 * { [2^1406 pi] + 741804 }. -- Its decimal value is -- 241031242692103258855207602219756607485695054850245994265411 -- 694195810883168261222889009385826134161467322714147790401219 -- 650364895705058263194273070680500922306273474534107340669624 -- 601458936165977404102716924945320037872943417032584377865919 -- 814376319377685986952408894019557734611984354530154704374720 -- 774996976375008430892633929555996888245787241299381012913029 -- 459299994792636526405928464720973038494721168143446471443848 -- 8520940127459844288859336526896320919633919 -- -- Prime modulus Length (32 bit words): 48, Data (hex): -- FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 -- 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD -- EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 -- E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED -- EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D -- C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F -- 83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D -- 670C354E 4ABC9804 F1746C08 CA237327 FFFFFFFF FFFFFFFF -- -- Generator: Length (32 bit words): 1, Data (hex): 2 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --D. Eastlake 3rd [Page 10] -- diff --cc doc/draft/draft-ietf-dnsext-wcard-clarify-10.txt index 9cf88a5831f,9cf88a5831f..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsext-wcard-clarify-10.txt +++ /dev/null @@@ -1,1063 -1,1063 +1,0 @@@ --Internet-Draft dnsext-wcard January 9, 2006 -- --DNSEXT Working Group E. Lewis --INTERNET DRAFT NeuStar --Expiration Date: July 9, 2006 January 9, 2006 --Updates RFC 1034, RFC 2672 -- -- The Role of Wildcards -- in the Domain Name System -- draft-ietf-dnsext-wcard-clarify-10.txt -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that -- any applicable patent or other IPR claims of which he or she is -- aware have been or will be disclosed, and any of which he or she -- becomes aware will be disclosed, in accordance with Section 6 of -- BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six -- months and may be updated, replaced, or obsoleted by other -- documents at any time. It is inappropriate to use Internet-Drafts -- as reference material or to cite them other than as "work in -- progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html -- -- This Internet-Draft will expire on July 9, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This is an update to the wildcard definition of RFC 1034. The -- interaction with wildcards and CNAME is changed, an error -- condition removed, and the words defining some concepts central -- to wildcards are changed. The overall goal is not to change -- wildcards, but to refine the definition of RFC 1034. -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 1] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --Table of Contents -- --1. Introduction . . . . . . . . . . . . . . . . 3 --1 1 Motivation 3 --1 2 The Original Definition 3 --1 3 Roadmap to This Document 4 --1 3 1 New Terms 4 --1.3.2 Changed Text 5 --1.3.3 Considerations with Special Types 5 --1.4 Standards Terminology 5 --2. Wildcard Syntax . . . . . . . . . . . . . . . 6 --2.1 Identifying a Wildcard 6 --2.1.1 Wild Card Domain Name and Asterisk Label 6 --2.1.2 Asterisks and Other Characters 6 --2.1.3 Non-terminal Wild Card Domain Names 6 --2.2 Existence Rules 7 --2.2.1 An Example 7 --2.2.2 Empty Non-terminals 9 --2.2.3 Yet Another Definition of Existence 10 --2.3 When is a Wild Card Domain Name Not Special 10 --3. Impact of a Wild Card Domain Name On a Response . . . . . 10 --3.1 Step 2 10 --3.2 Step 3 11 --3.3 Part 'c' 11 --3.3.1 Closest Encloser and the Source of Synthesis 12 --3.3.2 Closest Encloser and Source of Synthesis Examples 12 --3.3.3 Type Matching 13 --4. Considerations with Special Types . . . . . . . . . 13 --4.1 SOA RRSet at a Wild Card Domain Name 13 --4.2 NS RRSet at a Wild Card Domain Name 14 --4.2.1 Discarded Notions 14 --4.3 CNAME RRSet at a Wild Card Domain Name 15 --4.4 DNAME RRSet at a Wild Card Domain Name 15 --4.5 SRV RRSet at a Wild Card Domain Name 16 --4.6 DS RRSet at a Wild Card Domain Name 16 --4.7 NSEC RRSet at a Wild Card Domain Name 17 --4.8 RRSIG at a Wild Card Domain Name 17 --4.9 Empty Non-terminal Wild Card Domain Name 17 --5. Security Considerations . . . . . . . . . . . . . 17 --6. IANA Considerations . . . . . . . . . . . . . 17 --7. References . . . . . . . . . . . . . 17 --8. Editor . . . . . . . . . . . . . 18 --9. Others Contributing to the Document . . . . . . . . 18 --10. Trailing Boilerplate . . . . . . . . . . . . . 19 -- -- -- -- -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 2] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --1. Introduction -- -- In RFC 1034 [RFC1034], sections 4.3.2 and 4.3.3 describe the -- synthesis of answers from special resource records called -- wildcards. The definition in RFC 1034 is incomplete and has -- proven to be confusing. This document describes the wildcard -- synthesis by adding to the discussion and making limited -- modifications. Modifications are made to close inconsistencies -- that have led to interoperability issues. This description -- does not expand the service intended by the original definition. -- -- Staying within the spirit and style of the original documents, -- this document avoids specifying rules for DNS implementations -- regarding wildcards. The intention is to only describe what is -- needed for interoperability, not restrict implementation choices. -- In addition, consideration is given to minimize any backwards -- compatibility issues with implementations that comply with RFC -- 1034's definition. -- -- This document is focused on the concept of wildcards as defined -- in RFC 1034. Nothing is implied regarding alternative means of -- synthesizing resource record sets, nor are alternatives discussed. -- --1.1 Motivation -- -- Many DNS implementations diverge, in different ways, from the -- original definition of wildcards. Although there is clearly a -- need to clarify the original documents in light of this alone, -- the impetus for this document lay in the engineering of the DNS -- security extensions [RFC4033]. With an unclear definition of -- wildcards the design of authenticated denial became entangled. -- -- This document is intended to limit its changes, documenting only -- those based on implementation experience, and to remain as close -- to the original document as possible. To reinforce that this -- document is meant to clarify and adjust and not redefine wildcards, -- relevant sections of RFC 1034 are repeated verbatim to facilitate -- comparison of the old and new text. -- --1.2 The Original Definition -- -- The definition of the wildcard concept is comprised by the -- documentation of the algorithm by which a name server prepares -- a response (in RFC 1034's section 4.3.2) and the way in which -- a resource record (set) is identified as being a source of -- synthetic data (section 4.3.3). -- -- This is the definition of the term "wildcard" as it appears in -- RFC 1034, section 4.3.3. -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 3] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --# In the previous algorithm, special treatment was given to RRs with --# owner names starting with the label "*". Such RRs are called --# wildcards. Wildcard RRs can be thought of as instructions for --# synthesizing RRs. When the appropriate conditions are met, the name --# server creates RRs with an owner name equal to the query name and --# contents taken from the wildcard RRs. -- -- This passage follows the algorithm in which the term wildcard -- is first used. In this definition, wildcard refers to resource -- records. In other usage, wildcard has referred to domain names, -- and it has been used to describe the operational practice of -- relying on wildcards to generate answers. It is clear from this -- that there is a need to define clear and unambiguous terminology -- in the process of discussing wildcards. -- -- The mention of the use of wildcards in the preparation of a -- response is contained in step 3c of RFC 1034's section 4.3.2 -- entitled "Algorithm." Note that "wildcard" does not appear in -- the algorithm, instead references are made to the "*" label. -- The portion of the algorithm relating to wildcards is -- deconstructed in detail in section 3 of this document, this is -- the beginning of the relevant portion of the "Algorithm." -- --# c. If at some label, a match is impossible (i.e., the --# corresponding label does not exist), look to see if [...] --# the "*" label exists. -- -- The scope of this document is the RFC 1034 definition of -- wildcards and the implications of updates to those documents, -- such as DNSSEC. Alternate schemes for synthesizing answers are -- not considered. (Note that there is no reference listed. No -- document is known to describe any alternate schemes, although -- there has been some mention of them in mailing lists.) -- --1.3 Roadmap to This Document -- -- This document accomplishes these three items. -- o Defines new terms -- o Makes minor changes to avoid conflicting concepts -- o Describes the actions of certain resource records as wildcards -- --1.3.1 New Terms -- -- To help in discussing what resource records are wildcards, two -- terms will be defined - "asterisk label" and "wild card domain -- name". These are defined in section 2.1.1. -- -- To assist in clarifying the role of wildcards in the name server -- algorithm in RFC 1034, 4.3.2, "source of synthesis" and "closest -- encloser" are defined. These definitions are in section 3.3.2. -- "Label match" is defined in section 3.2. -- --DNSEXT Working Group Expires July 9, 2006 [Page 4] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- The new terms are used to make discussions of wildcards clearer. -- Terminology doesn't directly have an impact on implementations. -- --1.3.2 Changed Text -- -- The definition of "existence" is changed superficially. This -- change will not be apparent to implementations; it is needed to -- make descriptions more precise. The change appears in section -- 2.2.3. -- -- RFC 1034, section 4.3.3., seems to prohibit having two asterisk -- labels in a wildcard owner name. With this document the -- restriction is removed entirely. This change and its implications -- are in section 2.1.3. -- -- The actions when a source of synthesis owns a CNAME RR are -- changed to mirror the actions if an exact match name owns a -- CNAME RR. This is an addition to the words in RFC 1034, -- section 4.3.2, step 3, part c. The discussion of this is in -- section 3.3.3. -- -- Only the latter change represents an impact to implementations. -- The definition of existence is not a protocol impact. The change -- to the restriction on names is unlikely to have an impact, as -- RFC 1034 contained no specification on when and how to enforce the -- restriction. -- --1.3.3 Considerations with Special Types -- -- This document describes semantics of wildcard RRSets for -- "interesting" types as well as empty non-terminal wildcards. -- Understanding these situations in the context of wildcards has -- been clouded because these types incur special processing if -- they are the result of an exact match. This discussion is in -- section 4. -- -- These discussions do not have an implementation impact, they cover -- existing knowledge of the types, but to a greater level of detail. -- --1.4 Standards Terminology -- -- This document does not use terms as defined in "Key words for use -- in RFCs to Indicate Requirement Levels." [RFC2119] -- -- Quotations of RFC 1034 are denoted by a '#' in the leftmost -- column. References to section "4.3.2" are assumed to refer -- to RFC 1034's section 4.3.2, simply titled "Algorithm." -- -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 5] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --2. Wildcard Syntax -- -- The syntax of a wildcard is the same as any other DNS resource -- record, across all classes and types. The only significant -- feature is the owner name. -- -- Because wildcards are encoded as resource records with special -- names, they are included in zone transfers and incremental zone -- transfers[RFC1995] just as non-wildcard resource records are. -- This feature has been under appreciated until discussions on -- alternative approaches to wildcards appeared on mailing lists. -- --2.1 Identifying a Wildcard -- -- To provide a more accurate description of wildcards, the -- definition has to start with a discussion of the domain names -- that appear as owners. Two new terms are needed, "Asterisk -- Label" and "Wild Card Domain Name." -- --2.1.1 Wild Card Domain Name and Asterisk Label -- -- A "wild card domain name" is defined by having its initial -- (i.e., left-most or least significant) label be, in binary format: -- -- 0000 0001 0010 1010 (binary) = 0x01 0x2a (hexadecimal) -- -- The first octet is the normal label type and length for a 1 octet -- long label, the second octet is the ASCII representation [RFC20] -- for the '*' character. -- -- A descriptive name of a label equaling that value is an "asterisk -- label." -- -- RFC 1034's definition of wildcard would be "a resource record -- owned by a wild card domain name." -- --2.1.2 Asterisks and Other Characters -- -- No label values other than that in section 2.1.1 are asterisk -- labels, hence names beginning with other labels are never wild -- card domain names. Labels such as 'the*' and '**' are not -- asterisk labels so these labels do not start wild card domain -- names. -- --2.1.3 Non-terminal Wild Card Domain Names -- -- In section 4.3.3, the following is stated: -- --# .......................... The owner name of the wildcard RRs is of --# the form "*.", where is any domain name. --# should not contain other * labels...................... -- --DNSEXT Working Group Expires July 9, 2006 [Page 6] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- The restriction is now removed. The original documentation of it -- is incomplete and the restriction does not serve any purpose -- given years of operational experience. -- -- There are three possible reasons for putting the restriction in -- place, but none of the three has held up over time. One is -- that the restriction meant that there would never be subdomains -- of wild card domain names, but the restriciton as stated still -- permits "example.*.example." for instance. Another is that -- wild card domain names are not intended to be empty non-terminals, -- but this situation does not disrupt the algorithm in 4.3.2. -- Finally, "nested" wild card domain names are not ambiguous once -- the concept of the closest encloser had been documented. -- -- A wild card domain name can have subdomains. There is no need -- to inspect the subdomains to see if there is another asterisk -- label in any subdomain. -- -- A wild card domain name can be an empty non-terminal. (See the -- upcoming sections on empty non-terminals.) In this case, any -- lookup encountering it will terminate as would any empty -- non-terminal match. -- --2.2 Existence Rules -- -- The notion that a domain name 'exists' is mentioned in the -- definition of wildcards. In section 4.3.3 of RFC 1034: -- --# Wildcard RRs do not apply: --# --... --# - When the query name or a name between the wildcard domain and --# the query name is know[n] to exist. For example, if a wildcard -- -- "Existence" is therefore an important concept in the understanding -- of wildcards. Unfortunately, the definition of what exists, in RFC -- 1034, is unclear. So, in sections 2.2.2. and 2.2.3, another look is -- taken at the definition of existence. -- --2.2.1 An Example -- -- To illustrate what is meant by existence consider this complete -- zone: -- -- -- -- -- -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 7] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- $ORIGIN example. -- example. 3600 IN SOA -- example. 3600 NS ns.example.com. -- example. 3600 NS ns.example.net. -- *.example. 3600 TXT "this is a wild card" -- *.example. 3600 MX 10 host1.example. -- sub.*.example. 3600 TXT "this is not a wild card" -- host1.example. 3600 A 192.0.4.1 -- _ssh._tcp.host1.example. 3600 SRV -- _ssh._tcp.host2.example. 3600 SRV -- subdel.example. 3600 NS ns.example.com. -- subdel.example. 3600 NS ns.example.net. -- -- A look at the domain names in a tree structure is helpful: -- -- | -- -------------example------------ -- / / \ \ -- / / \ \ -- / / \ \ -- * host1 host2 subdel -- | | | -- | | | -- sub _tcp _tcp -- | | -- | | -- _ssh _ssh -- -- The following responses would be synthesized from one of the -- wildcards in the zone: -- -- QNAME=host3.example. QTYPE=MX, QCLASS=IN -- the answer will be a "host3.example. IN MX ..." -- -- QNAME=host3.example. QTYPE=A, QCLASS=IN -- the answer will reflect "no error, but no data" -- because there is no A RR set at '*.example.' -- -- QNAME=foo.bar.example. QTYPE=TXT, QCLASS=IN -- the answer will be "foo.bar.example. IN TXT ..." -- because bar.example. does not exist, but the wildcard -- does. -- -- The following responses would not be synthesized from any of the -- wildcards in the zone: -- -- QNAME=host1.example., QTYPE=MX, QCLASS=IN -- because host1.example. exists -- -- QNAME=sub.*.example., QTYPE=MX, QCLASS=IN -- because sub.*.example. exists -- --DNSEXT Working Group Expires July 9, 2006 [Page 8] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- QNAME=_telnet._tcp.host1.example., QTYPE=SRV, QCLASS=IN -- because _tcp.host1.example. exists (without data) -- -- QNAME=host.subdel.example., QTYPE=A, QCLASS=IN -- because subdel.example. exists (and is a zone cut) -- -- QNAME=ghost.*.example., QTYPE=MX, QCLASS=IN -- because *.example. exists -- -- The final example highlights one common misconception about -- wildcards. A wildcard "blocks itself" in the sense that a -- wildcard does not match its own subdomains. I.e. "*.example." -- does not match all names in the "example." zone, it fails to -- match the names below "*.example." To cover names under -- "*.example.", another wild card domain name is needed - -- "*.*.example." - which covers all but it's own subdomains. -- --2.2.2 Empty Non-terminals -- -- Empty non-terminals [RFC2136, Section 7.16] are domain names -- that own no resource records but have subdomains that do. In -- section 2.2.1, "_tcp.host1.example." is an example of a empty -- non-terminal name. Empty non-terminals are introduced by this -- text in section 3.1 of RFC 1034: -- --# The domain name space is a tree structure. Each node and leaf on --# the tree corresponds to a resource set (which may be empty). The --# domain system makes no distinctions between the uses of the --# interior nodes and leaves, and this memo uses the term "node" to --# refer to both. -- -- The parenthesized "which may be empty" specifies that empty non- -- terminals are explicitly recognized, and that empty non-terminals -- "exist." -- -- Pedantically reading the above paragraph can lead to an -- interpretation that all possible domains exist - up to the -- suggested limit of 255 octets for a domain name [RFC1035]. -- For example, www.example. may have an A RR, and as far as is -- practically concerned, is a leaf of the domain tree. But the -- definition can be taken to mean that sub.www.example. also -- exists, albeit with no data. By extension, all possible domains -- exist, from the root on down. -- -- As RFC 1034 also defines "an authoritative name error indicating -- that the name does not exist" in section 4.3.1, so this apparently -- is not the intent of the original definition, justifying the -- need for an updated definition in the next section. -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 9] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --2.2.3 Yet Another Definition of Existence -- -- RFC1034's wording is fixed by the following paragraph: -- -- The domain name space is a tree structure. Nodes in the tree -- either own at least one RRSet and/or have descendants that -- collectively own at least one RRSet. A node may exist with no -- RRSets only if it has descendents that do, this node is an empty -- non-terminal. -- -- A node with no descendants is a leaf node. Empty leaf nodes do -- not exist. -- -- Note that at a zone boundary, the domain name owns data, -- including the NS RR set. In the delegating zone, the NS RR -- set is not authoritative, but that is of no consequence here. -- The domain name owns data, therefore, it exists. -- --2.3 When is a Wild Card Domain Name Not Special -- -- When a wild card domain name appears in a message's query section, -- no special processing occurs. An asterisk label in a query name -- only matches a single, corresponding asterisk label in the -- existing zone tree when the 4.3.2 algorithm is being followed. -- -- When a wild card domain name appears in the resource data of a -- record, no special processing occurs. An asterisk label in that -- context literally means just an asterisk. -- --3. Impact of a Wild Card Domain Name On a Response -- -- RFC 1034's description of how wildcards impact response -- generation is in its section 4.3.2. That passage contains the -- algorithm followed by a server in constructing a response. -- Within that algorithm, step 3, part 'c' defines the behavior of -- the wildcard. -- -- The algorithm in section 4.3.2. is not intended to be pseudo-code, -- i.e., its steps are not intended to be followed in strict order. -- The "algorithm" is a suggested means of implementing the -- requirements. As such, in step 3, parts a, b, and c, do not have -- to be implemented in that order, provided that the result of the -- implemented code is compliant with the protocol's specification. -- --3.1 Step 2 -- -- Step 2 of section 4.3.2 reads: -- --# 2. Search the available zones for the zone which is the nearest --# ancestor to QNAME. If such a zone is found, go to step 3, --# otherwise step 4. -- --DNSEXT Working Group Expires July 9, 2006 [Page 10] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- In this step, the most appropriate zone for the response is -- chosen. The significance of this step is that it means all of -- step 3 is being performed within one zone. This has significance -- when considering whether or not an SOA RR can be ever be used for -- synthesis. -- --3.2 Step 3 -- -- Step 3 is dominated by three parts, labelled 'a', 'b', and 'c'. -- But the beginning of the step is important and needs explanation. -- --# 3. Start matching down, label by label, in the zone. The --# matching process can terminate several ways: -- -- The word 'matching' refers to label matching. The concept -- is based in the view of the zone as the tree of existing names. -- The query name is considered to be an ordered sequence of -- labels - as if the name were a path from the root to the owner -- of the desired data. (Which it is - 3rd paragraph of RFC 1034, -- section 3.1.) -- -- The process of label matching a query name ends in exactly one of -- three choices, the parts 'a', 'b', and 'c'. Either the name is -- found, the name is below a cut point, or the name is not found. -- -- Once one of the parts is chosen, the other parts are not -- considered. (E.g., do not execute part 'c' and then change -- the execution path to finish in part 'b'.) The process of label -- matching is also done independent of the query type (QTYPE). -- -- Parts 'a' and 'b' are not an issue for this clarification as they -- do not relate to record synthesis. Part 'a' is an exact match -- that results in an answer, part 'b' is a referral. -- --3.3 Part 'c' -- -- The context of part 'c' is that the process of label matching the -- labels of the query name has resulted in a situation in which -- there is no corresponding label in the tree. It is as if the -- lookup has "fallen off the tree." -- --# c. If at some label, a match is impossible (i.e., the --# corresponding label does not exist), look to see if [...] --# the "*" label exists. -- -- To help describe the process of looking 'to see if [...] the "*" -- label exists' a term has been coined to describe the last domain -- (node) matched. The term is "closest encloser." -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 11] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --3.3.1 Closest Encloser and the Source of Synthesis -- -- The closest encloser is the node in the zone's tree of existing -- domain names that has the most labels matching the query name -- (consecutively, counting from the root label downward). Each match -- is a "label match" and the order of the labels is the same. -- -- The closest encloser is, by definition, an existing name in the -- zone. The closest encloser might be an empty non-terminal or even -- be a wild card domain name itself. In no circumstances is the -- closest encloser to be used to synthesize records for the current -- query. -- -- The source of synthesis is defined in the context of a query -- process as that wild card domain name immediately descending -- from the closest encloser, provided that this wild card domain -- name exists. "Immediately descending" means that the source -- of synthesis has a name of the form: -- .. -- A source of synthesis does not guarantee having a RRSet to use -- for synthesis. The source of synthesis could be an empty -- non-terminal. -- -- If the source of synthesis does not exist (not on the domain -- tree), there will be no wildcard synthesis. There is no search -- for an alternate. -- -- The important concept is that for any given lookup process, there -- is at most one place at which wildcard synthetic records can be -- obtained. If the source of synthesis does not exist, the lookup -- terminates, the lookup does not look for other wildcard records. -- --3.3.2 Closest Encloser and Source of Synthesis Examples -- -- To illustrate, using the example zone in section 2.2.1 of this -- document, the following chart shows QNAMEs and the closest -- enclosers. -- -- QNAME Closest Encloser Source of Synthesis -- host3.example. example. *.example. -- _telnet._tcp.host1.example. _tcp.host1.example. no source -- _telnet._tcp.host2.example. host2.example. no source -- _telnet._tcp.host3.example. example. *.example. -- _chat._udp.host3.example. example. *.example. -- foobar.*.example. *.example. no source -- -- -- -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 12] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --3.3.3 Type Matching -- -- RFC 1034 concludes part 'c' with this: -- --# If the "*" label does not exist, check whether the name --# we are looking for is the original QNAME in the query --# or a name we have followed due to a CNAME. If the name --# is original, set an authoritative name error in the --# response and exit. Otherwise just exit. --# --# If the "*" label does exist, match RRs at that node --# against QTYPE. If any match, copy them into the answer --# section, but set the owner of the RR to be QNAME, and --# not the node with the "*" label. Go to step 6. -- -- The final paragraph covers the role of the QTYPE in the lookup -- process. -- -- Based on implementation feedback and similarities between step -- 'a' and step 'c' a change to this passage has been made. -- -- The change is to add the following text to step 'c' prior to the -- instructions to "go to step 6": -- -- If the data at the source of synthesis is a CNAME, and -- QTYPE doesn't match CNAME, copy the CNAME RR into the -- answer section of the response changing the owner name -- to the QNAME, change QNAME to the canonical name in the -- CNAME RR, and go back to step 1. -- -- This is essentially the same text in step a covering the -- processing of CNAME RRSets. -- --4. Considerations with Special Types -- -- Sections 2 and 3 of this document discuss wildcard synthesis -- with respect to names in the domain tree and ignore the impact -- of types. In this section, the implication of wildcards of -- specific types are discussed. The types covered are those -- that have proven to be the most difficult to understand. The -- types are SOA, NS, CNAME, DNAME, SRV, DS, NSEC, RRSIG and -- "none," i.e., empty non-terminal wild card domain names. -- --4.1 SOA RRSet at a Wild Card Domain Name -- -- A wild card domain name owning an SOA RRSet means that the -- domain is at the root of the zone (apex). The domain can not -- be a source of synthesis because that is, by definition, a -- descendent node (of the closest encloser) and a zone apex is -- at the top of the zone. -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 13] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- Although a wild card domain name owning an SOA RRSet can never -- be a source of synthesis, there is no reason to forbid the -- ownership of an SOA RRSet. -- -- E.g., given this zone: -- $ORIGIN *.example. -- @ 3600 IN SOA -- 3600 NS ns1.example.com. -- 3600 NS ns1.example.net. -- www 3600 TXT "the www txt record" -- -- A query for www.*.example.'s TXT record would still find the -- "the www txt record" answer. The asterisk label only becomes -- significant when section 4.3.2, step 3 part 'c' is in effect. -- -- Of course, there would need to be a delegation in the parent -- zone, "example." for this to work too. This is covered in the -- next section. -- --4.2 NS RRSet at a Wild Card Domain Name -- -- With the definition of DNSSEC [RFC4033, RFC4034, RFC4035] now -- in place, the semantics of a wild card domain name owning an -- NS RRSet has come to be poorly defined. The dilemma relates to -- a conflict between the rules for synthesis in part 'c' and the -- fact that the resulting synthesis generates a record for which -- the zone is not authoritative. In a DNSSEC signed zone, the -- mechanics of signature management (generation and inclusion -- in a message) have become unclear. -- -- Salient points of the working group discussion on this topic is -- summarized in section 4.2.1. -- -- As a result of these discussion, there is no definition given for -- wild card domain names owning an NS RRSet. The semantics are -- left undefined until there is a clear need to have a set defined, -- and until there is a clear direction to proceed. Operationally, -- inclusion of wild card NS RRSets in a zone is discouraged, but -- not barred. -- --4.2.1 Discarded Notions -- -- Prior to DNSSEC, a wild card domain name owning a NS RRSet -- appeared to be workable, and there are some instances in which -- it is found in deployments using implementations that support -- this. Continuing to allow this in the specification is not -- tenable with DNSSEC. The reason is that the synthesis of the -- NS RRSet is being done in a zone that has delegated away the -- responsibility for the name. This "unauthorized" synthesis is -- not a problem for the base DNS protocol, but DNSSEC, in affirming -- the authorization model for DNS exposes the problem. -- --DNSEXT Working Group Expires July 9, 2006 [Page 14] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- Outright banning of wildcards of type NS is also untenable as -- the DNS protocol does not define how to handle "illegal" data. -- Implementations may choose not to load a zone, but there is no -- protocol definition. The lack of the definition is complicated -- by having to cover dynamic update [RFC 2136], zone transfers, -- as well as loading at the master server. The case of a client -- (resolver, caching server) getting a wildcard of type NS in -- a reply would also have to be considered. -- -- Given the daunting challenge of a complete definition of how to -- ban such records, dealing with existing implementations that -- permit the records today is a further complication. There are -- uses of wild card domain name owning NS RRSets. -- -- One compromise proposed would have redefined wildcards of type -- NS to not be used in synthesis, this compromise fell apart -- because it would have required significant edits to the DNSSEC -- signing and validation work. (Again, DNSSEC catches -- unauthorized data.) -- -- With no clear consensus forming on the solution to this dilemma, -- and the realization that wildcards of type NS are a rarity in -- operations, the best course of action is to leave this open-ended -- until "it matters." -- --4.3 CNAME RRSet at a Wild Card Domain Name -- -- The issue of a CNAME RRSet owned by a wild card domain name has -- prompted a suggested change to the last paragraph of step 3c of -- the algorithm in 4.3.2. The changed text appears in section -- 3.3.3 of this document. -- --4.4 DNAME RRSet at a Wild Card Domain Name -- -- Ownership of a DNAME [RFC2672] RRSet by a wild card domain name -- represents a threat to the coherency of the DNS and is to be -- avoided or outright rejected. Such a DNAME RRSet represents -- non-deterministic synthesis of rules fed to different caches. -- As caches are fed the different rules (in an unpredictable -- manner) the caches will cease to be coherent. ("As caches -- are fed" refers to the storage in a cache of records obtained -- in responses by recursive or iterative servers.) -- -- For example, assume one cache, responding to a recursive -- request, obtains the record: -- "a.b.example. DNAME foo.bar.example.net." -- and another cache obtains: -- "b.example. DNAME foo.bar.example.net." -- both generated from the record: -- "*.example. DNAME foo.bar.example.net." -- by an authoritative server. -- --DNSEXT Working Group Expires July 9, 2006 [Page 15] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- The DNAME specification is not clear on whether DNAME records -- in a cache are used to rewrite queries. In some interpretations, -- the rewrite occurs, in some, it is not. Allowing for the -- occurrence of rewriting, queries for "sub.a.b.example. A" may -- be rewritten as "sub.foo.bar.tld. A" by the former caching -- server and may be rewritten as "sub.a.foo.bar.tld. A" by the -- latter. Coherency is lost, an operational nightmare ensues. -- -- Another justification for banning or avoiding wildcard DNAME -- records is the observation that such a record could synthesize -- a DNAME owned by "sub.foo.bar.example." and "foo.bar.example." -- There is a restriction in the DNAME definition that no domain -- exist below a DNAME-owning domain, hence, the wildcard DNAME -- is not to be permitted. -- --4.5 SRV RRSet at a Wild Card Domain Name -- -- The definition of the SRV RRset is RFC 2782 [RFC2782]. In the -- definition of the record, there is some confusion over the term -- "Name." The definition reads as follows: -- --# The format of the SRV RR --... --# _Service._Proto.Name TTL Class SRV Priority Weight Port Target --... --# Name --# The domain this RR refers to. The SRV RR is unique in that the --# name one searches for is not this name; the example near the end --# shows this clearly. -- -- Do not confuse the definition "Name" with the owner name. I.e., -- once removing the _Service and _Proto labels from the owner name -- of the SRV RRSet, what remains could be a wild card domain name -- but this is immaterial to the SRV RRSet. -- -- E.g., If an SRV record is: -- _foo._udp.*.example. 10800 IN SRV 0 1 9 old-slow-box.example. -- -- *.example is a wild card domain name and although it is the Name -- of the SRV RR, it is not the owner (domain name). The owner -- domain name is "_foo._udp.*.example." which is not a wild card -- domain name. -- -- The confusion is likely based on the mixture of the specification -- of the SRV RR and the description of a "use case." -- --4.6 DS RRSet at a Wild Card Domain Name -- -- A DS RRSet owned by a wild card domain name is meaningless and -- harmless. This statement is made in the context that an NS RRSet -- at a wild card domain name is undefined. At a non-delegation -- --DNSEXT Working Group Expires July 9, 2006 [Page 16] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- point, a DS RRSet has no value (no corresponding DNSKEY RRSet -- will be used in DNSSEC validation). If there is a synthesized -- DS RRSet, it alone will not be very useful as it exists in the -- context of a delegation point. -- --4.7 NSEC RRSet at a Wild Card Domain Name -- -- Wild card domain names in DNSSEC signed zones will have an NSEC -- RRSet. Synthesis of these records will only occur when the -- query exactly matches the record. Synthesized NSEC RR's will not -- be harmful as they will never be used in negative caching or to -- generate a negative response. [RFC2308] -- --4.8 RRSIG at a Wild Card Domain Name -- -- RRSIG records will be present at a wild card domain name in a -- signed zone, and will be synthesized along with data sought in a -- query. The fact that the owner name is synthesized is not a -- problem as the label count in the RRSIG will instruct the -- verifying code to ignore it. -- --4.9 Empty Non-terminal Wild Card Domain Name -- -- If a source of synthesis is an empty non-terminal, then the -- response will be one of no error in the return code and no RRSet -- in the answer section. -- --5. Security Considerations -- -- This document is refining the specifications to make it more -- likely that security can be added to DNS. No functional -- additions are being made, just refining what is considered -- proper to allow the DNS, security of the DNS, and extending -- the DNS to be more predictable. -- --6. IANA Considerations -- -- None. -- --7. References -- -- Normative References -- -- [RFC20] ASCII Format for Network Interchange, V.G. Cerf, -- Oct-16-1969 -- -- [RFC1034] Domain Names - Concepts and Facilities, -- P.V. Mockapetris, Nov-01-1987 -- -- [RFC1035] Domain Names - Implementation and Specification, P.V -- Mockapetris, Nov-01-1987 -- --DNSEXT Working Group Expires July 9, 2006 [Page 17] -- --Internet-Draft dnsext-wcard January 9, 2006 -- -- [RFC1995] Incremental Zone Transfer in DNS, M. Ohta, August 1996 -- -- [RFC2119] Key Words for Use in RFCs to Indicate Requirement -- Levels, S Bradner, March 1997 -- -- [RFC2308] Negative Caching of DNS Queries (DNS NCACHE), -- M. Andrews, March 1998 -- -- [RFC2672] Non-Terminal DNS Name Redirection, M. Crawford, -- August 1999. -- -- [RFC2782] A DNS RR for specifying the location of services (DNS -- SRV), A. Gulbrandsen, et.al., February 2000 -- -- [RFC4033] DNS Security Introduction and Requirements, R. Arends, -- et.al., March 2005 -- -- [RFC4034] Resource Records for the DNS Security Extensions, -- R. Arends, et.al., March 2005 -- -- [RFC4035] Protocol Modifications for the DNS Security Extensions, -- R. Arends, et.al., March 2005 -- -- Informative References -- -- [RFC2136] Dynamic Updates in the Domain Name System (DNS UPDATE), -- P. Vixie, Ed., S. Thomson, Y. Rekhter, J. Bound, -- April 1997 -- --8. Editor -- -- Name: Edward Lewis -- Affiliation: NeuStar -- Address: 46000 Center Oak Plaza, Sterling, VA, 20166, US -- Phone: +1-571-434-5468 -- Email: ed.lewis@neustar.biz -- -- Comments on this document can be sent to the editor or the mailing -- list for the DNSEXT WG, namedroppers@ops.ietf.org. -- --9. Others Contributing to the Document -- -- This document represents the work of a large working group. The -- editor merely recorded the collective wisdom of the working group. -- -- -- -- -- -- -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 17] -- --Internet-Draft dnsext-wcard January 9, 2006 -- --10. Trailing Boilerplate -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided -- on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION -- HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET -- SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL -- WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO -- ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT -- INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF -- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of -- any Intellectual Property Rights or other rights that might -- be claimed to pertain to the implementation or use of the -- technology described in this document or the extent to which -- any license under such rights might or might not be available; -- nor does it represent that it has made any independent effort -- to identify any such rights. Information on the procedures -- with respect to rights in RFC documents can be found in BCP 78 -- and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the -- use of such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR -- repository at http://www.ietf.org/ipr. The IETF invites any -- interested party to bring to its attention any copyrights, -- patents or patent applications, or other proprietary rights -- that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- --Expiration -- -- This document expires on or about July 9, 2006. -- -- -- --DNSEXT Working Group Expires July 9, 2006 [Page 19] diff --cc doc/draft/draft-ietf-dnsop-bad-dns-res-05.txt index 0855ba358c9,0855ba358c9..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsop-bad-dns-res-05.txt +++ /dev/null @@@ -1,1232 -1,1232 +1,0 @@@ -- -- -- --DNS Operations M. Larson --Internet-Draft P. Barber --Expires: August 14, 2006 VeriSign -- February 10, 2006 -- -- -- Observed DNS Resolution Misbehavior -- draft-ietf-dnsop-bad-dns-res-05 -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on August 14, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This memo describes DNS iterative resolver behavior that results in a -- significant query volume sent to the root and top-level domain (TLD) -- name servers. We offer implementation advice to iterative resolver -- developers to alleviate these unnecessary queries. The -- recommendations made in this document are a direct byproduct of -- observation and analysis of abnormal query traffic patterns seen at -- two of the thirteen root name servers and all thirteen com/net TLD -- name servers. -- -- -- --Larson & Barber Expires August 14, 2006 [Page 1] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119 [1]. -- -- --Table of Contents -- -- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 -- 1.1. A note about terminology in this memo . . . . . . . . . . 3 -- 2. Observed iterative resolver misbehavior . . . . . . . . . . . 5 -- 2.1. Aggressive requerying for delegation information . . . . . 5 -- 2.1.1. Recommendation . . . . . . . . . . . . . . . . . . . . 6 -- 2.2. Repeated queries to lame servers . . . . . . . . . . . . . 7 -- 2.2.1. Recommendation . . . . . . . . . . . . . . . . . . . . 7 -- 2.3. Inability to follow multiple levels of indirection . . . . 8 -- 2.3.1. Recommendation . . . . . . . . . . . . . . . . . . . . 9 -- 2.4. Aggressive retransmission when fetching glue . . . . . . . 9 -- 2.4.1. Recommendation . . . . . . . . . . . . . . . . . . . . 10 -- 2.5. Aggressive retransmission behind firewalls . . . . . . . . 10 -- 2.5.1. Recommendation . . . . . . . . . . . . . . . . . . . . 11 -- 2.6. Misconfigured NS records . . . . . . . . . . . . . . . . . 11 -- 2.6.1. Recommendation . . . . . . . . . . . . . . . . . . . . 12 -- 2.7. Name server records with zero TTL . . . . . . . . . . . . 12 -- 2.7.1. Recommendation . . . . . . . . . . . . . . . . . . . . 13 -- 2.8. Unnecessary dynamic update messages . . . . . . . . . . . 13 -- 2.8.1. Recommendation . . . . . . . . . . . . . . . . . . . . 14 -- 2.9. Queries for domain names resembling IPv4 addresses . . . . 14 -- 2.9.1. Recommendation . . . . . . . . . . . . . . . . . . . . 14 -- 2.10. Misdirected recursive queries . . . . . . . . . . . . . . 15 -- 2.10.1. Recommendation . . . . . . . . . . . . . . . . . . . . 15 -- 2.11. Suboptimal name server selection algorithm . . . . . . . . 15 -- 2.11.1. Recommendation . . . . . . . . . . . . . . . . . . . . 16 -- 3. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 -- 4. IANA considerations . . . . . . . . . . . . . . . . . . . . . 18 -- 5. Security considerations . . . . . . . . . . . . . . . . . . . 19 -- 6. Internationalization considerations . . . . . . . . . . . . . 20 -- 7. Informative References . . . . . . . . . . . . . . . . . . . . 20 -- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 -- Intellectual Property and Copyright Statements . . . . . . . . . . 22 -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 2] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --1. Introduction -- -- Observation of query traffic received by two root name servers and -- the thirteen com/net TLD name servers has revealed that a large -- proportion of the total traffic often consists of "requeries". A -- requery is the same question () asked -- repeatedly at an unexpectedly high rate. We have observed requeries -- from both a single IP address and multiple IP addresses (i.e., the -- same query received simultaneously from multiple IP addresses). -- -- By analyzing requery events we have found that the cause of the -- duplicate traffic is almost always a deficient iterative resolver, -- stub resolver or application implementation combined with an -- operational anomaly. The implementation deficiencies we have -- identified to date include well-intentioned recovery attempts gone -- awry, insufficient caching of failures, early abort when multiple -- levels of indirection must be followed, and aggressive retry by stub -- resolvers or applications. Anomalies that we have seen trigger -- requery events include lame delegations, unusual glue records, and -- anything that makes all authoritative name servers for a zone -- unreachable (DoS attacks, crashes, maintenance, routing failures, -- congestion, etc.). -- -- In the following sections, we provide a detailed explanation of the -- observed behavior and recommend changes that will reduce the requery -- rate. None of the changes recommended affects the core DNS protocol -- specification; instead, this document consists of guidelines to -- implementors of iterative resolvers. -- --1.1. A note about terminology in this memo -- -- To recast an old saying about standards, the nice thing about DNS -- terms is that there are so many of them to choose from. Writing or -- talking about DNS can be difficult and cause confusion resulting from -- a lack of agreed-upon terms for its various components. Further -- complicating matters are implementations that combine multiple roles -- into one piece of software, which makes naming the result -- problematic. An example is the entity that accepts recursive -- queries, issues iterative queries as necessary to resolve the initial -- recursive query, caches responses it receives, and which is also able -- to answer questions about certain zones authoritatively. This entity -- is an iterative resolver combined with an authoritative name server -- and is often called a "recursive name server" or a "caching name -- server". -- -- This memo is concerned principally with the behavior of iterative -- resolvers, which are typically found as part of a recursive name -- server. This memo uses the more precise term "iterative resolver", -- -- -- --Larson & Barber Expires August 14, 2006 [Page 3] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- because the focus is usually on that component. In instances where -- the name server role of this entity requires mentioning, this memo -- uses the term "recursive name server". As an example of the -- difference, the name server component of a recursive name server -- receives DNS queries and the iterative resolver component sends -- queries. -- -- The advent of IPv6 requires mentioning AAAA records as well as A -- records when discussing glue. To avoid continuous repetition and -- qualification, this memo uses the general term "address record" to -- encompass both A and AAAA records when a particular situation is -- relevant to both types. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 4] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --2. Observed iterative resolver misbehavior -- --2.1. Aggressive requerying for delegation information -- -- There can be times when every name server in a zone's NS RRset is -- unreachable (e.g., during a network outage), unavailable (e.g., the -- name server process is not running on the server host) or -- misconfigured (e.g., the name server is not authoritative for the -- given zone, also known as "lame"). Consider an iterative resolver -- that attempts to resolve a query for a domain name in such a zone and -- discovers that none of the zone's name servers can provide an answer. -- We have observed a recursive name server implementation whose -- iterative resolver then verifies the zone's NS RRset in its cache by -- querying for the zone's delegation information: it sends a query for -- the zone's NS RRset to one of the parent zone's name servers. (Note -- that queries with QTYPE=NS are not required by the standard -- resolution algorithm described in section 4.3.2 of RFC 1034 [2]. -- These NS queries represent this implementation's addition to that -- algorithm.) -- -- For example, suppose that "example.com" has the following NS RRset: -- -- example.com. IN NS ns1.example.com. -- example.com. IN NS ns2.example.com. -- -- Upon receipt of a query for "www.example.com" and assuming that -- neither "ns1.example.com" nor "ns2.example.com" can provide an -- answer, this iterative resolver implementation immediately queries a -- "com" zone name server for the "example.com" NS RRset to verify it -- has the proper delegation information. This implementation performs -- this query to a zone's parent zone for each recursive query it -- receives that fails because of a completely unresponsive set of name -- servers for the target zone. Consider the effect when a popular zone -- experiences a catastrophic failure of all its name servers: now every -- recursive query for domain names in that zone sent to this recursive -- name server implementation results in a query to the failed zone's -- parent name servers. On one occasion when several dozen popular -- zones became unreachable, the query load on the com/net name servers -- increased by 50%. -- -- We believe this verification query is not reasonable. Consider the -- circumstances: When an iterative resolver is resolving a query for a -- domain name in a zone it has not previously searched, it uses the -- list of name servers in the referral from the target zone's parent. -- If on its first attempt to search the target zone, none of the name -- servers in the referral is reachable, a verification query to the -- parent would be pointless: this query to the parent would come so -- quickly on the heels of the referral that it would be almost certain -- -- -- --Larson & Barber Expires August 14, 2006 [Page 5] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- to contain the same list of name servers. The chance of discovering -- any new information is slim. -- -- The other possibility is that the iterative resolver successfully -- contacts one of the target zone's name servers and then caches the NS -- RRset from the authority section of a response, the proper behavior -- according to section 5.4.1 of RFC 2181 [3], because the NS RRset from -- the target zone is more trustworthy than delegation information from -- the parent zone. If, while processing a subsequent recursive query, -- the iterative resolver discovers that none of the name servers -- specified in the cached NS RRset is available or authoritative, -- querying the parent would be wrong. An NS RRset from the parent zone -- would now be less trustworthy than data already in the cache. -- -- For this query of the parent zone to be useful, the target zone's -- entire set of name servers would have to change AND the former set of -- name servers would have to be deconfigured or decommissioned AND the -- delegation information in the parent zone would have to be updated -- with the new set of name servers, all within the TTL of the target -- zone's NS RRset. We believe this scenario is uncommon: -- administrative best practices dictate that changes to a zone's set of -- name servers happen gradually when at all possible, with servers -- removed from the NS RRset left authoritative for the zone as long as -- possible. The scenarios that we can envision that would benefit from -- the parent requery behavior do not outweigh its damaging effects. -- -- This section should not be understood to claim that all queries to a -- zone's parent are bad. In some cases, such queries are not only -- reasonable but required. Consider the situation when required -- information, such as the address of a name server (i.e., the address -- record corresponding to the RDATA of an NS record), has timed out of -- an iterative resolver's cache before the corresponding NS record. If -- the name of the name server is below the apex of the zone, then the -- name server's address record is only available as glue in the parent -- zone. For example, consider this NS record: -- -- example.com. IN NS ns.example.com. -- -- If a cache has this NS record but not the address record for -- "ns.example.com", it is unable to contact the "example.com" zone -- directly and must query the "com" zone to obtain the address record. -- Note, however, that such a query would not have QTYPE=NS according to -- the standard resolution algorithm. -- --2.1.1. Recommendation -- -- An iterative resolver MUST NOT send a query for the NS RRset of a -- non-responsive zone to any of the name servers for that zone's parent -- -- -- --Larson & Barber Expires August 14, 2006 [Page 6] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- zone. For the purposes of this injunction, a non-responsive zone is -- defined as a zone for which every name server listed in the zone's NS -- RRset: -- -- 1. is not authoritative for the zone (i.e., lame), or, -- -- 2. returns a server failure response (RCODE=2), or, -- -- 3. is dead or unreachable according to section 7.2 of RFC 2308 [4]. -- --2.2. Repeated queries to lame servers -- -- Section 2.1 describes a catastrophic failure: when every name server -- for a zone is unable to provide an answer for one reason or another. -- A more common occurrence is when a subset of a zone's name servers -- are unavailable or misconfigured. Different failure modes have -- different expected durations. Some symptoms indicate problems that -- are potentially transient; for example, various types of ICMP -- unreachable messages because a name server process is not running or -- a host or network is unreachable, or a complete lack of a response to -- a query. Such responses could be the result of a host rebooting or -- temporary outages; these events don't necessarily require any human -- intervention and can be reasonably expected to be temporary. -- -- Other symptoms clearly indicate a condition requiring human -- intervention, such as lame server: if a name server is misconfigured -- and not authoritative for a zone delegated to it, it is reasonable to -- assume that this condition has potential to last longer than -- unreachability or unresponsiveness. Consequently, repeated queries -- to known lame servers are not useful. In this case of a condition -- with potential to persist for a long time, a better practice would be -- to maintain a list of known lame servers and avoid querying them -- repeatedly in a short interval. -- -- It should also be noted, however, that some authoritative name server -- implementations appear to be lame only for queries of certain types -- as described in RFC 4074 [5]. In this case, it makes sense to retry -- the "lame" servers for other types of queries, particularly when all -- known authoritative name servers appear to be "lame". -- --2.2.1. Recommendation -- -- Iterative resolvers SHOULD cache name servers that they discover are -- not authoritative for zones delegated to them (i.e. lame servers). -- If this caching is performed, lame servers MUST be cached against the -- specific query tuple . Zone -- name can be derived from the owner name of the NS record that was -- referenced to query the name server that was discovered to be lame. -- -- -- --Larson & Barber Expires August 14, 2006 [Page 7] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- Implementations that perform lame server caching MUST refrain from -- sending queries to known lame servers based on a time interval from -- when the server is discovered to be lame. A minimum interval of -- thirty minutes is RECOMMENDED. -- -- An exception to this recommendation occurs if all name servers for a -- zone are marked lame. In that case, the iterative resolver SHOULD -- temporarily ignore the servers' lameness status and query one or more -- servers. This behavior is a workaround for the type-specific -- lameness issue described in the previous section. -- -- Implementors should take care not to make lame server avoidance logic -- overly broad: note that a name server could be lame for a parent zone -- but not a child zone, e.g., lame for "example.com" but properly -- authoritative for "sub.example.com". Therefore a name server should -- not be automatically considered lame for subzones. In the case -- above, even if a name server is known to be lame for "example.com", -- it should be queried for QNAMEs at or below "sub.example.com" if an -- NS record indicates it should be authoritative for that zone. -- --2.3. Inability to follow multiple levels of indirection -- -- Some iterative resolver implementations are unable to follow -- sufficient levels of indirection. For example, consider the -- following delegations: -- -- foo.example. IN NS ns1.example.com. -- foo.example. IN NS ns2.example.com. -- -- example.com. IN NS ns1.test.example.net. -- example.com. IN NS ns2.test.example.net. -- -- test.example.net. IN NS ns1.test.example.net. -- test.example.net. IN NS ns2.test.example.net. -- -- An iterative resolver resolving the name "www.foo.example" must -- follow two levels of indirection, first obtaining address records for -- "ns1.test.example.net" or "ns2.test.example.net" in order to obtain -- address records for "ns1.example.com" or "ns2.example.com" in order -- to query those name servers for the address records of -- "www.foo.example". While this situation may appear contrived, we -- have seen multiple similar occurrences and expect more as new generic -- top-level domains (gTLDs) become active. We anticipate many zones in -- new gTLDs will use name servers in existing gTLDs, increasing the -- number of delegations using out-of-zone name servers. -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 8] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --2.3.1. Recommendation -- -- Clearly constructing a delegation that relies on multiple levels of -- indirection is not a good administrative practice. However, the -- practice is widespread enough to require that iterative resolvers be -- able to cope with it. Iterative resolvers SHOULD be able to handle -- arbitrary levels of indirection resulting from out-of-zone name -- servers. Iterative resolvers SHOULD implement a level-of-effort -- counter to avoid loops or otherwise performing too much work in -- resolving pathological cases. -- -- A best practice that avoids this entire issue of indirection is to -- name one or more of a zone's name servers in the zone itself. For -- example, if the zone is named "example.com", consider naming some of -- the name servers "ns{1,2,...}.example.com" (or similar). -- --2.4. Aggressive retransmission when fetching glue -- -- When an authoritative name server responds with a referral, it -- includes NS records in the authority section of the response. -- According to the algorithm in section 4.3.2 of RFC 1034 [2], the name -- server should also "put whatever addresses are available into the -- additional section, using glue RRs if the addresses are not available -- from authoritative data or the cache." Some name server -- implementations take this address inclusion a step further with a -- feature called "glue fetching". A name server that implements glue -- fetching attempts to include address records for every NS record in -- the authority section. If necessary, the name server issues multiple -- queries of its own to obtain any missing address records. -- -- Problems with glue fetching can arise in the context of -- "authoritative-only" name servers, which only serve authoritative -- data and ignore requests for recursion. Such an entity will not -- normally generate any queries of its own. Instead it answers non- -- recursive queries from iterative resolvers looking for information in -- zones it serves. With glue fetching enabled, however, an -- authoritative server invokes an iterative resolver to look up an -- unknown address record to complete the additional section of a -- response. -- -- We have observed situations where the iterative resolver of a glue- -- fetching name server can send queries that reach other name servers, -- but is apparently prevented from receiving the responses. For -- example, perhaps the name server is authoritative-only and therefore -- its administrators expect it to receive only queries and not -- responses. Perhaps unaware of glue fetching and presuming that the -- name server's iterative resolver will generate no queries, its -- administrators place the name server behind a network device that -- -- -- --Larson & Barber Expires August 14, 2006 [Page 9] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- prevents it from receiving responses. If this is the case, all glue- -- fetching queries will go answered. -- -- We have observed name server implementations whose iterative -- resolvers retry excessively when glue-fetching queries are -- unanswered. A single com/net name server has received hundreds of -- queries per second from a single such source. Judging from the -- specific queries received and based on additional analysis, we -- believe these queries result from overly aggressive glue fetching. -- --2.4.1. Recommendation -- -- Implementers whose name servers support glue fetching SHOULD take -- care to avoid sending queries at excessive rates. Implementations -- SHOULD support throttling logic to detect when queries are sent but -- no responses are received. -- --2.5. Aggressive retransmission behind firewalls -- -- A common occurrence and one of the largest sources of repeated -- queries at the com/net and root name servers appears to result from -- resolvers behind misconfigured firewalls. In this situation, an -- iterative resolver is apparently allowed to send queries through a -- firewall to other name servers, but not receive the responses. The -- result is more queries than necessary because of retransmission, all -- of which are useless because the responses are never received. Just -- as with the glue-fetching scenario described in Section 2.4, the -- queries are sometimes sent at excessive rates. To make matters -- worse, sometimes the responses, sent in reply to legitimate queries, -- trigger an alarm on the originator's intrusion detection system. We -- are frequently contacted by administrators responding to such alarms -- who believe our name servers are attacking their systems. -- -- Not only do some resolvers in this situation retransmit queries at an -- excessive rate, but they continue to do so for days or even weeks. -- This scenario could result from an organization with multiple -- recursive name servers, only a subset of whose iterative resolvers' -- traffic is improperly filtered in this manner. Stub resolvers in the -- organization could be configured to query multiple recursive name -- servers. Consider the case where a stub resolver queries a filtered -- recursive name server first. The iterative resolver of this -- recursive name server sends one or more queries whose replies are -- filtered, so it can't respond to the stub resolver, which times out. -- Then the stub resolver retransmits to a recursive name server that is -- able to provide an answer. Since resolution ultimately succeeds the -- underlying problem might not be recognized or corrected. A popular -- stub resolver implementation has a very aggressive retransmission -- schedule, including simultaneous queries to multiple recursive name -- -- -- --Larson & Barber Expires August 14, 2006 [Page 10] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- servers, which could explain how such a situation could persist -- without being detected. -- --2.5.1. Recommendation -- -- The most obvious recommendation is that administrators SHOULD take -- care not to place iterative resolvers behind a firewall that allows -- queries to pass through but not the resulting replies. -- -- Iterative resolvers SHOULD take care to avoid sending queries at -- excessive rates. Implementations SHOULD support throttling logic to -- detect when queries are sent but no responses are received. -- --2.6. Misconfigured NS records -- -- Sometimes a zone administrator forgets to add the trailing dot on the -- domain names in the RDATA of a zone's NS records. Consider this -- fragment of the zone file for "example.com": -- -- $ORIGIN example.com. -- example.com. 3600 IN NS ns1.example.com ; Note missing -- example.com. 3600 IN NS ns2.example.com ; trailing dots -- -- The zone's authoritative servers will parse the NS RDATA as -- "ns1.example.com.example.com" and "ns2.example.com.example.com" and -- return NS records with this incorrect RDATA in responses, including -- typically the authority section of every response containing records -- from the "example.com" zone. -- -- Now consider a typical sequence of queries. An iterative resolver -- attempting to resolve address records for "www.example.com" with no -- cached information for this zone will query a "com" authoritative -- server. The "com" server responds with a referral to the -- "example.com" zone, consisting of NS records with valid RDATA and -- associated glue records. (This example assumes that the -- "example.com" zone delegation information is correct in the "com" -- zone.) The iterative resolver caches the NS RRset from the "com" -- server and follows the referral by querying one of the "example.com" -- authoritative servers. This server responds with the -- "www.example.com" address record in the answer section and, -- typically, the "example.com" NS records in the authority section and, -- if space in the message remains, glue address records in the -- additional section. According to Section 5.4 of RFC 2181 [3], NS -- records in the authority section of an authoritative answer are more -- trustworthy than NS records from the authority section of a non- -- authoritative answer. Thus the "example.com" NS RRset just received -- from the "example.com" authoritative server overrides the -- "example.com" NS RRset received moments ago from the "com" -- -- -- --Larson & Barber Expires August 14, 2006 [Page 11] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- authoritative server. -- -- But the "example.com" zone contains the erroneous NS RRset as shown -- in the example above. Subsequent queries for names in "example.com" -- will cause the iterative resolver to attempt to use the incorrect NS -- records and so it will try to resolve the nonexistent names -- "ns1.example.com.example.com" and "ns2.example.com.example.com". In -- this example, since all of the zone's name servers are named in the -- zone itself (i.e., "ns1.example.com.example.com" and -- "ns2.example.com.example.com" both end in "example.com") and all are -- bogus, the iterative resolver cannot reach any "example.com" name -- servers. Therefore attempts to resolve these names result in address -- record queries to the "com" authoritative servers. Queries for such -- obviously bogus glue address records occur frequently at the com/net -- name servers. -- --2.6.1. Recommendation -- -- An authoritative server can detect this situation. A trailing dot -- missing from an NS record's RDATA always results by definition in a -- name server name that exists somewhere under the apex of the zone the -- NS record appears in. Note that further levels of delegation are -- possible, so a missing trailing dot could inadvertently create a name -- server name that actually exists in a subzone. -- -- An authoritative name server SHOULD issue a warning when one of a -- zone's NS records references a name server below the zone's apex when -- a corresponding address record does not exist in the zone AND there -- are no delegated subzones where the address record could exist. -- --2.7. Name server records with zero TTL -- -- Sometimes a popular com/net subdomain's zone is configured with a TTL -- of zero on the zone's NS records, which prohibits these records from -- being cached and will result in a higher query volume to the zone's -- authoritative servers. The zone's administrator should understand -- the consequences of such a configuration and provision resources -- accordingly. A zero TTL on the zone's NS RRset, however, carries -- additional consequences beyond the zone itself: if an iterative -- resolver cannot cache a zone's NS records because of a zero TTL, it -- will be forced to query that zone's parent's name servers each time -- it resolves a name in the zone. The com/net authoritative servers do -- see an increased query load when a popular com/net subdomain's zone -- is configured with a TTL of zero on the zone's NS records. -- -- A zero TTL on an RRset expected to change frequently is extreme but -- permissible. A zone's NS RRset is a special case, however, because -- changes to it must be coordinated with the zone's parent. In most -- -- -- --Larson & Barber Expires August 14, 2006 [Page 12] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- zone parent/child relationships we are aware of, there is typically -- some delay involved in effecting changes. Further, changes to the -- set of a zone's authoritative name servers (and therefore to the -- zone's NS RRset) are typically relatively rare: providing reliable -- authoritative service requires a reasonably stable set of servers. -- Therefore an extremely low or zero TTL on a zone's NS RRset rarely -- makes sense, except in anticipation of an upcoming change. In this -- case, when the zone's administrator has planned a change and does not -- want iterative resolvers throughout the Internet to cache the NS -- RRset for a long period of time, a low TTL is reasonable. -- --2.7.1. Recommendation -- -- Because of the additional load placed on a zone's parent's -- authoritative servers resulting from a zero TTL on a zone's NS RRset, -- under such circumstances authoritative name servers SHOULD issue a -- warning when loading a zone. -- --2.8. Unnecessary dynamic update messages -- -- The UPDATE message specified in RFC 2136 [6] allows an authorized -- agent to update a zone's data on an authoritative name server using a -- DNS message sent over the network. Consider the case of an agent -- desiring to add a particular resource record. Because of zone cuts, -- the agent does not necessarily know the proper zone to which the -- record should be added. The dynamic update process requires that the -- agent determine the appropriate zone so the UPDATE message can be -- sent to one of the zone's authoritative servers (typically the -- primary master as specified in the zone's SOA MNAME field). -- -- The appropriate zone to update is the closest enclosing zone, which -- cannot be determined only by inspecting the domain name of the record -- to be updated, since zone cuts can occur anywhere. One way to -- determine the closest enclosing zone entails walking up the name -- space tree by sending repeated UPDATE messages until success. For -- example, consider an agent attempting to add an address record with -- the name "foo.bar.example.com". The agent could first attempt to -- update the "foo.bar.example.com" zone. If the attempt failed, the -- update could be directed to the "bar.example.com" zone, then the -- "example.com" zone, then the "com" zone, and finally the root zone. -- -- A popular dynamic agent follows this algorithm. The result is many -- UPDATE messages received by the root name servers, the com/net -- authoritative servers, and presumably other TLD authoritative -- servers. A valid question is why the algorithm proceeds to send -- updates all the way to TLD and root name servers. This behavior is -- not entirely unreasonable: in enterprise DNS architectures with an -- "internal root" design, there could conceivably be private, non- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 13] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- public TLD or root zones that would be the appropriate targets for a -- dynamic update. -- -- A significant deficiency with this algorithm is that knowledge of a -- given UPDATE message's failure is not helpful in directing future -- UPDATE messages to the appropriate servers. A better algorithm would -- be to find the closest enclosing zone by walking up the name space -- with queries for SOA or NS rather than "probing" with UPDATE -- messages. Once the appropriate zone is found, an UPDATE message can -- be sent. In addition, the results of these queries can be cached to -- aid in determining closest enclosing zones for future updates. Once -- the closest enclosing zone is determined with this method, the update -- will either succeed or fail and there is no need to send further -- updates to higher-level zones. The important point is that walking -- up the tree with queries yields cacheable information, whereas -- walking up the tree by sending UPDATE messages does not. -- --2.8.1. Recommendation -- -- Dynamic update agents SHOULD send SOA or NS queries to progressively -- higher-level names to find the closest enclosing zone for a given -- name to update. Only after the appropriate zone is found should the -- client send an UPDATE message to one of the zone's authoritative -- servers. Update clients SHOULD NOT "probe" using UPDATE messages by -- walking up the tree to progressively higher-level zones. -- --2.9. Queries for domain names resembling IPv4 addresses -- -- The root name servers receive a significant number of A record -- queries where the QNAME looks like an IPv4 address. The source of -- these queries is unknown. It could be attributed to situations where -- a user believes an application will accept either a domain name or an -- IP address in a given configuration option. The user enters an IP -- address, but the application assumes any input is a domain name and -- attempts to resolve it, resulting in an A record lookup. There could -- also be applications that produce such queries in a misguided attempt -- to reverse map IP addresses. -- -- These queries result in Name Error (RCODE=3) responses. An iterative -- resolver can negatively cache such responses, but each response -- requires a separate cache entry, i.e., a negative cache entry for the -- domain name "192.0.2.1" does not prevent a subsequent query for the -- domain name "192.0.2.2". -- --2.9.1. Recommendation -- -- It would be desirable for the root name servers not to have to answer -- these queries: they unnecessarily consume CPU resources and network -- -- -- --Larson & Barber Expires August 14, 2006 [Page 14] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- bandwidth. A possible solution is to delegate these numeric TLDs -- from the root zone to a separate set of servers to absorb the -- traffic. The "black hole servers" used by the AS 112 Project [8], -- which are currently delegated the in-addr.arpa zones corresponding to -- RFC 1918 [7] private use address space, would be a possible choice to -- receive these delegations. Of course, the proper and usual root zone -- change procedures would have to be followed to make such a change to -- the root zone. -- --2.10. Misdirected recursive queries -- -- The root name servers receive a significant number of recursive -- queries (i.e., queries with the RD bit set in the header). Since -- none of the root servers offers recursion, the servers' response in -- such a situation ignores the request for recursion and the response -- probably does not contain the data the querier anticipated. Some of -- these queries result from users configuring stub resolvers to query a -- root server. (This situation is not hypothetical: we have received -- complaints from users when this configuration does not work as -- hoped.) Of course, users should not direct stub resolvers to use -- name servers that do not offer recursion, but we are not aware of any -- stub resolver implementation that offers any feedback to the user -- when so configured, aside from simply "not working". -- --2.10.1. Recommendation -- -- When the IP address of a name server that supposedly offers recursion -- is configured in a stub resolver using an interactive user interface, -- the resolver could send a test query to verify that the server indeed -- supports recursion (i.e., verify that the response has the RA bit set -- in the header). The user could be immediately notified if the server -- is non-recursive. -- -- The stub resolver could also report an error, either through a user -- interface or in a log file, if the queried server does not support -- recursion. Error reporting SHOULD be throttled to avoid a -- notification or log message for every response from a non-recursive -- server. -- --2.11. Suboptimal name server selection algorithm -- -- An entire document could be devoted to the topic of problems with -- different implementations of the recursive resolution algorithm. The -- entire process of recursion is woefully under specified, requiring -- each implementor to design an algorithm. Sometimes implementors make -- poor design choices that could be avoided if a suggested algorithm -- and best practices were documented, but that is a topic for another -- document. -- -- -- --Larson & Barber Expires August 14, 2006 [Page 15] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- -- Some deficiencies cause significant operational impact and are -- therefore worth mentioning here. One of these is name server -- selection by an iterative resolver. When an iterative resolver wants -- to contact one of a zone's authoritative name servers, how does it -- choose from the NS records listed in the zone's NS RRset? If the -- selection mechanism is suboptimal, queries are not spread evenly -- among a zone's authoritative servers. The details of the selection -- mechanism are up to the implementor, but we offer some suggestions. -- --2.11.1. Recommendation -- -- This list is not conclusive, but reflects the changes that would -- produce the most impact in terms of reducing disproportionate query -- load among a zone's authoritative servers. I.e., these changes would -- help spread the query load evenly. -- -- o Do not make assumptions based on NS RRset order: all NS RRs SHOULD -- be treated equally. (In the case of the "com" zone, for example, -- most of the root servers return the NS record for "a.gtld- -- servers.net" first in the authority section of referrals. -- Apparently as a result, this server receives disproportionately -- more traffic than the other 12 authoritative servers for "com".) -- -- o Use all NS records in an RRset. (For example, we are aware of -- implementations that hard-coded information for a subset of the -- root servers.) -- -- o Maintain state and favor the best-performing of a zone's -- authoritative servers. A good definition of performance is -- response time. Non-responsive servers can be penalized with an -- extremely high response time. -- -- o Do not lock onto the best-performing of a zone's name servers. An -- iterative resolver SHOULD periodically check the performance of -- all of a zone's name servers to adjust its determination of the -- best-performing one. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 16] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --3. Acknowledgments -- -- The authors would like to thank the following people for their -- comments that improved this document: Andras Salamon, Dave Meyer, -- Doug Barton, Jaap Akkerhuis, Jinmei Tatuya, John Brady, Kevin Darcy, -- Olafur Gudmundsson, Pekka Savola, Peter Koch and Rob Austein. We -- apologize if we have omitted anyone; any oversight was unintentional. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 17] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --4. IANA considerations -- -- There are no new IANA considerations introduced by this memo. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 18] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --5. Security considerations -- -- The iterative resolver misbehavior discussed in this document exposes -- the root and TLD name servers to increased risk of both intentional -- and unintentional denial of service attacks. -- -- We believe that implementation of the recommendations offered in this -- document will reduce the amount of unnecessary traffic seen at root -- and TLD name servers, thus reducing the opportunity for an attacker -- to use such queries to his or her advantage. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 19] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --6. Internationalization considerations -- -- There are no new internationalization considerations introduced by -- this memo. -- --7. Informative References -- -- [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- [2] Mockapetris, P., "Domain names - concepts and facilities", -- STD 13, RFC 1034, November 1987. -- -- [3] Elz, R. and R. Bush, "Clarifications to the DNS Specification", -- RFC 2181, July 1997. -- -- [4] Andrews, M., "Negative Caching of DNS Queries (DNS NCACHE)", -- RFC 2308, March 1998. -- -- [5] Morishita, Y. and T. Jinmei, "Common Misbehavior Against DNS -- Queries for IPv6 Addresses", RFC 4074, May 2005. -- -- [6] Vixie, P., Thomson, S., Rekhter, Y., and J. Bound, "Dynamic -- Updates in the Domain Name System (DNS UPDATE)", RFC 2136, -- April 1997. -- -- [7] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and E. -- Lear, "Address Allocation for Private Internets", BCP 5, -- RFC 1918, February 1996. -- -- [8] -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 20] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --Authors' Addresses -- -- Matt Larson -- VeriSign, Inc. -- 21345 Ridgetop Circle -- Dulles, VA 20166-6503 -- USA -- -- Email: mlarson@verisign.com -- -- -- Piet Barber -- VeriSign, Inc. -- 21345 Ridgetop Circle -- Dulles, VA 20166-6503 -- USA -- -- Email: pbarber@verisign.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 21] -- --Internet-Draft Observed DNS Resolution Misbehavior February 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- --Larson & Barber Expires August 14, 2006 [Page 22] -- diff --cc doc/draft/draft-ietf-dnsop-respsize-06.txt index b041925afbc,b041925afbc..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsop-respsize-06.txt +++ /dev/null @@@ -1,640 -1,640 +1,0 @@@ -- -- -- -- -- -- -- DNSOP Working Group Paul Vixie, ISC -- INTERNET-DRAFT Akira Kato, WIDE -- August 2006 -- -- DNS Referral Response Size Issues -- -- Status of this Memo -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- Copyright Notice -- -- Copyright (C) The Internet Society (2006). All Rights Reserved. -- -- -- -- -- Abstract -- -- With a mandated default minimum maximum message size of 512 octets, -- the DNS protocol presents some special problems for zones wishing to -- expose a moderate or high number of authority servers (NS RRs). This -- document explains the operational issues caused by, or related to -- this response size limit, and suggests ways to optimize the use of -- this limited space. Guidance is offered to DNS server implementors -- and to DNS zone operators. -- -- -- -- -- Expires January 2007 [Page 1] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- 1 - Introduction and Overview -- -- 1.1. The DNS standard (see [RFC1035 4.2.1]) limits message size to 512 -- octets. Even though this limitation was due to the required minimum IP -- reassembly limit for IPv4, it became a hard DNS protocol limit and is -- not implicitly relaxed by changes in transport, for example to IPv6. -- -- 1.2. The EDNS0 protocol extension (see [RFC2671 2.3, 4.5]) permits -- larger responses by mutual agreement of the requester and responder. -- The 512 octet message size limit will remain in practical effect until -- there is widespread deployment of EDNS0 in DNS resolvers on the -- Internet. -- -- 1.3. Since DNS responses include a copy of the request, the space -- available for response data is somewhat less than the full 512 octets. -- Negative responses are quite small, but for positive and delegation -- responses, every octet must be carefully and sparingly allocated. This -- document specifically addresses delegation response sizes. -- -- 2 - Delegation Details -- -- 2.1. RELEVANT PROTOCOL ELEMENTS -- -- 2.1.1. A delegation response will include the following elements: -- -- Header Section: fixed length (12 octets) -- Question Section: original query (name, class, type) -- Answer Section: empty, or a CNAME/DNAME chain -- Authority Section: NS RRset (nameserver names) -- Additional Section: A and AAAA RRsets (nameserver addresses) -- -- 2.1.2. If the total response size exceeds 512 octets, and if the data -- that does not fit was "required", then the TC bit will be set -- (indicating truncation). This will usually cause the requester to retry -- using TCP, depending on what information was desired and what -- information was omitted. For example, truncation in the authority -- section is of no interest to a stub resolver who only plans to consume -- the answer section. If a retry using TCP is needed, the total cost of -- the transaction is much higher. See [RFC1123 6.1.3.2] for details on -- the requirement that UDP be attempted before falling back to TCP. -- -- 2.1.3. RRsets are never sent partially unless TC bit set to indicate -- truncation. When TC bit is set, the final apparent RRset in the final -- non-empty section must be considered "possibly damaged" (see [RFC1035 -- 6.2], [RFC2181 9]). -- -- -- -- Expires January 2007 [Page 2] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- 2.1.4. With or without truncation, the glue present in the additional -- data section should be considered "possibly incomplete", and requesters -- should be prepared to re-query for any damaged or missing RRsets. Note -- that truncation of the additional data section might not be signalled -- via the TC bit since additional data is often optional (see discussion -- in [RFC4472 B]). -- -- 2.1.5. DNS label compression allows a domain name to be instantiated -- only once per DNS message, and then referenced with a two-octet -- "pointer" from other locations in that same DNS message (see [RFC1035 -- 4.1.4]). If all nameserver names in a message share a common parent -- (for example, all ending in ".ROOT-SERVERS.NET"), then more space will -- be available for incompressable data (such as nameserver addresses). -- -- 2.1.6. The query name can be as long as 255 octets of network data. In -- this worst case scenario, the question section will be 259 octets in -- size, which would leave only 240 octets for the authority and additional -- sections (after deducting 12 octets for the fixed length header.) -- -- 2.2. ADVICE TO ZONE OWNERS -- -- 2.2.1. Average and maximum question section sizes can be predicted by -- the zone owner, since they will know what names actually exist, and can -- measure which ones are queried for most often. Note that if the zone -- contains any wildcards, it is possible for maximum length queries to -- require positive responses, but that it is reasonable to expect -- truncation and TCP retry in that case. For cost and performance -- reasons, the majority of requests should be satisfied without truncation -- or TCP retry. -- -- 2.2.2. Some queries to non-existing names can be large, but this is not -- a problem because negative responses need not contain any answer, -- authority or additional records. See [RFC2308 2.1] for more information -- about the format of negative responses. -- -- 2.2.3. The minimum useful number of name servers is two, for redundancy -- (see [RFC1034 4.1]). A zone's name servers should be reachable by all -- IP transport protocols (e.g., IPv4 and IPv6) in common use. -- -- 2.2.4. The best case is no truncation at all. This is because many -- requesters will retry using TCP immediately, or will automatically re- -- query for RRsets that are possibly truncated, without considering -- whether the omitted data was actually necessary. -- -- -- -- -- -- Expires January 2007 [Page 3] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- 2.3. ADVICE TO SERVER IMPLEMENTORS -- -- 2.3.1. In case of multi-homed name servers, it is advantageous to -- include an address record from each of several name servers before -- including several address records for any one name server. If address -- records for more than one transport (for example, A and AAAA) are -- available, then it is advantageous to include records of both types -- early on, before the message is full. -- -- 2.3.2. Each added NS RR for a zone will add 12 fixed octets (name, type, -- class, ttl, and rdlen) plus 2 to 255 variable octets (for the NSDNAME). -- Each A RR will require 16 octets, and each AAAA RR will require 28 -- octets. -- -- 2.3.3. While DNS distinguishes between necessary and optional resource -- records, this distinction is according to protocol elements necessary to -- signify facts, and takes no official notice of protocol content -- necessary to ensure correct operation. For example, a nameserver name -- that is in or below the zone cut being described by a delegation is -- "necessary content," since there is no way to reach that zone unless the -- parent zone's delegation includes "glue records" describing that name -- server's addresses. -- -- 2.3.4. It is also necessary to distinguish between "explicit truncation" -- where a message could not contain enough records to convey its intended -- meaning, and so the TC bit has been set, and "silent truncation", where -- the message was not large enough to contain some records which were "not -- required", and so the TC bit was not set. -- -- 2.3.5. A delegation response should prioritize glue records as follows. -- -- first -- All glue RRsets for one name server whose name is in or below the -- zone being delegated, or which has multiple address RRsets (currently -- A and AAAA), or preferably both; -- -- second -- Alternate between adding all glue RRsets for any name servers whose -- names are in or below the zone being delegated, and all glue RRsets -- for any name servers who have multiple address RRsets (currently A -- and AAAA); -- -- thence -- All other glue RRsets, in any order. -- -- -- -- -- Expires January 2007 [Page 4] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- Whenever there are multiple candidates for a position in this priority -- scheme, one should be chosen on a round-robin or fully random basis. -- -- The goal of this priority scheme is to offer "necessary" glue first, -- avoiding silent truncation for this glue if possible. -- -- 2.3.6. If any "necessary content" is silently truncated, then it is -- advisable that the TC bit be set in order to force a TCP retry, rather -- than have the zone be unreachable. Note that a parent server's proper -- response to a query for in-child glue or below-child glue is a referral -- rather than an answer, and that this referral MUST be able to contain -- the in-child or below-child glue, and that in outlying cases, only EDNS -- or TCP will be large enough to contain that data. -- -- 3 - Analysis -- -- 3.1. An instrumented protocol trace of a best case delegation response -- follows. Note that 13 servers are named, and 13 addresses are given. -- This query was artificially designed to exactly reach the 512 octet -- limit. -- -- ;; flags: qr rd; QUERY: 1, ANS: 0, AUTH: 13, ADDIT: 13 -- ;; QUERY SECTION: -- ;; [23456789.123456789.123456789.\ -- 123456789.123456789.123456789.com A IN] ;; @80 -- -- ;; AUTHORITY SECTION: -- com. 86400 NS E.GTLD-SERVERS.NET. ;; @112 -- com. 86400 NS F.GTLD-SERVERS.NET. ;; @128 -- com. 86400 NS G.GTLD-SERVERS.NET. ;; @144 -- com. 86400 NS H.GTLD-SERVERS.NET. ;; @160 -- com. 86400 NS I.GTLD-SERVERS.NET. ;; @176 -- com. 86400 NS J.GTLD-SERVERS.NET. ;; @192 -- com. 86400 NS K.GTLD-SERVERS.NET. ;; @208 -- com. 86400 NS L.GTLD-SERVERS.NET. ;; @224 -- com. 86400 NS M.GTLD-SERVERS.NET. ;; @240 -- com. 86400 NS A.GTLD-SERVERS.NET. ;; @256 -- com. 86400 NS B.GTLD-SERVERS.NET. ;; @272 -- com. 86400 NS C.GTLD-SERVERS.NET. ;; @288 -- com. 86400 NS D.GTLD-SERVERS.NET. ;; @304 -- -- -- -- -- -- -- -- -- Expires January 2007 [Page 5] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- ;; ADDITIONAL SECTION: -- A.GTLD-SERVERS.NET. 86400 A 192.5.6.30 ;; @320 -- B.GTLD-SERVERS.NET. 86400 A 192.33.14.30 ;; @336 -- C.GTLD-SERVERS.NET. 86400 A 192.26.92.30 ;; @352 -- D.GTLD-SERVERS.NET. 86400 A 192.31.80.30 ;; @368 -- E.GTLD-SERVERS.NET. 86400 A 192.12.94.30 ;; @384 -- F.GTLD-SERVERS.NET. 86400 A 192.35.51.30 ;; @400 -- G.GTLD-SERVERS.NET. 86400 A 192.42.93.30 ;; @416 -- H.GTLD-SERVERS.NET. 86400 A 192.54.112.30 ;; @432 -- I.GTLD-SERVERS.NET. 86400 A 192.43.172.30 ;; @448 -- J.GTLD-SERVERS.NET. 86400 A 192.48.79.30 ;; @464 -- K.GTLD-SERVERS.NET. 86400 A 192.52.178.30 ;; @480 -- L.GTLD-SERVERS.NET. 86400 A 192.41.162.30 ;; @496 -- M.GTLD-SERVERS.NET. 86400 A 192.55.83.30 ;; @512 -- -- ;; MSG SIZE sent: 80 rcvd: 512 -- -- 3.2. For longer query names, the number of address records supplied will -- be lower. Furthermore, it is only by using a common parent name (which -- is GTLD-SERVERS.NET in this example) that all 13 addresses are able to -- fit, due to the use of DNS compression pointers in the last 12 -- occurances of the parent domain name. The following output from a -- response simulator demonstrates these properties. -- -- % perl respsize.pl a.dns.br b.dns.br c.dns.br d.dns.br -- a.dns.br requires 10 bytes -- b.dns.br requires 4 bytes -- c.dns.br requires 4 bytes -- d.dns.br requires 4 bytes -- # of NS: 4 -- For maximum size query (255 byte): -- only A is considered: # of A is 4 (green) -- A and AAAA are considered: # of A+AAAA is 3 (yellow) -- preferred-glue A is assumed: # of A is 4, # of AAAA is 3 (yellow) -- For average size query (64 byte): -- only A is considered: # of A is 4 (green) -- A and AAAA are considered: # of A+AAAA is 4 (green) -- preferred-glue A is assumed: # of A is 4, # of AAAA is 4 (green) -- -- -- -- -- -- -- -- -- -- -- Expires January 2007 [Page 6] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- % perl respsize.pl ns-ext.isc.org ns.psg.com ns.ripe.net ns.eu.int -- ns-ext.isc.org requires 16 bytes -- ns.psg.com requires 12 bytes -- ns.ripe.net requires 13 bytes -- ns.eu.int requires 11 bytes -- # of NS: 4 -- For maximum size query (255 byte): -- only A is considered: # of A is 4 (green) -- A and AAAA are considered: # of A+AAAA is 3 (yellow) -- preferred-glue A is assumed: # of A is 4, # of AAAA is 2 (yellow) -- For average size query (64 byte): -- only A is considered: # of A is 4 (green) -- A and AAAA are considered: # of A+AAAA is 4 (green) -- preferred-glue A is assumed: # of A is 4, # of AAAA is 4 (green) -- -- (Note: The response simulator program is shown in Section 5.) -- -- Here we use the term "green" if all address records could fit, or -- "yellow" if two or more could fit, or "orange" if only one could fit, or -- "red" if no address record could fit. It's clear that without a common -- parent for nameserver names, much space would be lost. For these -- examples we use an average/common name size of 15 octets, befitting our -- assumption of GTLD-SERVERS.NET as our common parent name. -- -- We're assuming a medium query name size of 64 since that is the typical -- size seen in trace data at the time of this writing. If -- Internationalized Domain Name (IDN) or any other technology which -- results in larger query names be deployed significantly in advance of -- EDNS, then new measurements and new estimates will have to be made. -- -- 4 - Conclusions -- -- 4.1. The current practice of giving all nameserver names a common parent -- (such as GTLD-SERVERS.NET or ROOT-SERVERS.NET) saves space in DNS -- responses and allows for more nameservers to be enumerated than would -- otherwise be possible, since the common parent domain name only appears -- once in a DNS message and is referred to via "compression pointers" -- thereafter. -- -- 4.2. If all nameserver names for a zone share a common parent, then it -- is operationally advisable to make all servers for the zone thus served -- also be authoritative for the zone of that common parent. For example, -- the root name servers (?.ROOT-SERVERS.NET) can answer authoritatively -- for the ROOT-SERVERS.NET. This is to ensure that the zone's servers -- always have the zone's nameservers' glue available when delegating, and -- -- -- -- Expires January 2007 [Page 7] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- will be able to respond with answers rather than referrals if a -- requester who wants that glue comes back asking for it. In this case -- the name server will likely be a "stealth server" -- authoritative but -- unadvertised in the glue zone's NS RRset. See [RFC1996 2] for more -- information about stealth servers. -- -- 4.3. Thirteen (13) is the effective maximum number of nameserver names -- usable traditional (non-extended) DNS, assuming a common parent domain -- name, and given that implicit referral response truncation is -- undesirable in the average case. -- -- 4.4. Multi-homing of name servers within a protocol family is -- inadvisable since the necessary glue RRsets (A or AAAA) are atomically -- indivisible, and will be larger than a single resource record. Larger -- RRsets are more likely to lead to or encounter truncation. -- -- 4.5. Multi-homing of name servers across protocol families is less -- likely to lead to or encounter truncation, partly because multiprotocol -- clients are more likely to speak EDNS which can use a larger response -- size limit, and partly because the resource records (A and AAAA) are in -- different RRsets and are therefore divisible from each other. -- -- 4.6. Name server names which are at or below the zone they serve are -- more sensitive to referral response truncation, and glue records for -- them should be considered "less optional" than other glue records, in -- the assembly of referral responses. -- -- 4.7. If a zone is served by thirteen (13) name servers having a common -- parent name (such as ?.ROOT-SERVERS.NET) and each such name server has a -- single address record in some protocol family (e.g., an A RR), then all -- thirteen name servers or any subset thereof could multi-home in a second -- protocol family by adding a second address record (e.g., an AAAA RR) -- without reducing the reachability of the zone thus served. -- -- 5 - Source Code -- -- #!/usr/bin/perl -- # -- # SYNOPSIS -- # repsize.pl [ -z zone ] fqdn_ns1 fqdn_ns2 ... -- # if all queries are assumed to have a same zone suffix, -- # such as "jp" in JP TLD servers, specify it in -z option -- # -- use strict; -- use Getopt::Std; -- -- -- -- Expires January 2007 [Page 8] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- my ($sz_msg) = (512); -- my ($sz_header, $sz_ptr, $sz_rr_a, $sz_rr_aaaa) = (12, 2, 16, 28); -- my ($sz_type, $sz_class, $sz_ttl, $sz_rdlen) = (2, 2, 4, 2); -- my (%namedb, $name, $nssect, %opts, $optz); -- my $n_ns = 0; -- -- getopt('z', %opts); -- if (defined($opts{'z'})) { -- server_name_len($opts{'z'}); # just register it -- } -- -- foreach $name (@ARGV) { -- my $len; -- $n_ns++; -- $len = server_name_len($name); -- print "$name requires $len bytes\n"; -- $nssect += $sz_ptr + $sz_type + $sz_class + $sz_ttl -- + $sz_rdlen + $len; -- } -- print "# of NS: $n_ns\n"; -- arsect(255, $nssect, $n_ns, "maximum"); -- arsect(64, $nssect, $n_ns, "average"); -- -- sub server_name_len { -- my ($name) = @_; -- my (@labels, $len, $n, $suffix); -- -- $name =~ tr/A-Z/a-z/; -- @labels = split(/\./, $name); -- $len = length(join('.', @labels)) + 2; -- for ($n = 0; $#labels >= 0; $n++, shift @labels) { -- $suffix = join('.', @labels); -- return length($name) - length($suffix) + $sz_ptr -- if (defined($namedb{$suffix})); -- $namedb{$suffix} = 1; -- } -- return $len; -- } -- -- sub arsect { -- my ($sz_query, $nssect, $n_ns, $cond) = @_; -- my ($space, $n_a, $n_a_aaaa, $n_p_aaaa, $ansect); -- $ansect = $sz_query + 1 + $sz_type + $sz_class; -- $space = $sz_msg - $sz_header - $ansect - $nssect; -- $n_a = atmost(int($space / $sz_rr_a), $n_ns); -- -- -- -- Expires January 2007 [Page 9] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- $n_a_aaaa = atmost(int($space -- / ($sz_rr_a + $sz_rr_aaaa)), $n_ns); -- $n_p_aaaa = atmost(int(($space - $sz_rr_a * $n_ns) -- / $sz_rr_aaaa), $n_ns); -- printf "For %s size query (%d byte):\n", $cond, $sz_query; -- printf " only A is considered: "; -- printf "# of A is %d (%s)\n", $n_a, &judge($n_a, $n_ns); -- printf " A and AAAA are considered: "; -- printf "# of A+AAAA is %d (%s)\n", -- $n_a_aaaa, &judge($n_a_aaaa, $n_ns); -- printf " preferred-glue A is assumed: "; -- printf "# of A is %d, # of AAAA is %d (%s)\n", -- $n_a, $n_p_aaaa, &judge($n_p_aaaa, $n_ns); -- } -- -- sub judge { -- my ($n, $n_ns) = @_; -- return "green" if ($n >= $n_ns); -- return "yellow" if ($n >= 2); -- return "orange" if ($n == 1); -- return "red"; -- } -- -- sub atmost { -- my ($a, $b) = @_; -- return 0 if ($a < 0); -- return $b if ($a > $b); -- return $a; -- } -- -- 6 - Security Considerations -- -- The recommendations contained in this document have no known security -- implications. -- -- 7 - IANA Considerations -- -- This document does not call for changes or additions to any IANA -- registry. -- -- 8 - Acknowledgement -- -- The authors thank Peter Koch, Rob Austein, Joe Abley, and Mark Andrews -- for their valuable comments and suggestions. -- -- -- -- -- Expires January 2007 [Page 10] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- This work was supported by the US National Science Foundation (research -- grant SCI-0427144) and DNS-OARC. -- -- 9 - References -- -- [RFC1034] Mockapetris, P.V., "Domain names - Concepts and Facilities", -- RFC1034, November 1987. -- -- [RFC1035] Mockapetris, P.V., "Domain names - Implementation and -- Specification", RFC1035, November 1987. -- -- [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - -- Application and Support", RFC1123, October 1989. -- -- [RFC1996] Vixie, P., "A Mechanism for Prompt Notification of Zone -- Changes (DNS NOTIFY)", RFC1996, August 1996. -- -- [RFC2181] Elz, R., Bush, R., "Clarifications to the DNS Specification", -- RFC2181, July 1997. -- -- [RFC2308] Andrews, M., "Negative Caching of DNS Queries (DNS NCACHE)", -- RFC2308, March 1998. -- -- [RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC2671, -- August 1999. -- -- [RFC4472] Durand, A., Ihren, J., Savola, P., "Operational Consideration -- and Issues with IPV6 DNS", April 2006. -- -- 10 - Authors' Addresses -- -- Paul Vixie -- Internet Systems Consortium, Inc. -- 950 Charter Street -- Redwood City, CA 94063 -- +1 650 423 1301 -- vixie@isc.org -- -- Akira Kato -- University of Tokyo, Information Technology Center -- 2-11-16 Yayoi Bunkyo -- Tokyo 113-8658, JAPAN -- +81 3 5841 2750 -- kato@wide.ad.jp -- -- -- -- -- Expires January 2007 [Page 11] -- -- INTERNET-DRAFT August 2006 RESPSIZE -- -- -- Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors retain -- all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR -- IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in this -- document or the extent to which any license under such rights might or -- might not be available; nor does it represent that it has made any -- independent effort to identify any such rights. Information on the -- procedures with respect to rights in RFC documents can be found in BCP -- 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an attempt -- made to obtain a general license or permission for the use of such -- proprietary rights by implementers or users of this specification can be -- obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary rights -- that may cover technology that may be required to implement this -- standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- Expires January 2007 [Page 12] -- -- diff --cc doc/draft/draft-ietf-dnsop-serverid-06.txt index c6ec7e42a55,c6ec7e42a55..00000000000 deleted file mode 100644,100644 --- a/doc/draft/draft-ietf-dnsop-serverid-06.txt +++ /dev/null @@@ -1,618 -1,618 +1,0 @@@ -- -- -- -- --Network Working Group S. Woolf --Internet-Draft Internet Systems Consortium, Inc. --Expires: September 6, 2006 D. Conrad -- Nominum, Inc. -- March 5, 2006 -- -- -- Requirements for a Mechanism Identifying a Name Server Instance -- draft-ietf-dnsop-serverid-06 -- --Status of this Memo -- -- By submitting this Internet-Draft, each author represents that any -- applicable patent or other IPR claims of which he or she is aware -- have been or will be disclosed, and any of which he or she becomes -- aware will be disclosed, in accordance with Section 6 of BCP 79. -- -- Internet-Drafts are working documents of the Internet Engineering -- Task Force (IETF), its areas, and its working groups. Note that -- other groups may also distribute working documents as Internet- -- Drafts. -- -- Internet-Drafts are draft documents valid for a maximum of six months -- and may be updated, replaced, or obsoleted by other documents at any -- time. It is inappropriate to use Internet-Drafts as reference -- material or to cite them other than as "work in progress." -- -- The list of current Internet-Drafts can be accessed at -- http://www.ietf.org/ietf/1id-abstracts.txt. -- -- The list of Internet-Draft Shadow Directories can be accessed at -- http://www.ietf.org/shadow.html. -- -- This Internet-Draft will expire on September 6, 2006. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- With the increased use of DNS anycast, load balancing, and other -- mechanisms allowing more than one DNS name server to share a single -- IP address, it is sometimes difficult to tell which of a pool of name -- servers has answered a particular query. A standardized mechanism to -- determine the identity of a name server responding to a particular -- query would be useful, particularly as a diagnostic aid for -- administrators. Existing ad hoc mechanisms for addressing this need -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 1] -- --Internet-Draft Serverid March 2006 -- -- -- have some shortcomings, not the least of which is the lack of prior -- analysis of exactly how such a mechanism should be designed and -- deployed. This document describes the existing convention used in -- some widely deployed implementations of the DNS protocol, including -- advantages and disadvantages, and discusses some attributes of an -- improved mechanism. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 2] -- --Internet-Draft Serverid March 2006 -- -- --1. Introduction and Rationale -- -- Identifying which name server is responding to queries is often -- useful, particularly in attempting to diagnose name server -- difficulties. This is most obviously useful for authoritative -- nameservers in the attempt to diagnose the source or prevalence of -- inaccurate data, but can also conceivably be useful for caching -- resolvers in similar and other situations. Furthermore, the ability -- to identify which server is responding to a query has become more -- useful as DNS has become more critical to more Internet users, and as -- network and server deployment topologies have become more complex. -- -- The traditional means for determining which of several possible -- servers is answering a query has traditionally been based on the use -- of the server's IP address as a unique identifier. However, the -- modern Internet has seen the deployment of various load balancing, -- fault-tolerance, or attack-resistance schemes such as shared use of -- unicast IP addresses as documented in [RFC3258]. An unfortunate side -- effect of these schemes has been to make the use of IP addresses as -- identifiers somewhat problematic. Specifically, a dedicated DNS -- query may not go to the same server as answered a previous query, -- even though sent to the same IP address. Non-DNS methods such as -- ICMP ping, TCP connections, or non-DNS UDP packets (such as those -- generated by tools like "traceroute"), etc., may well be even less -- certain to reach the same server as the one which receives the DNS -- queries. -- -- There is a well-known and frequently-used technique for determining -- an identity for a nameserver more specific than the possibly-non- -- unique "server that answered the query I sent to IP address XXX". -- The widespread use of the existing convention suggests a need for a -- documented, interoperable means of querying the identity of a -- nameserver that may be part of an anycast or load-balancing cluster. -- At the same time, however, it also has some drawbacks that argue -- against standardizing it as it's been practiced so far. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 3] -- --Internet-Draft Serverid March 2006 -- -- --2. Existing Conventions -- -- For some time, the commonly deployed Berkeley Internet Name Domain -- implementation of the DNS protocol suite from the Internet Systems -- Consortium [BIND] has supported a way of identifying a particular -- server via the use of a standards-compliant, if somewhat unusual, DNS -- query. Specifically, a query to a recent BIND server for a TXT -- resource record in class 3 (CHAOS) for the domain name -- "HOSTNAME.BIND." will return a string that can be configured by the -- name server administrator to provide a unique identifier for the -- responding server. (The value defaults to the result of a -- gethostname() call). This mechanism, which is an extension of the -- BIND convention of using CHAOS class TXT RR queries to sub-domains of -- the "BIND." domain for version information, has been copied by -- several name server vendors. -- -- A refinement to the BIND-based mechanism, which dropped the -- implementation-specific string, replaces ".BIND" with ".SERVER". -- Thus the query string to learn the unique name of a server may be -- queried as "ID.SERVER". -- -- (For reference, the other well-known name used by recent versions of -- BIND within the CHAOS class "BIND." domain is "VERSION.BIND." A -- query for a CHAOS TXT RR for this name will return an -- administratively defined string which defaults to the version of the -- server responding. This is, however, not generally implemented by -- other vendors.) -- --2.1. Advantages -- -- There are several valuable attributes to this mechanism, which -- account for its usefulness. -- -- 1. The "HOSTNAME.BIND" or "ID.SERVER" query response mechanism is -- within the DNS protocol itself. An identification mechanism that -- relies on the DNS protocol is more likely to be successful -- (although not guaranteed) in going to the same system as a -- "normal" DNS query. -- -- 2. Since the identity information is requested and returned within -- the DNS protocol, it doesn't require allowing any other query -- mechanism to the server, such as holes in firewalls for -- otherwise-unallowed ICMP Echo requests. Thus it is likely to -- reach the same server over a path subject to the same routing, -- resource, and security policy as the query, without any special -- exceptions to site security policy. -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 4] -- --Internet-Draft Serverid March 2006 -- -- -- 3. It is simple to configure. An administrator can easily turn on -- this feature and control the results of the relevant query. -- -- 4. It allows the administrator complete control of what information -- is given out in the response, minimizing passive leakage of -- implementation or configuration details. Such details are often -- considered sensitive by infrastructure operators. -- -- 5. Hypothetically, since it's an ordinary DNS record and the -- relevant DNSSEC RRs are class independent, the id.server response -- RR could be signed, which has the advantages described in -- [RFC4033]. -- --2.2. Disadvantages -- -- At the same time, there are some serious drawbacks to the CHAOS/TXT -- query mechanism that argue against standardizing it as it currently -- operates. -- -- 1. It requires an additional query to correlate between the answer -- to a DNS query under normal conditions and the supposed identity -- of the server receiving the query. There are a number of -- situations in which this simply isn't reliable. -- -- 2. It reserves an entire class in the DNS (CHAOS) for what amounts -- to one zone. While CHAOS class is defined in [RFC1034] and -- [RFC1035], it's not clear that supporting it solely for this -- purpose is a good use of the namespace or of implementation -- effort. -- -- 3. The initial and still common form, using .BIND, is implementation -- specific. BIND is one DNS implementation. At the time of this -- writing, it is probably the most prevalent for authoritative -- servers. This does not justify standardizing on its ad hoc -- solution to a problem shared across many operators and -- implementors. Meanwhile, the proposed refinement changes the -- string but preserves the ad hoc CHAOS/TXT mechanism. -- -- 4. There is no convention or shared understanding of what -- information an answer to such a query for a server identity could -- or should include, including a possible encoding or -- authentication mechanism. -- -- The first of the listed disadvantages may be technically the most -- serious. It argues for an attempt to design a good answer to the -- problem that "I need to know what nameserver is answering my -- queries", not simply a convenient one. -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 5] -- --Internet-Draft Serverid March 2006 -- -- --2.3. Characteristics of an Implementation Neutral Convention -- -- The discussion above of advantages and disadvantages to the -- HOSTNAME.BIND mechanism suggest some requirements for a better -- solution to the server identification problem. These are summarized -- here as guidelines for any effort to provide appropriate protocol -- extensions: -- -- 1. The mechanism adopted must be in-band for the DNS protocol. That -- is, it needs to allow the query for the server's identifying -- information to be part of a normal, operational query. It should -- also permit a separate, dedicated query for the server's -- identifying information. But it should preserve the ability of -- the CHAOS/TXT query-based mechanism to work through firewalls and -- in other situations where only DNS can be relied upon to reach -- the server of interest. -- -- 2. The new mechanism should not require dedicated namespaces or -- other reserved values outside of the existing protocol mechanisms -- for these, i.e. the OPT pseudo-RR. In particular, it should not -- propagate the existing drawback of requiring support for a CLASS -- and top level domain in the authoritative server (or the querying -- tool) to be useful. -- -- 3. Support for the identification functionality should be easy to -- implement and easy to enable. It must be easy to disable and -- should lend itself to access controls on who can query for it. -- -- 4. It should be possible to return a unique identifier for a server -- without requiring the exposure of information that may be non- -- public and considered sensitive by the operator, such as a -- hostname or unicast IP address maintained for administrative -- purposes. -- -- 5. It should be possible to authenticate the received data by some -- mechanism analogous to those provided by DNSSEC. In this -- context, the need could be met by including encryption options in -- the specification of a new mechanism. -- -- 6. The identification mechanism should not be implementation- -- specific. -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 6] -- --Internet-Draft Serverid March 2006 -- -- --3. IANA Considerations -- -- This document proposes no specific IANA action. Protocol extensions, -- if any, to meet the requirements described are out of scope for this -- document. A proposed extension, specified and adopted by normal IETF -- process, is described in [NSID], including relevant IANA action. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 7] -- --Internet-Draft Serverid March 2006 -- -- --4. Security Considerations -- -- Providing identifying information as to which server is responding to -- a particular query from a particular location in the Internet can be -- seen as information leakage and thus a security risk. This motivates -- the suggestion above that a new mechanism for server identification -- allow the administrator to disable the functionality altogether or -- partially restrict availability of the data. It also suggests that -- the serverid data should not be readily correlated with a hostname or -- unicast IP address that may be considered private to the nameserver -- operator's management infrastructure. -- -- Propagation of protocol or service meta-data can sometimes expose the -- application to denial of service or other attack. As DNS is a -- critically important infrastructure service for the production -- Internet, extra care needs to be taken against this risk for -- designers, implementors, and operators of a new mechanism for server -- identification. -- -- Both authentication and confidentiality of serverid data are -- potentially of interest to administrators-- that is, operators may -- wish to make serverid data available and reliable to themselves and -- their chosen associates only. This would imply both an ability to -- authenticate it to themselves and keep it private from arbitrary -- other parties. This led to Characteristics 4 and 5 of an improved -- solution. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 8] -- --Internet-Draft Serverid March 2006 -- -- --5. Acknowledgements -- -- The technique for host identification documented here was initially -- implemented by Paul Vixie of the Internet Software Consortium in the -- Berkeley Internet Name Daemon package. Comments and questions on -- earlier drafts were provided by Bob Halley, Brian Wellington, Andreas -- Gustafsson, Ted Hardie, Chris Yarnell, Randy Bush, and members of the -- ICANN Root Server System Advisory Committee. The newest version -- takes a significantly different direction from previous versions, -- owing to discussion among contributors to the DNSOP working group and -- others, particularly Olafur Gudmundsson, Ed Lewis, Bill Manning, Sam -- Weiler, and Rob Austein. -- --6. References -- -- [1] Mockapetris, P., "Domain Names - Concepts and Facilities", -- RFC 1034, STD 0013, November 1987. -- -- [2] Mockapetris, P., "Domain Names - Implementation and -- Specification", RFC 1035, STD 0013, November 1987. -- -- [3] Hardie, T., "Distributing Authoritative Name Servers via Shared -- Unicast Addresses", RFC 3258, April 2002. -- -- [4] ISC, "BIND 9 Configuration Reference". -- -- [5] Austein, S., "DNS Name Server Identifier Option (NSID)", -- Internet Drafts http://www.ietf.org/internet-drafts/ -- draft-ietf-dnsext-nsid-01.txt, January 2006. -- -- [6] Arends, R., Austein, S., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, -- March 2005. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 9] -- --Internet-Draft Serverid March 2006 -- -- --Authors' Addresses -- -- Suzanne Woolf -- Internet Systems Consortium, Inc. -- 950 Charter Street -- Redwood City, CA 94063 -- US -- -- Phone: +1 650 423-1333 -- Email: woolf@isc.org -- URI: http://www.isc.org/ -- -- -- David Conrad -- Nominum, Inc. -- 2385 Bay Road -- Redwood City, CA 94063 -- US -- -- Phone: +1 1 650 381 6003 -- Email: david.conrad@nominum.com -- URI: http://www.nominum.com/ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 10] -- --Internet-Draft Serverid March 2006 -- -- --Intellectual Property Statement -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- -- --Disclaimer of Validity -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- -- --Copyright Statement -- -- Copyright (C) The Internet Society (2006). This document is subject -- to the rights, licenses and restrictions contained in BCP 78, and -- except as set forth therein, the authors retain all their rights. -- -- --Acknowledgment -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- --Woolf & Conrad Expires September 6, 2006 [Page 11] -- -- diff --cc doc/rfc/rfc4193.txt index 17e2c0b42da,17e2c0b42da..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4193.txt +++ /dev/null @@@ -1,899 -1,899 +1,0 @@@ -- -- -- -- -- -- --Network Working Group R. Hinden --Request for Comments: 4193 Nokia --Category: Standards Track B. Haberman -- JHU-APL -- October 2005 -- -- -- Unique Local IPv6 Unicast Addresses -- --Status of This Memo -- -- This document specifies an Internet standards track protocol for the -- Internet community, and requests discussion and suggestions for -- improvements. Please refer to the current edition of the "Internet -- Official Protocol Standards" (STD 1) for the standardization state -- and status of this protocol. Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2005). -- --Abstract -- -- This document defines an IPv6 unicast address format that is globally -- unique and is intended for local communications, usually inside of a -- site. These addresses are not expected to be routable on the global -- Internet. -- --Table of Contents -- -- 1. Introduction ....................................................2 -- 2. Acknowledgements ................................................3 -- 3. Local IPv6 Unicast Addresses ....................................3 -- 3.1. Format .....................................................3 -- 3.1.1. Background ..........................................4 -- 3.2. Global ID ..................................................4 -- 3.2.1. Locally Assigned Global IDs .........................5 -- 3.2.2. Sample Code for Pseudo-Random Global ID Algorithm ...5 -- 3.2.3. Analysis of the Uniqueness of Global IDs ............6 -- 3.3. Scope Definition ...........................................6 -- 4. Operational Guidelines ..........................................7 -- 4.1. Routing ....................................................7 -- 4.2. Renumbering and Site Merging ...............................7 -- 4.3. Site Border Router and Firewall Packet Filtering ...........8 -- 4.4. DNS Issues .................................................8 -- 4.5. Application and Higher Level Protocol Issues ...............9 -- 4.6. Use of Local IPv6 Addresses for Local Communication ........9 -- 4.7. Use of Local IPv6 Addresses with VPNs .....................10 -- -- -- --Hinden & Haberman Standards Track [Page 1] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- 5. Global Routing Considerations ..................................11 -- 5.1. From the Standpoint of the Internet .......................11 -- 5.2. From the Standpoint of a Site .............................11 -- 6. Advantages and Disadvantages ...................................12 -- 6.1. Advantages ................................................12 -- 6.2. Disadvantages .............................................13 -- 7. Security Considerations ........................................13 -- 8. IANA Considerations ............................................13 -- 9. References .....................................................13 -- 9.1. Normative References ......................................13 -- 9.2. Informative References ....................................14 -- --1. Introduction -- -- This document defines an IPv6 unicast address format that is globally -- unique and is intended for local communications [IPV6]. These -- addresses are called Unique Local IPv6 Unicast Addresses and are -- abbreviated in this document as Local IPv6 addresses. They are not -- expected to be routable on the global Internet. They are routable -- inside of a more limited area such as a site. They may also be -- routed between a limited set of sites. -- -- Local IPv6 unicast addresses have the following characteristics: -- -- - Globally unique prefix (with high probability of uniqueness). -- -- - Well-known prefix to allow for easy filtering at site -- boundaries. -- -- - Allow sites to be combined or privately interconnected without -- creating any address conflicts or requiring renumbering of -- interfaces that use these prefixes. -- -- - Internet Service Provider independent and can be used for -- communications inside of a site without having any permanent or -- intermittent Internet connectivity. -- -- - If accidentally leaked outside of a site via routing or DNS, -- there is no conflict with any other addresses. -- -- - In practice, applications may treat these addresses like global -- scoped addresses. -- -- This document defines the format of Local IPv6 addresses, how to -- allocate them, and usage considerations including routing, site -- border routers, DNS, application support, VPN usage, and guidelines -- for how to use for local communication inside a site. -- -- -- -- --Hinden & Haberman Standards Track [Page 2] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [RFC2119]. -- --2. Acknowledgements -- -- The underlying idea of creating Local IPv6 addresses described in -- this document has been proposed a number of times by a variety of -- people. The authors of this document do not claim exclusive credit. -- Credit goes to Brian Carpenter, Christian Huitema, Aidan Williams, -- Andrew White, Charlie Perkins, and many others. The authors would -- also like to thank Brian Carpenter, Charlie Perkins, Harald -- Alvestrand, Keith Moore, Margaret Wasserman, Shannon Behrens, Alan -- Beard, Hans Kruse, Geoff Huston, Pekka Savola, Christian Huitema, Tim -- Chown, Steve Bellovin, Alex Zinin, Tony Hain, Bill Fenner, Sam -- Hartman, and Elwyn Davies for their comments and suggestions on this -- document. -- --3. Local IPv6 Unicast Addresses -- --3.1. Format -- -- The Local IPv6 addresses are created using a pseudo-randomly -- allocated global ID. They have the following format: -- -- | 7 bits |1| 40 bits | 16 bits | 64 bits | -- +--------+-+------------+-----------+----------------------------+ -- | Prefix |L| Global ID | Subnet ID | Interface ID | -- +--------+-+------------+-----------+----------------------------+ -- -- Where: -- -- Prefix FC00::/7 prefix to identify Local IPv6 unicast -- addresses. -- -- L Set to 1 if the prefix is locally assigned. -- Set to 0 may be defined in the future. See -- Section 3.2 for additional information. -- -- Global ID 40-bit global identifier used to create a -- globally unique prefix. See Section 3.2 for -- additional information. -- -- Subnet ID 16-bit Subnet ID is an identifier of a subnet -- within the site. -- -- Interface ID 64-bit Interface ID as defined in [ADDARCH]. -- -- -- -- --Hinden & Haberman Standards Track [Page 3] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --3.1.1. Background -- -- There were a range of choices available when choosing the size of the -- prefix and Global ID field length. There is a direct tradeoff -- between having a Global ID field large enough to support foreseeable -- future growth and not using too much of the IPv6 address space -- needlessly. A reasonable way of evaluating a specific field length -- is to compare it to a projected 2050 world population of 9.3 billion -- [POPUL] and the number of resulting /48 prefixes per person. A range -- of prefix choices is shown in the following table: -- -- Prefix Global ID Number of Prefixes % of IPv6 -- Length /48 Prefixes per Person Address Space -- -- /11 37 137,438,953,472 15 0.049% -- /10 38 274,877,906,944 30 0.098% -- /9 39 549,755,813,888 59 0.195% -- /8 40 1,099,511,627,776 118 0.391% -- /7 41 2,199,023,255,552 236 0.781% -- /6 42 4,398,046,511,104 473 1.563% -- -- A very high utilization ratio of these allocations can be assumed -- because the Global ID field does not require internal structure, and -- there is no reason to be able to aggregate the prefixes. -- -- The authors believe that a /7 prefix resulting in a 41-bit Global ID -- space (including the L bit) is a good choice. It provides for a -- large number of assignments (i.e., 2.2 trillion) and at the same time -- uses less than .8% of the total IPv6 address space. It is unlikely -- that this space will be exhausted. If more than this were to be -- needed, then additional IPv6 address space could be allocated for -- this purpose. -- --3.2. Global ID -- -- The allocation of Global IDs is pseudo-random [RANDOM]. They MUST -- NOT be assigned sequentially or with well-known numbers. This is to -- ensure that there is not any relationship between allocations and to -- help clarify that these prefixes are not intended to be routed -- globally. Specifically, these prefixes are not designed to -- aggregate. -- -- This document defines a specific local method to allocate Global IDs, -- indicated by setting the L bit to 1. Another method, indicated by -- clearing the L bit, may be defined later. Apart from the allocation -- method, all Local IPv6 addresses behave and are treated identically. -- -- -- -- -- --Hinden & Haberman Standards Track [Page 4] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- The local assignments are self-generated and do not need any central -- coordination or assignment, but have an extremely high probability of -- being unique. -- --3.2.1. Locally Assigned Global IDs -- -- Locally assigned Global IDs MUST be generated with a pseudo-random -- algorithm consistent with [RANDOM]. Section 3.2.2 describes a -- suggested algorithm. It is important that all sites generating -- Global IDs use a functionally similar algorithm to ensure there is a -- high probability of uniqueness. -- -- The use of a pseudo-random algorithm to generate Global IDs in the -- locally assigned prefix gives an assurance that any network numbered -- using such a prefix is highly unlikely to have that address space -- clash with any other network that has another locally assigned prefix -- allocated to it. This is a particularly useful property when -- considering a number of scenarios including networks that merge, -- overlapping VPN address space, or hosts mobile between such networks. -- --3.2.2. Sample Code for Pseudo-Random Global ID Algorithm -- -- The algorithm described below is intended to be used for locally -- assigned Global IDs. In each case the resulting global ID will be -- used in the appropriate prefix as defined in Section 3.2. -- -- 1) Obtain the current time of day in 64-bit NTP format [NTP]. -- -- 2) Obtain an EUI-64 identifier from the system running this -- algorithm. If an EUI-64 does not exist, one can be created from -- a 48-bit MAC address as specified in [ADDARCH]. If an EUI-64 -- cannot be obtained or created, a suitably unique identifier, -- local to the node, should be used (e.g., system serial number). -- -- 3) Concatenate the time of day with the system-specific identifier -- in order to create a key. -- -- 4) Compute an SHA-1 digest on the key as specified in [FIPS, SHA1]; -- the resulting value is 160 bits. -- -- 5) Use the least significant 40 bits as the Global ID. -- -- 6) Concatenate FC00::/7, the L bit set to 1, and the 40-bit Global -- ID to create a Local IPv6 address prefix. -- -- This algorithm will result in a Global ID that is reasonably unique -- and can be used to create a locally assigned Local IPv6 address -- prefix. -- -- -- --Hinden & Haberman Standards Track [Page 5] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --3.2.3. Analysis of the Uniqueness of Global IDs -- -- The selection of a pseudo random Global ID is similar to the -- selection of an SSRC identifier in RTP/RTCP defined in Section 8.1 of -- [RTP]. This analysis is adapted from that document. -- -- Since Global IDs are chosen randomly (and independently), it is -- possible that separate networks have chosen the same Global ID. For -- any given network, with one or more random Global IDs, that has -- inter-connections to other such networks, having a total of N such -- IDs, the probability that two or more of these IDs will collide can -- be approximated using the formula: -- -- P = 1 - exp(-N**2 / 2**(L+1)) -- -- where P is the probability of collision, N is the number of -- interconnected Global IDs, and L is the length of the Global ID. -- -- The following table shows the probability of a collision for a range -- of connections using a 40-bit Global ID field. -- -- Connections Probability of Collision -- -- 2 1.81*10^-12 -- 10 4.54*10^-11 -- 100 4.54*10^-09 -- 1000 4.54*10^-07 -- 10000 4.54*10^-05 -- -- Based on this analysis, the uniqueness of locally generated Global -- IDs is adequate for sites planning a small to moderate amount of -- inter-site communication using locally generated Global IDs. -- --3.3. Scope Definition -- -- By default, the scope of these addresses is global. That is, they -- are not limited by ambiguity like the site-local addresses defined in -- [ADDARCH]. Rather, these prefixes are globally unique, and as such, -- their applicability is greater than site-local addresses. Their -- limitation is in the routability of the prefixes, which is limited to -- a site and any explicit routing agreements with other sites to -- propagate them (also see Section 4.1). Also, unlike site-locals, a -- site may have more than one of these prefixes and use them at the -- same time. -- -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 6] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --4. Operational Guidelines -- -- The guidelines in this section do not require any change to the -- normal routing and forwarding functionality in an IPv6 host or -- router. These are configuration and operational usage guidelines. -- --4.1. Routing -- -- Local IPv6 addresses are designed to be routed inside of a site in -- the same manner as other types of unicast addresses. They can be -- carried in any IPv6 routing protocol without any change. -- -- It is expected that they would share the same Subnet IDs with -- provider-based global unicast addresses, if they were being used -- concurrently [GLOBAL]. -- -- The default behavior of exterior routing protocol sessions between -- administrative routing regions must be to ignore receipt of and not -- advertise prefixes in the FC00::/7 block. A network operator may -- specifically configure prefixes longer than FC00::/7 for inter-site -- communication. -- -- If BGP is being used at the site border with an ISP, the default BGP -- configuration must filter out any Local IPv6 address prefixes, both -- incoming and outgoing. It must be set both to keep any Local IPv6 -- address prefixes from being advertised outside of the site as well as -- to keep these prefixes from being learned from another site. The -- exception to this is if there are specific /48 or longer routes -- created for one or more Local IPv6 prefixes. -- -- For link-state IGPs, it is suggested that a site utilizing IPv6 local -- address prefixes be contained within one IGP domain or area. By -- containing an IPv6 local address prefix to a single link-state area -- or domain, the distribution of prefixes can be controlled. -- --4.2. Renumbering and Site Merging -- -- The use of Local IPv6 addresses in a site results in making -- communication that uses these addresses independent of renumbering a -- site's provider-based global addresses. -- -- When merging multiple sites, the addresses created with these -- prefixes are unlikely to need to be renumbered because all of the -- addresses have a high probability of being unique. Routes for each -- specific prefix would have to be configured to allow routing to work -- correctly between the formerly separate sites. -- -- -- -- -- --Hinden & Haberman Standards Track [Page 7] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --4.3. Site Border Router and Firewall Packet Filtering -- -- While no serious harm will be done if packets with these addresses -- are sent outside of a site via a default route, it is recommended -- that routers be configured by default to keep any packets with Local -- IPv6 addresses from leaking outside of the site and to keep any site -- prefixes from being advertised outside of their site. -- -- Site border routers and firewalls should be configured to not forward -- any packets with Local IPv6 source or destination addresses outside -- of the site, unless they have been explicitly configured with routing -- information about specific /48 or longer Local IPv6 prefixes. This -- will ensure that packets with Local IPv6 destination addresses will -- not be forwarded outside of the site via a default route. The -- default behavior of these devices should be to install a "reject" -- route for these prefixes. Site border routers should respond with -- the appropriate ICMPv6 Destination Unreachable message to inform the -- source that the packet was not forwarded. [ICMPV6]. This feedback is -- important to avoid transport protocol timeouts. -- -- Routers that maintain peering arrangements between Autonomous Systems -- throughout the Internet should obey the recommendations for site -- border routers, unless configured otherwise. -- --4.4. DNS Issues -- -- At the present time, AAAA and PTR records for locally assigned local -- IPv6 addresses are not recommended to be installed in the global DNS. -- -- For background on this recommendation, one of the concerns about -- adding AAAA and PTR records to the global DNS for locally assigned -- Local IPv6 addresses stems from the lack of complete assurance that -- the prefixes are unique. There is a small possibility that the same -- locally assigned IPv6 Local addresses will be used by two different -- organizations both claiming to be authoritative with different -- contents. In this scenario, it is likely there will be a connection -- attempt to the closest host with the corresponding locally assigned -- IPv6 Local address. This may result in connection timeouts, -- connection failures indicated by ICMP Destination Unreachable -- messages, or successful connections to the wrong host. Due to this -- concern, adding AAAA records for these addresses to the global DNS is -- thought to be unwise. -- -- Reverse (address-to-name) queries for locally assigned IPv6 Local -- addresses MUST NOT be sent to name servers for the global DNS, due to -- the load that such queries would create for the authoritative name -- servers for the ip6.arpa zone. This form of query load is not -- specific to locally assigned Local IPv6 addresses; any current form -- -- -- --Hinden & Haberman Standards Track [Page 8] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- of local addressing creates additional load of this kind, due to -- reverse queries leaking out of the site. However, since allowing -- such queries to escape from the site serves no useful purpose, there -- is no good reason to make the existing load problems worse. -- -- The recommended way to avoid sending such queries to nameservers for -- the global DNS is for recursive name server implementations to act as -- if they were authoritative for an empty d.f.ip6.arpa zone and return -- RCODE 3 for any such query. Implementations that choose this -- strategy should allow it to be overridden, but returning an RCODE 3 -- response for such queries should be the default, both because this -- will reduce the query load problem and also because, if the site -- administrator has not set up the reverse tree corresponding to the -- locally assigned IPv6 Local addresses in use, returning RCODE 3 is in -- fact the correct answer. -- --4.5. Application and Higher Level Protocol Issues -- -- Application and other higher level protocols can treat Local IPv6 -- addresses in the same manner as other types of global unicast -- addresses. No special handling is required. This type of address -- may not be reachable, but that is no different from other types of -- IPv6 global unicast address. Applications need to be able to handle -- multiple addresses that may or may not be reachable at any point in -- time. In most cases, this complexity should be hidden in APIs. -- -- From a host's perspective, the difference between Local IPv6 and -- other types of global unicast addresses shows up as different -- reachability and could be handled by default in that way. In some -- cases, it is better for nodes and applications to treat them -- differently from global unicast addresses. A starting point might be -- to give them preference over global unicast, but fall back to global -- unicast if a particular destination is found to be unreachable. Much -- of this behavior can be controlled by how they are allocated to nodes -- and put into the DNS. However, it is useful if a host can have both -- types of addresses and use them appropriately. -- -- Note that the address selection mechanisms of [ADDSEL], and in -- particular the policy override mechanism replacing default address -- selection, are expected to be used on a site where Local IPv6 -- addresses are configured. -- --4.6. Use of Local IPv6 Addresses for Local Communication -- -- Local IPv6 addresses, like global scope unicast addresses, are only -- assigned to nodes if their use has been enabled (via IPv6 address -- autoconfiguration [ADDAUTO], DHCPv6 [DHCP6], or manually). They are -- -- -- -- --Hinden & Haberman Standards Track [Page 9] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- not created automatically in the way that IPv6 link-local addresses -- are and will not appear or be used unless they are purposely -- configured. -- -- In order for hosts to autoconfigure Local IPv6 addresses, routers -- have to be configured to advertise Local IPv6 /64 prefixes in router -- advertisements, or a DHCPv6 server must have been configured to -- assign them. In order for a node to learn the Local IPv6 address of -- another node, the Local IPv6 address must have been installed in a -- naming system (e.g., DNS, proprietary naming system, etc.) For these -- reasons, controlling their usage in a site is straightforward. -- -- To limit the use of Local IPv6 addresses the following guidelines -- apply: -- -- - Nodes that are to only be reachable inside of a site: The local -- DNS should be configured to only include the Local IPv6 -- addresses of these nodes. Nodes with only Local IPv6 addresses -- must not be installed in the global DNS. -- -- - Nodes that are to be limited to only communicate with other -- nodes in the site: These nodes should be set to only -- autoconfigure Local IPv6 addresses via [ADDAUTO] or to only -- receive Local IPv6 addresses via [DHCP6]. Note: For the case -- where both global and Local IPv6 prefixes are being advertised -- on a subnet, this will require a switch in the devices to only -- autoconfigure Local IPv6 addresses. -- -- - Nodes that are to be reachable from inside of the site and from -- outside of the site: The DNS should be configured to include -- the global addresses of these nodes. The local DNS may be -- configured to also include the Local IPv6 addresses of these -- nodes. -- -- - Nodes that can communicate with other nodes inside of the site -- and outside of the site: These nodes should autoconfigure global -- addresses via [ADDAUTO] or receive global address via [DHCP6]. -- They may also obtain Local IPv6 addresses via the same -- mechanisms. -- --4.7. Use of Local IPv6 Addresses with VPNs -- -- Local IPv6 addresses can be used for inter-site Virtual Private -- Networks (VPN) if appropriate routes are set up. Because the -- addresses are unique, these VPNs will work reliably and without the -- need for translation. They have the additional property that they -- will continue to work if the individual sites are renumbered or -- merged. -- -- -- --Hinden & Haberman Standards Track [Page 10] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --5. Global Routing Considerations -- -- Section 4.1 provides operational guidelines that forbid default -- routing of local addresses between sites. Concerns were raised to -- the IPv6 working group and to the IETF as a whole that sites may -- attempt to use local addresses as globally routed provider- -- independent addresses. This section describes why using local -- addresses as globally-routed provider-independent addresses is -- unadvisable. -- --5.1. From the Standpoint of the Internet -- -- There is a mismatch between the structure of IPv6 local addresses and -- the normal IPv6 wide area routing model. The /48 prefix of an IPv6 -- local addresses fits nowhere in the normal hierarchy of IPv6 unicast -- addresses. Normal IPv6 unicast addresses can be routed -- hierarchically down to physical subnet (link) level and only have to -- be flat-routed on the physical subnet. IPv6 local addresses would -- have to be flat-routed even over the wide area Internet. -- -- Thus, packets whose destination address is an IPv6 local address -- could be routed over the wide area only if the corresponding /48 -- prefix were carried by the wide area routing protocol in use, such as -- BGP. This contravenes the operational assumption that long prefixes -- will be aggregated into many fewer short prefixes, to limit the table -- size and convergence time of the routing protocol. If a network uses -- both normal IPv6 addresses [ADDARCH] and IPv6 local addresses, these -- types of addresses will certainly not aggregate with each other, -- since they differ from the most significant bit onwards. Neither -- will IPv6 local addresses aggregate with each other, due to their -- random bit patterns. This means that there would be a very -- significant operational penalty for attempting to use IPv6 local -- address prefixes generically with currently known wide area routing -- technology. -- --5.2. From the Standpoint of a Site -- -- There are a number of design factors in IPv6 local addresses that -- reduce the likelihood that IPv6 local addresses will be used as -- arbitrary global unicast addresses. These include: -- -- - The default rules to filter packets and routes make it very -- difficult to use IPv6 local addresses for arbitrary use across -- the Internet. For a site to use them as general purpose unicast -- addresses, it would have to make sure that the default rules -- were not being used by all other sites and intermediate ISPs -- used for their current and future communication. -- -- -- -- --Hinden & Haberman Standards Track [Page 11] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- - They are not mathematically guaranteed to be unique and are not -- registered in public databases. Collisions, while highly -- unlikely, are possible and a collision can compromise the -- integrity of the communications. The lack of public -- registration creates operational problems. -- -- - The addresses are allocated randomly. If a site had multiple -- prefixes that it wanted to be used globally, the cost of -- advertising them would be very high because they could not be -- aggregated. -- -- - They have a long prefix (i.e., /48) so a single local address -- prefix doesn't provide enough address space to be used -- exclusively by the largest organizations. -- --6. Advantages and Disadvantages -- --6.1. Advantages -- -- This approach has the following advantages: -- -- - Provides Local IPv6 prefixes that can be used independently of -- any provider-based IPv6 unicast address allocations. This is -- useful for sites not always connected to the Internet or sites -- that wish to have a distinct prefix that can be used to localize -- traffic inside of the site. -- -- - Applications can treat these addresses in an identical manner as -- any other type of global IPv6 unicast addresses. -- -- - Sites can be merged without any renumbering of the Local IPv6 -- addresses. -- -- - Sites can change their provider-based IPv6 unicast address -- without disrupting any communication that uses Local IPv6 -- addresses. -- -- - Well-known prefix that allows for easy filtering at site -- boundary. -- -- - Can be used for inter-site VPNs. -- -- - If accidently leaked outside of a site via routing or DNS, there -- is no conflict with any other addresses. -- -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 12] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --6.2. Disadvantages -- -- This approach has the following disadvantages: -- -- - Not possible to route Local IPv6 prefixes on the global Internet -- with current routing technology. Consequentially, it is -- necessary to have the default behavior of site border routers to -- filter these addresses. -- -- - There is a very low probability of non-unique locally assigned -- Global IDs being generated by the algorithm in Section 3.2.3. -- This risk can be ignored for all practical purposes, but it -- leads to a theoretical risk of clashing address prefixes. -- --7. Security Considerations -- -- Local IPv6 addresses do not provide any inherent security to the -- nodes that use them. They may be used with filters at site -- boundaries to keep Local IPv6 traffic inside of the site, but this is -- no more or less secure than filtering any other type of global IPv6 -- unicast addresses. -- -- Local IPv6 addresses do allow for address-based security mechanisms, -- including IPsec, across end to end VPN connections. -- --8. IANA Considerations -- -- The IANA has assigned the FC00::/7 prefix to "Unique Local Unicast". -- --9. References -- --9.1. Normative References -- -- [ADDARCH] Hinden, R. and S. Deering, "Internet Protocol Version 6 -- (IPv6) Addressing Architecture", RFC 3513, April 2003. -- -- [FIPS] "Federal Information Processing Standards Publication", -- (FIPS PUB) 180-1, Secure Hash Standard, 17 April 1995. -- -- [GLOBAL] Hinden, R., Deering, S., and E. Nordmark, "IPv6 Global -- Unicast Address Format", RFC 3587, August 2003. -- -- [ICMPV6] Conta, A. and S. Deering, "Internet Control Message -- Protocol (ICMPv6) for the Internet Protocol Version 6 -- (IPv6) Specification", RFC 2463, December 1998. -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 13] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- -- [IPV6] Deering, S. and R. Hinden, "Internet Protocol, Version 6 -- (IPv6) Specification", RFC 2460, December 1998. -- -- [NTP] Mills, D., "Network Time Protocol (Version 3) -- Specification, Implementation and Analysis", RFC 1305, -- March 1992. -- -- [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, -- "Randomness Requirements for Security", BCP 106, RFC 4086, -- June 2005. -- -- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- -- [SHA1] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 -- (SHA1)", RFC 3174, September 2001. -- --9.2. Informative References -- -- [ADDAUTO] Thomson, S. and T. Narten, "IPv6 Stateless Address -- Autoconfiguration", RFC 2462, December 1998. -- -- [ADDSEL] Draves, R., "Default Address Selection for Internet -- Protocol version 6 (IPv6)", RFC 3484, February 2003. -- -- [DHCP6] Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and -- M. Carney, "Dynamic Host Configuration Protocol for IPv6 -- (DHCPv6)", RFC 3315, July 2003. -- -- [POPUL] Population Reference Bureau, "World Population Data Sheet -- of the Population Reference Bureau 2002", August 2002. -- -- [RTP] Schulzrinne, H., Casner, S., Frederick, R., and V. -- Jacobson, "RTP: A Transport Protocol for Real-Time -- Applications", STD 64, RFC 3550, July 2003. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 14] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --Authors' Addresses -- -- Robert M. Hinden -- Nokia -- 313 Fairchild Drive -- Mountain View, CA 94043 -- USA -- -- Phone: +1 650 625-2004 -- EMail: bob.hinden@nokia.com -- -- -- Brian Haberman -- Johns Hopkins University -- Applied Physics Lab -- 11100 Johns Hopkins Road -- Laurel, MD 20723 -- USA -- -- Phone: +1 443 778 1319 -- EMail: brian@innovationslab.net -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 15] -- --RFC 4193 Unique Local IPv6 Unicast Addresses October 2005 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2005). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at ietf- -- ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is currently provided by the -- Internet Society. -- -- -- -- -- -- -- --Hinden & Haberman Standards Track [Page 16] -- diff --cc doc/rfc/rfc4255.txt index f350b7af957,f350b7af957..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4255.txt +++ /dev/null @@@ -1,507 -1,507 +1,0 @@@ -- -- -- -- -- -- --Network Working Group J. Schlyter --Request for Comments: 4255 OpenSSH --Category: Standards Track W. Griffin -- SPARTA -- January 2006 -- -- -- Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints -- --Status of This Memo -- -- This document specifies an Internet standards track protocol for the -- Internet community, and requests discussion and suggestions for -- improvements. Please refer to the current edition of the "Internet -- Official Protocol Standards" (STD 1) for the standardization state -- and status of this protocol. Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document describes a method of verifying Secure Shell (SSH) host -- keys using Domain Name System Security (DNSSEC). The document -- defines a new DNS resource record that contains a standard SSH key -- fingerprint. -- --Table of Contents -- -- 1. Introduction ....................................................2 -- 2. SSH Host Key Verification .......................................2 -- 2.1. Method .....................................................2 -- 2.2. Implementation Notes .......................................2 -- 2.3. Fingerprint Matching .......................................3 -- 2.4. Authentication .............................................3 -- 3. The SSHFP Resource Record .......................................3 -- 3.1. The SSHFP RDATA Format .....................................4 -- 3.1.1. Algorithm Number Specification ......................4 -- 3.1.2. Fingerprint Type Specification ......................4 -- 3.1.3. Fingerprint .........................................5 -- 3.2. Presentation Format of the SSHFP RR ........................5 -- 4. Security Considerations .........................................5 -- 5. IANA Considerations .............................................6 -- 6. Normative References ............................................7 -- 7. Informational References ........................................7 -- 8. Acknowledgements ................................................8 -- -- -- -- --Schlyter & Griffin Standards Track [Page 1] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- --1. Introduction -- -- The SSH [6] protocol provides secure remote login and other secure -- network services over an insecure network. The security of the -- connection relies on the server authenticating itself to the client -- as well as the user authenticating itself to the server. -- -- If a connection is established to a server whose public key is not -- already known to the client, a fingerprint of the key is presented to -- the user for verification. If the user decides that the fingerprint -- is correct and accepts the key, the key is saved locally and used for -- verification for all following connections. While some security- -- conscious users verify the fingerprint out-of-band before accepting -- the key, many users blindly accept the presented key. -- -- The method described here can provide out-of-band verification by -- looking up a fingerprint of the server public key in the DNS [1][2] -- and using DNSSEC [5] to verify the lookup. -- -- In order to distribute the fingerprint using DNS, this document -- defines a new DNS resource record, "SSHFP", to carry the fingerprint. -- -- Basic understanding of the DNS system [1][2] and the DNS security -- extensions [5] is assumed by this document. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119 [3]. -- --2. SSH Host Key Verification -- --2.1. Method -- -- Upon connection to an SSH server, the SSH client MAY look up the -- SSHFP resource record(s) for the host it is connecting to. If the -- algorithm and fingerprint of the key received from the SSH server -- match the algorithm and fingerprint of one of the SSHFP resource -- record(s) returned from DNS, the client MAY accept the identity of -- the server. -- --2.2. Implementation Notes -- -- Client implementors SHOULD provide a configurable policy used to -- select the order of methods used to verify a host key. This document -- defines one method: Fingerprint storage in DNS. Another method -- defined in the SSH Architecture [6] uses local files to store keys -- for comparison. Other methods that could be defined in the future -- might include storing fingerprints in LDAP or other databases. A -- -- -- --Schlyter & Griffin Standards Track [Page 2] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- -- configurable policy will allow administrators to determine which -- methods they want to use and in what order the methods should be -- prioritized. This will allow administrators to determine how much -- trust they want to place in the different methods. -- -- One specific scenario for having a configurable policy is where -- clients do not use fully qualified host names to connect to servers. -- In this scenario, the implementation SHOULD verify the host key -- against a local database before verifying the key via the fingerprint -- returned from DNS. This would help prevent an attacker from -- injecting a DNS search path into the local resolver and forcing the -- client to connect to a different host. -- --2.3. Fingerprint Matching -- -- The public key and the SSHFP resource record are matched together by -- comparing algorithm number and fingerprint. -- -- The public key algorithm and the SSHFP algorithm number MUST -- match. -- -- A message digest of the public key, using the message digest -- algorithm specified in the SSHFP fingerprint type, MUST match the -- SSHFP fingerprint. -- --2.4. Authentication -- -- A public key verified using this method MUST NOT be trusted if the -- SSHFP resource record (RR) used for verification was not -- authenticated by a trusted SIG RR. -- -- Clients that do validate the DNSSEC signatures themselves SHOULD use -- standard DNSSEC validation procedures. -- -- Clients that do not validate the DNSSEC signatures themselves MUST -- use a secure transport (e.g., TSIG [9], SIG(0) [10], or IPsec [8]) -- between themselves and the entity performing the signature -- validation. -- --3. The SSHFP Resource Record -- -- The SSHFP resource record (RR) is used to store a fingerprint of an -- SSH public host key that is associated with a Domain Name System -- (DNS) name. -- -- The RR type code for the SSHFP RR is 44. -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 3] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- --3.1. The SSHFP RDATA Format -- -- The RDATA for a SSHFP RR consists of an algorithm number, fingerprint -- type and the fingerprint of the public host key. -- -- 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 -- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | algorithm | fp type | / -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / -- / / -- / fingerprint / -- / / -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- --3.1.1. Algorithm Number Specification -- -- This algorithm number octet describes the algorithm of the public -- key. The following values are assigned: -- -- Value Algorithm name -- ----- -------------- -- 0 reserved -- 1 RSA -- 2 DSS -- -- Reserving other types requires IETF consensus [4]. -- --3.1.2. Fingerprint Type Specification -- -- The fingerprint type octet describes the message-digest algorithm -- used to calculate the fingerprint of the public key. The following -- values are assigned: -- -- Value Fingerprint type -- ----- ---------------- -- 0 reserved -- 1 SHA-1 -- -- Reserving other types requires IETF consensus [4]. -- -- For interoperability reasons, as few fingerprint types as possible -- should be reserved. The only reason to reserve additional types is -- to increase security. -- -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 4] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- --3.1.3. Fingerprint -- -- The fingerprint is calculated over the public key blob as described -- in [7]. -- -- The message-digest algorithm is presumed to produce an opaque octet -- string output, which is placed as-is in the RDATA fingerprint field. -- --3.2. Presentation Format of the SSHFP RR -- -- The RDATA of the presentation format of the SSHFP resource record -- consists of two numbers (algorithm and fingerprint type) followed by -- the fingerprint itself, presented in hex, e.g.: -- -- host.example. SSHFP 2 1 123456789abcdef67890123456789abcdef67890 -- -- The use of mnemonics instead of numbers is not allowed. -- --4. Security Considerations -- -- Currently, the amount of trust a user can realistically place in a -- server key is proportional to the amount of attention paid to -- verifying that the public key presented actually corresponds to the -- private key of the server. If a user accepts a key without verifying -- the fingerprint with something learned through a secured channel, the -- connection is vulnerable to a man-in-the-middle attack. -- -- The overall security of using SSHFP for SSH host key verification is -- dependent on the security policies of the SSH host administrator and -- DNS zone administrator (in transferring the fingerprint), detailed -- aspects of how verification is done in the SSH implementation, and in -- the client's diligence in accessing the DNS in a secure manner. -- -- One such aspect is in which order fingerprints are looked up (e.g., -- first checking local file and then SSHFP). We note that, in addition -- to protecting the first-time transfer of host keys, SSHFP can -- optionally be used for stronger host key protection. -- -- If SSHFP is checked first, new SSH host keys may be distributed by -- replacing the corresponding SSHFP in DNS. -- -- If SSH host key verification can be configured to require SSHFP, -- SSH host key revocation can be implemented by removing the -- corresponding SSHFP from DNS. -- -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 5] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- -- As stated in Section 2.2, we recommend that SSH implementors provide -- a policy mechanism to control the order of methods used for host key -- verification. One specific scenario for having a configurable policy -- is where clients use unqualified host names to connect to servers. -- In this case, we recommend that SSH implementations check the host -- key against a local database before verifying the key via the -- fingerprint returned from DNS. This would help prevent an attacker -- from injecting a DNS search path into the local resolver and forcing -- the client to connect to a different host. -- -- A different approach to solve the DNS search path issue would be for -- clients to use a trusted DNS search path, i.e., one not acquired -- through DHCP or other autoconfiguration mechanisms. Since there is -- no way with current DNS lookup APIs to tell whether a search path is -- from a trusted source, the entire client system would need to be -- configured with this trusted DNS search path. -- -- Another dependency is on the implementation of DNSSEC itself. As -- stated in Section 2.4, we mandate the use of secure methods for -- lookup and that SSHFP RRs are authenticated by trusted SIG RRs. This -- is especially important if SSHFP is to be used as a basis for host -- key rollover and/or revocation, as described above. -- -- Since DNSSEC only protects the integrity of the host key fingerprint -- after it is signed by the DNS zone administrator, the fingerprint -- must be transferred securely from the SSH host administrator to the -- DNS zone administrator. This could be done manually between the -- administrators or automatically using secure DNS dynamic update [11] -- between the SSH server and the nameserver. We note that this is no -- different from other key enrollment situations, e.g., a client -- sending a certificate request to a certificate authority for signing. -- --5. IANA Considerations -- -- IANA has allocated the RR type code 44 for SSHFP from the standard RR -- type space. -- -- IANA has opened a new registry for the SSHFP RR type for public key -- algorithms. The defined types are: -- -- 0 is reserved -- 1 is RSA -- 2 is DSA -- -- Adding new reservations requires IETF consensus [4]. -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 6] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- -- IANA has opened a new registry for the SSHFP RR type for fingerprint -- types. The defined types are: -- -- 0 is reserved -- 1 is SHA-1 -- -- Adding new reservations requires IETF consensus [4]. -- --6. Normative References -- -- [1] Mockapetris, P., "Domain names - concepts and facilities", STD -- 13, RFC 1034, November 1987. -- -- [2] Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- -- [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- [4] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA -- Considerations Section in RFCs", BCP 26, RFC 2434, October -- 1998. -- -- [5] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, March -- 2005. -- -- Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", RFC -- 4035, March 2005. -- -- [6] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) -- Protocol Architecture", RFC 4251, January 2006. -- -- [7] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) -- Transport Layer Protocol", RFC 4253, January 2006. -- --7. Informational References -- -- [8] Thayer, R., Doraswamy, N., and R. Glenn, "IP Security Document -- Roadmap", RFC 2411, November 1998. -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 7] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- -- [9] Vixie, P., Gudmundsson, O., Eastlake 3rd, D., and B. -- Wellington, "Secret Key Transaction Authentication for DNS -- (TSIG)", RFC 2845, May 2000. -- -- [10] Eastlake 3rd, D., "DNS Request and Transaction Signatures -- ( SIG(0)s )", RFC 2931, September 2000. -- -- [11] Wellington, B., "Secure Domain Name System (DNS) Dynamic -- Update", RFC 3007, November 2000. -- --8. Acknowledgements -- -- The authors gratefully acknowledge, in no particular order, the -- contributions of the following persons: -- -- Martin Fredriksson -- -- Olafur Gudmundsson -- -- Edward Lewis -- -- Bill Sommerfeld -- --Authors' Addresses -- -- Jakob Schlyter -- OpenSSH -- 812 23rd Avenue SE -- Calgary, Alberta T2G 1N8 -- Canada -- -- EMail: jakob@openssh.com -- URI: http://www.openssh.com/ -- -- -- Wesley Griffin -- SPARTA -- 7075 Samuel Morse Drive -- Columbia, MD 21046 -- USA -- -- EMail: wgriffin@sparta.com -- URI: http://www.sparta.com/ -- -- -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 8] -- --RFC 4255 DNS and SSH Fingerprints January 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Schlyter & Griffin Standards Track [Page 9] -- diff --cc doc/rfc/rfc4343.txt index 621420a45f4,621420a45f4..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4343.txt +++ /dev/null @@@ -1,563 -1,563 +1,0 @@@ -- -- -- -- -- -- --Network Working Group D. Eastlake 3rd --Request for Comments: 4343 Motorola Laboratories --Updates: 1034, 1035, 2181 January 2006 --Category: Standards Track -- -- -- Domain Name System (DNS) Case Insensitivity Clarification -- --Status of This Memo -- -- This document specifies an Internet standards track protocol for the -- Internet community, and requests discussion and suggestions for -- improvements. Please refer to the current edition of the "Internet -- Official Protocol Standards" (STD 1) for the standardization state -- and status of this protocol. Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- Domain Name System (DNS) names are "case insensitive". This document -- explains exactly what that means and provides a clear specification -- of the rules. This clarification updates RFCs 1034, 1035, and 2181. -- --Table of Contents -- -- 1. Introduction ....................................................2 -- 2. Case Insensitivity of DNS Labels ................................2 -- 2.1. Escaping Unusual DNS Label Octets ..........................2 -- 2.2. Example Labels with Escapes ................................3 -- 3. Name Lookup, Label Types, and CLASS .............................3 -- 3.1. Original DNS Label Types ...................................4 -- 3.2. Extended Label Type Case Insensitivity Considerations ......4 -- 3.3. CLASS Case Insensitivity Considerations ....................4 -- 4. Case on Input and Output ........................................5 -- 4.1. DNS Output Case Preservation ...............................5 -- 4.2. DNS Input Case Preservation ................................5 -- 5. Internationalized Domain Names ..................................6 -- 6. Security Considerations .........................................6 -- 7. Acknowledgements ................................................7 -- Normative References................................................7 -- Informative References..............................................8 -- -- -- -- -- -- -- --Eastlake 3rd Standards Track [Page 1] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- --1. Introduction -- -- The Domain Name System (DNS) is the global hierarchical replicated -- distributed database system for Internet addressing, mail proxy, and -- other information. Each node in the DNS tree has a name consisting -- of zero or more labels [STD13, RFC1591, RFC2606] that are treated in -- a case insensitive fashion. This document clarifies the meaning of -- "case insensitive" for the DNS. This clarification updates RFCs -- 1034, 1035 [STD13], and [RFC2181]. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [RFC2119]. -- --2. Case Insensitivity of DNS Labels -- -- DNS was specified in the era of [ASCII]. DNS names were expected to -- look like most host names or Internet email address right halves (the -- part after the at-sign, "@") or to be numeric, as in the in-addr.arpa -- part of the DNS name space. For example, -- -- foo.example.net. -- aol.com. -- www.gnu.ai.mit.edu. -- or 69.2.0.192.in-addr.arpa. -- -- Case-varied alternatives to the above [RFC3092] would be DNS names -- like -- -- Foo.ExamplE.net. -- AOL.COM. -- WWW.gnu.AI.mit.EDU. -- or 69.2.0.192.in-ADDR.ARPA. -- -- However, the individual octets of which DNS names consist are not -- limited to valid ASCII character codes. They are 8-bit bytes, and -- all values are allowed. Many applications, however, interpret them -- as ASCII characters. -- --2.1. Escaping Unusual DNS Label Octets -- -- In Master Files [STD13] and other human-readable and -writable ASCII -- contexts, an escape is needed for the byte value for period (0x2E, -- ".") and all octet values outside of the inclusive range from 0x21 -- ("!") to 0x7E ("~"). That is to say, 0x2E and all octet values in -- the two inclusive ranges from 0x00 to 0x20 and from 0x7F to 0xFF. -- -- -- -- -- --Eastlake 3rd Standards Track [Page 2] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- One typographic convention for octets that do not correspond to an -- ASCII printing graphic is to use a back-slash followed by the value -- of the octet as an unsigned integer represented by exactly three -- decimal digits. -- -- The same convention can be used for printing ASCII characters so that -- they will be treated as a normal label character. This includes the -- back-slash character used in this convention itself, which can be -- expressed as \092 or \\, and the special label separator period -- ("."), which can be expressed as and \046 or \. It is advisable to -- avoid using a backslash to quote an immediately following non- -- printing ASCII character code to avoid implementation difficulties. -- -- A back-slash followed by only one or two decimal digits is undefined. -- A back-slash followed by four decimal digits produces two octets, the -- first octet having the value of the first three digits considered as -- a decimal number, and the second octet being the character code for -- the fourth decimal digit. -- --2.2. Example Labels with Escapes -- -- The first example below shows embedded spaces and a period (".") -- within a label. The second one shows a 5-octet label where the -- second octet has all bits zero, the third is a backslash, and the -- fourth octet has all bits one. -- -- Donald\032E\.\032Eastlake\0323rd.example. -- and a\000\\\255z.example. -- --3. Name Lookup, Label Types, and CLASS -- -- According to the original DNS design decision, comparisons on name -- lookup for DNS queries should be case insensitive [STD13]. That is -- to say, a lookup string octet with a value in the inclusive range -- from 0x41 to 0x5A, the uppercase ASCII letters, MUST match the -- identical value and also match the corresponding value in the -- inclusive range from 0x61 to 0x7A, the lowercase ASCII letters. A -- lookup string octet with a lowercase ASCII letter value MUST -- similarly match the identical value and also match the corresponding -- value in the uppercase ASCII letter range. -- -- (Historical note: The terms "uppercase" and "lowercase" were invented -- after movable type. The terms originally referred to the two font -- trays for storing, in partitioned areas, the different physical type -- elements. Before movable type, the nearest equivalent terms were -- "majuscule" and "minuscule".) -- -- -- -- -- --Eastlake 3rd Standards Track [Page 3] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- One way to implement this rule would be to subtract 0x20 from all -- octets in the inclusive range from 0x61 to 0x7A before comparing -- octets. Such an operation is commonly known as "case folding", but -- implementation via case folding is not required. Note that the DNS -- case insensitivity does NOT correspond to the case folding specified -- in [ISO-8859-1] or [ISO-8859-2]. For example, the octets 0xDD (\221) -- and 0xFD (\253) do NOT match, although in other contexts, where they -- are interpreted as the upper- and lower-case version of "Y" with an -- acute accent, they might. -- --3.1. Original DNS Label Types -- -- DNS labels in wire-encoded names have a type associated with them. -- The original DNS standard [STD13] had only two types: ASCII labels, -- with a length from zero to 63 octets, and indirect (or compression) -- labels, which consist of an offset pointer to a name location -- elsewhere in the wire encoding on a DNS message. (The ASCII label of -- length zero is reserved for use as the name of the root node of the -- name tree.) ASCII labels follow the ASCII case conventions described -- herein and, as stated above, can actually contain arbitrary byte -- values. Indirect labels are, in effect, replaced by the name to -- which they point, which is then treated with the case insensitivity -- rules in this document. -- --3.2. Extended Label Type Case Insensitivity Considerations -- -- DNS was extended by [RFC2671] so that additional label type numbers -- would be available. (The only such type defined so far is the BINARY -- type [RFC2673], which is now Experimental [RFC3363].) -- -- The ASCII case insensitivity conventions only apply to ASCII labels; -- that is to say, label type 0x0, whether appearing directly or invoked -- by indirect labels. -- --3.3. CLASS Case Insensitivity Considerations -- -- As described in [STD13] and [RFC2929], DNS has an additional axis for -- data location called CLASS. The only CLASS in global use at this -- time is the "IN" (Internet) CLASS. -- -- The handling of DNS label case is not CLASS dependent. With the -- original design of DNS, it was intended that a recursive DNS resolver -- be able to handle new CLASSes that were unknown at the time of its -- implementation. This requires uniform handling of label case -- insensitivity. Should it become desirable, for example, to allocate -- a CLASS with "case sensitive ASCII labels", it would be necessary to -- allocate a new label type for these labels. -- -- -- -- --Eastlake 3rd Standards Track [Page 4] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- --4. Case on Input and Output -- -- While ASCII label comparisons are case insensitive, [STD13] says case -- MUST be preserved on output and preserved when convenient on input. -- However, this means less than it would appear, since the preservation -- of case on output is NOT required when output is optimized by the use -- of indirect labels, as explained below. -- --4.1. DNS Output Case Preservation -- -- [STD13] views the DNS namespace as a node tree. ASCII output is as -- if a name were marshaled by taking the label on the node whose name -- is to be output, converting it to a typographically encoded ASCII -- string, walking up the tree outputting each label encountered, and -- preceding all labels but the first with a period ("."). Wire output -- follows the same sequence, but each label is wire encoded, and no -- periods are inserted. No "case conversion" or "case folding" is done -- during such output operations, thus "preserving" case. However, to -- optimize output, indirect labels may be used to point to names -- elsewhere in the DNS answer. In determining whether the name to be -- pointed to (for example, the QNAME) is the "same" as the remainder of -- the name being optimized, the case insensitive comparison specified -- above is done. Thus, such optimization may easily destroy the output -- preservation of case. This type of optimization is commonly called -- "name compression". -- --4.2. DNS Input Case Preservation -- -- Originally, DNS data came from an ASCII Master File as defined in -- [STD13] or a zone transfer. DNS Dynamic update and incremental zone -- transfers [RFC1995] have been added as a source of DNS data [RFC2136, -- RFC3007]. When a node in the DNS name tree is created by any of such -- inputs, no case conversion is done. Thus, the case of ASCII labels -- is preserved if they are for nodes being created. However, when a -- name label is input for a node that already exists in DNS data being -- held, the situation is more complex. Implementations are free to -- retain the case first loaded for such a label, to allow new input to -- override the old case, or even to maintain separate copies preserving -- the input case. -- -- For example, if data with owner name "foo.bar.example" [RFC3092] is -- loaded and then later data with owner name "xyz.BAR.example" is -- input, the name of the label on the "bar.example" node (i.e., "bar") -- might or might not be changed to "BAR" in the DNS stored data. Thus, -- later retrieval of data stored under "xyz.bar.example" in this case -- can use "xyz.BAR.example" in all returned data, use "xyz.bar.example" -- in all returned data, or even, when more than one RR is being -- returned, use a mixture of these two capitalizations. This last case -- -- -- --Eastlake 3rd Standards Track [Page 5] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- is unlikely, as optimization of answer length through indirect labels -- tends to cause only one copy of the name tail ("bar.example" or -- "BAR.example") to be used for all returned RRs. Note that none of -- this has any effect on the number or completeness of the RR set -- returned, only on the case of the names in the RR set returned. -- -- The same considerations apply when inputting multiple data records -- with owner names differing only in case. For example, if an "A" -- record is the first resource record stored under owner name -- "xyz.BAR.example" and then a second "A" record is stored under -- "XYZ.BAR.example", the second MAY be stored with the first (lower -- case initial label) name, the second MAY override the first so that -- only an uppercase initial label is retained, or both capitalizations -- MAY be kept in the DNS stored data. In any case, a retrieval with -- either capitalization will retrieve all RRs with either -- capitalization. -- -- Note that the order of insertion into a server database of the DNS -- name tree nodes that appear in a Master File is not defined so that -- the results of inconsistent capitalization in a Master File are -- unpredictable output capitalization. -- --5. Internationalized Domain Names -- -- A scheme has been adopted for "internationalized domain names" and -- "internationalized labels" as described in [RFC3490, RFC3454, -- RFC3491, and RFC3492]. It makes most of [UNICODE] available through -- a separate application level transformation from internationalized -- domain name to DNS domain name and from DNS domain name to -- internationalized domain name. Any case insensitivity that -- internationalized domain names and labels have varies depending on -- the script and is handled entirely as part of the transformation -- described in [RFC3454] and [RFC3491], which should be seen for -- further details. This is not a part of the DNS as standardized in -- STD 13. -- --6. Security Considerations -- -- The equivalence of certain DNS label types with case differences, as -- clarified in this document, can lead to security problems. For -- example, a user could be confused by believing that two domain names -- differing only in case were actually different names. -- -- Furthermore, a domain name may be used in contexts other than the -- DNS. It could be used as a case sensitive index into some database -- or file system. Or it could be interpreted as binary data by some -- integrity or authentication code system. These problems can usually -- be handled by using a standardized or "canonical" form of the DNS -- -- -- --Eastlake 3rd Standards Track [Page 6] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- ASCII type labels; that is, always mapping the ASCII letter value -- octets in ASCII labels to some specific pre-chosen case, either -- uppercase or lower case. An example of a canonical form for domain -- names (and also a canonical ordering for them) appears in Section 6 -- of [RFC4034]. See also [RFC3597]. -- -- Finally, a non-DNS name may be stored into DNS with the false -- expectation that case will always be preserved. For example, -- although this would be quite rare, on a system with case sensitive -- email address local parts, an attempt to store two Responsible Person -- (RP) [RFC1183] records that differed only in case would probably -- produce unexpected results that might have security implications. -- That is because the entire email address, including the possibly case -- sensitive local or left-hand part, is encoded into a DNS name in a -- readable fashion where the case of some letters might be changed on -- output as described above. -- --7. Acknowledgements -- -- The contributions to this document by Rob Austein, Olafur -- Gudmundsson, Daniel J. Anderson, Alan Barrett, Marc Blanchet, Dana, -- Andreas Gustafsson, Andrew Main, Thomas Narten, and Scott Seligman -- are gratefully acknowledged. -- --Normative References -- -- [ASCII] ANSI, "USA Standard Code for Information Interchange", -- X3.4, American National Standards Institute: New York, -- 1968. -- -- [RFC1995] Ohta, M., "Incremental Zone Transfer in DNS", RFC 1995, -- August 1996. -- -- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- -- [RFC2136] Vixie, P., Thomson, S., Rekhter, Y., and J. Bound, -- "Dynamic Updates in the Domain Name System (DNS -- UPDATE)", RFC 2136, April 1997. -- -- [RFC2181] Elz, R. and R. Bush, "Clarifications to the DNS -- Specification", RFC 2181, July 1997. -- -- [RFC3007] Wellington, B., "Secure Domain Name System (DNS) Dynamic -- Update", RFC 3007, November 2000. -- -- -- -- -- -- --Eastlake 3rd Standards Track [Page 7] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- [RFC3597] Gustafsson, A., "Handling of Unknown DNS Resource Record -- (RR) Types", RFC 3597, September 2003. -- -- [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. -- Rose, "Resource Records for the DNS Security -- Extensions", RFC 4034, March 2005. -- -- [STD13] Mockapetris, P., "Domain names - concepts and -- facilities", STD 13, RFC 1034, November 1987. -- -- Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- --Informative References -- -- [ISO-8859-1] International Standards Organization, Standard for -- Character Encodings, Latin-1. -- -- [ISO-8859-2] International Standards Organization, Standard for -- Character Encodings, Latin-2. -- -- [RFC1183] Everhart, C., Mamakos, L., Ullmann, R., and P. -- Mockapetris, "New DNS RR Definitions", RFC 1183, October -- 1990. -- -- [RFC1591] Postel, J., "Domain Name System Structure and -- Delegation", RFC 1591, March 1994. -- -- [RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS -- Names", BCP 32, RFC 2606, June 1999. -- -- [RFC2929] Eastlake 3rd, D., Brunner-Williams, E., and B. Manning, -- "Domain Name System (DNS) IANA Considerations", BCP 42, -- RFC 2929, September 2000. -- -- [RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC -- 2671, August 1999. -- -- [RFC2673] Crawford, M., "Binary Labels in the Domain Name System", -- RFC 2673, August 1999. -- -- [RFC3092] Eastlake 3rd, D., Manros, C., and E. Raymond, "Etymology -- of "Foo"", RFC 3092, 1 April 2001. -- -- [RFC3363] Bush, R., Durand, A., Fink, B., Gudmundsson, O., and T. -- Hain, "Representing Internet Protocol version 6 (IPv6) -- Addresses in the Domain Name System (DNS)", RFC 3363, -- August 2002. -- -- -- --Eastlake 3rd Standards Track [Page 8] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- -- [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of -- Internationalized Strings ("stringprep")", RFC 3454, -- December 2002. -- -- [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, -- "Internationalizing Domain Names in Applications -- (IDNA)", RFC 3490, March 2003. -- -- [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep -- Profile for Internationalized Domain Names (IDN)", RFC -- 3491, March 2003. -- -- [RFC3492] Costello, A., "Punycode: A Bootstring encoding of -- Unicode for Internationalized Domain Names in -- Applications (IDNA)", RFC 3492, March 2003. -- -- [UNICODE] The Unicode Consortium, "The Unicode Standard", -- . -- --Author's Address -- -- Donald E. Eastlake 3rd -- Motorola Laboratories -- 155 Beaver Street -- Milford, MA 01757 USA -- -- Phone: +1 508-786-7554 (w) -- EMail: Donald.Eastlake@motorola.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd Standards Track [Page 9] -- --RFC 4343 DNS Case Insensitivity Clarification January 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Eastlake 3rd Standards Track [Page 10] -- diff --cc doc/rfc/rfc4367.txt index f066b6468eb,f066b6468eb..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4367.txt +++ /dev/null @@@ -1,955 -1,955 +1,0 @@@ -- -- -- -- -- -- --Network Working Group J. Rosenberg, Ed. --Request for Comments: 4367 IAB --Category: Informational February 2006 -- -- -- What's in a Name: False Assumptions about DNS Names -- --Status of This Memo -- -- This memo provides information for the Internet community. It does -- not specify an Internet standard of any kind. Distribution of this -- memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- The Domain Name System (DNS) provides an essential service on the -- Internet, mapping structured names to a variety of data, usually IP -- addresses. These names appear in email addresses, Uniform Resource -- Identifiers (URIs), and other application-layer identifiers that are -- often rendered to human users. Because of this, there has been a -- strong demand to acquire names that have significance to people, -- through equivalence to registered trademarks, company names, types of -- services, and so on. There is a danger in this trend; the humans and -- automata that consume and use such names will associate specific -- semantics with some names and thereby make assumptions about the -- services that are, or should be, provided by the hosts associated -- with the names. Those assumptions can often be false, resulting in a -- variety of failure conditions. This document discusses this problem -- in more detail and makes recommendations on how it can be avoided. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Rosenberg Informational [Page 1] -- --RFC 4367 Name Assumptions February 2006 -- -- --Table of Contents -- -- 1. Introduction ....................................................2 -- 2. Target Audience .................................................4 -- 3. Modeling Usage of the DNS .......................................4 -- 4. Possible Assumptions ............................................5 -- 4.1. By the User ................................................5 -- 4.2. By the Client ..............................................6 -- 4.3. By the Server ..............................................7 -- 5. Consequences of False Assumptions ...............................8 -- 6. Reasons Why the Assumptions Can Be False ........................9 -- 6.1. Evolution ..................................................9 -- 6.2. Leakage ...................................................10 -- 6.3. Sub-Delegation ............................................10 -- 6.4. Mobility ..................................................12 -- 6.5. Human Error ...............................................12 -- 7. Recommendations ................................................12 -- 8. A Note on RFC 2219 and RFC 2782 ................................13 -- 9. Security Considerations ........................................14 -- 10. Acknowledgements ..............................................14 -- 11. IAB Members ...................................................14 -- 12. Informative References ........................................15 -- --1. Introduction -- -- The Domain Name System (DNS) [1] provides an essential service on the -- Internet, mapping structured names to a variety of different types of -- data. Most often it is used to obtain the IP address of a host -- associated with that name [2] [1] [3]. However, it can be used to -- obtain other information, and proposals have been made for nearly -- everything, including geographic information [4]. -- -- Domain names are most often used in identifiers used by application -- protocols. The most well known include email addresses and URIs, -- such as the HTTP URL [5], Real Time Streaming Protocol (RTSP) URL -- [6], and SIP URI [7]. These identifiers are ubiquitous, appearing on -- business cards, web pages, street signs, and so on. Because of this, -- there has been a strong demand to acquire domain names that have -- significance to people through equivalence to registered trademarks, -- company names, types of services, and so on. Such identifiers serve -- many business purposes, including extension of brand, advertising, -- and so on. -- -- People often make assumptions about the type of service that is or -- should be provided by a host associated with that name, based on -- their expectations and understanding of what the name implies. This, -- in turn, triggers attempts by organizations to register domain names -- based on that presumed user expectation. Examples of this are the -- -- -- --Rosenberg Informational [Page 2] -- --RFC 4367 Name Assumptions February 2006 -- -- -- various proposals for a Top-Level Domain (TLD) that could be -- associated with adult content [8], the requests for creation of TLDs -- associated with mobile devices and services, and even phishing -- attacks. -- -- When these assumptions are codified into the behavior of an -- automaton, such as an application client or server, as a result of -- implementor choice, management directive, or domain owner policy, the -- overall system can fail in various ways. This document describes a -- number of typical ways in which these assumptions can be codified, -- how they can be wrong, the consequences of those mistakes, and the -- recommended ways in which they can be avoided. -- -- Section 4 describes some of the possible assumptions that clients, -- servers, and people can make about a domain name. In this context, -- an "assumption" is defined as any behavior that is expected when -- accessing a service at a domain name, even though the behavior is not -- explicitly codified in protocol specifications. Frequently, these -- assumptions involve ignoring parts of a specification based on an -- assumption that the client or server is deployed in an environment -- that is more rigid than the specification allows. Section 5 -- overviews some of the consequences of these false assumptions. -- Generally speaking, these consequences can include a variety of -- different interoperability failures, user experience failures, and -- system failures. Section 6 discusses why these assumptions can be -- false from the very beginning or become false at some point in the -- future. Most commonly, they become false because the environment -- changes in unexpected ways over time, and what was a valid assumption -- before, no longer is. Other times, the assumptions prove wrong -- because they were based on the belief that a specific community of -- clients and servers was participating, and an element outside of that -- community began participating. -- -- Section 7 then provides some recommendations. These recommendations -- encapsulate some of the engineering mantras that have been at the -- root of Internet protocol design for decades. These include: -- -- Follow the specifications. -- -- Use the capability negotiation techniques provided in the -- protocols. -- -- Be liberal in what you accept, and conservative in what you send. -- [18] -- -- Overall, automata should not change their behavior within a protocol -- based on the domain name, or some component of the domain name, of -- the host they are communicating with. -- -- -- --Rosenberg Informational [Page 3] -- --RFC 4367 Name Assumptions February 2006 -- -- --2. Target Audience -- -- This document has several audiences. Firstly, it is aimed at -- implementors who ultimately develop the software that make the false -- assumptions that are the subject of this document. The -- recommendations described here are meant to reinforce the engineering -- guidelines that are often understood by implementors, but frequently -- forgotten as deadlines near and pressures mount. -- -- The document is also aimed at technology managers, who often develop -- the requirements that lead to these false assumptions. For them, -- this document serves as a vehicle for emphasizing the importance of -- not taking shortcuts in the scope of applicability of a project. -- -- Finally, this document is aimed at domain name policy makers and -- administrators. For them, it points out the perils in establishing -- domain policies that get codified into the operation of applications -- running within that domain. -- --3. Modeling Usage of the DNS -- -- -- +--------+ -- | | -- | | -- | DNS | -- |Service | -- | | -- +--------+ -- ^ | -- | | -- | | -- | | -- /--\ | | -- | | | V -- | | +--------+ +--------+ -- \--/ | | | | -- | | | | | -- ---+--- | Client |-------------------->| Server | -- | | | | | -- | | | | | -- /\ +--------+ +--------+ -- / \ -- / \ -- -- User -- Figure 1 -- -- -- -- --Rosenberg Informational [Page 4] -- --RFC 4367 Name Assumptions February 2006 -- -- -- Figure 1 shows a simple conceptual model of how the DNS is used by -- applications. A user of the application obtains an identifier for -- particular content or service it wishes to obtain. This identifier -- is often a URL or URI that contains a domain name. The user enters -- this identifier into its client application (for example, by typing -- in the URL in a web browser window). The client is the automaton (a -- software and/or hardware system) that contacts a server for that -- application in order to provide service to the user. To do that, it -- contacts a DNS server to resolve the domain name in the identifier to -- an IP address. It then contacts the server at that IP address. This -- simple model applies to application protocols such as HTTP [5], SIP -- [7], RTSP [6], and SMTP [9]. -- -- >From this model, it is clear that three entities in the system can -- potentially make false assumptions about the service provided by the -- server. The human user may form expectations relating to the content -- of the service based on a parsing of the host name from which the -- content originated. The server might assume that the client -- connecting to it supports protocols that it does not, can process -- content that it cannot, or has capabilities that it does not. -- Similarly, the client might assume that the server supports -- protocols, content, or capabilities that it does not. Furthermore, -- applications can potentially contain a multiplicity of humans, -- clients, and servers, all of which can independently make these false -- assumptions. -- --4. Possible Assumptions -- -- For each of the three elements, there are many types of false -- assumptions that can be made. -- --4.1. By the User -- -- The set of possible assumptions here is nearly boundless. Users -- might assume that an HTTP URL that looks like a company name maps to -- a server run by that company. They might assume that an email from a -- email address in the .gov TLD is actually from a government employee. -- They might assume that the content obtained from a web server within -- a TLD labeled as containing adult materials (for example, .sex) -- actually contains adult content [8]. These assumptions are -- unavoidable, may all be false, and are not the focus of this -- document. -- -- -- -- -- -- -- -- -- --Rosenberg Informational [Page 5] -- --RFC 4367 Name Assumptions February 2006 -- -- --4.2. By the Client -- -- Even though the client is an automaton, it can make some of the same -- assumptions that a human user might make. For example, many clients -- assume that any host with a hostname that begins with "www" is a web -- server, even though this assumption may be false. -- -- In addition, the client concerns itself with the protocols needed to -- communicate with the server. As a result, it might make assumptions -- about the operation of the protocols for communicating with the -- server. These assumptions manifest themselves in an implementation -- when a standardized protocol negotiation technique defined by the -- protocol is ignored, and instead, some kind of rule is coded into the -- software that comes to its own conclusion about what the negotiation -- would have determined. The result is often a loss of -- interoperability, degradation in reliability, and worsening of user -- experience. -- -- Authentication Algorithm: Though a protocol might support a -- multiplicity of authentication techniques, a client might assume -- that a server always supports one that is only optional according -- to the protocol. For example, a SIP client contacting a SIP -- server in a domain that is apparently used to identify mobile -- devices (for example, www.example.cellular) might assume that the -- server supports the optional Authentication and Key Agreement -- (AKA) digest technique [10], just because of the domain name that -- was used to access the server. As another example, a web client -- might assume that a server with the name https.example.com -- supports HTTP over Transport Layer Security (TLS) [16]. -- -- Data Formats: Though a protocol might allow a multiplicity of data -- formats to be sent from the server to the client, the client might -- assume a specific one, rather than using the content labeling and -- negotiation capabilities of the underlying protocol. For example, -- an RTSP client might assume that all audio content delivered to it -- from media.example.cellular uses a low-bandwidth codec. As -- another example, a mail client might assume that the contents of -- messages it retrieves from a mail server at mail.example.cellular -- are always text, instead of checking the MIME headers [11] in the -- message in order to determine the actual content type. -- -- Protocol Extensions: A client may attempt an operation on the server -- that requires the server to support an optional protocol -- extension. However, rather than implementing the necessary -- fallback logic, the client may falsely assume that the extension -- is supported. As an example, a SIP client that requires reliable -- provisional responses to its request (RFC 3262 [17]) might assume -- that this extension is supported on servers in the domain -- -- -- --Rosenberg Informational [Page 6] -- --RFC 4367 Name Assumptions February 2006 -- -- -- sip.example.telecom. Furthermore, the client would not implement -- the fallback behavior defined in RFC 3262, since it would assume -- that all servers it will communicate with are in this domain and -- that all therefore support this extension. However, if the -- assumptions prove wrong, the client is unable to make any phone -- calls. -- -- Languages: A client may support facilities for processing text -- content differently depending on the language of the text. Rather -- than determining the language from markers in the message from the -- server, the client might assume a language based on the domain -- name. This assumption can easily be wrong. For example, a client -- might assume that any text in a web page retrieved from a server -- within the .de country code TLD (ccTLD) is in German, and attempt -- a translation to Finnish. This would fail dramatically if the -- text was actually in French. Unfortunately, this client behavior -- is sometimes exhibited because the server has not properly labeled -- the language of the content in the first place, often because the -- server assumed such a labeling was not needed. This is an example -- of how these false assumptions can create vicious cycles. -- --4.3. By the Server -- -- The server, like the client, is an automaton. Let us consider one -- servicing a particular domain -- www.company.cellular, for example. -- It might assume that all clients connecting to this domain support -- particular capabilities, rather than using the underlying protocol to -- make this determination. Some examples include: -- -- Authentication Algorithm: The server can assume that a client -- supports a particular, optional, authentication technique, and it -- therefore does not support the mandatory one. -- -- Language: The server can serve content in a particular language, -- based on an assumption that clients accessing the domain speak a -- particular language, or based on an assumption that clients coming -- from a particular IP address speak a certain language. -- -- Data Formats: The server can assume that the client supports a -- particular set of MIME types and is only capable of sending ones -- within that set. When it generates content in a protocol -- response, it ignores any content negotiation headers that were -- present in the request. For example, a web server might ignore -- the Accept HTTP header field and send a specific image format. -- -- -- -- -- -- -- --Rosenberg Informational [Page 7] -- --RFC 4367 Name Assumptions February 2006 -- -- -- Protocol Extensions: The server might assume that the client supports -- a particular optional protocol extension, and so it does not -- support the fallback behavior necessary in the case where the -- client does not. -- -- Client Characteristics: The server might assume certain things about -- the physical characteristics of its clients, such as memory -- footprint, processing power, screen sizes, screen colors, pointing -- devices, and so on. Based on these assumptions, it might choose -- specific behaviors when processing a request. For example, a web -- server might always assume that clients connect through cell -- phones, and therefore return content that lacks images and is -- tuned for such devices. -- --5. Consequences of False Assumptions -- -- There are numerous negative outcomes that can arise from the various -- false assumptions that users, servers, and clients can make. These -- include: -- -- Interoperability Failure: In these cases, the client or server -- assumed some kind of protocol operation, and this assumption was -- wrong. The result is that the two are unable to communicate, and -- the user receives some kind of an error. This represents a total -- interoperability failure, manifesting itself as a lack of service -- to users of the system. Unfortunately, this kind of failure -- persists. Repeated attempts over time by the client to access the -- service will fail. Only a change in the server or client software -- can fix this problem. -- -- System Failure: In these cases, the client or server misinterpreted a -- protocol operation, and this misinterpretation was serious enough -- to uncover a bug in the implementation. The bug causes a system -- crash or some kind of outage, either transient or permanent (until -- user reset). If this failure occurs in a server, not only will -- the connecting client lose service, but other clients attempting -- to connect will not get service. As an example, if a web server -- assumes that content passed to it from a client (created, for -- example, by a digital camera) is of a particular content type, and -- it always passes image content to a codec for decompression prior -- to storage, the codec might crash when it unexpectedly receives an -- image compressed in a different format. Of course, it might crash -- even if the Content-Type was correct, but the compressed bitstream -- was invalid. False assumptions merely introduce additional -- failure cases. -- -- -- -- -- -- --Rosenberg Informational [Page 8] -- --RFC 4367 Name Assumptions February 2006 -- -- -- Poor User Experience: In these cases, the client and server -- communicate, but the user receives a diminished user experience. -- For example, if a client on a PC connects to a web site that -- provides content for mobile devices, the content may be -- underwhelming when viewed on the PC. Or, a client accessing a -- streaming media service may receive content of very low bitrate, -- even though the client supported better codecs. Indeed, if a user -- wishes to access content from both a cellular device and a PC -- using a shared address book (that is, an address book shared -- across multiple devices), the user would need two entries in that -- address book, and would need to use the right one from the right -- device. This is a poor user experience. -- -- Degraded Security: In these cases, a weaker security mechanism is -- used than the one that ought to have been used. As an example, a -- server in a domain might assume that it is only contacted by -- clients with a limited set of authentication algorithms, even -- though the clients have been recently upgraded to support a -- stronger set. -- --6. Reasons Why the Assumptions Can Be False -- -- Assumptions made by clients and servers about the operation of -- protocols when contacting a particular domain are brittle, and can be -- wrong for many reasons. On the server side, many of the assumptions -- are based on the notion that a domain name will only be given to, or -- used by, a restricted set of clients. If the holder of the domain -- name assumes something about those clients, and can assume that only -- those clients use the domain name, then it can configure or program -- the server to operate specifically for those clients. Both parts of -- this assumption can be wrong, as discussed in more detail below. -- -- On the client side, the notion is similar, being based on the -- assumption that a server within a particular domain will provide a -- specific type of service. Sub-delegation and evolution, both -- discussed below, can make these assumptions wrong. -- --6.1. Evolution -- -- The Internet and the devices that access it are constantly evolving, -- often at a rapid pace. Unfortunately, there is a tendency to build -- for the here and now, and then worry about the future at a later -- time. Many of the assumptions above are predicated on -- characteristics of today's clients and servers. Support for specific -- protocols, authentication techniques, or content are based on today's -- standards and today's devices. Even though they may, for the most -- part, be true, they won't always be. An excellent example is mobile -- devices. A server servicing a domain accessed by mobile devices -- -- -- --Rosenberg Informational [Page 9] -- --RFC 4367 Name Assumptions February 2006 -- -- -- might try to make assumptions about the protocols, protocol -- extensions, security mechanisms, screen sizes, or processor power of -- such devices. However, all of these characteristics can and will -- change over time. -- -- When they do change, the change is usually evolutionary. The result -- is that the assumptions remain valid in some cases, but not in -- others. It is difficult to fix such systems, since it requires the -- server to detect what type of client is connecting, and what its -- capabilities are. Unless the system is built and deployed with these -- capability negotiation techniques built in to begin with, such -- detection can be extremely difficult. In fact, fixing it will often -- require the addition of such capability negotiation features that, if -- they had been in place and used to begin with, would have avoided the -- problem altogether. -- --6.2. Leakage -- -- Servers also make assumptions because of the belief that they will -- only be accessed by specific clients, and in particular, those that -- are configured or provisioned to use the domain name. In essence, -- there is an assumption of community -- that a specific community -- knows and uses the domain name, while others outside of the community -- do not. -- -- The problem is that this notion of community is a false one. The -- Internet is global. The DNS is global. There is no technical -- barrier that separates those inside of the community from those -- outside. The ease with which information propagates across the -- Internet makes it extremely likely that such domain names will -- eventually find their way into clients outside of the presumed -- community. The ubiquitous presence of domain names in various URI -- formats, coupled with the ease of conveyance of URIs, makes such -- leakage merely a matter of time. Furthermore, since the DNS is -- global, and since it can only have one root [12], it becomes possible -- for clients outside of the community to search and find and use such -- "special" domain names. -- -- Indeed, this leakage is a strength of the Internet architecture, not -- a weakness. It enables global access to services from any client -- with a connection to the Internet. That, in turn, allows for rapid -- growth in the number of customers for any particular service. -- --6.3. Sub-Delegation -- -- Clients and users make assumptions about domains because of the -- notion that there is some kind of centralized control that can -- enforce those assumptions. However, the DNS is not centralized; it -- -- -- --Rosenberg Informational [Page 10] -- --RFC 4367 Name Assumptions February 2006 -- -- -- is distributed. If a domain doesn't delegate its sub-domains and has -- its records within a single zone, it is possible to maintain a -- centralized policy about operation of its domain. However, once a -- domain gets sufficiently large that the domain administrators begin -- to delegate sub-domains to other authorities, it becomes increasingly -- difficult to maintain any kind of central control on the nature of -- the service provided in each sub-domain. -- -- Similarly, the usage of domain names with human semantic connotation -- tends to lead to a registration of multiple domains in which a -- particular service is to run. As an example, a service provider with -- the name "example" might register and set up its services in -- "example.com", "example.net", and generally example.foo for each foo -- that is a valid TLD. This, like sub-delegation, results in a growth -- in the number of domains over which it is difficult to maintain -- centralized control. -- -- Not that it is not possible, since there are many examples of -- successful administration of policies across sub-domains many levels -- deep. However, it takes an increasing amount of effort to ensure -- this result, as it requires human intervention and the creation of -- process and procedure. Automated validation of adherence to policies -- is very difficult to do, as there is no way to automatically verify -- many policies that might be put into place. -- -- A less costly process for providing centralized management of -- policies is to just hope that any centralized policies are being -- followed, and then wait for complaints or perform random audits. -- Those approaches have many problems. -- -- The invalidation of assumptions due to sub-delegation is discussed in -- further detail in Section 4.1.3 of [8] and in Section 3.3 of [20]. -- -- As a result of the fragility of policy continuity across sub- -- delegations, if a client or user assumes some kind of property -- associated with a TLD (such as ".wifi"), it becomes increasingly more -- likely with the number of sub-domains that this property will not -- exist in a server identified by a particular name. For example, in -- "store.chain.company.provider.wifi", there may be four levels of -- delegation from ".wifi", making it quite likely that, unless the -- holder of ".wifi" is working diligently, the properties that the -- holder of ".wifi" wishes to enforce are not present. These -- properties may not be present due to human error or due to a willful -- decision not to adhere to them. -- -- -- -- -- -- -- --Rosenberg Informational [Page 11] -- --RFC 4367 Name Assumptions February 2006 -- -- --6.4. Mobility -- -- One of the primary value propositions of a hostname as an identifier -- is its persistence. A client can change IP addresses, yet still -- retain a persistent identifier used by other hosts to reach it. -- Because their value derives from their persistence, hostnames tend to -- move with a host not just as it changes IP addresses, but as it -- changes access network providers and technologies. For this reason, -- assumptions made about a host based on the presumed access network -- corresponding to that hostname tend to be wrong over time. As an -- example, a PC might normally be connected to its broadband provider, -- and through dynamic DNS have a hostname within the domain of that -- provider. However, one cannot assume that any host within that -- network has access over a broadband link; the user could connect -- their PC over a low-bandwidth wireless access network and still -- retain its domain name. -- --6.5. Human Error -- -- Of course, human error can be the source of errors in any system, and -- the same is true here. There are many examples relevant to the -- problem under discussion. -- -- A client implementation may make the assumption that, just because a -- DNS SRV record exists for a particular protocol in a particular -- domain, indicating that the service is available on some port, that -- the service is, in fact, running there. This assumption could be -- wrong because the SRV records haven't been updated by the system -- administrators to reflect the services currently running. As another -- example, a client might assume that a particular domain policy -- applies to all sub-domains. However, a system administrator might -- have omitted to apply the policy to servers running in one of those -- sub-domains. -- --7. Recommendations -- -- Based on these problems, the clear conclusion is that clients, -- servers, and users should not make assumptions on the nature of the -- service provided to, or by, a domain. More specifically, however, -- the following can be said: -- -- Follow the specifications: When specifications define mandatory -- baseline procedures and formats, those should be implemented and -- supported, even if the expectation is that optional procedures -- will most often be used. For example, if a specification mandates -- a particular baseline authentication technique, but allows others -- to be negotiated and used, implementations need to implement the -- baseline authentication algorithm even if the other ones are used -- -- -- --Rosenberg Informational [Page 12] -- --RFC 4367 Name Assumptions February 2006 -- -- -- most of the time. Put more simply, the behavior of the protocol -- machinery should never change based on the domain name of the -- host. -- -- Use capability negotiation: Many protocols are engineered with -- capability negotiation mechanisms. For example, a content -- negotiation framework has been defined for protocols using MIME -- content [13] [14] [15]. SIP allows for clients to negotiate the -- media types used in the multimedia session, as well as protocol -- parameters. HTTP allows for clients to negotiate the media types -- returned in requests for content. When such features are -- available in a protocol, client and servers should make use of -- them rather than making assumptions about supported capabilities. -- A corollary is that protocol designers should include such -- mechanisms when evolution is expected in the usage of the -- protocol. -- -- "Be liberal in what you accept, and conservative in what you send" -- [18]: This axiom of Internet protocol design is applicable here -- as well. Implementations should be prepared for the full breadth -- of what a protocol allows another entity to send, rather than be -- limiting in what it is willing to receive. -- -- To summarize -- there is never a need to make assumptions. Rather -- than doing so, utilize the specifications and the negotiation -- capabilities they provide, and the overall system will be robust and -- interoperable. -- --8. A Note on RFC 2219 and RFC 2782 -- -- Based on the definition of an assumption given here, the behavior -- hinted at by records in the DNS also represents an assumption. RFC -- 2219 [19] defines well-known aliases that can be used to construct -- domain names for reaching various well-known services in a domain. -- This approach was later followed by the definition of a new resource -- record, the SRV record [2], which specifies that a particular service -- is running on a server in a domain. Although both of these -- mechanisms are useful as a hint that a particular service is running -- in a domain, both of them represent assumptions that may be false. -- However, they differ in the set of reasons why those assumptions -- might be false. -- -- A client that assumes that "ftp.example.com" is an FTP server may be -- wrong because the presumed naming convention in RFC 2219 was not -- known by, or not followed by, the owner of domain.com. With RFC -- 2782, an SRV record for a particular service would be present only by -- explicit choice of the domain administrator, and thus a client that -- -- -- -- --Rosenberg Informational [Page 13] -- --RFC 4367 Name Assumptions February 2006 -- -- -- assumes that the corresponding host provides this service would be -- wrong only because of human error in configuration. In this case, -- the assumption is less likely to be wrong, but it certainly can be. -- -- The only way to determine with certainty that a service is running on -- a host is to initiate a connection to the port for that service, and -- check. Implementations need to be careful not to codify any -- behaviors that cause failures should the information provided in the -- record actually be false. This borders on common sense for robust -- implementations, but it is valuable to raise this point explicitly. -- --9. Security Considerations -- -- One of the assumptions that can be made by clients or servers is the -- availability and usage (or lack thereof) of certain security -- protocols and algorithms. For example, a client accessing a service -- in a particular domain might assume a specific authentication -- algorithm or hash function in the application protocol. It is -- possible that, over time, weaknesses are found in such a technique, -- requiring usage of a different mechanism. Similarly, a system might -- start with an insecure mechanism, and then decide later on to use a -- secure one. In either case, assumptions made on security properties -- can result in interoperability failures, or worse yet, providing -- service in an insecure way, even though the client asked for, and -- thought it would get, secure service. These kinds of assumptions are -- fundamentally unsound even if the records themselves are secured with -- DNSSEC. -- --10. Acknowledgements -- -- The IAB would like to thank John Klensin, Keith Moore and Peter Koch -- for their comments. -- --11. IAB Members -- -- Internet Architecture Board members at the time of writing of this -- document are: -- -- Bernard Aboba -- -- Loa Andersson -- -- Brian Carpenter -- -- Leslie Daigle -- -- Patrik Faltstrom -- -- -- -- --Rosenberg Informational [Page 14] -- --RFC 4367 Name Assumptions February 2006 -- -- -- Bob Hinden -- -- Kurtis Lindqvist -- -- David Meyer -- -- Pekka Nikander -- -- Eric Rescorla -- -- Pete Resnick -- -- Jonathan Rosenberg -- --12. Informative References -- -- [1] Mockapetris, P., "Domain names - concepts and facilities", -- STD 13, RFC 1034, November 1987. -- -- [2] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for -- specifying the location of services (DNS SRV)", RFC 2782, -- February 2000. -- -- [3] Mealling, M., "Dynamic Delegation Discovery System (DDDS) Part -- Three: The Domain Name System (DNS) Database", RFC 3403, -- October 2002. -- -- [4] Davis, C., Vixie, P., Goodwin, T., and I. Dickinson, "A Means -- for Expressing Location Information in the Domain Name System", -- RFC 1876, January 1996. -- -- [5] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., -- Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- -- HTTP/1.1", RFC 2616, June 1999. -- -- [6] Schulzrinne, H., Rao, A., and R. Lanphier, "Real Time Streaming -- Protocol (RTSP)", RFC 2326, April 1998. -- -- [7] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., -- Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: -- Session Initiation Protocol", RFC 3261, June 2002. -- -- [8] Eastlake, D., ".sex Considered Dangerous", RFC 3675, -- February 2004. -- -- [9] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, -- April 2001. -- -- -- -- --Rosenberg Informational [Page 15] -- --RFC 4367 Name Assumptions February 2006 -- -- -- [10] Niemi, A., Arkko, J., and V. Torvinen, "Hypertext Transfer -- Protocol (HTTP) Digest Authentication Using Authentication and -- Key Agreement (AKA)", RFC 3310, September 2002. -- -- [11] Freed, N. and N. Borenstein, "Multipurpose Internet Mail -- Extensions (MIME) Part One: Format of Internet Message Bodies", -- RFC 2045, November 1996. -- -- [12] Internet Architecture Board, "IAB Technical Comment on the -- Unique DNS Root", RFC 2826, May 2000. -- -- [13] Klyne, G., "Indicating Media Features for MIME Content", -- RFC 2912, September 2000. -- -- [14] Klyne, G., "A Syntax for Describing Media Feature Sets", -- RFC 2533, March 1999. -- -- [15] Klyne, G., "Protocol-independent Content Negotiation -- Framework", RFC 2703, September 1999. -- -- [16] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. -- -- [17] Rosenberg, J. and H. Schulzrinne, "Reliability of Provisional -- Responses in Session Initiation Protocol (SIP)", RFC 3262, -- June 2002. -- -- [18] Braden, R., "Requirements for Internet Hosts - Communication -- Layers", STD 3, RFC 1122, October 1989. -- -- [19] Hamilton, M. and R. Wright, "Use of DNS Aliases for Network -- Services", BCP 17, RFC 2219, October 1997. -- -- [20] Faltstrom, P., "Design Choices When Expanding DNS", Work in -- Progress, June 2005. -- --Author's Address -- -- Jonathan Rosenberg, Editor -- IAB -- 600 Lanidex Plaza -- Parsippany, NJ 07054 -- US -- -- Phone: +1 973 952-5000 -- EMail: jdrosen@cisco.com -- URI: http://www.jdrosen.net -- -- -- -- -- --Rosenberg Informational [Page 16] -- --RFC 4367 Name Assumptions February 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Rosenberg Informational [Page 17] -- diff --cc doc/rfc/rfc4398.txt index 6437436e6a9,6437436e6a9..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4398.txt +++ /dev/null @@@ -1,955 -1,955 +1,0 @@@ -- -- -- -- -- -- --Network Working Group S. Josefsson --Request for Comments: 4398 March 2006 --Obsoletes: 2538 --Category: Standards Track -- -- -- Storing Certificates in the Domain Name System (DNS) -- --Status of This Memo -- -- This document specifies an Internet standards track protocol for the -- Internet community, and requests discussion and suggestions for -- improvements. Please refer to the current edition of the "Internet -- Official Protocol Standards" (STD 1) for the standardization state -- and status of this protocol. Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- Cryptographic public keys are frequently published, and their -- authenticity is demonstrated by certificates. A CERT resource record -- (RR) is defined so that such certificates and related certificate -- revocation lists can be stored in the Domain Name System (DNS). -- -- This document obsoletes RFC 2538. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 1] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --Table of Contents -- -- 1. Introduction ....................................................3 -- 2. The CERT Resource Record ........................................3 -- 2.1. Certificate Type Values ....................................4 -- 2.2. Text Representation of CERT RRs ............................6 -- 2.3. X.509 OIDs .................................................6 -- 3. Appropriate Owner Names for CERT RRs ............................7 -- 3.1. Content-Based X.509 CERT RR Names ..........................8 -- 3.2. Purpose-Based X.509 CERT RR Names ..........................9 -- 3.3. Content-Based OpenPGP CERT RR Names ........................9 -- 3.4. Purpose-Based OpenPGP CERT RR Names .......................10 -- 3.5. Owner Names for IPKIX, ISPKI, IPGP, and IACPKIX ...........10 -- 4. Performance Considerations .....................................11 -- 5. Contributors ...................................................11 -- 6. Acknowledgements ...............................................11 -- 7. Security Considerations ........................................12 -- 8. IANA Considerations ............................................12 -- 9. Changes since RFC 2538 .........................................13 -- 10. References ....................................................14 -- 10.1. Normative References .....................................14 -- 10.2. Informative References ...................................15 -- Appendix A. Copying Conditions ...................................16 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 2] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --1. Introduction -- -- Public keys are frequently published in the form of a certificate, -- and their authenticity is commonly demonstrated by certificates and -- related certificate revocation lists (CRLs). A certificate is a -- binding, through a cryptographic digital signature, of a public key, -- a validity interval and/or conditions, and identity, authorization, -- or other information. A certificate revocation list is a list of -- certificates that are revoked, and of incidental information, all -- signed by the signer (issuer) of the revoked certificates. Examples -- are X.509 certificates/CRLs in the X.500 directory system or OpenPGP -- certificates/revocations used by OpenPGP software. -- -- Section 2 specifies a CERT resource record (RR) for the storage of -- certificates in the Domain Name System [1] [2]. -- -- Section 3 discusses appropriate owner names for CERT RRs. -- -- Sections 4, 7, and 8 cover performance, security, and IANA -- considerations, respectively. -- -- Section 9 explains the changes in this document compared to RFC 2538. -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [3]. -- --2. The CERT Resource Record -- -- The CERT resource record (RR) has the structure given below. Its RR -- type code is 37. -- -- 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 -- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | type | key tag | -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -- | algorithm | / -- +---------------+ certificate or CRL / -- / / -- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| -- -- The type field is the certificate type as defined in Section 2.1 -- below. -- -- The key tag field is the 16-bit value computed for the key embedded -- in the certificate, using the RRSIG Key Tag algorithm described in -- Appendix B of [12]. This field is used as an efficiency measure to -- -- -- --Josefsson Standards Track [Page 3] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- pick which CERT RRs may be applicable to a particular key. The key -- tag can be calculated for the key in question, and then only CERT RRs -- with the same key tag need to be examined. Note that two different -- keys can have the same key tag. However, the key MUST be transformed -- to the format it would have as the public key portion of a DNSKEY RR -- before the key tag is computed. This is only possible if the key is -- applicable to an algorithm and complies to limits (such as key size) -- defined for DNS security. If it is not, the algorithm field MUST be -- zero and the tag field is meaningless and SHOULD be zero. -- -- The algorithm field has the same meaning as the algorithm field in -- DNSKEY and RRSIG RRs [12], except that a zero algorithm field -- indicates that the algorithm is unknown to a secure DNS, which may -- simply be the result of the algorithm not having been standardized -- for DNSSEC [11]. -- --2.1. Certificate Type Values -- -- The following values are defined or reserved: -- -- Value Mnemonic Certificate Type -- ----- -------- ---------------- -- 0 Reserved -- 1 PKIX X.509 as per PKIX -- 2 SPKI SPKI certificate -- 3 PGP OpenPGP packet -- 4 IPKIX The URL of an X.509 data object -- 5 ISPKI The URL of an SPKI certificate -- 6 IPGP The fingerprint and URL of an OpenPGP packet -- 7 ACPKIX Attribute Certificate -- 8 IACPKIX The URL of an Attribute Certificate -- 9-252 Available for IANA assignment -- 253 URI URI private -- 254 OID OID private -- 255 Reserved -- 256-65279 Available for IANA assignment -- 65280-65534 Experimental -- 65535 Reserved -- -- These values represent the initial content of the IANA registry; see -- Section 8. -- -- The PKIX type is reserved to indicate an X.509 certificate conforming -- to the profile defined by the IETF PKIX working group [8]. The -- certificate section will start with a one-octet unsigned OID length -- and then an X.500 OID indicating the nature of the remainder of the -- -- -- -- -- --Josefsson Standards Track [Page 4] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- certificate section (see Section 2.3, below). (NOTE: X.509 -- certificates do not include their X.500 directory-type-designating -- OID as a prefix.) -- -- The SPKI and ISPKI types are reserved to indicate the SPKI -- certificate format [15], for use when the SPKI documents are moved -- from experimental status. The format for these two CERT RR types -- will need to be specified later. -- -- The PGP type indicates an OpenPGP packet as described in [5] and its -- extensions and successors. This is used to transfer public key -- material and revocation signatures. The data is binary and MUST NOT -- be encoded into an ASCII armor. An implementation SHOULD process -- transferable public keys as described in Section 10.1 of [5], but it -- MAY handle additional OpenPGP packets. -- -- The ACPKIX type indicates an Attribute Certificate format [9]. -- -- The IPKIX and IACPKIX types indicate a URL that will serve the -- content that would have been in the "certificate, CRL, or URL" field -- of the corresponding type (PKIX or ACPKIX, respectively). -- -- The IPGP type contains both an OpenPGP fingerprint for the key in -- question, as well as a URL. The certificate portion of the IPGP CERT -- RR is defined as a one-octet fingerprint length, followed by the -- OpenPGP fingerprint, followed by the URL. The OpenPGP fingerprint is -- calculated as defined in RFC 2440 [5]. A zero-length fingerprint or -- a zero-length URL are legal, and indicate URL-only IPGP data or -- fingerprint-only IPGP data, respectively. A zero-length fingerprint -- and a zero-length URL are meaningless and invalid. -- -- The IPKIX, ISPKI, IPGP, and IACPKIX types are known as "indirect". -- These types MUST be used when the content is too large to fit in the -- CERT RR and MAY be used at the implementer's discretion. They SHOULD -- NOT be used where the DNS message is 512 octets or smaller and could -- thus be expected to fit a UDP packet. -- -- The URI private type indicates a certificate format defined by an -- absolute URI. The certificate portion of the CERT RR MUST begin with -- a null-terminated URI [10], and the data after the null is the -- private format certificate itself. The URI SHOULD be such that a -- retrieval from it will lead to documentation on the format of the -- certificate. Recognition of private certificate types need not be -- based on URI equality but can use various forms of pattern matching -- so that, for example, subtype or version information can also be -- encoded into the URI. -- -- -- -- -- --Josefsson Standards Track [Page 5] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- The OID private type indicates a private format certificate specified -- by an ISO OID prefix. The certificate section will start with a -- one-octet unsigned OID length and then a BER-encoded OID indicating -- the nature of the remainder of the certificate section. This can be -- an X.509 certificate format or some other format. X.509 certificates -- that conform to the IETF PKIX profile SHOULD be indicated by the PKIX -- type, not the OID private type. Recognition of private certificate -- types need not be based on OID equality but can use various forms of -- pattern matching such as OID prefix. -- --2.2. Text Representation of CERT RRs -- -- The RDATA portion of a CERT RR has the type field as an unsigned -- decimal integer or as a mnemonic symbol as listed in Section 2.1, -- above. -- -- The key tag field is represented as an unsigned decimal integer. -- -- The algorithm field is represented as an unsigned decimal integer or -- a mnemonic symbol as listed in [12]. -- -- The certificate/CRL portion is represented in base 64 [16] and may be -- divided into any number of white-space-separated substrings, down to -- single base-64 digits, which are concatenated to obtain the full -- signature. These substrings can span lines using the standard -- parenthesis. -- -- Note that the certificate/CRL portion may have internal sub-fields, -- but these do not appear in the master file representation. For -- example, with type 254, there will be an OID size, an OID, and then -- the certificate/CRL proper. However, only a single logical base-64 -- string will appear in the text representation. -- --2.3. X.509 OIDs -- -- OIDs have been defined in connection with the X.500 directory for -- user certificates, certification authority certificates, revocations -- of certification authority, and revocations of user certificates. -- The following table lists the OIDs, their BER encoding, and their -- length-prefixed hex format for use in CERT RRs: -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 6] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- id-at-userCertificate -- = { joint-iso-ccitt(2) ds(5) at(4) 36 } -- == 0x 03 55 04 24 -- id-at-cACertificate -- = { joint-iso-ccitt(2) ds(5) at(4) 37 } -- == 0x 03 55 04 25 -- id-at-authorityRevocationList -- = { joint-iso-ccitt(2) ds(5) at(4) 38 } -- == 0x 03 55 04 26 -- id-at-certificateRevocationList -- = { joint-iso-ccitt(2) ds(5) at(4) 39 } -- == 0x 03 55 04 27 -- --3. Appropriate Owner Names for CERT RRs -- -- It is recommended that certificate CERT RRs be stored under a domain -- name related to their subject, i.e., the name of the entity intended -- to control the private key corresponding to the public key being -- certified. It is recommended that certificate revocation list CERT -- RRs be stored under a domain name related to their issuer. -- -- Following some of the guidelines below may result in DNS names with -- characters that require DNS quoting as per Section 5.1 of RFC 1035 -- [2]. -- -- The choice of name under which CERT RRs are stored is important to -- clients that perform CERT queries. In some situations, the clients -- may not know all information about the CERT RR object it wishes to -- retrieve. For example, a client may not know the subject name of an -- X.509 certificate, or the email address of the owner of an OpenPGP -- key. Further, the client might only know the hostname of a service -- that uses X.509 certificates or the Key ID of an OpenPGP key. -- -- Therefore, two owner name guidelines are defined: content-based owner -- names and purpose-based owner names. A content-based owner name is -- derived from the content of the CERT RR data; for example, the -- Subject field in an X.509 certificate or the User ID field in OpenPGP -- keys. A purpose-based owner name is a name that a client retrieving -- CERT RRs ought to know already; for example, the host name of an -- X.509 protected service or the Key ID of an OpenPGP key. The -- content-based and purpose-based owner name may be the same; for -- example, when a client looks up a key based on the From: address of -- an incoming email. -- -- Implementations SHOULD use the purpose-based owner name guidelines -- described in this document and MAY use CNAME RRs at content-based -- owner names (or other names), pointing to the purpose-based owner -- name. -- -- -- --Josefsson Standards Track [Page 7] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- Note that this section describes an application-based mapping from -- the name space used in a certificate to the name space used by DNS. -- The DNS does not infer any relationship amongst CERT resource records -- based on similarities or differences of the DNS owner name(s) of CERT -- resource records. For example, if multiple labels are used when -- mapping from a CERT identifier to a domain name, then care must be -- taken in understanding wildcard record synthesis. -- --3.1. Content-Based X.509 CERT RR Names -- -- Some X.509 versions, such as the PKIX profile of X.509 [8], permit -- multiple names to be associated with subjects and issuers under -- "Subject Alternative Name" and "Issuer Alternative Name". For -- example, the PKIX profile has such Alternate Names with an ASN.1 -- specification as follows: -- -- GeneralName ::= CHOICE { -- otherName [0] OtherName, -- rfc822Name [1] IA5String, -- dNSName [2] IA5String, -- x400Address [3] ORAddress, -- directoryName [4] Name, -- ediPartyName [5] EDIPartyName, -- uniformResourceIdentifier [6] IA5String, -- iPAddress [7] OCTET STRING, -- registeredID [8] OBJECT IDENTIFIER } -- -- The recommended locations of CERT storage are as follows, in priority -- order: -- -- 1. If a domain name is included in the identification in the -- certificate or CRL, that ought to be used. -- 2. If a domain name is not included but an IP address is included, -- then the translation of that IP address into the appropriate -- inverse domain name ought to be used. -- 3. If neither of the above is used, but a URI containing a domain -- name is present, that domain name ought to be used. -- 4. If none of the above is included but a character string name is -- included, then it ought to be treated as described below for -- OpenPGP names. -- 5. If none of the above apply, then the distinguished name (DN) -- ought to be mapped into a domain name as specified in [4]. -- -- Example 1: An X.509v3 certificate is issued to /CN=John Doe /DC=Doe/ -- DC=com/DC=xy/O=Doe Inc/C=XY/ with Subject Alternative Names of (a) -- string "John (the Man) Doe", (b) domain name john-doe.com, and (c) -- URI . The storage locations -- recommended, in priority order, would be -- -- -- --Josefsson Standards Track [Page 8] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- 1. john-doe.com, -- 2. www.secure.john-doe.com, and -- 3. Doe.com.xy. -- -- Example 2: An X.509v3 certificate is issued to /CN=James Hacker/ -- L=Basingstoke/O=Widget Inc/C=GB/ with Subject Alternate names of (a) -- domain name widget.foo.example, (b) IPv4 address 10.251.13.201, and -- (c) string "James Hacker ". The -- storage locations recommended, in priority order, would be -- -- 1. widget.foo.example, -- 2. 201.13.251.10.in-addr.arpa, and -- 3. hacker.mail.widget.foo.example. -- --3.2. Purpose-Based X.509 CERT RR Names -- -- Due to the difficulty for clients that do not already possess a -- certificate to reconstruct the content-based owner name, -- purpose-based owner names are recommended in this section. -- Recommendations for purpose-based owner names vary per scenario. The -- following table summarizes the purpose-based X.509 CERT RR owner name -- guidelines for use with S/MIME [17], SSL/TLS [13], and IPsec [14]: -- -- Scenario Owner name -- ------------------ ---------------------------------------------- -- S/MIME Certificate Standard translation of an RFC 2822 email -- address. Example: An S/MIME certificate for -- "postmaster@example.org" will use a standard -- hostname translation of the owner name, -- "postmaster.example.org". -- -- TLS Certificate Hostname of the TLS server. -- -- IPsec Certificate Hostname of the IPsec machine and/or, for IPv4 -- or IPv6 addresses, the fully qualified domain -- name in the appropriate reverse domain. -- -- An alternate approach for IPsec is to store raw public keys [18]. -- --3.3. Content-Based OpenPGP CERT RR Names -- -- OpenPGP signed keys (certificates) use a general character string -- User ID [5]. However, it is recommended by OpenPGP that such names -- include the RFC 2822 [7] email address of the party, as in "Leslie -- Example ". If such a format is used, the CERT -- ought to be under the standard translation of the email address into -- -- -- -- -- --Josefsson Standards Track [Page 9] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- a domain name, which would be leslie.host.example in this case. If -- no RFC 2822 name can be extracted from the string name, no specific -- domain name is recommended. -- -- If a user has more than one email address, the CNAME type can be used -- to reduce the amount of data stored in the DNS. For example: -- -- $ORIGIN example.org. -- smith IN CERT PGP 0 0 -- john.smith IN CNAME smith -- js IN CNAME smith -- --3.4. Purpose-Based OpenPGP CERT RR Names -- -- Applications that receive an OpenPGP packet containing encrypted or -- signed data but do not know the email address of the sender will have -- difficulties constructing the correct owner name and cannot use the -- content-based owner name guidelines. However, these clients commonly -- know the key fingerprint or the Key ID. The key ID is found in -- OpenPGP packets, and the key fingerprint is commonly found in -- auxiliary data that may be available. In this case, use of an owner -- name identical to the key fingerprint and the key ID expressed in -- hexadecimal [16] is recommended. For example: -- -- $ORIGIN example.org. -- 0424D4EE81A0E3D119C6F835EDA21E94B565716F IN CERT PGP ... -- F835EDA21E94B565716F IN CERT PGP ... -- B565716F IN CERT PGP ... -- -- If the same key material is stored for several owner names, the use -- of CNAME may help avoid data duplication. Note that CNAME is not -- always applicable, because it maps one owner name to the other for -- all purposes, which may be sub-optimal when two keys with the same -- Key ID are stored. -- --3.5. Owner Names for IPKIX, ISPKI, IPGP, and IACPKIX -- -- These types are stored under the same owner names, both purpose- and -- content-based, as the PKIX, SPKI, PGP, and ACPKIX types. -- -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 10] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --4. Performance Considerations -- -- The Domain Name System (DNS) protocol was designed for small -- transfers, typically below 512 octets. While larger transfers will -- perform correctly and work is underway to make larger transfers more -- efficient, it is still advisable at this time that every reasonable -- effort be made to minimize the size of certificates stored within the -- DNS. Steps that can be taken may include using the fewest possible -- optional or extension fields and using short field values for -- necessary variable-length fields. -- -- The RDATA field in the DNS protocol may only hold data of size 65535 -- octets (64kb) or less. This means that each CERT RR MUST NOT contain -- more than 64kb of payload, even if the corresponding certificate or -- certificate revocation list is larger. This document addresses this -- by defining "indirect" data types for each normal type. -- -- Deploying CERT RRs to support digitally signed email changes the -- access patterns of DNS lookups from per-domain to per-user. If -- digitally signed email and a key/certificate lookup based on CERT RRs -- are deployed on a wide scale, this may lead to an increased DNS load, -- with potential performance and cache effectiveness consequences. -- Whether or not this load increase will be noticeable is not known. -- --5. Contributors -- -- The majority of this document is copied verbatim from RFC 2538, by -- Donald Eastlake 3rd and Olafur Gudmundsson. -- --6. Acknowledgements -- -- Thanks to David Shaw and Michael Graff for their contributions to -- earlier works that motivated, and served as inspiration for, this -- document. -- -- This document was improved by suggestions and comments from Olivier -- Dubuisson, Scott Hollenbeck, Russ Housley, Peter Koch, Olaf M. -- Kolkman, Ben Laurie, Edward Lewis, John Loughney, Allison Mankin, -- Douglas Otis, Marcos Sanz, Pekka Savola, Jason Sloderbeck, Samuel -- Weiler, and Florian Weimer. No doubt the list is incomplete. We -- apologize to anyone we left out. -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 11] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --7. Security Considerations -- -- By definition, certificates contain their own authenticating -- signatures. Thus, it is reasonable to store certificates in -- non-secure DNS zones or to retrieve certificates from DNS with DNS -- security checking not implemented or deferred for efficiency. The -- results may be trusted if the certificate chain is verified back to a -- known trusted key and this conforms with the user's security policy. -- -- Alternatively, if certificates are retrieved from a secure DNS zone -- with DNS security checking enabled and are verified by DNS security, -- the key within the retrieved certificate may be trusted without -- verifying the certificate chain if this conforms with the user's -- security policy. -- -- If an organization chooses to issue certificates for its employees, -- placing CERT RRs in the DNS by owner name, and if DNSSEC (with NSEC) -- is in use, it is possible for someone to enumerate all employees of -- the organization. This is usually not considered desirable, for the -- same reason that enterprise phone listings are not often publicly -- published and are even marked confidential. -- -- Using the URI type introduces another level of indirection that may -- open a new vulnerability. One method of securing that indirection is -- to include a hash of the certificate in the URI itself. -- -- If DNSSEC is used, then the non-existence of a CERT RR and, -- consequently, certificates or revocation lists can be securely -- asserted. Without DNSSEC, this is not possible. -- --8. IANA Considerations -- -- The IANA has created a new registry for CERT RR: certificate types. -- The initial contents of this registry is: -- -- Decimal Type Meaning Reference -- ------- ---- ------- --------- -- 0 Reserved RFC 4398 -- 1 PKIX X.509 as per PKIX RFC 4398 -- 2 SPKI SPKI certificate RFC 4398 -- 3 PGP OpenPGP packet RFC 4398 -- 4 IPKIX The URL of an X.509 data object RFC 4398 -- 5 ISPKI The URL of an SPKI certificate RFC 4398 -- 6 IPGP The fingerprint and URL RFC 4398 -- of an OpenPGP packet -- 7 ACPKIX Attribute Certificate RFC 4398 -- 8 IACPKIX The URL of an Attribute RFC 4398 -- Certificate -- -- -- --Josefsson Standards Track [Page 12] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- 9-252 Available for IANA assignment -- by IETF Standards action -- 253 URI URI private RFC 4398 -- 254 OID OID private RFC 4398 -- 255 Reserved RFC 4398 -- 256-65279 Available for IANA assignment -- by IETF Consensus -- 65280-65534 Experimental RFC 4398 -- 65535 Reserved RFC 4398 -- -- Certificate types 0x0000 through 0x00FF and 0xFF00 through 0xFFFF can -- only be assigned by an IETF standards action [6]. This document -- assigns 0x0001 through 0x0008 and 0x00FD and 0x00FE. Certificate -- types 0x0100 through 0xFEFF are assigned through IETF Consensus [6] -- based on RFC documentation of the certificate type. The availability -- of private types under 0x00FD and 0x00FE ought to satisfy most -- requirements for proprietary or private types. -- -- The CERT RR reuses the DNS Security Algorithm Numbers registry. In -- particular, the CERT RR requires that algorithm number 0 remain -- reserved, as described in Section 2. The IANA will reference the -- CERT RR as a user of this registry and value 0, in particular. -- --9. Changes since RFC 2538 -- -- 1. Editorial changes to conform with new document requirements, -- including splitting reference section into two parts and -- updating the references to point at latest versions, and to add -- some additional references. -- 2. Improve terminology. For example replace "PGP" with "OpenPGP", -- to align with RFC 2440. -- 3. In Section 2.1, clarify that OpenPGP public key data are binary, -- not the ASCII armored format, and reference 10.1 in RFC 2440 on -- how to deal with OpenPGP keys, and acknowledge that -- implementations may handle additional packet types. -- 4. Clarify that integers in the representation format are decimal. -- 5. Replace KEY/SIG with DNSKEY/RRSIG etc, to align with DNSSECbis -- terminology. Improve reference for Key Tag Algorithm -- calculations. -- 6. Add examples that suggest use of CNAME to reduce bandwidth. -- 7. In Section 3, appended the last paragraphs that discuss -- "content-based" vs "purpose-based" owner names. Add Section 3.2 -- for purpose-based X.509 CERT owner names, and Section 3.4 for -- purpose-based OpenPGP CERT owner names. -- 8. Added size considerations. -- 9. The SPKI types has been reserved, until RFC 2692/2693 is moved -- from the experimental status. -- 10. Added indirect types IPKIX, ISPKI, IPGP, and IACPKIX. -- -- -- --Josefsson Standards Track [Page 13] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- -- 11. An IANA registry of CERT type values was created. -- --10. References -- --10.1. Normative References -- -- [1] Mockapetris, P., "Domain names - concepts and facilities", -- STD 13, RFC 1034, November 1987. -- -- [2] Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- -- [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- [4] Kille, S., Wahl, M., Grimstad, A., Huber, R., and S. Sataluri, -- "Using Domains in LDAP/X.500 Distinguished Names", RFC 2247, -- January 1998. -- -- [5] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, -- "OpenPGP Message Format", RFC 2440, November 1998. -- -- [6] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA -- Considerations Section in RFCs", BCP 26, RFC 2434, -- October 1998. -- -- [7] Resnick, P., "Internet Message Format", RFC 2822, April 2001. -- -- [8] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet X.509 -- Public Key Infrastructure Certificate and Certificate -- Revocation List (CRL) Profile", RFC 3280, April 2002. -- -- [9] Farrell, S. and R. Housley, "An Internet Attribute Certificate -- Profile for Authorization", RFC 3281, April 2002. -- -- [10] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform -- Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, -- January 2005. -- -- [11] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, -- March 2005. -- -- [12] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- -- -- -- --Josefsson Standards Track [Page 14] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --10.2. Informative References -- -- [13] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", -- RFC 2246, January 1999. -- -- [14] Kent, S. and K. Seo, "Security Architecture for the Internet -- Protocol", RFC 4301, December 2005. -- -- [15] Ellison, C., Frantz, B., Lampson, B., Rivest, R., Thomas, B., -- and T. Ylonen, "SPKI Certificate Theory", RFC 2693, -- September 1999. -- -- [16] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", -- RFC 3548, July 2003. -- -- [17] Ramsdell, B., "Secure/Multipurpose Internet Mail Extensions -- (S/MIME) Version 3.1 Message Specification", RFC 3851, -- July 2004. -- -- [18] Richardson, M., "A Method for Storing IPsec Keying Material in -- DNS", RFC 4025, March 2005. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 15] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --Appendix A. Copying Conditions -- -- Regarding the portion of this document that was written by Simon -- Josefsson ("the author", for the remainder of this section), the -- author makes no guarantees and is not responsible for any damage -- resulting from its use. The author grants irrevocable permission to -- anyone to use, modify, and distribute it in any way that does not -- diminish the rights of anyone else to use, modify, and distribute it, -- provided that redistributed derivative works do not contain -- misleading author or version information. Derivative works need not -- be licensed under similar terms. -- --Author's Address -- -- Simon Josefsson -- -- EMail: simon@josefsson.org -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Josefsson Standards Track [Page 16] -- --RFC 4398 Storing Certificates in the DNS February 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Josefsson Standards Track [Page 17] -- diff --cc doc/rfc/rfc4408.txt index bc1b3f539ca,bc1b3f539ca..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4408.txt +++ /dev/null @@@ -1,2691 -1,2691 +1,0 @@@ -- -- -- -- -- -- --Network Working Group M. Wong --Request for Comments: 4408 W. Schlitt --Category: Experimental April 2006 -- -- -- Sender Policy Framework (SPF) for -- Authorizing Use of Domains in E-Mail, Version 1 -- --Status of This Memo -- -- This memo defines an Experimental Protocol for the Internet -- community. It does not specify an Internet standard of any kind. -- Discussion and suggestions for improvement are requested. -- Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --IESG Note -- -- The following documents (RFC 4405, RFC 4406, RFC 4407, and RFC 4408) -- are published simultaneously as Experimental RFCs, although there is -- no general technical consensus and efforts to reconcile the two -- approaches have failed. As such, these documents have not received -- full IETF review and are published "AS-IS" to document the different -- approaches as they were considered in the MARID working group. -- -- The IESG takes no position about which approach is to be preferred -- and cautions the reader that there are serious open issues for each -- approach and concerns about using them in tandem. The IESG believes -- that documenting the different approaches does less harm than not -- documenting them. -- -- Note that the Sender ID experiment may use DNS records that may have -- been created for the current SPF experiment or earlier versions in -- this set of experiments. Depending on the content of the record, -- this may mean that Sender-ID heuristics would be applied incorrectly -- to a message. Depending on the actions associated by the recipient -- with those heuristics, the message may not be delivered or may be -- discarded on receipt. -- -- Participants relying on Sender ID experiment DNS records are warned -- that they may lose valid messages in this set of circumstances. -- aParticipants publishing SPF experiment DNS records should consider -- the advice given in section 3.4 of RFC 4406 and may wish to publish -- both v=spf1 and spf2.0 records to avoid the conflict. -- -- -- -- --Wong & Schlitt Experimental [Page 1] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Participants in the Sender-ID experiment need to be aware that the -- way Resent-* header fields are used will result in failure to receive -- legitimate email when interacting with standards-compliant systems -- (specifically automatic forwarders which comply with the standards by -- not adding Resent-* headers, and systems which comply with RFC 822 -- but have not yet implemented RFC 2822 Resent-* semantics). It would -- be inappropriate to advance Sender-ID on the standards track without -- resolving this interoperability problem. -- -- The community is invited to observe the success or failure of the two -- approaches during the two years following publication, in order that -- a community consensus can be reached in the future. -- --Abstract -- -- E-mail on the Internet can be forged in a number of ways. In -- particular, existing protocols place no restriction on what a sending -- host can use as the reverse-path of a message or the domain given on -- the SMTP HELO/EHLO commands. This document describes version 1 of -- the Sender Policy Framework (SPF) protocol, whereby a domain may -- explicitly authorize the hosts that are allowed to use its domain -- name, and a receiving host may check such authorization. -- --Table of Contents -- -- 1. Introduction ....................................................4 -- 1.1. Protocol Status ............................................4 -- 1.2. Terminology ................................................5 -- 2. Operation .......................................................5 -- 2.1. The HELO Identity ..........................................5 -- 2.2. The MAIL FROM Identity .....................................5 -- 2.3. Publishing Authorization ...................................6 -- 2.4. Checking Authorization .....................................6 -- 2.5. Interpreting the Result ....................................7 -- 2.5.1. None ................................................8 -- 2.5.2. Neutral .............................................8 -- 2.5.3. Pass ................................................8 -- 2.5.4. Fail ................................................8 -- 2.5.5. SoftFail ............................................9 -- 2.5.6. TempError ...........................................9 -- 2.5.7. PermError ...........................................9 -- 3. SPF Records .....................................................9 -- 3.1. Publishing ................................................10 -- 3.1.1. DNS Resource Record Types ..........................10 -- 3.1.2. Multiple DNS Records ...............................11 -- 3.1.3. Multiple Strings in a Single DNS record ............11 -- 3.1.4. Record Size ........................................11 -- 3.1.5. Wildcard Records ...................................11 -- -- -- --Wong & Schlitt Experimental [Page 2] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- 4. The check_host() Function ......................................12 -- 4.1. Arguments .................................................12 -- 4.2. Results ...................................................13 -- 4.3. Initial Processing ........................................13 -- 4.4. Record Lookup .............................................13 -- 4.5. Selecting Records .........................................13 -- 4.6. Record Evaluation .........................................14 -- 4.6.1. Term Evaluation ....................................14 -- 4.6.2. Mechanisms .........................................15 -- 4.6.3. Modifiers ..........................................15 -- 4.7. Default Result ............................................16 -- 4.8. Domain Specification ......................................16 -- 5. Mechanism Definitions ..........................................16 -- 5.1. "all" .....................................................17 -- 5.2. "include" .................................................18 -- 5.3. "a" .......................................................19 -- 5.4. "mx" ......................................................20 -- 5.5. "ptr" .....................................................20 -- 5.6. "ip4" and "ip6" ...........................................21 -- 5.7. "exists" ..................................................22 -- 6. Modifier Definitions ...........................................22 -- 6.1. redirect: Redirected Query ................................23 -- 6.2. exp: Explanation ..........................................23 -- 7. The Received-SPF Header Field ..................................25 -- 8. Macros .........................................................27 -- 8.1. Macro Definitions .........................................27 -- 8.2. Expansion Examples ........................................30 -- 9. Implications ...................................................31 -- 9.1. Sending Domains ...........................................31 -- 9.2. Mailing Lists .............................................32 -- 9.3. Forwarding Services and Aliases ...........................32 -- 9.4. Mail Services .............................................34 -- 9.5. MTA Relays ................................................34 -- 10. Security Considerations .......................................35 -- 10.1. Processing Limits ........................................35 -- 10.2. SPF-Authorized E-Mail May Contain Other False -- Identities ...............................................37 -- 10.3. Spoofed DNS and IP Data ..................................37 -- 10.4. Cross-User Forgery .......................................37 -- 10.5. Untrusted Information Sources ............................38 -- 10.6. Privacy Exposure .........................................38 -- 11. Contributors and Acknowledgements .............................38 -- 12. IANA Considerations ...........................................39 -- 12.1. The SPF DNS Record Type ..................................39 -- 12.2. The Received-SPF Mail Header Field .......................39 -- 13. References ....................................................39 -- 13.1. Normative References .....................................39 -- 13.2. Informative References ...................................40 -- -- -- --Wong & Schlitt Experimental [Page 3] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Appendix A. Collected ABNF .......................................42 -- Appendix B. Extended Examples ....................................44 -- B.1. Simple Examples ..........................................44 -- B.2. Multiple Domain Example ..................................45 -- B.3. DNSBL Style Example ......................................46 -- B.4. Multiple Requirements Example ............................46 -- --1. Introduction -- -- The current E-Mail infrastructure has the property that any host -- injecting mail into the mail system can identify itself as any domain -- name it wants. Hosts can do this at a variety of levels: in -- particular, the session, the envelope, and the mail headers. -- Although this feature is desirable in some circumstances, it is a -- major obstacle to reducing Unsolicited Bulk E-Mail (UBE, aka spam). -- Furthermore, many domain name holders are understandably concerned -- about the ease with which other entities may make use of their domain -- names, often with malicious intent. -- -- This document defines a protocol by which domain owners may authorize -- hosts to use their domain name in the "MAIL FROM" or "HELO" identity. -- Compliant domain holders publish Sender Policy Framework (SPF) -- records specifying which hosts are permitted to use their names, and -- compliant mail receivers use the published SPF records to test the -- authorization of sending Mail Transfer Agents (MTAs) using a given -- "HELO" or "MAIL FROM" identity during a mail transaction. -- -- An additional benefit to mail receivers is that after the use of an -- identity is verified, local policy decisions about the mail can be -- made based on the sender's domain, rather than the host's IP address. -- This is advantageous because reputation of domain names is likely to -- be more accurate than reputation of host IP addresses. Furthermore, -- if a claimed identity fails verification, local policy can take -- stronger action against such E-Mail, such as rejecting it. -- --1.1. Protocol Status -- -- SPF has been in development since the summer of 2003 and has seen -- deployment beyond the developers beginning in December 2003. The -- design of SPF slowly evolved until the spring of 2004 and has since -- stabilized. There have been quite a number of forms of SPF, some -- written up as documents, some submitted as Internet Drafts, and many -- discussed and debated in development forums. -- -- The goal of this document is to clearly document the protocol defined -- by earlier draft specifications of SPF as used in existing -- implementations. This conception of SPF is sometimes called "SPF -- Classic". It is understood that particular implementations and -- -- -- --Wong & Schlitt Experimental [Page 4] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- deployments may differ from, and build upon, this work. It is hoped -- that we have nonetheless captured the common understanding of SPF -- version 1. -- --1.2. Terminology -- -- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in [RFC2119]. -- -- This document is concerned with the portion of a mail message -- commonly called "envelope sender", "return path", "reverse path", -- "bounce address", "2821 FROM", or "MAIL FROM". Since these terms are -- either not well defined or often used casually, this document defines -- the "MAIL FROM" identity in Section 2.2. Note that other terms that -- may superficially look like the common terms, such as "reverse-path", -- are used only with the defined meanings from normative documents. -- --2. Operation -- --2.1. The HELO Identity -- -- The "HELO" identity derives from either the SMTP HELO or EHLO command -- (see [RFC2821]). These commands supply the SMTP client (sending -- host) for the SMTP session. Note that requirements for the domain -- presented in the EHLO or HELO command are not always clear to the -- sending party, and SPF clients must be prepared for the "HELO" -- identity to be malformed or an IP address literal. At the time of -- this writing, many legitimate E-Mails are delivered with invalid HELO -- domains. -- -- It is RECOMMENDED that SPF clients not only check the "MAIL FROM" -- identity, but also separately check the "HELO" identity by applying -- the check_host() function (Section 4) to the "HELO" identity as the -- . -- --2.2. The MAIL FROM Identity -- -- The "MAIL FROM" identity derives from the SMTP MAIL command (see -- [RFC2821]). This command supplies the "reverse-path" for a message, -- which generally consists of the sender mailbox, and is the mailbox to -- which notification messages are to be sent if there are problems -- delivering the message. -- -- [RFC2821] allows the reverse-path to be null (see Section 4.5.5 in -- RFC 2821). In this case, there is no explicit sender mailbox, and -- such a message can be assumed to be a notification message from the -- mail system itself. When the reverse-path is null, this document -- -- -- --Wong & Schlitt Experimental [Page 5] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- defines the "MAIL FROM" identity to be the mailbox composed of the -- localpart "postmaster" and the "HELO" identity (which may or may not -- have been checked separately before). -- -- SPF clients MUST check the "MAIL FROM" identity. SPF clients check -- the "MAIL FROM" identity by applying the check_host() function to the -- "MAIL FROM" identity as the . -- --2.3. Publishing Authorization -- -- An SPF-compliant domain MUST publish a valid SPF record as described -- in Section 3. This record authorizes the use of the domain name in -- the "HELO" and "MAIL FROM" identities by the MTAs it specifies. -- -- If domain owners choose to publish SPF records, it is RECOMMENDED -- that they end in "-all", or redirect to other records that do, so -- that a definitive determination of authorization can be made. -- -- Domain holders may publish SPF records that explicitly authorize no -- hosts if mail should never originate using that domain. -- -- When changing SPF records, care must be taken to ensure that there is -- a transition period so that the old policy remains valid until all -- legitimate E-Mail has been checked. -- --2.4. Checking Authorization -- -- A mail receiver can perform a set of SPF checks for each mail message -- it receives. An SPF check tests the authorization of a client host -- to emit mail with a given identity. Typically, such checks are done -- by a receiving MTA, but can be performed elsewhere in the mail -- processing chain so long as the required information is available and -- reliable. At least the "MAIL FROM" identity MUST be checked, but it -- is RECOMMENDED that the "HELO" identity also be checked beforehand. -- -- Without explicit approval of the domain owner, checking other -- identities against SPF version 1 records is NOT RECOMMENDED because -- there are cases that are known to give incorrect results. For -- example, almost all mailing lists rewrite the "MAIL FROM" identity -- (see Section 9.2), but some do not change any other identities in the -- message. The scenario described in Section 9.3, sub-section 1.2, is -- another example. Documents that define other identities should -- define the method for explicit approval. -- -- It is possible that mail receivers will use the SPF check as part of -- a larger set of tests on incoming mail. The results of other tests -- may influence whether or not a particular SPF check is performed. -- For example, finding the sending host's IP address on a local white -- -- -- --Wong & Schlitt Experimental [Page 6] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- list may cause all other tests to be skipped and all mail from that -- host to be accepted. -- -- When a mail receiver decides to perform an SPF check, it MUST use a -- correctly-implemented check_host() function (Section 4) evaluated -- with the correct parameters. Although the test as a whole is -- optional, once it has been decided to perform a test it must be -- performed as specified so that the correct semantics are preserved -- between publisher and receiver. -- -- To make the test, the mail receiver MUST evaluate the check_host() -- function with the arguments set as follows: -- -- - the IP address of the SMTP client that is emitting the -- mail, either IPv4 or IPv6. -- -- - the domain portion of the "MAIL FROM" or "HELO" identity. -- -- - the "MAIL FROM" or "HELO" identity. -- -- Note that the argument may not be a well-formed domain name. -- For example, if the reverse-path was null, then the EHLO/HELO domain -- is used, with its associated problems (see Section 2.1). In these -- cases, check_host() is defined in Section 4.3 to return a "None" -- result. -- -- Although invalid, malformed, or non-existent domains cause SPF checks -- to return "None" because no SPF record can be found, it has long been -- the policy of many MTAs to reject E-Mail from such domains, -- especially in the case of invalid "MAIL FROM". In order to prevent -- the circumvention of SPF records, rejecting E-Mail from invalid -- domains should be considered. -- -- Implementations must take care to correctly extract the from -- the data given with the SMTP MAIL FROM command as many MTAs will -- still accept such things as source routes (see [RFC2821], Appendix -- C), the %-hack (see [RFC1123]), and bang paths (see [RFC1983]). -- These archaic features have been maliciously used to bypass security -- systems. -- --2.5. Interpreting the Result -- -- This section describes how software that performs the authorization -- should interpret the results of the check_host() function. The -- authorization check SHOULD be performed during the processing of the -- SMTP transaction that sends the mail. This allows errors to be -- returned directly to the sending MTA by way of SMTP replies. -- -- -- -- --Wong & Schlitt Experimental [Page 7] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Performing the authorization after the SMTP transaction has finished -- may cause problems, such as the following: (1) It may be difficult to -- accurately extract the required information from potentially -- deceptive headers; (2) legitimate E-Mail may fail because the -- sender's policy may have since changed. -- -- Generating non-delivery notifications to forged identities that have -- failed the authorization check is generally abusive and against the -- explicit wishes of the identity owner. -- --2.5.1. None -- -- A result of "None" means that no records were published by the domain -- or that no checkable sender domain could be determined from the given -- identity. The checking software cannot ascertain whether or not the -- client host is authorized. -- --2.5.2. Neutral -- -- The domain owner has explicitly stated that he cannot or does not -- want to assert whether or not the IP address is authorized. A -- "Neutral" result MUST be treated exactly like the "None" result; the -- distinction exists only for informational purposes. Treating -- "Neutral" more harshly than "None" would discourage domain owners -- from testing the use of SPF records (see Section 9.1). -- --2.5.3. Pass -- -- A "Pass" result means that the client is authorized to inject mail -- with the given identity. The domain can now, in the sense of -- reputation, be considered responsible for sending the message. -- Further policy checks can now proceed with confidence in the -- legitimate use of the identity. -- --2.5.4. Fail -- -- A "Fail" result is an explicit statement that the client is not -- authorized to use the domain in the given identity. The checking -- software can choose to mark the mail based on this or to reject the -- mail outright. -- -- If the checking software chooses to reject the mail during the SMTP -- transaction, then it SHOULD use an SMTP reply code of 550 (see -- [RFC2821]) and, if supported, the 5.7.1 Delivery Status Notification -- (DSN) code (see [RFC3464]), in addition to an appropriate reply text. -- The check_host() function may return either a default explanation -- string or one from the domain that published the SPF records (see -- Section 6.2). If the information does not originate with the -- -- -- --Wong & Schlitt Experimental [Page 8] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- checking software, it should be made clear that the text is provided -- by the sender's domain. For example: -- -- 550-5.7.1 SPF MAIL FROM check failed: -- 550-5.7.1 The domain example.com explains: -- 550 5.7.1 Please see http://www.example.com/mailpolicy.html -- --2.5.5. SoftFail -- -- A "SoftFail" result should be treated as somewhere between a "Fail" -- and a "Neutral". The domain believes the host is not authorized but -- is not willing to make that strong of a statement. Receiving -- software SHOULD NOT reject the message based solely on this result, -- but MAY subject the message to closer scrutiny than normal. -- -- The domain owner wants to discourage the use of this host and thus -- desires limited feedback when a "SoftFail" result occurs. For -- example, the recipient's Mail User Agent (MUA) could highlight the -- "SoftFail" status, or the receiving MTA could give the sender a -- message using a technique called "greylisting" whereby the MTA can -- issue an SMTP reply code of 451 (4.3.0 DSN code) with a note the -- first time the message is received, but accept it the second time. -- --2.5.6. TempError -- -- A "TempError" result means that the SPF client encountered a -- transient error while performing the check. Checking software can -- choose to accept or temporarily reject the message. If the message -- is rejected during the SMTP transaction for this reason, the software -- SHOULD use an SMTP reply code of 451 and, if supported, the 4.4.3 DSN -- code. -- --2.5.7. PermError -- -- A "PermError" result means that the domain's published records could -- not be correctly interpreted. This signals an error condition that -- requires manual intervention to be resolved, as opposed to the -- TempError result. Be aware that if the domain owner uses macros -- (Section 8), it is possible that this result is due to the checked -- identities having an unexpected format. -- --3. SPF Records -- -- An SPF record is a DNS Resource Record (RR) that declares which hosts -- are, and are not, authorized to use a domain name for the "HELO" and -- "MAIL FROM" identities. Loosely, the record partitions all hosts -- into permitted and not-permitted sets (though some hosts might fall -- into neither category). -- -- -- --Wong & Schlitt Experimental [Page 9] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- The SPF record is a single string of text. An example record is the -- following: -- -- v=spf1 +mx a:colo.example.com/28 -all -- -- This record has a version of "spf1" and three directives: "+mx", -- "a:colo.example.com/28" (the + is implied), and "-all". -- --3.1. Publishing -- -- Domain owners wishing to be SPF compliant must publish SPF records -- for the hosts that are used in the "MAIL FROM" and "HELO" identities. -- The SPF records are placed in the DNS tree at the host name it -- pertains to, not a subdomain under it, such as is done with SRV -- records. This is the same whether the TXT or SPF RR type (see -- Section 3.1.1) is used. -- -- The example above in Section 3 might be published via these lines in -- a domain zone file: -- -- example.com. TXT "v=spf1 +mx a:colo.example.com/28 -all" -- smtp-out.example.com. TXT "v=spf1 a -all" -- -- When publishing via TXT records, beware of other TXT records -- published there for other purposes. They may cause problems with -- size limits (see Section 3.1.4). -- --3.1.1. DNS Resource Record Types -- -- This document defines a new DNS RR of type SPF, code 99. The format -- of this type is identical to the TXT RR [RFC1035]. For either type, -- the character content of the record is encoded as [US-ASCII]. -- -- It is recognized that the current practice (using a TXT record) is -- not optimal, but it is necessary because there are a number of DNS -- server and resolver implementations in common use that cannot handle -- the new RR type. The two-record-type scheme provides a forward path -- to the better solution of using an RR type reserved for this purpose. -- -- An SPF-compliant domain name SHOULD have SPF records of both RR -- types. A compliant domain name MUST have a record of at least one -- type. If a domain has records of both types, they MUST have -- identical content. For example, instead of publishing just one -- record as in Section 3.1 above, it is better to publish: -- -- example.com. IN TXT "v=spf1 +mx a:colo.example.com/28 -all" -- example.com. IN SPF "v=spf1 +mx a:colo.example.com/28 -all" -- -- -- -- --Wong & Schlitt Experimental [Page 10] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Example RRs in this document are shown with the TXT record type; -- however, they could be published with the SPF type or with both -- types. -- --3.1.2. Multiple DNS Records -- -- A domain name MUST NOT have multiple records that would cause an -- authorization check to select more than one record. See Section 4.5 -- for the selection rules. -- --3.1.3. Multiple Strings in a Single DNS record -- -- As defined in [RFC1035] sections 3.3.14 and 3.3, a single text DNS -- record (either TXT or SPF RR types) can be composed of more than one -- string. If a published record contains multiple strings, then the -- record MUST be treated as if those strings are concatenated together -- without adding spaces. For example: -- -- IN TXT "v=spf1 .... first" "second string..." -- -- MUST be treated as equivalent to -- -- IN TXT "v=spf1 .... firstsecond string..." -- -- SPF or TXT records containing multiple strings are useful in -- constructing records that would exceed the 255-byte maximum length of -- a string within a single TXT or SPF RR record. -- --3.1.4. Record Size -- -- The published SPF record for a given domain name SHOULD remain small -- enough that the results of a query for it will fit within 512 octets. -- This will keep even older DNS implementations from falling over to -- TCP. Since the answer size is dependent on many things outside the -- scope of this document, it is only possible to give this guideline: -- If the combined length of the DNS name and the text of all the -- records of a given type (TXT or SPF) is under 450 characters, then -- DNS answers should fit in UDP packets. Note that when computing the -- sizes for queries of the TXT format, one must take into account any -- other TXT records published at the domain name. Records that are too -- long to fit in a single UDP packet MAY be silently ignored by SPF -- clients. -- --3.1.5. Wildcard Records -- -- Use of wildcard records for publishing is not recommended. Care must -- be taken if wildcard records are used. If a domain publishes -- wildcard MX records, it may want to publish wildcard declarations, -- -- -- --Wong & Schlitt Experimental [Page 11] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- subject to the same requirements and problems. In particular, the -- declaration must be repeated for any host that has any RR records at -- all, and for subdomains thereof. For example, the example given in -- [RFC1034], Section 4.3.3, could be extended with the following: -- -- X.COM. MX 10 A.X.COM -- X.COM. TXT "v=spf1 a:A.X.COM -all" -- -- *.X.COM. MX 10 A.X.COM -- *.X.COM. TXT "v=spf1 a:A.X.COM -all" -- -- A.X.COM. A 1.2.3.4 -- A.X.COM. MX 10 A.X.COM -- A.X.COM. TXT "v=spf1 a:A.X.COM -all" -- -- *.A.X.COM. MX 10 A.X.COM -- *.A.X.COM. TXT "v=spf1 a:A.X.COM -all" -- -- Notice that SPF records must be repeated twice for every name within -- the domain: once for the name, and once with a wildcard to cover the -- tree under the name. -- -- Use of wildcards is discouraged in general as they cause every name -- under the domain to exist and queries against arbitrary names will -- never return RCODE 3 (Name Error). -- --4. The check_host() Function -- -- The check_host() function fetches SPF records, parses them, and -- interprets them to determine whether a particular host is or is not -- permitted to send mail with a given identity. Mail receivers that -- perform this check MUST correctly evaluate the check_host() function -- as described here. -- -- Implementations MAY use a different algorithm than the canonical -- algorithm defined here, so long as the results are the same in all -- cases. -- --4.1. Arguments -- -- The check_host() function takes these arguments: -- -- - the IP address of the SMTP client that is emitting the -- mail, either IPv4 or IPv6. -- -- - the domain that provides the sought-after authorization -- information; initially, the domain portion of the "MAIL -- FROM" or "HELO" identity. -- -- -- --Wong & Schlitt Experimental [Page 12] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- - the "MAIL FROM" or "HELO" identity. -- -- The domain portion of will usually be the same as the -- argument when check_host() is initially evaluated. However, -- this will generally not be true for recursive evaluations (see -- Section 5.2 below). -- -- Actual implementations of the check_host() function may need -- additional arguments. -- --4.2. Results -- -- The function check_host() can return one of several results described -- in Section 2.5. Based on the result, the action to be taken is -- determined by the local policies of the receiver. -- --4.3. Initial Processing -- -- If the is malformed (label longer than 63 characters, zero- -- length label not at the end, etc.) or is not a fully qualified domain -- name, or if the DNS lookup returns "domain does not exist" (RCODE 3), -- check_host() immediately returns the result "None". -- -- If the has no localpart, substitute the string "postmaster" -- for the localpart. -- --4.4. Record Lookup -- -- In accordance with how the records are published (see Section 3.1 -- above), a DNS query needs to be made for the name, querying -- for either RR type TXT, SPF, or both. If both SPF and TXT RRs are -- looked up, the queries MAY be done in parallel. -- -- If all DNS lookups that are made return a server failure (RCODE 2), -- or other error (RCODE other than 0 or 3), or time out, then -- check_host() exits immediately with the result "TempError". -- --4.5. Selecting Records -- -- Records begin with a version section: -- -- record = version terms *SP -- version = "v=spf1" -- -- Starting with the set of records that were returned by the lookup, -- record selection proceeds in two steps: -- -- -- -- -- --Wong & Schlitt Experimental [Page 13] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- 1. Records that do not begin with a version section of exactly -- "v=spf1" are discarded. Note that the version section is -- terminated either by an SP character or the end of the record. A -- record with a version section of "v=spf10" does not match and must -- be discarded. -- -- 2. If any records of type SPF are in the set, then all records of -- type TXT are discarded. -- -- After the above steps, there should be exactly one record remaining -- and evaluation can proceed. If there are two or more records -- remaining, then check_host() exits immediately with the result of -- "PermError". -- -- If no matching records are returned, an SPF client MUST assume that -- the domain makes no SPF declarations. SPF processing MUST stop and -- return "None". -- --4.6. Record Evaluation -- -- After one SPF record has been selected, the check_host() function -- parses and interprets it to find a result for the current test. If -- there are any syntax errors, check_host() returns immediately with -- the result "PermError". -- -- Implementations MAY choose to parse the entire record first and -- return "PermError" if the record is not syntactically well formed. -- However, in all cases, any syntax errors anywhere in the record MUST -- be detected. -- --4.6.1. Term Evaluation -- -- There are two types of terms: mechanisms and modifiers. A record -- contains an ordered list of these as specified in the following -- Augmented Backus-Naur Form (ABNF). -- -- terms = *( 1*SP ( directive / modifier ) ) -- -- directive = [ qualifier ] mechanism -- qualifier = "+" / "-" / "?" / "~" -- mechanism = ( all / include -- / A / MX / PTR / IP4 / IP6 / exists ) -- modifier = redirect / explanation / unknown-modifier -- unknown-modifier = name "=" macro-string -- -- name = ALPHA *( ALPHA / DIGIT / "-" / "_" / "." ) -- -- Most mechanisms allow a ":" or "/" character after the name. -- -- -- --Wong & Schlitt Experimental [Page 14] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Modifiers always contain an equals ('=') character immediately after -- the name, and before any ":" or "/" characters that may be part of -- the macro-string. -- -- Terms that do not contain any of "=", ":", or "/" are mechanisms, as -- defined in Section 5. -- -- As per the definition of the ABNF notation in [RFC4234], mechanism -- and modifier names are case-insensitive. -- --4.6.2. Mechanisms -- -- Each mechanism is considered in turn from left to right. If there -- are no more mechanisms, the result is specified in Section 4.7. -- -- When a mechanism is evaluated, one of three things can happen: it can -- match, not match, or throw an exception. -- -- If it matches, processing ends and the qualifier value is returned as -- the result of that record. If it does not match, processing -- continues with the next mechanism. If it throws an exception, -- mechanism processing ends and the exception value is returned. -- -- The possible qualifiers, and the results they return are as follows: -- -- "+" Pass -- "-" Fail -- "~" SoftFail -- "?" Neutral -- -- The qualifier is optional and defaults to "+". -- -- When a mechanism matches and the qualifier is "-", then a "Fail" -- result is returned and the explanation string is computed as -- described in Section 6.2. -- -- The specific mechanisms are described in Section 5. -- --4.6.3. Modifiers -- -- Modifiers are not mechanisms: they do not return match or not-match. -- Instead they provide additional information. Although modifiers do -- not directly affect the evaluation of the record, the "redirect" -- modifier has an effect after all the mechanisms have been evaluated. -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 15] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --4.7. Default Result -- -- If none of the mechanisms match and there is no "redirect" modifier, -- then the check_host() returns a result of "Neutral", just as if -- "?all" were specified as the last directive. If there is a -- "redirect" modifier, check_host() proceeds as defined in Section 6.1. -- -- Note that records SHOULD always use either a "redirect" modifier or -- an "all" mechanism to explicitly terminate processing. -- -- For example: -- -- v=spf1 +mx -all -- or -- v=spf1 +mx redirect=_spf.example.com -- --4.8. Domain Specification -- -- Several of these mechanisms and modifiers have a -- section. The string is macro expanded (see Section 8). -- The resulting string is the common presentation form of a fully- -- qualified DNS name: a series of labels separated by periods. This -- domain is called the in the rest of this document. -- -- Note: The result of the macro expansion is not subject to any further -- escaping. Hence, this facility cannot produce all characters that -- are legal in a DNS label (e.g., the control characters). However, -- this facility is powerful enough to express legal host names and -- common utility labels (such as "_spf") that are used in DNS. -- -- For several mechanisms, the is optional. If it is not -- provided, the is used as the . -- --5. Mechanism Definitions -- -- This section defines two types of mechanisms. -- -- Basic mechanisms contribute to the language framework. They do not -- specify a particular type of authorization scheme. -- -- all -- include -- -- Designated sender mechanisms are used to designate a set of -- addresses as being permitted or not permitted to use the for -- sending mail. -- -- -- -- -- --Wong & Schlitt Experimental [Page 16] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- a -- mx -- ptr -- ip4 -- ip6 -- exists -- -- The following conventions apply to all mechanisms that perform a -- comparison between and an IP address at any point: -- -- If no CIDR-length is given in the directive, then and the IP -- address are compared for equality. (Here, CIDR is Classless Inter- -- Domain Routing.) -- -- If a CIDR-length is specified, then only the specified number of -- high-order bits of and the IP address are compared for equality. -- -- When any mechanism fetches host addresses to compare with , when -- is an IPv4 address, A records are fetched, when is an IPv6 -- address, AAAA records are fetched. Even if the SMTP connection is -- via IPv6, an IPv4-mapped IPv6 IP address (see [RFC3513], Section -- 2.5.5) MUST still be considered an IPv4 address. -- -- Several mechanisms rely on information fetched from DNS. For these -- DNS queries, except where noted, if the DNS server returns an error -- (RCODE other than 0 or 3) or the query times out, the mechanism -- throws the exception "TempError". If the server returns "domain does -- not exist" (RCODE 3), then evaluation of the mechanism continues as -- if the server returned no error (RCODE 0) and zero answer records. -- --5.1. "all" -- -- all = "all" -- -- The "all" mechanism is a test that always matches. It is used as the -- rightmost mechanism in a record to provide an explicit default. -- -- For example: -- -- v=spf1 a mx -all -- -- Mechanisms after "all" will never be tested. Any "redirect" modifier -- (Section 6.1) has no effect when there is an "all" mechanism. -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 17] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --5.2. "include" -- -- include = "include" ":" domain-spec -- -- The "include" mechanism triggers a recursive evaluation of -- check_host(). The domain-spec is expanded as per Section 8. Then -- check_host() is evaluated with the resulting string as the . -- The and arguments remain the same as in the current -- evaluation of check_host(). -- -- In hindsight, the name "include" was poorly chosen. Only the -- evaluated result of the referenced SPF record is used, rather than -- acting as if the referenced SPF record was literally included in the -- first. For example, evaluating a "-all" directive in the referenced -- record does not terminate the overall processing and does not -- necessarily result in an overall "Fail". (Better names for this -- mechanism would have been "if-pass", "on-pass", etc.) -- -- The "include" mechanism makes it possible for one domain to designate -- multiple administratively-independent domains. For example, a vanity -- domain "example.net" might send mail using the servers of -- administratively-independent domains example.com and example.org. -- -- Example.net could say -- -- IN TXT "v=spf1 include:example.com include:example.org -all" -- -- This would direct check_host() to, in effect, check the records of -- example.com and example.org for a "Pass" result. Only if the host -- were not permitted for either of those domains would the result be -- "Fail". -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 18] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Whether this mechanism matches, does not match, or throws an -- exception depends on the result of the recursive evaluation of -- check_host(): -- -- +---------------------------------+---------------------------------+ -- | A recursive check_host() result | Causes the "include" mechanism | -- | of: | to: | -- +---------------------------------+---------------------------------+ -- | Pass | match | -- | | | -- | Fail | not match | -- | | | -- | SoftFail | not match | -- | | | -- | Neutral | not match | -- | | | -- | TempError | throw TempError | -- | | | -- | PermError | throw PermError | -- | | | -- | None | throw PermError | -- +---------------------------------+---------------------------------+ -- -- The "include" mechanism is intended for crossing administrative -- boundaries. Although it is possible to use includes to consolidate -- multiple domains that share the same set of designated hosts, domains -- are encouraged to use redirects where possible, and to minimize the -- number of includes within a single administrative domain. For -- example, if example.com and example.org were managed by the same -- entity, and if the permitted set of hosts for both domains was -- "mx:example.com", it would be possible for example.org to specify -- "include:example.com", but it would be preferable to specify -- "redirect=example.com" or even "mx:example.com". -- --5.3. "a" -- -- This mechanism matches if is one of the 's IP -- addresses. -- -- A = "a" [ ":" domain-spec ] [ dual-cidr-length ] -- -- An address lookup is done on the . The is compared -- to the returned address(es). If any address matches, the mechanism -- matches. -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 19] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --5.4. "mx" -- -- This mechanism matches if is one of the MX hosts for a domain -- name. -- -- MX = "mx" [ ":" domain-spec ] [ dual-cidr-length ] -- -- check_host() first performs an MX lookup on the . Then -- it performs an address lookup on each MX name returned. The is -- compared to each returned IP address. To prevent Denial of Service -- (DoS) attacks, more than 10 MX names MUST NOT be looked up during the -- evaluation of an "mx" mechanism (see Section 10). If any address -- matches, the mechanism matches. -- -- Note regarding implicit MXs: If the has no MX records, -- check_host() MUST NOT pretend the target is its single MX, and MUST -- NOT default to an A lookup on the directly. This -- behavior breaks with the legacy "implicit MX" rule. See [RFC2821], -- Section 5. If such behavior is desired, the publisher should specify -- an "a" directive. -- --5.5. "ptr" -- -- This mechanism tests whether the DNS reverse-mapping for exists -- and correctly points to a domain name within a particular domain. -- -- PTR = "ptr" [ ":" domain-spec ] -- -- First, the 's name is looked up using this procedure: perform a -- DNS reverse-mapping for , looking up the corresponding PTR record -- in "in-addr.arpa." if the address is an IPv4 one and in "ip6.arpa." -- if it is an IPv6 address. For each record returned, validate the -- domain name by looking up its IP address. To prevent DoS attacks, -- more than 10 PTR names MUST NOT be looked up during the evaluation of -- a "ptr" mechanism (see Section 10). If is among the returned IP -- addresses, then that domain name is validated. In pseudocode: -- -- sending-domain_names := ptr_lookup(sending-host_IP); if more than 10 -- sending-domain_names are found, use at most 10. for each name in -- (sending-domain_names) { -- IP_addresses := a_lookup(name); -- if the sending-domain_IP is one of the IP_addresses { -- validated-sending-domain_names += name; -- } } -- -- Check all validated domain names to see if they end in the -- domain. If any do, this mechanism matches. If no -- validated domain name can be found, or if none of the validated -- -- -- --Wong & Schlitt Experimental [Page 20] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- domain names end in the , this mechanism fails to match. -- If a DNS error occurs while doing the PTR RR lookup, then this -- mechanism fails to match. If a DNS error occurs while doing an A RR -- lookup, then that domain name is skipped and the search continues. -- -- Pseudocode: -- -- for each name in (validated-sending-domain_names) { -- if name ends in , return match. -- if name is , return match. -- } -- return no-match. -- -- This mechanism matches if the is either an ancestor of -- a validated domain name or if the and a validated -- domain name are the same. For example: "mail.example.com" is within -- the domain "example.com", but "mail.bad-example.com" is not. -- -- Note: Use of this mechanism is discouraged because it is slow, it is -- not as reliable as other mechanisms in cases of DNS errors, and it -- places a large burden on the arpa name servers. If used, proper PTR -- records must be in place for the domain's hosts and the "ptr" -- mechanism should be one of the last mechanisms checked. -- --5.6. "ip4" and "ip6" -- -- These mechanisms test whether is contained within a given IP -- network. -- -- IP4 = "ip4" ":" ip4-network [ ip4-cidr-length ] -- IP6 = "ip6" ":" ip6-network [ ip6-cidr-length ] -- -- ip4-cidr-length = "/" 1*DIGIT -- ip6-cidr-length = "/" 1*DIGIT -- dual-cidr-length = [ ip4-cidr-length ] [ "/" ip6-cidr-length ] -- -- ip4-network = qnum "." qnum "." qnum "." qnum -- qnum = DIGIT ; 0-9 -- / %x31-39 DIGIT ; 10-99 -- / "1" 2DIGIT ; 100-199 -- / "2" %x30-34 DIGIT ; 200-249 -- / "25" %x30-35 ; 250-255 -- ; as per conventional dotted quad notation. e.g., 192.0.2.0 -- ip6-network = -- ; e.g., 2001:DB8::CD30 -- -- The is compared to the given network. If CIDR-length high-order -- bits match, the mechanism matches. -- -- -- --Wong & Schlitt Experimental [Page 21] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- If ip4-cidr-length is omitted, it is taken to be "/32". If -- ip6-cidr-length is omitted, it is taken to be "/128". It is not -- permitted to omit parts of the IP address instead of using CIDR -- notations. That is, use 192.0.2.0/24 instead of 192.0.2. -- --5.7. "exists" -- -- This mechanism is used to construct an arbitrary domain name that is -- used for a DNS A record query. It allows for complicated schemes -- involving arbitrary parts of the mail envelope to determine what is -- permitted. -- -- exists = "exists" ":" domain-spec -- -- The domain-spec is expanded as per Section 8. The resulting domain -- name is used for a DNS A RR lookup. If any A record is returned, -- this mechanism matches. The lookup type is A even when the -- connection type is IPv6. -- -- Domains can use this mechanism to specify arbitrarily complex -- queries. For example, suppose example.com publishes the record: -- -- v=spf1 exists:%{ir}.%{l1r+-}._spf.%{d} -all -- -- The might expand to -- "1.2.0.192.someuser._spf.example.com". This makes fine-grained -- decisions possible at the level of the user and client IP address. -- -- This mechanism enables queries that mimic the style of tests that -- existing anti-spam DNS blacklists (DNSBL) use. -- --6. Modifier Definitions -- -- Modifiers are name/value pairs that provide additional information. -- Modifiers always have an "=" separating the name and the value. -- -- The modifiers defined in this document ("redirect" and "exp") MAY -- appear anywhere in the record, but SHOULD appear at the end, after -- all mechanisms. Ordering of these two modifiers does not matter. -- These two modifiers MUST NOT appear in a record more than once each. -- If they do, then check_host() exits with a result of "PermError". -- -- Unrecognized modifiers MUST be ignored no matter where in a record, -- or how often. This allows implementations of this document to -- gracefully handle records with modifiers that are defined in other -- specifications. -- -- -- -- -- --Wong & Schlitt Experimental [Page 22] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --6.1. redirect: Redirected Query -- -- If all mechanisms fail to match, and a "redirect" modifier is -- present, then processing proceeds as follows: -- -- redirect = "redirect" "=" domain-spec -- -- The domain-spec portion of the redirect section is expanded as per -- the macro rules in Section 8. Then check_host() is evaluated with -- the resulting string as the . The and -- arguments remain the same as current evaluation of check_host(). -- -- The result of this new evaluation of check_host() is then considered -- the result of the current evaluation with the exception that if no -- SPF record is found, or if the target-name is malformed, the result -- is a "PermError" rather than "None". -- -- Note that the newly-queried domain may itself specify redirect -- processing. -- -- This facility is intended for use by organizations that wish to apply -- the same record to multiple domains. For example: -- -- la.example.com. TXT "v=spf1 redirect=_spf.example.com" -- ny.example.com. TXT "v=spf1 redirect=_spf.example.com" -- sf.example.com. TXT "v=spf1 redirect=_spf.example.com" -- _spf.example.com. TXT "v=spf1 mx:example.com -all" -- -- In this example, mail from any of the three domains is described by -- the same record. This can be an administrative advantage. -- -- Note: In general, the domain "A" cannot reliably use a redirect to -- another domain "B" not under the same administrative control. Since -- the stays the same, there is no guarantee that the record at -- domain "B" will correctly work for mailboxes in domain "A", -- especially if domain "B" uses mechanisms involving localparts. An -- "include" directive may be more appropriate. -- -- For clarity, it is RECOMMENDED that any "redirect" modifier appear as -- the very last term in a record. -- --6.2. exp: Explanation -- -- explanation = "exp" "=" domain-spec -- -- If check_host() results in a "Fail" due to a mechanism match (such as -- "-all"), and the "exp" modifier is present, then the explanation -- string returned is computed as described below. If no "exp" modifier -- -- -- --Wong & Schlitt Experimental [Page 23] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- is present, then either a default explanation string or an empty -- explanation string may be returned. -- -- The is macro expanded (see Section 8) and becomes the -- . The DNS TXT record for the is fetched. -- -- If is empty, or there are any DNS processing errors -- (any RCODE other than 0), or if no records are returned, or if more -- than one record is returned, or if there are syntax errors in the -- explanation string, then proceed as if no exp modifier was given. -- -- The fetched TXT record's strings are concatenated with no spaces, and -- then treated as an , which is macro-expanded. This -- final result is the explanation string. Implementations MAY limit -- the length of the resulting explanation string to allow for other -- protocol constraints and/or reasonable processing limits. Since the -- explanation string is intended for an SMTP response and [RFC2821] -- Section 2.4 says that responses are in [US-ASCII], the explanation -- string is also limited to US-ASCII. -- -- Software evaluating check_host() can use this string to communicate -- information from the publishing domain in the form of a short message -- or URL. Software SHOULD make it clear that the explanation string -- comes from a third party. For example, it can prepend the macro -- string "%{o} explains: " to the explanation, such as shown in Section -- 2.5.4. -- -- Suppose example.com has this record: -- -- v=spf1 mx -all exp=explain._spf.%{d} -- -- Here are some examples of possible explanation TXT records at -- explain._spf.example.com: -- -- "Mail from example.com should only be sent by its own servers." -- -- a simple, constant message -- -- "%{i} is not one of %{d}'s designated mail servers." -- -- a message with a little more information, including the IP -- address that failed the check -- -- "See http://%{d}/why.html?s=%{S}&i=%{I}" -- -- a complicated example that constructs a URL with the -- arguments to check_host() so that a web page can be -- generated with detailed, custom instructions -- -- Note: During recursion into an "include" mechanism, an exp= modifier -- from the MUST NOT be used. In contrast, when executing -- -- -- --Wong & Schlitt Experimental [Page 24] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- a "redirect" modifier, an exp= modifier from the original domain MUST -- NOT be used. -- --7. The Received-SPF Header Field -- -- It is RECOMMENDED that SMTP receivers record the result of SPF -- processing in the message header. If an SMTP receiver chooses to do -- so, it SHOULD use the "Received-SPF" header field defined here for -- each identity that was checked. This information is intended for the -- recipient. (Information intended for the sender is described in -- Section 6.2, Explanation.) -- -- The Received-SPF header field is a trace field (see [RFC2822] Section -- 3.6.7) and SHOULD be prepended to the existing header, above the -- Received: field that is generated by the SMTP receiver. It MUST -- appear above all other Received-SPF fields in the message. The -- header field has the following format: -- -- header-field = "Received-SPF:" [CFWS] result FWS [comment FWS] -- [ key-value-list ] CRLF -- -- result = "Pass" / "Fail" / "SoftFail" / "Neutral" / -- "None" / "TempError" / "PermError" -- -- key-value-list = key-value-pair *( ";" [CFWS] key-value-pair ) -- [";"] -- -- key-value-pair = key [CFWS] "=" ( dot-atom / quoted-string ) -- -- key = "client-ip" / "envelope-from" / "helo" / -- "problem" / "receiver" / "identity" / -- mechanism / "x-" name / name -- -- identity = "mailfrom" ; for the "MAIL FROM" identity -- / "helo" ; for the "HELO" identity -- / name ; other identities -- -- dot-atom = -- quoted-string = -- comment = -- CFWS = -- FWS = -- CRLF = -- -- The header field SHOULD include a "(...)" style after the -- result, conveying supporting information for the result, such as -- , , and . -- -- -- -- --Wong & Schlitt Experimental [Page 25] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- The following key-value pairs are designed for later machine parsing. -- SPF clients SHOULD give enough information so that the SPF results -- can be verified. That is, at least "client-ip", "helo", and, if the -- "MAIL FROM" identity was checked, "envelope-from". -- -- client-ip the IP address of the SMTP client -- -- envelope-from the envelope sender mailbox -- -- helo the host name given in the HELO or EHLO command -- -- mechanism the mechanism that matched (if no mechanisms matched, -- substitute the word "default") -- -- problem if an error was returned, details about the error -- -- receiver the host name of the SPF client -- -- identity the identity that was checked; see the ABNF -- rule -- -- Other keys may be defined by SPF clients. Until a new key name -- becomes widely accepted, new key names should start with "x-". -- -- SPF clients MUST make sure that the Received-SPF header field does -- not contain invalid characters, is not excessively long, and does not -- contain malicious data that has been provided by the sender. -- -- Examples of various header styles that could be generated are the -- following: -- -- Received-SPF: Pass (mybox.example.org: domain of -- myname@example.com designates 192.0.2.1 as permitted sender) -- receiver=mybox.example.org; client-ip=192.0.2.1; -- envelope-from=; helo=foo.example.com; -- -- Received-SPF: Fail (mybox.example.org: domain of -- myname@example.com does not designate -- 192.0.2.1 as permitted sender) -- identity=mailfrom; client-ip=192.0.2.1; -- envelope-from=; -- -- -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 26] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --8. Macros -- --8.1. Macro Definitions -- -- Many mechanisms and modifiers perform macro expansion on part of the -- term. -- -- domain-spec = macro-string domain-end -- domain-end = ( "." toplabel [ "." ] ) / macro-expand -- -- toplabel = ( *alphanum ALPHA *alphanum ) / -- ( 1*alphanum "-" *( alphanum / "-" ) alphanum ) -- ; LDH rule plus additional TLD restrictions -- ; (see [RFC3696], Section 2) -- alphanum = ALPHA / DIGIT -- -- explain-string = *( macro-string / SP ) -- -- macro-string = *( macro-expand / macro-literal ) -- macro-expand = ( "%{" macro-letter transformers *delimiter "}" ) -- / "%%" / "%_" / "%-" -- macro-literal = %x21-24 / %x26-7E -- ; visible characters except "%" -- macro-letter = "s" / "l" / "o" / "d" / "i" / "p" / "h" / -- "c" / "r" / "t" -- transformers = *DIGIT [ "r" ] -- delimiter = "." / "-" / "+" / "," / "/" / "_" / "=" -- -- A literal "%" is expressed by "%%". -- -- "%_" expands to a single " " space. -- "%-" expands to a URL-encoded space, viz., "%20". -- -- The following macro letters are expanded in term arguments: -- -- s = -- l = local-part of -- o = domain of -- d = -- i = -- p = the validated domain name of -- v = the string "in-addr" if is ipv4, or "ip6" if is ipv6 -- h = HELO/EHLO domain -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 27] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- The following macro letters are allowed only in "exp" text: -- -- c = SMTP client IP (easily readable format) -- r = domain name of host performing the check -- t = current timestamp -- -- A '%' character not followed by a '{', '%', '-', or '_' character is -- a syntax error. So -- -- -exists:%(ir).sbl.spamhaus.example.org -- -- is incorrect and will cause check_host() to return a "PermError". -- Instead, say -- -- -exists:%{ir}.sbl.spamhaus.example.org -- -- Optional transformers are the following: -- -- *DIGIT = zero or more digits -- 'r' = reverse value, splitting on dots by default -- -- If transformers or delimiters are provided, the replacement value for -- a macro letter is split into parts. After performing any reversal -- operation and/or removal of left-hand parts, the parts are rejoined -- using "." and not the original splitting characters. -- -- By default, strings are split on "." (dots). Note that no special -- treatment is given to leading, trailing, or consecutive delimiters, -- and so the list of parts may contain empty strings. Older -- implementations of SPF prohibit trailing dots in domain names, so -- trailing dots should not be published by domain owners, although they -- must be accepted by implementations conforming to this document. -- Macros may specify delimiter characters that are used instead of ".". -- -- The 'r' transformer indicates a reversal operation: if the client IP -- address were 192.0.2.1, the macro %{i} would expand to "192.0.2.1" -- and the macro %{ir} would expand to "1.2.0.192". -- -- The DIGIT transformer indicates the number of right-hand parts to -- use, after optional reversal. If a DIGIT is specified, the value -- MUST be nonzero. If no DIGITs are specified, or if the value -- specifies more parts than are available, all the available parts are -- used. If the DIGIT was 5, and only 3 parts were available, the macro -- interpreter would pretend the DIGIT was 3. Implementations MUST -- support at least a value of 128, as that is the maximum number of -- labels in a domain name. -- -- -- -- -- --Wong & Schlitt Experimental [Page 28] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- The "s" macro expands to the argument. It is an E-Mail -- address with a localpart, an "@" character, and a domain. The "l" -- macro expands to just the localpart. The "o" macro expands to just -- the domain part. Note that these values remain the same during -- recursive and chained evaluations due to "include" and/or "redirect". -- Note also that if the original had no localpart, the -- localpart was set to "postmaster" in initial processing (see Section -- 4.3). -- -- For IPv4 addresses, both the "i" and "c" macros expand to the -- standard dotted-quad format. -- -- For IPv6 addresses, the "i" macro expands to a dot-format address; it -- is intended for use in %{ir}. The "c" macro may expand to any of the -- hexadecimal colon-format addresses specified in [RFC3513], Section -- 2.2. It is intended for humans to read. -- -- The "p" macro expands to the validated domain name of . The -- procedure for finding the validated domain name is defined in Section -- 5.5. If the is present in the list of validated domains, it -- SHOULD be used. Otherwise, if a subdomain of the is -- present, it SHOULD be used. Otherwise, any name from the list may be -- used. If there are no validated domain names or if a DNS error -- occurs, the string "unknown" is used. -- -- The "r" macro expands to the name of the receiving MTA. This SHOULD -- be a fully qualified domain name, but if one does not exist (as when -- the checking is done by a MUA) or if policy restrictions dictate -- otherwise, the word "unknown" SHOULD be substituted. The domain name -- may be different from the name found in the MX record that the client -- MTA used to locate the receiving MTA. -- -- The "t" macro expands to the decimal representation of the -- approximate number of seconds since the Epoch (Midnight, January 1, -- 1970, UTC). This is the same value as is returned by the POSIX -- time() function in most standards-compliant libraries. -- -- When the result of macro expansion is used in a domain name query, if -- the expanded domain name exceeds 253 characters (the maximum length -- of a domain name), the left side is truncated to fit, by removing -- successive domain labels until the total length does not exceed 253 -- characters. -- -- Uppercased macros expand exactly as their lowercased equivalents, and -- are then URL escaped. URL escaping must be performed for characters -- not in the "uric" set, which is defined in [RFC3986]. -- -- -- -- -- --Wong & Schlitt Experimental [Page 29] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Note: Care must be taken so that macro expansion for legitimate -- E-Mail does not exceed the 63-character limit on DNS labels. The -- localpart of E-Mail addresses, in particular, can have more than 63 -- characters between dots. -- -- Note: Domains should avoid using the "s", "l", "o", or "h" macros in -- conjunction with any mechanism directive. Although these macros are -- powerful and allow per-user records to be published, they severely -- limit the ability of implementations to cache results of check_host() -- and they reduce the effectiveness of DNS caches. -- -- Implementations should be aware that if no directive processed during -- the evaluation of check_host() contains an "s", "l", "o", or "h" -- macro, then the results of the evaluation can be cached on the basis -- of and alone for as long as the shortest Time To Live -- (TTL) of all the DNS records involved. -- --8.2. Expansion Examples -- -- The is strong-bad@email.example.com. -- The IPv4 SMTP client IP is 192.0.2.3. -- The IPv6 SMTP client IP is 2001:DB8::CB01. -- The PTR domain name of the client IP is mx.example.org. -- -- macro expansion -- ------- ---------------------------- -- %{s} strong-bad@email.example.com -- %{o} email.example.com -- %{d} email.example.com -- %{d4} email.example.com -- %{d3} email.example.com -- %{d2} example.com -- %{d1} com -- %{dr} com.example.email -- %{d2r} example.email -- %{l} strong-bad -- %{l-} strong.bad -- %{lr} strong-bad -- %{lr-} bad.strong -- %{l1r-} strong -- -- -- -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 30] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- macro-string expansion -- -------------------------------------------------------------------- -- %{ir}.%{v}._spf.%{d2} 3.2.0.192.in-addr._spf.example.com -- %{lr-}.lp._spf.%{d2} bad.strong.lp._spf.example.com -- -- %{lr-}.lp.%{ir}.%{v}._spf.%{d2} -- bad.strong.lp.3.2.0.192.in-addr._spf.example.com -- -- %{ir}.%{v}.%{l1r-}.lp._spf.%{d2} -- 3.2.0.192.in-addr.strong.lp._spf.example.com -- -- %{d2}.trusted-domains.example.net -- example.com.trusted-domains.example.net -- -- IPv6: -- %{ir}.%{v}._spf.%{d2} 1.0.B.C.0.0.0.0. -- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.B.D.0.1.0.0.2.ip6._spf.example.com -- --9. Implications -- -- This section outlines the major implications that adoption of this -- document will have on various entities involved in Internet E-Mail. -- It is intended to make clear to the reader where this document -- knowingly affects the operation of such entities. This section is -- not a "how-to" manual, or a "best practices" document, and it is not -- a comprehensive list of what such entities should do in light of this -- document. -- -- This section is non-normative. -- --9.1. Sending Domains -- -- Domains that wish to be compliant with this specification will need -- to determine the list of hosts that they allow to use their domain -- name in the "HELO" and "MAIL FROM" identities. It is recognized that -- forming such a list is not just a simple technical exercise, but -- involves policy decisions with both technical and administrative -- considerations. -- -- It can be helpful to publish records that include a "tracking -- exists:" mechanism. By looking at the name server logs, a rough list -- may then be generated. For example: -- -- v=spf1 exists:_h.%{h}._l.%{l}._o.%{o}._i.%{i}._spf.%{d} ?all -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 31] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --9.2. Mailing Lists -- -- Mailing lists must be aware of how they re-inject mail that is sent -- to the list. Mailing lists MUST comply with the requirements in -- [RFC2821], Section 3.10, and [RFC1123], Section 5.3.6, that say that -- the reverse-path MUST be changed to be the mailbox of a person or -- other entity who administers the list. Whereas the reasons for -- changing the reverse-path are many and long-standing, SPF adds -- enforcement to this requirement. -- -- In practice, almost all mailing list software in use already complies -- with this requirement. Mailing lists that do not comply may or may -- not encounter problems depending on how access to the list is -- restricted. Such lists that are entirely internal to a domain (only -- people in the domain can send to or receive from the list) are not -- affected. -- --9.3. Forwarding Services and Aliases -- -- Forwarding services take mail that is received at a mailbox and -- direct it to some external mailbox. At the time of this writing, the -- near-universal practice of such services is to use the original "MAIL -- FROM" of a message when re-injecting it for delivery to the external -- mailbox. [RFC1123] and [RFC2821] describe this action as an "alias" -- rather than a "mail list". This means that the external mailbox's -- MTA sees all such mail in a connection from a host of the forwarding -- service, and so the "MAIL FROM" identity will not, in general, pass -- authorization. -- -- There are three places that techniques can be used to ameliorate this -- problem. -- -- 1. The beginning, when E-Mail is first sent. -- -- 1. "Neutral" results could be given for IP addresses that may be -- forwarders, instead of "Fail" results. For example: -- -- "v=spf1 mx -exists:%{ir}.sbl.spamhaus.example.org ?all" -- -- This would cause a lookup on an anti-spam DNS blacklist -- (DNSBL) and cause a result of "Fail" only for E-Mail coming -- from listed sources. All other E-Mail, including E-Mail sent -- through forwarders, would receive a "Neutral" result. By -- checking the DNSBL after the known good sources, problems with -- incorrect listing on the DNSBL are greatly reduced. -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 32] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- 2. The "MAIL FROM" identity could have additional information in -- the localpart that cryptographically identifies the mail as -- coming from an authorized source. In this case, such an SPF -- record could be used: -- -- "v=spf1 mx exists:%{l}._spf_verify.%{d} -all" -- -- Then, a specialized DNS server can be set up to serve the -- _spf_verify subdomain that validates the localpart. Although -- this requires an extra DNS lookup, this happens only when the -- E-Mail would otherwise be rejected as not coming from a known -- good source. -- -- Note that due to the 63-character limit for domain labels, -- this approach only works reliably if the localpart signature -- scheme is guaranteed either to only produce localparts with a -- maximum of 63 characters or to gracefully handle truncated -- localparts. -- -- 3. Similarly, a specialized DNS server could be set up that will -- rate-limit the E-Mail coming from unexpected IP addresses. -- -- "v=spf1 mx exists:%{ir}._spf_rate.%{d} -all" -- -- 4. SPF allows the creation of per-user policies for special -- cases. For example, the following SPF record and appropriate -- wildcard DNS records can be used: -- -- "v=spf1 mx redirect=%{l1r+}._at_.%{o}._spf.%{d}" -- -- 2. The middle, when E-Mail is forwarded. -- -- 1. Forwarding services can solve the problem by rewriting the -- "MAIL FROM" to be in their own domain. This means that mail -- bounced from the external mailbox will have to be re-bounced -- by the forwarding service. Various schemes to do this exist -- though they vary widely in complexity and resource -- requirements on the part of the forwarding service. -- -- 2. Several popular MTAs can be forced from "alias" semantics to -- "mailing list" semantics by configuring an additional alias -- with "owner-" prepended to the original alias name (e.g., an -- alias of "friends: george@example.com, fred@example.org" would -- need another alias of the form "owner-friends: localowner"). -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 33] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- 3. The end, when E-Mail is received. -- -- 1. If the owner of the external mailbox wishes to trust the -- forwarding service, he can direct the external mailbox's MTA -- to skip SPF tests when the client host belongs to the -- forwarding service. -- -- 2. Tests against other identities, such as the "HELO" identity, -- may be used to override a failed test against the "MAIL FROM" -- identity. -- -- 3. For larger domains, it may not be possible to have a complete -- or accurate list of forwarding services used by the owners of -- the domain's mailboxes. In such cases, whitelists of -- generally-recognized forwarding services could be employed. -- --9.4. Mail Services -- -- Service providers that offer mail services to third-party domains, -- such as sending of bulk mail, may want to adjust their setup in light -- of the authorization check described in this document. If the "MAIL -- FROM" identity used for such E-Mail uses the domain of the service -- provider, then the provider needs only to ensure that its sending -- host is authorized by its own SPF record, if any. -- -- If the "MAIL FROM" identity does not use the mail service provider's -- domain, then extra care must be taken. The SPF record format has -- several options for the third-party domain to authorize the service -- provider's MTAs to send mail on its behalf. For mail service -- providers, such as ISPs, that have a wide variety of customers using -- the same MTA, steps should be taken to prevent cross-customer forgery -- (see Section 10.4). -- --9.5. MTA Relays -- -- The authorization check generally precludes the use of arbitrary MTA -- relays between sender and receiver of an E-Mail message. -- -- Within an organization, MTA relays can be effectively deployed. -- However, for purposes of this document, such relays are effectively -- transparent. The SPF authorization check is a check between border -- MTAs of different domains. -- -- For mail senders, this means that published SPF records must -- authorize any MTAs that actually send across the Internet. Usually, -- these are just the border MTAs as internal MTAs simply forward mail -- to these MTAs for delivery. -- -- -- -- --Wong & Schlitt Experimental [Page 34] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- Mail receivers will generally want to perform the authorization check -- at the border MTAs, specifically including all secondary MXs. This -- allows mail that fails to be rejected during the SMTP session rather -- than bounced. Internal MTAs then do not perform the authorization -- test. To perform the authorization test other than at the border, -- the host that first transferred the message to the organization must -- be determined, which can be difficult to extract from the message -- header. Testing other than at the border is not recommended. -- --10. Security Considerations -- --10.1. Processing Limits -- -- As with most aspects of E-Mail, there are a number of ways that -- malicious parties could use the protocol as an avenue for a -- Denial-of-Service (DoS) attack. The processing limits outlined here -- are designed to prevent attacks such as the following: -- -- o A malicious party could create an SPF record with many references -- to a victim's domain and send many E-Mails to different SPF -- clients; those SPF clients would then create a DoS attack. In -- effect, the SPF clients are being used to amplify the attacker's -- bandwidth by using fewer bytes in the SMTP session than are used -- by the DNS queries. Using SPF clients also allows the attacker to -- hide the true source of the attack. -- -- o Whereas implementations of check_host() are supposed to limit the -- number of DNS lookups, malicious domains could publish records -- that exceed these limits in an attempt to waste computation effort -- at their targets when they send them mail. Malicious domains -- could also design SPF records that cause particular -- implementations to use excessive memory or CPU usage, or to -- trigger bugs. -- -- o Malicious parties could send a large volume of mail purporting to -- come from the intended target to a wide variety of legitimate mail -- hosts. These legitimate machines would then present a DNS load on -- the target as they fetched the relevant records. -- -- Of these, the case of a third party referenced in the SPF record is -- the easiest for a DoS attack to effectively exploit. As a result, -- limits that may seem reasonable for an individual mail server can -- still allow an unreasonable amount of bandwidth amplification. -- Therefore, the processing limits need to be quite low. -- -- SPF implementations MUST limit the number of mechanisms and modifiers -- that do DNS lookups to at most 10 per SPF check, including any -- lookups caused by the use of the "include" mechanism or the -- -- -- --Wong & Schlitt Experimental [Page 35] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- "redirect" modifier. If this number is exceeded during a check, a -- PermError MUST be returned. The "include", "a", "mx", "ptr", and -- "exists" mechanisms as well as the "redirect" modifier do count -- against this limit. The "all", "ip4", and "ip6" mechanisms do not -- require DNS lookups and therefore do not count against this limit. -- The "exp" modifier does not count against this limit because the DNS -- lookup to fetch the explanation string occurs after the SPF record -- has been evaluated. -- -- When evaluating the "mx" and "ptr" mechanisms, or the %{p} macro, -- there MUST be a limit of no more than 10 MX or PTR RRs looked up and -- checked. -- -- SPF implementations SHOULD limit the total amount of data obtained -- from the DNS queries. For example, when DNS over TCP or EDNS0 are -- available, there may need to be an explicit limit to how much data -- will be accepted to prevent excessive bandwidth usage or memory usage -- and DoS attacks. -- -- MTAs or other processors MAY also impose a limit on the maximum -- amount of elapsed time to evaluate check_host(). Such a limit SHOULD -- allow at least 20 seconds. If such a limit is exceeded, the result -- of authorization SHOULD be "TempError". -- -- Domains publishing records SHOULD try to keep the number of "include" -- mechanisms and chained "redirect" modifiers to a minimum. Domains -- SHOULD also try to minimize the amount of other DNS information -- needed to evaluate a record. This can be done by choosing directives -- that require less DNS information and placing lower-cost mechanisms -- earlier in the SPF record. -- -- For example, consider a domain set up as follows: -- -- example.com. IN MX 10 mx.example.com. -- mx.example.com. IN A 192.0.2.1 -- a.example.com. IN TXT "v=spf1 mx:example.com -all" -- b.example.com. IN TXT "v=spf1 a:mx.example.com -all" -- c.example.com. IN TXT "v=spf1 ip4:192.0.2.1 -all" -- -- Evaluating check_host() for the domain "a.example.com" requires the -- MX records for "example.com", and then the A records for the listed -- hosts. Evaluating for "b.example.com" requires only the A records. -- Evaluating for "c.example.com" requires none. -- -- However, there may be administrative considerations: using "a" over -- "ip4" allows hosts to be renumbered easily. Using "mx" over "a" -- allows the set of mail hosts to be changed easily. -- -- -- -- --Wong & Schlitt Experimental [Page 36] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --10.2. SPF-Authorized E-Mail May Contain Other False Identities -- -- The "MAIL FROM" and "HELO" identity authorizations must not be -- construed to provide more assurance than they do. It is entirely -- possible for a malicious sender to inject a message using his own -- domain in the identities used by SPF, to have that domain's SPF -- record authorize the sending host, and yet the message can easily -- list other identities in its header. Unless the user or the MUA -- takes care to note that the authorized identity does not match the -- other more commonly-presented identities (such as the From: header -- field), the user may be lulled into a false sense of security. -- --10.3. Spoofed DNS and IP Data -- -- There are two aspects of this protocol that malicious parties could -- exploit to undermine the validity of the check_host() function: -- -- o The evaluation of check_host() relies heavily on DNS. A malicious -- attacker could attack the DNS infrastructure and cause -- check_host() to see spoofed DNS data, and then return incorrect -- results. This could include returning "Pass" for an value -- where the actual domain's record would evaluate to "Fail". See -- [RFC3833] for a description of DNS weaknesses. -- -- o The client IP address, , is assumed to be correct. A -- malicious attacker could spoof TCP sequence numbers to make mail -- appear to come from a permitted host for a domain that the -- attacker is impersonating. -- --10.4. Cross-User Forgery -- -- By definition, SPF policies just map domain names to sets of -- authorized MTAs, not whole E-Mail addresses to sets of authorized -- users. Although the "l" macro (Section 8) provides a limited way to -- define individual sets of authorized MTAs for specific E-Mail -- addresses, it is generally impossible to verify, through SPF, the use -- of specific E-Mail addresses by individual users of the same MTA. -- -- It is up to mail services and their MTAs to directly prevent -- cross-user forgery: based on SMTP AUTH ([RFC2554]), users should be -- restricted to using only those E-Mail addresses that are actually -- under their control (see [RFC4409], Section 6.1). Another means to -- verify the identity of individual users is message cryptography such -- as PGP ([RFC2440]) or S/MIME ([RFC3851]). -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 37] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --10.5. Untrusted Information Sources -- -- SPF uses information supplied by third parties, such as the "HELO" -- domain name, the "MAIL FROM" address, and SPF records. This -- information is then passed to the receiver in the Received-SPF: trace -- fields and possibly returned to the client MTA in the form of an SMTP -- rejection message. This information must be checked for invalid -- characters and excessively long lines. -- -- When the authorization check fails, an explanation string may be -- included in the reject response. Both the sender and the rejecting -- receiver need to be aware that the explanation was determined by the -- publisher of the SPF record checked and, in general, not the -- receiver. The explanation may contain malicious URLs, or it may be -- offensive or misleading. -- -- This is probably less of a concern than it may initially seem since -- such messages are returned to the sender, and the explanation strings -- come from the sender policy published by the domain in the identity -- claimed by that very sender. As long as the DSN is not redirected to -- someone other than the actual sender, the only people who see -- malicious explanation strings are people whose messages claim to be -- from domains that publish such strings in their SPF records. In -- practice, DSNs can be misdirected, such as when an MTA accepts an -- E-Mail and then later generates a DSN to a forged address, or when an -- E-Mail forwarder does not direct the DSN back to the original sender. -- --10.6. Privacy Exposure -- -- Checking SPF records causes DNS queries to be sent to the domain -- owner. These DNS queries, especially if they are caused by the -- "exists" mechanism, can contain information about who is sending -- E-Mail and likely to which MTA the E-Mail is being sent. This can -- introduce some privacy concerns, which may be more or less of an -- issue depending on local laws and the relationship between the domain -- owner and the person sending the E-Mail. -- --11. Contributors and Acknowledgements -- -- This document is largely based on the work of Meng Weng Wong and Mark -- Lentczner. Although, as this section acknowledges, many people have -- contributed to this document, a very large portion of the writing and -- editing are due to Meng and Mark. -- -- This design owes a debt of parentage to [RMX] by Hadmut Danisch and -- to [DMP] by Gordon Fecyk. The idea of using a DNS record to check -- the legitimacy of an E-Mail address traces its ancestry further back -- through messages on the namedroppers mailing list by Paul Vixie -- -- -- --Wong & Schlitt Experimental [Page 38] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- [Vixie] (based on suggestion by Jim Miller) and by David Green -- [Green]. -- -- Philip Gladstone contributed the concept of macros to the -- specification, multiplying the expressiveness of the language and -- making per-user and per-IP lookups possible. -- -- The authors would also like to thank the literally hundreds of -- individuals who have participated in the development of this design. -- They are far too numerous to name, but they include the following: -- -- The folks on the spf-discuss mailing list. -- The folks on the SPAM-L mailing list. -- The folks on the IRTF ASRG mailing list. -- The folks on the IETF MARID mailing list. -- The folks on #perl. -- --12. IANA Considerations -- --12.1. The SPF DNS Record Type -- -- The IANA has assigned a new Resource Record Type and Qtype from the -- DNS Parameters Registry for the SPF RR type with code 99. -- --12.2. The Received-SPF Mail Header Field -- -- Per [RFC3864], the "Received-SPF:" header field is added to the IANA -- Permanent Message Header Field Registry. The following is the -- registration template: -- -- Header field name: Received-SPF -- Applicable protocol: mail ([RFC2822]) -- Status: Experimental -- Author/Change controller: IETF -- Specification document(s): RFC 4408 -- Related information: -- Requesting SPF Council review of any proposed changes and -- additions to this field are recommended. For information about -- the SPF Council see http://www.openspf.org/Council -- --13. References -- --13.1. Normative References -- -- [RFC1035] Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- -- -- -- -- --Wong & Schlitt Experimental [Page 39] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- [RFC1123] Braden, R., "Requirements for Internet Hosts - Application -- and Support", STD 3, RFC 1123, October 1989. -- -- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate -- Requirement Levels", BCP 14, RFC 2119, March 1997. -- -- [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, -- April 2001. -- -- [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April -- 2001. -- -- [RFC3464] Moore, K. and G. Vaudreuil, "An Extensible Message Format -- for Delivery Status Notifications", RFC 3464, January -- 2003. -- -- [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 -- (IPv6) Addressing Architecture", RFC 3513, April 2003. -- -- [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration -- Procedures for Message Header Fields", BCP 90, RFC 3864, -- September 2004. -- -- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform -- Resource Identifier (URI): Generic Syntax", STD 66, RFC -- 3986, January 2005. -- -- [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax -- Specifications: ABNF", RFC 4234, October 2005. -- -- [US-ASCII] American National Standards Institute (formerly United -- States of America Standards Institute), "USA Code for -- Information Interchange, X3.4", 1968. -- -- ANSI X3.4-1968 has been replaced by newer versions with slight -- modifications, but the 1968 version remains definitive for -- the Internet. -- --13.2 Informative References -- -- [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", -- STD 13, RFC 1034, November 1987. -- -- [RFC1983] Malkin, G., "Internet Users' Glossary", RFC 1983, August -- 1996. -- -- [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, -- "OpenPGP Message Format", RFC 2440, November 1998. -- -- -- --Wong & Schlitt Experimental [Page 40] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- [RFC2554] Myers, J., "SMTP Service Extension for Authentication", -- RFC 2554, March 1999. -- -- [RFC3696] Klensin, J., "Application Techniques for Checking and -- Transformation of Names", RFC 3696, February 2004. -- -- [RFC3833] Atkins, D. and R. Austein, "Threat Analysis of the Domain -- Name System (DNS)", RFC 3833, August 2004. -- -- [RFC3851] Ramsdell, B., "Secure/Multipurpose Internet Mail -- Extensions (S/MIME) Version 3.1 Message Specification", -- RFC 3851, July 2004. -- -- [RFC4409] Gellens, R. and J. Klensin, "Message Submission for Mail", -- RFC 4409, April 2006. -- -- [RMX] Danish, H., "The RMX DNS RR Type for light weight sender -- authentication", Work In Progress -- -- [DMP] Fecyk, G., "Designated Mailers Protocol", Work In Progress -- -- [Vixie] Vixie, P., "Repudiating MAIL FROM", 2002. -- -- [Green] Green, D., "Domain-Authorized SMTP Mail", 2002. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 41] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --Appendix A. Collected ABNF -- -- This section is normative and any discrepancies with the ABNF -- fragments in the preceding text are to be resolved in favor of this -- grammar. -- -- See [RFC4234] for ABNF notation. Please note that as per this ABNF -- definition, literal text strings (those in quotes) are case- -- insensitive. Hence, "mx" matches "mx", "MX", "mX", and "Mx". -- -- record = version terms *SP -- version = "v=spf1" -- -- terms = *( 1*SP ( directive / modifier ) ) -- -- directive = [ qualifier ] mechanism -- qualifier = "+" / "-" / "?" / "~" -- mechanism = ( all / include -- / A / MX / PTR / IP4 / IP6 / exists ) -- -- all = "all" -- include = "include" ":" domain-spec -- A = "a" [ ":" domain-spec ] [ dual-cidr-length ] -- MX = "mx" [ ":" domain-spec ] [ dual-cidr-length ] -- PTR = "ptr" [ ":" domain-spec ] -- IP4 = "ip4" ":" ip4-network [ ip4-cidr-length ] -- IP6 = "ip6" ":" ip6-network [ ip6-cidr-length ] -- exists = "exists" ":" domain-spec -- -- modifier = redirect / explanation / unknown-modifier -- redirect = "redirect" "=" domain-spec -- explanation = "exp" "=" domain-spec -- unknown-modifier = name "=" macro-string -- -- ip4-cidr-length = "/" 1*DIGIT -- ip6-cidr-length = "/" 1*DIGIT -- dual-cidr-length = [ ip4-cidr-length ] [ "/" ip6-cidr-length ] -- -- ip4-network = qnum "." qnum "." qnum "." qnum -- qnum = DIGIT ; 0-9 -- / %x31-39 DIGIT ; 10-99 -- / "1" 2DIGIT ; 100-199 -- / "2" %x30-34 DIGIT ; 200-249 -- / "25" %x30-35 ; 250-255 -- ; conventional dotted quad notation. e.g., 192.0.2.0 -- ip6-network = -- ; e.g., 2001:DB8::CD30 -- -- -- -- --Wong & Schlitt Experimental [Page 42] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- domain-spec = macro-string domain-end -- domain-end = ( "." toplabel [ "." ] ) / macro-expand -- toplabel = ( *alphanum ALPHA *alphanum ) / -- ( 1*alphanum "-" *( alphanum / "-" ) alphanum ) -- ; LDH rule plus additional TLD restrictions -- ; (see [RFC3696], Section 2) -- -- alphanum = ALPHA / DIGIT -- -- explain-string = *( macro-string / SP ) -- -- macro-string = *( macro-expand / macro-literal ) -- macro-expand = ( "%{" macro-letter transformers *delimiter "}" ) -- / "%%" / "%_" / "%-" -- macro-literal = %x21-24 / %x26-7E -- ; visible characters except "%" -- macro-letter = "s" / "l" / "o" / "d" / "i" / "p" / "h" / -- "c" / "r" / "t" -- transformers = *DIGIT [ "r" ] -- delimiter = "." / "-" / "+" / "," / "/" / "_" / "=" -- -- name = ALPHA *( ALPHA / DIGIT / "-" / "_" / "." ) -- -- header-field = "Received-SPF:" [CFWS] result FWS [comment FWS] -- [ key-value-list ] CRLF -- -- result = "Pass" / "Fail" / "SoftFail" / "Neutral" / -- "None" / "TempError" / "PermError" -- -- key-value-list = key-value-pair *( ";" [CFWS] key-value-pair ) -- [";"] -- -- key-value-pair = key [CFWS] "=" ( dot-atom / quoted-string ) -- -- key = "client-ip" / "envelope-from" / "helo" / -- "problem" / "receiver" / "identity" / -- mechanism / "x-" name / name -- -- identity = "mailfrom" ; for the "MAIL FROM" identity -- / "helo" ; for the "HELO" identity -- / name ; other identities -- -- dot-atom = -- quoted-string = -- comment = -- CFWS = -- FWS = -- CRLF = -- -- -- --Wong & Schlitt Experimental [Page 43] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --Appendix B. Extended Examples -- -- These examples are based on the following DNS setup: -- -- ; A domain with two mail servers, two hosts -- ; and two servers at the domain name -- $ORIGIN example.com. -- @ MX 10 mail-a -- MX 20 mail-b -- A 192.0.2.10 -- A 192.0.2.11 -- amy A 192.0.2.65 -- bob A 192.0.2.66 -- mail-a A 192.0.2.129 -- mail-b A 192.0.2.130 -- www CNAME example.com. -- -- ; A related domain -- $ORIGIN example.org. -- @ MX 10 mail-c -- mail-c A 192.0.2.140 -- -- ; The reverse IP for those addresses -- $ORIGIN 2.0.192.in-addr.arpa. -- 10 PTR example.com. -- 11 PTR example.com. -- 65 PTR amy.example.com. -- 66 PTR bob.example.com. -- 129 PTR mail-a.example.com. -- 130 PTR mail-b.example.com. -- 140 PTR mail-c.example.org. -- -- ; A rogue reverse IP domain that claims to be -- ; something it's not -- $ORIGIN 0.0.10.in-addr.arpa. -- 4 PTR bob.example.com. -- --B.1. Simple Examples -- -- These examples show various possible published records for -- example.com and which values if would cause check_host() to -- return "Pass". Note that is "example.com". -- -- v=spf1 +all -- -- any passes -- -- v=spf1 a -all -- -- hosts 192.0.2.10 and 192.0.2.11 pass -- -- -- --Wong & Schlitt Experimental [Page 44] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- -- v=spf1 a:example.org -all -- -- no sending hosts pass since example.org has no A records -- -- v=spf1 mx -all -- -- sending hosts 192.0.2.129 and 192.0.2.130 pass -- -- v=spf1 mx:example.org -all -- -- sending host 192.0.2.140 passes -- -- v=spf1 mx mx:example.org -all -- -- sending hosts 192.0.2.129, 192.0.2.130, and 192.0.2.140 pass -- -- v=spf1 mx/30 mx:example.org/30 -all -- -- any sending host in 192.0.2.128/30 or 192.0.2.140/30 passes -- -- v=spf1 ptr -all -- -- sending host 192.0.2.65 passes (reverse DNS is valid and is in -- example.com) -- -- sending host 192.0.2.140 fails (reverse DNS is valid, but not -- in example.com) -- -- sending host 10.0.0.4 fails (reverse IP is not valid) -- -- v=spf1 ip4:192.0.2.128/28 -all -- -- sending host 192.0.2.65 fails -- -- sending host 192.0.2.129 passes -- --B.2. Multiple Domain Example -- -- These examples show the effect of related records: -- -- example.org: "v=spf1 include:example.com include:example.net -all" -- -- This record would be used if mail from example.org actually came -- through servers at example.com and example.net. Example.org's -- designated servers are the union of example.com's and example.net's -- designated servers. -- -- la.example.org: "v=spf1 redirect=example.org" -- ny.example.org: "v=spf1 redirect=example.org" -- sf.example.org: "v=spf1 redirect=example.org" -- -- These records allow a set of domains that all use the same mail -- system to make use of that mail system's record. In this way, only -- the mail system's record needs to be updated when the mail setup -- changes. These domains' records never have to change. -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 45] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --B.3. DNSBL Style Example -- -- Imagine that, in addition to the domain records listed above, there -- are these: -- -- $ORIGIN _spf.example.com. mary.mobile-users A -- 127.0.0.2 fred.mobile-users A 127.0.0.2 -- 15.15.168.192.joel.remote-users A 127.0.0.2 -- 16.15.168.192.joel.remote-users A 127.0.0.2 -- -- The following records describe users at example.com who mail from -- arbitrary servers, or who mail from personal servers. -- -- example.com: -- -- v=spf1 mx -- include:mobile-users._spf.%{d} -- include:remote-users._spf.%{d} -- -all -- -- mobile-users._spf.example.com: -- -- v=spf1 exists:%{l1r+}.%{d} -- -- remote-users._spf.example.com: -- -- v=spf1 exists:%{ir}.%{l1r+}.%{d} -- --B.4. Multiple Requirements Example -- -- Say that your sender policy requires both that the IP address is -- within a certain range and that the reverse DNS for the IP matches. -- This can be done several ways, including the following: -- -- example.com. SPF ( "v=spf1 " -- "-include:ip4._spf.%{d} " -- "-include:ptr._spf.%{d} " -- "+all" ) -- ip4._spf.example.com. SPF "v=spf1 -ip4:192.0.2.0/24 +all" -- ptr._spf.example.com. SPF "v=spf1 -ptr +all" -- -- This example shows how the "-include" mechanism can be useful, how an -- SPF record that ends in "+all" can be very restrictive, and the use -- of De Morgan's Law. -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 46] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --Authors' Addresses -- -- Meng Weng Wong -- Singapore -- -- EMail: mengwong+spf@pobox.com -- -- -- Wayne Schlitt -- 4615 Meredeth #9 -- Lincoln Nebraska, NE 68506 -- United States of America -- -- EMail: wayne@schlitt.net -- URI: http://www.schlitt.net/spf/ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 47] -- --RFC 4408 Sender Policy Framework (SPF) April 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Wong & Schlitt Experimental [Page 48] -- diff --cc doc/rfc/rfc4431.txt index 8b3887229c6,8b3887229c6..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4431.txt +++ /dev/null @@@ -1,227 -1,227 +1,0 @@@ -- -- -- -- -- -- --Network Working Group M. Andrews --Request for Comments: 4431 Internet Systems Consortium --Category: Informational S. Weiler -- SPARTA, Inc. -- February 2006 -- -- -- The DNSSEC Lookaside Validation (DLV) DNS Resource Record -- --Status of This Memo -- -- This memo provides information for the Internet community. It does -- not specify an Internet standard of any kind. Distribution of this -- memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document defines a new DNS resource record, called the DNSSEC -- Lookaside Validation (DLV) RR, for publishing DNSSEC trust anchors -- outside of the DNS delegation chain. -- --1. Introduction -- -- DNSSEC [1] [2] [3] authenticates DNS data by building public-key -- signature chains along the DNS delegation chain from a trust anchor, -- ideally a trust anchor for the DNS root. -- -- This document defines a new resource record for publishing such trust -- anchors outside of the DNS's normal delegation chain. Use of these -- records by DNSSEC validators is outside the scope of this document, -- but it is expected that these records will help resolvers validate -- DNSSEC-signed data from zones whose ancestors either aren't signed or -- refuse to publish delegation signer (DS) records for their children. -- --2. DLV Resource Record -- -- The DLV resource record has exactly the same wire and presentation -- formats as the DS resource record, defined in RFC 4034, Section 5. -- It uses the same IANA-assigned values in the algorithm and digest -- type fields as the DS record. (Those IANA registries are known as -- the "DNS Security Algorithm Numbers" and "DS RR Type Algorithm -- Numbers" registries.) -- -- -- -- -- --Andrews & Weiler Informational [Page 1] -- --RFC 4431 DLV Resource Record February 2006 -- -- -- The DLV record is a normal DNS record type without any special -- processing requirements. In particular, the DLV record does not -- inherit any of the special processing or handling requirements of the -- DS record type (described in Section 3.1.4.1 of RFC 4035). Unlike -- the DS record, the DLV record may not appear on the parent's side of -- a zone cut. A DLV record may, however, appear at the apex of a zone. -- --3. Security Considerations -- -- For authoritative servers and resolvers that do not attempt to use -- DLV RRs as part of DNSSEC validation, there are no particular -- security concerns -- DLV RRs are just like any other DNS data. -- -- Software using DLV RRs as part of DNSSEC validation will almost -- certainly want to impose constraints on their use, but those -- constraints are best left to be described by the documents that more -- fully describe the particulars of how the records are used. At a -- minimum, it would be unwise to use the records without some sort of -- cryptographic authentication. More likely than not, DNSSEC itself -- will be used to authenticate the DLV RRs. Depending on how a DLV RR -- is used, failure to properly authenticate it could lead to -- significant additional security problems including failure to detect -- spoofed DNS data. -- -- RFC 4034, Section 8, describes security considerations specific to -- the DS RR. Those considerations are equally applicable to DLV RRs. -- Of particular note, the key tag field is used to help select DNSKEY -- RRs efficiently, but it does not uniquely identify a single DNSKEY -- RR. It is possible for two distinct DNSKEY RRs to have the same -- owner name, the same algorithm type, and the same key tag. An -- implementation that uses only the key tag to select a DNSKEY RR might -- select the wrong public key in some circumstances. -- -- For further discussion of the security implications of DNSSEC, see -- RFC 4033, RFC 4034, and RFC 4035. -- --4. IANA Considerations -- -- IANA has assigned DNS type code 32769 to the DLV resource record from -- the Specification Required portion of the DNS Resource Record Type -- registry, as defined in [4]. -- -- The DLV resource record reuses the same algorithm and digest type -- registries already used for the DS resource record, currently known -- as the "DNS Security Algorithm Numbers" and "DS RR Type Algorithm -- Numbers" registries. -- -- -- -- -- --Andrews & Weiler Informational [Page 2] -- --RFC 4431 DLV Resource Record February 2006 -- -- --5. Normative References -- -- [1] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, -- March 2005. -- -- [2] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- [3] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", -- RFC 4035, March 2005. -- -- [4] Eastlake, D., Brunner-Williams, E., and B. Manning, "Domain Name -- System (DNS) IANA Considerations", BCP 42, RFC 2929, -- September 2000. -- --Authors' Addresses -- -- Mark Andrews -- Internet Systems Consortium -- 950 Charter St. -- Redwood City, CA 94063 -- US -- -- EMail: Mark_Andrews@isc.org -- -- -- Samuel Weiler -- SPARTA, Inc. -- 7075 Samuel Morse Drive -- Columbia, Maryland 21046 -- US -- -- EMail: weiler@tislabs.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Andrews & Weiler Informational [Page 3] -- --RFC 4431 DLV Resource Record February 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Andrews & Weiler Informational [Page 4] -- diff --cc doc/rfc/rfc4470.txt index ac12d65c44c,ac12d65c44c..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4470.txt +++ /dev/null @@@ -1,451 -1,451 +1,0 @@@ -- -- -- -- -- -- --Network Working Group S. Weiler --Request for Comments: 4470 SPARTA, Inc. --Updates: 4035, 4034 J. Ihren --Category: Standards Track Autonomica AB -- April 2006 -- -- -- Minimally Covering NSEC Records and DNSSEC On-line Signing -- -- --Status of This Memo -- -- This document specifies an Internet standards track protocol for the -- Internet community, and requests discussion and suggestions for -- improvements. Please refer to the current edition of the "Internet -- Official Protocol Standards" (STD 1) for the standardization state -- and status of this protocol. Distribution of this memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document describes how to construct DNSSEC NSEC resource records -- that cover a smaller range of names than called for by RFC 4034. By -- generating and signing these records on demand, authoritative name -- servers can effectively stop the disclosure of zone contents -- otherwise made possible by walking the chain of NSEC records in a -- signed zone. -- --Table of Contents -- -- 1. Introduction ....................................................1 -- 2. Applicability of This Technique .................................2 -- 3. Minimally Covering NSEC Records .................................2 -- 4. Better Epsilon Functions ........................................4 -- 5. Security Considerations .........................................5 -- 6. Acknowledgements ................................................6 -- 7. Normative References ............................................6 -- --1. Introduction -- -- With DNSSEC [1], an NSEC record lists the next instantiated name in -- its zone, proving that no names exist in the "span" between the -- NSEC's owner name and the name in the "next name" field. In this -- document, an NSEC record is said to "cover" the names between its -- owner name and next name. -- -- -- --Weiler & Ihren Standards Track [Page 1] -- --RFC 4470 NSEC Epsilon April 2006 -- -- -- Through repeated queries that return NSEC records, it is possible to -- retrieve all of the names in the zone, a process commonly called -- "walking" the zone. Some zone owners have policies forbidding zone -- transfers by arbitrary clients; this side effect of the NSEC -- architecture subverts those policies. -- -- This document presents a way to prevent zone walking by constructing -- NSEC records that cover fewer names. These records can make zone -- walking take approximately as many queries as simply asking for all -- possible names in a zone, making zone walking impractical. Some of -- these records must be created and signed on demand, which requires -- on-line private keys. Anyone contemplating use of this technique is -- strongly encouraged to review the discussion of the risks of on-line -- signing in Section 5. -- --1.2. Keywords -- -- The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -- document are to be interpreted as described in RFC 2119 [4]. -- --2. Applicability of This Technique -- -- The technique presented here may be useful to a zone owner that wants -- to use DNSSEC, is concerned about exposure of its zone contents via -- zone walking, and is willing to bear the costs of on-line signing. -- -- As discussed in Section 5, on-line signing has several security -- risks, including an increased likelihood of private keys being -- disclosed and an increased risk of denial of service attack. Anyone -- contemplating use of this technique is strongly encouraged to review -- the discussion of the risks of on-line signing in Section 5. -- -- Furthermore, at the time this document was published, the DNSEXT -- working group was actively working on a mechanism to prevent zone -- walking that does not require on-line signing (tentatively called -- NSEC3). The new mechanism is likely to expose slightly more -- information about the zone than this technique (e.g., the number of -- instantiated names), but it may be preferable to this technique. -- --3. Minimally Covering NSEC Records -- -- This mechanism involves changes to NSEC records for instantiated -- names, which can still be generated and signed in advance, as well as -- the on-demand generation and signing of new NSEC records whenever a -- name must be proven not to exist. -- -- -- -- -- --Weiler & Ihren Standards Track [Page 2] -- --RFC 4470 NSEC Epsilon April 2006 -- -- -- In the "next name" field of instantiated names' NSEC records, rather -- than list the next instantiated name in the zone, list any name that -- falls lexically after the NSEC's owner name and before the next -- instantiated name in the zone, according to the ordering function in -- RFC 4034 [2] Section 6.1. This relaxes the requirement in Section -- 4.1.1 of RFC 4034 that the "next name" field contains the next owner -- name in the zone. This change is expected to be fully compatible -- with all existing DNSSEC validators. These NSEC records are returned -- whenever proving something specifically about the owner name (e.g., -- that no resource records of a given type appear at that name). -- -- Whenever an NSEC record is needed to prove the non-existence of a -- name, a new NSEC record is dynamically produced and signed. The new -- NSEC record has an owner name lexically before the QNAME but -- lexically following any existing name and a "next name" lexically -- following the QNAME but before any existing name. -- -- The generated NSEC record's type bitmap MUST have the RRSIG and NSEC -- bits set and SHOULD NOT have any other bits set. This relaxes the -- requirement in Section 2.3 of RFC4035 that NSEC RRs not appear at -- names that did not exist before the zone was signed. -- -- The functions to generate the lexically following and proceeding -- names need not be perfect or consistent, but the generated NSEC -- records must not cover any existing names. Furthermore, this -- technique works best when the generated NSEC records cover as few -- names as possible. In this document, the functions that generate the -- nearby names are called "epsilon" functions, a reference to the -- mathematical convention of using the greek letter epsilon to -- represent small deviations. -- -- An NSEC record denying the existence of a wildcard may be generated -- in the same way. Since the NSEC record covering a non-existent -- wildcard is likely to be used in response to many queries, -- authoritative name servers using the techniques described here may -- want to pregenerate or cache that record and its corresponding RRSIG. -- -- For example, a query for an A record at the non-instantiated name -- example.com might produce the following two NSEC records, the first -- denying the existence of the name example.com and the second denying -- the existence of a wildcard: -- -- exampld.com 3600 IN NSEC example-.com ( RRSIG NSEC ) -- -- \).com 3600 IN NSEC +.com ( RRSIG NSEC ) -- -- -- -- -- -- --Weiler & Ihren Standards Track [Page 3] -- --RFC 4470 NSEC Epsilon April 2006 -- -- -- Before answering a query with these records, an authoritative server -- must test for the existence of names between these endpoints. If the -- generated NSEC would cover existing names (e.g., exampldd.com or -- *bizarre.example.com), a better epsilon function may be used or the -- covered name closest to the QNAME could be used as the NSEC owner -- name or next name, as appropriate. If an existing name is used as -- the NSEC owner name, that name's real NSEC record MUST be returned. -- Using the same example, assuming an exampldd.com delegation exists, -- this record might be returned from the parent: -- -- exampldd.com 3600 IN NSEC example-.com ( NS DS RRSIG NSEC ) -- -- Like every authoritative record in the zone, each generated NSEC -- record MUST have corresponding RRSIGs generated using each algorithm -- (but not necessarily each DNSKEY) in the zone's DNSKEY RRset, as -- described in RFC 4035 [3] Section 2.2. To minimize the number of -- signatures that must be generated, a zone may wish to limit the -- number of algorithms in its DNSKEY RRset. -- --4. Better Epsilon Functions -- -- Section 6.1 of RFC 4034 defines a strict ordering of DNS names. -- Working backward from that definition, it should be possible to -- define epsilon functions that generate the immediately following and -- preceding names, respectively. This document does not define such -- functions. Instead, this section presents functions that come -- reasonably close to the perfect ones. As described above, an -- authoritative server should still ensure than no generated NSEC -- covers any existing name. -- -- To increment a name, add a leading label with a single null (zero- -- value) octet. -- -- To decrement a name, decrement the last character of the leftmost -- label, then fill that label to a length of 63 octets with octets of -- value 255. To decrement a null (zero-value) octet, remove the octet -- -- if an empty label is left, remove the label. Defining this -- function numerically: fill the leftmost label to its maximum length -- with zeros (numeric, not ASCII zeros) and subtract one. -- -- In response to a query for the non-existent name foo.example.com, -- these functions produce NSEC records of the following: -- -- -- -- -- -- -- -- -- --Weiler & Ihren Standards Track [Page 4] -- --RFC 4470 NSEC Epsilon April 2006 -- -- -- fon\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255.example.com 3600 IN NSEC \000.foo.example.com ( NSEC RRSIG ) -- -- \)\255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255\255\255\255\255\255\255\255\255\255\255\255\255\255 -- \255\255.example.com 3600 IN NSEC \000.*.example.com ( NSEC RRSIG ) -- -- The first of these NSEC RRs proves that no exact match for -- foo.example.com exists, and the second proves that there is no -- wildcard in example.com. -- -- Both of these functions are imperfect: they do not take into account -- constraints on number of labels in a name nor total length of a name. -- As noted in the previous section, though, this technique does not -- depend on the use of perfect epsilon functions: it is sufficient to -- test whether any instantiated names fall into the span covered by the -- generated NSEC and, if so, substitute those instantiated owner names -- for the NSEC owner name or next name, as appropriate. -- --5. Security Considerations -- -- This approach requires on-demand generation of RRSIG records. This -- creates several new vulnerabilities. -- -- First, on-demand signing requires that a zone's authoritative servers -- have access to its private keys. Storing private keys on well-known -- Internet-accessible servers may make them more vulnerable to -- unintended disclosure. -- -- Second, since generation of digital signatures tends to be -- computationally demanding, the requirement for on-demand signing -- makes authoritative servers vulnerable to a denial of service attack. -- -- Last, if the epsilon functions are predictable, on-demand signing may -- enable a chosen-plaintext attack on a zone's private keys. Zones -- using this approach should attempt to use cryptographic algorithms -- that are resistant to chosen-plaintext attacks. It is worth noting -- that although DNSSEC has a "mandatory to implement" algorithm, that -- is a requirement on resolvers and validators -- there is no -- requirement that a zone be signed with any given algorithm. -- -- The success of using minimally covering NSEC records to prevent zone -- walking depends greatly on the quality of the epsilon functions -- -- -- --Weiler & Ihren Standards Track [Page 5] -- --RFC 4470 NSEC Epsilon April 2006 -- -- -- chosen. An increment function that chooses a name obviously derived -- from the next instantiated name may be easily reverse engineered, -- destroying the value of this technique. An increment function that -- always returns a name close to the next instantiated name is likewise -- a poor choice. Good choices of epsilon functions are the ones that -- produce the immediately following and preceding names, respectively, -- though zone administrators may wish to use less perfect functions -- that return more human-friendly names than the functions described in -- Section 4 above. -- -- Another obvious but misguided concern is the danger from synthesized -- NSEC records being replayed. It is possible for an attacker to -- replay an old but still validly signed NSEC record after a new name -- has been added in the span covered by that NSEC, incorrectly proving -- that there is no record at that name. This danger exists with DNSSEC -- as defined in [3]. The techniques described here actually decrease -- the danger, since the span covered by any NSEC record is smaller than -- before. Choosing better epsilon functions will further reduce this -- danger. -- --6. Acknowledgements -- -- Many individuals contributed to this design. They include, in -- addition to the authors of this document, Olaf Kolkman, Ed Lewis, -- Peter Koch, Matt Larson, David Blacka, Suzanne Woolf, Jaap Akkerhuis, -- Jakob Schlyter, Bill Manning, and Joao Damas. -- -- In addition, the editors would like to thank Ed Lewis, Scott Rose, -- and David Blacka for their careful review of the document. -- --7. Normative References -- -- [1] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, March -- 2005. -- -- [2] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- [3] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", RFC -- 4035, March 2005. -- -- [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- -- -- -- --Weiler & Ihren Standards Track [Page 6] -- --RFC 4470 NSEC Epsilon April 2006 -- -- --Authors' Addresses -- -- Samuel Weiler -- SPARTA, Inc. -- 7075 Samuel Morse Drive -- Columbia, Maryland 21046 -- US -- -- EMail: weiler@tislabs.com -- -- -- Johan Ihren -- Autonomica AB -- Bellmansgatan 30 -- Stockholm SE-118 47 -- Sweden -- -- EMail: johani@autonomica.se -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Weiler & Ihren Standards Track [Page 7] -- --RFC 4470 NSEC Epsilon April 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Weiler & Ihren Standards Track [Page 8] -- diff --cc doc/rfc/rfc4634.txt index b672df8a445,b672df8a445..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4634.txt +++ /dev/null @@@ -1,6051 -1,6051 +1,0 @@@ -- -- -- -- -- -- --Network Working Group D. Eastlake 3rd --Request for Comments: 4634 Motorola Labs --Updates: 3174 T. Hansen --Category: Informational AT&T Labs -- July 2006 -- -- -- US Secure Hash Algorithms (SHA and HMAC-SHA) -- --Status of This Memo -- -- This memo provides information for the Internet community. It does -- not specify an Internet standard of any kind. Distribution of this -- memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- The United States of America has adopted a suite of Secure Hash -- Algorithms (SHAs), including four beyond SHA-1, as part of a Federal -- Information Processing Standard (FIPS), specifically SHA-224 (RFC -- 3874), SHA-256, SHA-384, and SHA-512. The purpose of this document -- is to make source code performing these hash functions conveniently -- available to the Internet community. The sample code supports input -- strings of arbitrary bit length. SHA-1's sample code from RFC 3174 -- has also been updated to handle input strings of arbitrary bit -- length. Most of the text herein was adapted by the authors from FIPS -- 180-2. -- -- Code to perform SHA-based HMACs, with arbitrary bit length text, is -- also included. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 1] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --Table of Contents -- -- 1. Overview of Contents ............................................3 -- 1.1. License ....................................................4 -- 2. Notation for Bit Strings and Integers ...........................4 -- 3. Operations on Words .............................................5 -- 4. Message Padding and Parsing .....................................6 -- 4.1. SHA-224 and SHA-256 ........................................7 -- 4.2. SHA-384 and SHA-512 ........................................8 -- 5. Functions and Constants Used ....................................9 -- 5.1. SHA-224 and SHA-256 ........................................9 -- 5.2. SHA-384 and SHA-512 .......................................10 -- 6. Computing the Message Digest ...................................11 -- 6.1. SHA-224 and SHA-256 Initialization ........................11 -- 6.2. SHA-224 and SHA-256 Processing ............................11 -- 6.3. SHA-384 and SHA-512 Initialization ........................13 -- 6.4. SHA-384 and SHA-512 Processing ............................14 -- 7. SHA-Based HMACs ................................................15 -- 8. C Code for SHAs ................................................15 -- 8.1. The .h File ...............................................18 -- 8.2. The SHA Code ..............................................24 -- 8.2.1. sha1.c .............................................24 -- 8.2.2. sha224-256.c .......................................33 -- 8.2.3. sha384-512.c .......................................45 -- 8.2.4. usha.c .............................................67 -- 8.2.5. sha-private.h ......................................72 -- 8.3. The HMAC Code .............................................73 -- 8.4. The Test Driver ...........................................78 -- 9. Security Considerations .......................................106 -- 10. Normative References .........................................106 -- 11. Informative References .......................................106 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 2] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --1. Overview of Contents -- -- NOTE: Much of the text below is taken from [FIPS180-2] and assertions -- therein of the security of the algorithms described are made by the -- US Government, the author of [FIPS180-2], and not by the authors of -- this document. -- -- The text below specifies Secure Hash Algorithms, SHA-224 [RFC3874], -- SHA-256, SHA-384, and SHA-512, for computing a condensed -- representation of a message or a data file. (SHA-1 is specified in -- [RFC3174].) When a message of any length < 2^64 bits (for SHA-224 -- and SHA-256) or < 2^128 bits (for SHA-384 and SHA-512) is input to -- one of these algorithms, the result is an output called a message -- digest. The message digests range in length from 224 to 512 bits, -- depending on the algorithm. Secure hash algorithms are typically -- used with other cryptographic algorithms, such as digital signature -- algorithms and keyed hash authentication codes, or in the generation -- of random numbers [RFC4086]. -- -- The four algorithms specified in this document are called secure -- because it is computationally infeasible to (1) find a message that -- corresponds to a given message digest, or (2) find two different -- messages that produce the same message digest. Any change to a -- message in transit will, with very high probability, result in a -- different message digest. This will result in a verification failure -- when the secure hash algorithm is used with a digital signature -- algorithm or a keyed-hash message authentication algorithm. -- -- The code provided herein supports input strings of arbitrary bit -- length. SHA-1's sample code from [RFC3174] has also been updated to -- handle input strings of arbitrary bit length. See Section 1.1 for -- license information for this code. -- -- Section 2 below defines the terminology and functions used as -- building blocks to form these algorithms. Section 3 describes the -- fundamental operations on words from which these algorithms are -- built. Section 4 describes how messages are padded up to an integral -- multiple of the required block size and then parsed into blocks. -- Section 5 defines the constants and the composite functions used to -- specify these algorithms. Section 6 gives the actual specification -- for the SHA-224, SHA-256, SHA-384, and SHA-512 functions. Section 7 -- provides pointers to the specification of HMAC keyed message -- authentication codes based on the SHA algorithms. Section 8 gives -- sample code for the SHA algorithms and Section 9 code for SHA-based -- HMACs. The SHA-based HMACs will accept arbitrary bit length text. -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 3] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --1.1. License -- -- Permission is granted for all uses, commercial and non-commercial, of -- the sample code found in Section 8. Royalty free license to use, -- copy, modify and distribute the software found in Section 8 is -- granted, provided that this document is identified in all material -- mentioning or referencing this software, and provided that -- redistributed derivative works do not contain misleading author or -- version information. -- -- The authors make no representations concerning either the -- merchantability of this software or the suitability of this software -- for any particular purpose. It is provided "as is" without express -- or implied warranty of any kind. -- --2. Notation for Bit Strings and Integers -- -- The following terminology related to bit strings and integers will be -- used: -- -- a. A hex digit is an element of the set {0, 1, ... , 9, A, ... , -- F}. A hex digit is the representation of a 4-bit string. -- Examples: 7 = 0111, A = 1010. -- -- b. A word equals a 32-bit or 64-bit string, which may be -- represented as a sequence of 8 or 16 hex digits, respectively. -- To convert a word to hex digits, each 4-bit string is converted -- to its hex equivalent as described in (a) above. Example: -- -- 1010 0001 0000 0011 1111 1110 0010 0011 = A103FE23. -- -- Throughout this document, the "big-endian" convention is used -- when expressing both 32-bit and 64-bit words, so that within -- each word the most significant bit is shown in the left-most bit -- position. -- -- c. An integer may be represented as a word or pair of words. -- -- An integer between 0 and 2^32 - 1 inclusive may be represented -- as a 32-bit word. The least significant four bits of the -- integer are represented by the right-most hex digit of the word -- representation. Example: the integer 291 = 2^8+2^5+2^1+2^0 = -- 256+32+2+1 is represented by the hex word 00000123. -- -- The same holds true for an integer between 0 and 2^64-1 -- inclusive, which may be represented as a 64-bit word. -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 4] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- If Z is an integer, 0 <= z < 2^64, then z = (2^32)x + y where 0 -- <= x < 2^32 and 0 <= y < 2^32. Since x and y can be represented -- as words X and Y, respectively, z can be represented as the pair -- of words (X,Y). -- -- d. block = 512-bit or 1024-bit string. A block (e.g., B) may be -- represented as a sequence of 32-bit or 64-bit words. -- --3. Operations on Words -- -- The following logical operators will be applied to words in all four -- hash operations specified herein. SHA-224 and SHA-256 operate on -- 32-bit words, while SHA-384 and SHA-512 operate on 64-bit words. -- -- In the operations below, x<>n -- -- d. The rotate right (circular right shift) operation ROTR^n(x), -- where x is a w-bit word and n is an integer with 0 <= n < w, is -- defined by -- -- ROTR^n(x) = (x>>n) OR (x<<(w-n)) -- -- e. The rotate left (circular left shift) operation ROTL^n(x), where -- x is a w-bit word and n is an integer with 0 <= n < w, is -- defined by -- -- ROTL^n(X) = (x<>w-n) -- -- Note the following equivalence relationships, where w is fixed -- in each relationship: -- -- ROTL^n(x) = ROTR^(w-x)(x) -- -- ROTR^n(x) = ROTL^(w-n)(x) -- --4. Message Padding and Parsing -- -- The hash functions specified herein are used to compute a message -- digest for a message or data file that is provided as input. The -- message or data file should be considered to be a bit string. The -- length of the message is the number of bits in the message (the empty -- message has length 0). If the number of bits in a message is a -- multiple of 8, for compactness we can represent the message in hex. -- The purpose of message padding is to make the total length of a -- padded message a multiple of 512 for SHA-224 and SHA-256 or a -- multiple of 1024 for SHA-384 and SHA-512. -- -- The following specifies how this padding shall be performed. As a -- summary, a "1" followed by a number of "0"s followed by a 64-bit or -- 128-bit integer are appended to the end of the message to produce a -- padded message of length 512*n or 1024*n. The minimum number of "0"s -- necessary to meet this criterion is used. The appended integer is -- the length of the original message. The padded message is then -- processed by the hash function as n 512-bit or 1024-bit blocks. -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 6] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --4.1. SHA-224 and SHA-256 -- -- Suppose a message has length L < 2^64. Before it is input to the -- hash function, the message is padded on the right as follows: -- -- a. "1" is appended. Example: if the original message is -- "01010000", this is padded to "010100001". -- -- b. K "0"s are appended where K is the smallest, non-negative -- solution to the equation -- -- L + 1 + K = 448 (mod 512) -- -- c. Then append the 64-bit block that is L in binary representation. -- After appending this block, the length of the message will be a -- multiple of 512 bits. -- -- Example: Suppose the original message is the bit string -- -- 01100001 01100010 01100011 01100100 01100101 -- -- After step (a), this gives -- -- 01100001 01100010 01100011 01100100 01100101 1 -- -- Since L = 40, the number of bits in the above is 41 and K = 407 -- "0"s are appended, making the total now 448. This gives the -- following in hex: -- -- 61626364 65800000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 -- -- The 64-bit representation of L = 40 is hex 00000000 00000028. -- Hence the final padded message is the following hex: -- -- 61626364 65800000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000028 -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 7] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --4.2. SHA-384 and SHA-512 -- -- Suppose a message has length L < 2^128. Before it is input to the -- hash function, the message is padded on the right as follows: -- -- a. "1" is appended. Example: if the original message is -- "01010000", this is padded to "010100001". -- -- b. K "0"s are appended where K is the smallest, non-negative -- solution to the equation -- -- L + 1 + K = 896 (mod 1024) -- -- c. Then append the 128-bit block that is L in binary -- representation. After appending this block, the length of the -- message will be a multiple of 1024 bits. -- -- Example: Suppose the original message is the bit string -- -- 01100001 01100010 01100011 01100100 01100101 -- -- After step (a) this gives -- -- 01100001 01100010 01100011 01100100 01100101 1 -- -- Since L = 40, the number of bits in the above is 41 and K = 855 -- "0"s are appended, making the total now 896. This gives the -- following in hex: -- -- 61626364 65800000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- -- The 128-bit representation of L = 40 is hex 00000000 00000000 -- 00000000 00000028. Hence the final padded message is the -- following hex: -- -- 61626364 65800000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 8] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000000 -- 00000000 00000000 00000000 00000028 -- --5. Functions and Constants Used -- -- The following subsections give the six logical functions and the -- table of constants used in each of the hash functions. -- --5.1. SHA-224 and SHA-256 -- -- SHA-224 and SHA-256 use six logical functions, where each function -- operates on 32-bit words, which are represented as x, y, and z. The -- result of each function is a new 32-bit word. -- -- CH( x, y, z) = (x AND y) XOR ( (NOT x) AND z) -- -- MAJ( x, y, z) = (x AND y) XOR (x AND z) XOR (y AND z) -- -- BSIG0(x) = ROTR^2(x) XOR ROTR^13(x) XOR ROTR^22(x) -- -- BSIG1(x) = ROTR^6(x) XOR ROTR^11(x) XOR ROTR^25(x) -- -- SSIG0(x) = ROTR^7(x) XOR ROTR^18(x) XOR SHR^3(x) -- -- SSIG1(x) = ROTR^17(x) XOR ROTR^19(x) XOR SHR^10(x) -- -- SHA-224 and SHA-256 use the same sequence of sixty-four constant -- 32-bit words, K0, K1, ..., K63. These words represent the first -- thirty-two bits of the fractional parts of the cube roots of the -- first sixty-four prime numbers. In hex, these constant words are as -- follows (from left to right): -- -- 428a2f98 71374491 b5c0fbcf e9b5dba5 -- 3956c25b 59f111f1 923f82a4 ab1c5ed5 -- d807aa98 12835b01 243185be 550c7dc3 -- 72be5d74 80deb1fe 9bdc06a7 c19bf174 -- e49b69c1 efbe4786 0fc19dc6 240ca1cc -- 2de92c6f 4a7484aa 5cb0a9dc 76f988da -- 983e5152 a831c66d b00327c8 bf597fc7 -- c6e00bf3 d5a79147 06ca6351 14292967 -- 27b70a85 2e1b2138 4d2c6dfc 53380d13 -- 650a7354 766a0abb 81c2c92e 92722c85 -- a2bfe8a1 a81a664b c24b8b70 c76c51a3 -- d192e819 d6990624 f40e3585 106aa070 -- 19a4c116 1e376c08 2748774c 34b0bcb5 -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 9] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- 391c0cb3 4ed8aa4a 5b9cca4f 682e6ff3 -- 748f82ee 78a5636f 84c87814 8cc70208 -- 90befffa a4506ceb bef9a3f7 c67178f2 -- --5.2. SHA-384 and SHA-512 -- -- SHA-384 and SHA-512 each use six logical functions, where each -- function operates on 64-bit words, which are represented as x, y, and -- z. The result of each function is a new 64-bit word. -- -- CH( x, y, z) = (x AND y) XOR ( (NOT x) AND z) -- -- MAJ( x, y, z) = (x AND y) XOR (x AND z) XOR (y AND z) -- -- BSIG0(x) = ROTR^28(x) XOR ROTR^34(x) XOR ROTR^39(x) -- -- BSIG1(x) = ROTR^14(x) XOR ROTR^18(x) XOR ROTR^41(x) -- -- SSIG0(x) = ROTR^1(x) XOR ROTR^8(x) XOR SHR^7(x) -- -- SSIG1(x) = ROTR^19(x) XOR ROTR^61(x) XOR SHR^6(x) -- -- SHA-384 and SHA-512 use the same sequence of eighty constant 64-bit -- words, K0, K1, ... K79. These words represent the first sixty-four -- bits of the fractional parts of the cube roots of the first eighty -- prime numbers. In hex, these constant words are as follows (from -- left to right): -- -- 428a2f98d728ae22 7137449123ef65cd b5c0fbcfec4d3b2f e9b5dba58189dbbc -- 3956c25bf348b538 59f111f1b605d019 923f82a4af194f9b ab1c5ed5da6d8118 -- d807aa98a3030242 12835b0145706fbe 243185be4ee4b28c 550c7dc3d5ffb4e2 -- 72be5d74f27b896f 80deb1fe3b1696b1 9bdc06a725c71235 c19bf174cf692694 -- e49b69c19ef14ad2 efbe4786384f25e3 0fc19dc68b8cd5b5 240ca1cc77ac9c65 -- 2de92c6f592b0275 4a7484aa6ea6e483 5cb0a9dcbd41fbd4 76f988da831153b5 -- 983e5152ee66dfab a831c66d2db43210 b00327c898fb213f bf597fc7beef0ee4 -- c6e00bf33da88fc2 d5a79147930aa725 06ca6351e003826f 142929670a0e6e70 -- 27b70a8546d22ffc 2e1b21385c26c926 4d2c6dfc5ac42aed 53380d139d95b3df -- 650a73548baf63de 766a0abb3c77b2a8 81c2c92e47edaee6 92722c851482353b -- a2bfe8a14cf10364 a81a664bbc423001 c24b8b70d0f89791 c76c51a30654be30 -- d192e819d6ef5218 d69906245565a910 f40e35855771202a 106aa07032bbd1b8 -- 19a4c116b8d2d0c8 1e376c085141ab53 2748774cdf8eeb99 34b0bcb5e19b48a8 -- 391c0cb3c5c95a63 4ed8aa4ae3418acb 5b9cca4f7763e373 682e6ff3d6b2b8a3 -- 748f82ee5defb2fc 78a5636f43172f60 84c87814a1f0ab72 8cc702081a6439ec -- 90befffa23631e28 a4506cebde82bde9 bef9a3f7b2c67915 c67178f2e372532b -- ca273eceea26619c d186b8c721c0c207 eada7dd6cde0eb1e f57d4f7fee6ed178 -- 06f067aa72176fba 0a637dc5a2c898a6 113f9804bef90dae 1b710b35131c471b -- 28db77f523047d84 32caab7b40c72493 3c9ebe0a15c9bebc 431d67c49c100d4c -- 4cc5d4becb3e42b6 597f299cfc657e2a 5fcb6fab3ad6faec 6c44198c4a475817 -- -- -- --Eastlake 3rd & Hansen Informational [Page 10] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --6. Computing the Message Digest -- -- The output of each of the secure hash functions, after being applied -- to a message of N blocks, is the hash quantity H(N). For SHA-224 and -- SHA-256, H(i) can be considered to be eight 32-bit words, H(i)0, -- H(i)1, ... H(i)7. For SHA-384 and SHA-512, it can be considered to -- be eight 64-bit words, H(i)0, H(i)1, ..., H(i)7. -- -- As described below, the hash words are initialized, modified as each -- message block is processed, and finally concatenated after processing -- the last block to yield the output. For SHA-256 and SHA-512, all of -- the H(N) variables are concatenated while the SHA-224 and SHA-384 -- hashes are produced by omitting some from the final concatenation. -- --6.1. SHA-224 and SHA-256 Initialization -- -- For SHA-224, the initial hash value, H(0), consists of the following -- 32-bit words in hex: -- -- H(0)0 = c1059ed8 -- H(0)1 = 367cd507 -- H(0)2 = 3070dd17 -- H(0)3 = f70e5939 -- H(0)4 = ffc00b31 -- H(0)5 = 68581511 -- H(0)6 = 64f98fa7 -- H(0)7 = befa4fa4 -- -- For SHA-256, the initial hash value, H(0), consists of the following -- eight 32-bit words, in hex. These words were obtained by taking the -- first thirty-two bits of the fractional parts of the square roots of -- the first eight prime numbers. -- -- H(0)0 = 6a09e667 -- H(0)1 = bb67ae85 -- H(0)2 = 3c6ef372 -- H(0)3 = a54ff53a -- H(0)4 = 510e527f -- H(0)5 = 9b05688c -- H(0)6 = 1f83d9ab -- H(0)7 = 5be0cd19 -- --6.2. SHA-224 and SHA-256 Processing -- -- SHA-224 and SHA-256 perform identical processing on messages blocks -- and differ only in how H(0) is initialized and how they produce their -- final output. They may be used to hash a message, M, having a length -- of L bits, where 0 <= L < 2^64. The algorithm uses (1) a message -- -- -- --Eastlake 3rd & Hansen Informational [Page 11] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- schedule of sixty-four 32-bit words, (2) eight working variables of -- 32 bits each, and (3) a hash value of eight 32-bit words. -- -- The words of the message schedule are labeled W0, W1, ..., W63. The -- eight working variables are labeled a, b, c, d, e, f, g, and h. The -- words of the hash value are labeled H(i)0, H(i)1, ..., H(i)7, which -- will hold the initial hash value, H(0), replaced by each successive -- intermediate hash value (after each message block is processed), -- H(i), and ending with the final hash value, H(N), after all N blocks -- are processed. They also use two temporary words, T1 and T2. -- -- The input message is padded as described in Section 4.1 above then -- parsed into 512-bit blocks, which are considered to be composed of 16 -- 32-bit words M(i)0, M(i)1, ..., M(i)15. The following computations -- are then performed for each of the N message blocks. All addition is -- performed modulo 2^32. -- -- For i = 1 to N -- -- 1. Prepare the message schedule W: -- For t = 0 to 15 -- Wt = M(i)t -- For t = 16 to 63 -- Wt = SSIG1(W(t-2)) + W(t-7) + SSIG0(t-15) + W(t-16) -- -- 2. Initialize the working variables: -- a = H(i-1)0 -- b = H(i-1)1 -- c = H(i-1)2 -- d = H(i-1)3 -- e = H(i-1)4 -- f = H(i-1)5 -- g = H(i-1)6 -- h = H(i-1)7 -- -- 3. Perform the main hash computation: -- For t = 0 to 63 -- T1 = h + BSIG1(e) + CH(e,f,g) + Kt + Wt -- T2 = BSIG0(a) + MAJ(a,b,c) -- h = g -- g = f -- f = e -- e = d + T1 -- d = c -- c = b -- b = a -- a = T1 + T2 -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 12] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- 4. Compute the intermediate hash value H(i): -- H(i)0 = a + H(i-1)0 -- H(i)1 = b + H(i-1)1 -- H(i)2 = c + H(i-1)2 -- H(i)3 = d + H(i-1)3 -- H(i)4 = e + H(i-1)4 -- H(i)5 = f + H(i-1)5 -- H(i)6 = g + H(i-1)6 -- H(i)7 = h + H(i-1)7 -- -- After the above computations have been sequentially performed for all -- of the blocks in the message, the final output is calculated. For -- SHA-256, this is the concatenation of all of H(N)0, H(N)1, through -- H(N)7. For SHA-224, this is the concatenation of H(N)0, H(N)1, -- through H(N)6. -- --6.3. SHA-384 and SHA-512 Initialization -- -- For SHA-384, the initial hash value, H(0), consists of the following -- eight 64-bit words, in hex. These words were obtained by taking the -- first sixty-four bits of the fractional parts of the square roots of -- the ninth through sixteenth prime numbers. -- -- H(0)0 = cbbb9d5dc1059ed8 -- H(0)1 = 629a292a367cd507 -- H(0)2 = 9159015a3070dd17 -- H(0)3 = 152fecd8f70e5939 -- H(0)4 = 67332667ffc00b31 -- H(0)5 = 8eb44a8768581511 -- H(0)6 = db0c2e0d64f98fa7 -- H(0)7 = 47b5481dbefa4fa4 -- -- For SHA-512, the initial hash value, H(0), consists of the following -- eight 64-bit words, in hex. These words were obtained by taking the -- first sixty-four bits of the fractional parts of the square roots of -- the first eight prime numbers. -- -- H(0)0 = 6a09e667f3bcc908 -- H(0)1 = bb67ae8584caa73b -- H(0)2 = 3c6ef372fe94f82b -- H(0)3 = a54ff53a5f1d36f1 -- H(0)4 = 510e527fade682d1 -- H(0)5 = 9b05688c2b3e6c1f -- H(0)6 = 1f83d9abfb41bd6b -- H(0)7 = 5be0cd19137e2179 -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 13] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --6.4. SHA-384 and SHA-512 Processing -- -- SHA-384 and SHA-512 perform identical processing on message blocks -- and differ only in how H(0) is initialized and how they produce their -- final output. They may be used to hash a message, M, having a length -- of L bits, where 0 <= L < 2^128. The algorithm uses (1) a message -- schedule of eighty 64-bit words, (2) eight working variables of 64 -- bits each, and (3) a hash value of eight 64-bit words. -- -- The words of the message schedule are labeled W0, W1, ..., W79. The -- eight working variables are labeled a, b, c, d, e, f, g, and h. The -- words of the hash value are labeled H(i)0, H(i)1, ..., H(i)7, which -- will hold the initial hash value, H(0), replaced by each successive -- intermediate hash value (after each message block is processed), -- H(i), and ending with the final hash value, H(N) after all N blocks -- are processed. -- -- The input message is padded as described in Section 4.2 above, then -- parsed into 1024-bit blocks, which are considered to be composed of -- 16 64-bit words M(i)0, M(i)1, ..., M(i)15. The following -- computations are then performed for each of the N message blocks. -- All addition is performed modulo 2^64. -- -- For i = 1 to N -- -- 1. Prepare the message schedule W: -- For t = 0 to 15 -- Wt = M(i)t -- For t = 16 to 79 -- Wt = SSIG1(W(t-2)) + W(t-7) + SSIG0(t-15) + W(t-16) -- -- 2. Initialize the working variables: -- a = H(i-1)0 -- b = H(i-1)1 -- c = H(i-1)2 -- d = H(i-1)3 -- e = H(i-1)4 -- f = H(i-1)5 -- g = H(i-1)6 -- h = H(i-1)7 -- -- 3. Perform the main hash computation: -- For t = 0 to 79 -- T1 = h + BSIG1(e) + CH(e,f,g) + Kt + Wt -- T2 = BSIG0(a) + MAJ(a,b,c) -- h = g -- g = f -- f = e -- -- -- --Eastlake 3rd & Hansen Informational [Page 14] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- e = d + T1 -- d = c -- c = b -- b = a -- a = T1 + T2 -- -- 4. Compute the intermediate hash value H(i): -- H(i)0 = a + H(i-1)0 -- H(i)1 = b + H(i-1)1 -- H(i)2 = c + H(i-1)2 -- H(i)3 = d + H(i-1)3 -- H(i)4 = e + H(i-1)4 -- H(i)5 = f + H(i-1)5 -- H(i)6 = g + H(i-1)6 -- H(i)7 = h + H(i-1)7 -- -- After the above computations have been sequentially performed for all -- of the blocks in the message, the final output is calculated. For -- SHA-512, this is the concatenation of all of H(N)0, H(N)1, through -- H(N)7. For SHA-384, this is the concatenation of H(N)0, H(N)1, -- through H(N)5. -- --7. SHA-Based HMACs -- -- HMAC is a method for computing a keyed MAC (message authentication -- code) using a hash function as described in [RFC2104]. It uses a key -- to mix in with the input text to produce the final hash. -- -- Sample code is also provided, in Section 8.3 below, to perform HMAC -- based on any of the SHA algorithms described herein. The sample code -- found in [RFC2104] was written in terms of a specified text size. -- Since SHA is defined in terms of an arbitrary number of bits, the -- sample HMAC code has been written to allow the text input to HMAC to -- have an arbitrary number of octets and bits. A fixed-length -- interface is also provided. -- --8. C Code for SHAs -- -- Below is a demonstration implementation of these secure hash -- functions in C. Section 8.1 contains the header file sha.h, which -- declares all constants, structures, and functions used by the sha and -- hmac functions. Section 8.2 contains the C code for sha1.c, -- sha224-256.c, sha384-512.c, and usha.c along with sha-private.h, -- which provides some declarations common to all the sha functions. -- Section 8.3 contains the C code for the hmac functions. Section 8.4 -- contains a test driver to exercise the code. -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 15] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- For each of the digest length $$$, there is the following set of -- constants, a structure, and functions: -- -- Constants: -- SHA$$$HashSize number of octets in the hash -- SHA$$$HashSizeBits number of bits in the hash -- SHA$$$_Message_Block_Size -- number of octets used in the intermediate -- message blocks -- shaSuccess = 0 constant returned by each function on success -- shaNull = 1 constant returned by each function when -- presented with a null pointer parameter -- shaInputTooLong = 2 constant returned by each function when the -- input data is too long -- shaStateError constant returned by each function when -- SHA$$$Input is called after SHA$$$FinalBits or -- SHA$$$Result. -- -- Structure: -- typedef SHA$$$Context -- an opaque structure holding the complete state -- for producing the hash -- -- Functions: -- int SHA$$$Reset(SHA$$$Context *); -- Reset the hash context state -- int SHA$$$Input(SHA$$$Context *, const uint8_t *octets, -- unsigned int bytecount); -- Incorporate bytecount octets into the hash. -- int SHA$$$FinalBits(SHA$$$Context *, const uint8_t octet, -- unsigned int bitcount); -- Incorporate bitcount bits into the hash. The bits are in -- the upper portion of the octet. SHA$$$Input() cannot be -- called after this. -- int SHA$$$Result(SHA$$$Context *, -- uint8_t Message_Digest[SHA$$$HashSize]); -- Do the final calculations on the hash and copy the value -- into Message_Digest. -- -- In addition, functions with the prefix USHA are provided that take a -- SHAversion value (SHA$$$) to select the SHA function suite. They add -- the following constants, structure, and functions: -- -- Constants: -- shaBadParam constant returned by USHA functions when -- presented with a bad SHAversion (SHA$$$) -- parameter -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 16] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- SHA$$$ SHAversion enumeration values, used by usha -- and hmac functions to select the SHA function -- suite -- -- Structure: -- typedef USHAContext -- an opaque structure holding the complete state -- for producing the hash -- -- Functions: -- int USHAReset(USHAContext *, SHAversion whichSha); -- Reset the hash context state. -- int USHAInput(USHAContext *, -- const uint8_t *bytes, unsigned int bytecount); -- Incorporate bytecount octets into the hash. -- int USHAFinalBits(USHAContext *, -- const uint8_t bits, unsigned int bitcount); -- Incorporate bitcount bits into the hash. -- int USHAResult(USHAContext *, -- uint8_t Message_Digest[USHAMaxHashSize]); -- Do the final calculations on the hash and copy the value -- into Message_Digest. Octets in Message_Digest beyond -- USHAHashSize(whichSha) are left untouched. -- int USHAHashSize(enum SHAversion whichSha); -- The number of octets in the given hash. -- int USHAHashSizeBits(enum SHAversion whichSha); -- The number of bits in the given hash. -- int USHABlockSize(enum SHAversion whichSha); -- The internal block size for the given hash. -- -- The hmac functions follow the same pattern to allow any length of -- text input to be used. -- -- Structure: -- typedef HMACContext an opaque structure holding the complete state -- for producing the hash -- -- Functions: -- int hmacReset(HMACContext *ctx, enum SHAversion whichSha, -- const unsigned char *key, int key_len); -- Reset the hash context state. -- int hmacInput(HMACContext *ctx, const unsigned char *text, -- int text_len); -- Incorporate text_len octets into the hash. -- int hmacFinalBits(HMACContext *ctx, const uint8_t bits, -- unsigned int bitcount); -- Incorporate bitcount bits into the hash. -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 17] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- int hmacResult(HMACContext *ctx, -- uint8_t Message_Digest[USHAMaxHashSize]); -- Do the final calculations on the hash and copy the value -- into Message_Digest. Octets in Message_Digest beyond -- USHAHashSize(whichSha) are left untouched. -- -- In addition, a combined interface is provided, similar to that shown -- in RFC 2104, that allows a fixed-length text input to be used. -- -- int hmac(SHAversion whichSha, -- const unsigned char *text, int text_len, -- const unsigned char *key, int key_len, -- uint8_t Message_Digest[USHAMaxHashSize]); -- Calculate the given digest for the given text and key, and -- return the resulting hash. Octets in Message_Digest beyond -- USHAHashSize(whichSha) are left untouched. -- --8.1. The .h File -- --/**************************** sha.h ****************************/ --/******************* See RFC 4634 for details ******************/ --#ifndef _SHA_H_ --#define _SHA_H_ -- --/* -- * Description: -- * This file implements the Secure Hash Signature Standard -- * algorithms as defined in the National Institute of Standards -- * and Technology Federal Information Processing Standards -- * Publication (FIPS PUB) 180-1 published on April 17, 1995, 180-2 -- * published on August 1, 2002, and the FIPS PUB 180-2 Change -- * Notice published on February 28, 2004. -- * -- * A combined document showing all algorithms is available at -- * http://csrc.nist.gov/publications/fips/ -- * fips180-2/fips180-2withchangenotice.pdf -- * -- * The five hashes are defined in these sizes: -- * SHA-1 20 byte / 160 bit -- * SHA-224 28 byte / 224 bit -- * SHA-256 32 byte / 256 bit -- * SHA-384 48 byte / 384 bit -- * SHA-512 64 byte / 512 bit -- */ -- --#include --/* -- * If you do not have the ISO standard stdint.h header file, then you -- -- -- --Eastlake 3rd & Hansen Informational [Page 18] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * must typedef the following: -- * name meaning -- * uint64_t unsigned 64 bit integer -- * uint32_t unsigned 32 bit integer -- * uint8_t unsigned 8 bit integer (i.e., unsigned char) -- * int_least16_t integer of >= 16 bits -- * -- */ -- --#ifndef _SHA_enum_ --#define _SHA_enum_ --/* -- * All SHA functions return one of these values. -- */ --enum { -- shaSuccess = 0, -- shaNull, /* Null pointer parameter */ -- shaInputTooLong, /* input data too long */ -- shaStateError, /* called Input after FinalBits or Result */ -- shaBadParam /* passed a bad parameter */ --}; --#endif /* _SHA_enum_ */ -- --/* -- * These constants hold size information for each of the SHA -- * hashing operations -- */ --enum { -- SHA1_Message_Block_Size = 64, SHA224_Message_Block_Size = 64, -- SHA256_Message_Block_Size = 64, SHA384_Message_Block_Size = 128, -- SHA512_Message_Block_Size = 128, -- USHA_Max_Message_Block_Size = SHA512_Message_Block_Size, -- -- SHA1HashSize = 20, SHA224HashSize = 28, SHA256HashSize = 32, -- SHA384HashSize = 48, SHA512HashSize = 64, -- USHAMaxHashSize = SHA512HashSize, -- -- SHA1HashSizeBits = 160, SHA224HashSizeBits = 224, -- SHA256HashSizeBits = 256, SHA384HashSizeBits = 384, -- SHA512HashSizeBits = 512, USHAMaxHashSizeBits = SHA512HashSizeBits --}; -- --/* -- * These constants are used in the USHA (unified sha) functions. -- */ --typedef enum SHAversion { -- SHA1, SHA224, SHA256, SHA384, SHA512 --} SHAversion; -- -- -- --Eastlake 3rd & Hansen Informational [Page 19] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * This structure will hold context information for the SHA-1 -- * hashing operation. -- */ --typedef struct SHA1Context { -- uint32_t Intermediate_Hash[SHA1HashSize/4]; /* Message Digest */ -- -- uint32_t Length_Low; /* Message length in bits */ -- uint32_t Length_High; /* Message length in bits */ -- -- int_least16_t Message_Block_Index; /* Message_Block array index */ -- /* 512-bit message blocks */ -- uint8_t Message_Block[SHA1_Message_Block_Size]; -- -- int Computed; /* Is the digest computed? */ -- int Corrupted; /* Is the digest corrupted? */ --} SHA1Context; -- --/* -- * This structure will hold context information for the SHA-256 -- * hashing operation. -- */ --typedef struct SHA256Context { -- uint32_t Intermediate_Hash[SHA256HashSize/4]; /* Message Digest */ -- -- uint32_t Length_Low; /* Message length in bits */ -- uint32_t Length_High; /* Message length in bits */ -- -- int_least16_t Message_Block_Index; /* Message_Block array index */ -- /* 512-bit message blocks */ -- uint8_t Message_Block[SHA256_Message_Block_Size]; -- -- int Computed; /* Is the digest computed? */ -- int Corrupted; /* Is the digest corrupted? */ --} SHA256Context; -- --/* -- * This structure will hold context information for the SHA-512 -- * hashing operation. -- */ --typedef struct SHA512Context { --#ifdef USE_32BIT_ONLY -- uint32_t Intermediate_Hash[SHA512HashSize/4]; /* Message Digest */ -- uint32_t Length[4]; /* Message length in bits */ --#else /* !USE_32BIT_ONLY */ -- uint64_t Intermediate_Hash[SHA512HashSize/8]; /* Message Digest */ -- uint64_t Length_Low, Length_High; /* Message length in bits */ --#endif /* USE_32BIT_ONLY */ -- -- -- --Eastlake 3rd & Hansen Informational [Page 20] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- int_least16_t Message_Block_Index; /* Message_Block array index */ -- /* 1024-bit message blocks */ -- uint8_t Message_Block[SHA512_Message_Block_Size]; -- -- int Computed; /* Is the digest computed?*/ -- int Corrupted; /* Is the digest corrupted? */ --} SHA512Context; -- --/* -- * This structure will hold context information for the SHA-224 -- * hashing operation. It uses the SHA-256 structure for computation. -- */ --typedef struct SHA256Context SHA224Context; -- --/* -- * This structure will hold context information for the SHA-384 -- * hashing operation. It uses the SHA-512 structure for computation. -- */ --typedef struct SHA512Context SHA384Context; -- --/* -- * This structure holds context information for all SHA -- * hashing operations. -- */ --typedef struct USHAContext { -- int whichSha; /* which SHA is being used */ -- union { -- SHA1Context sha1Context; -- SHA224Context sha224Context; SHA256Context sha256Context; -- SHA384Context sha384Context; SHA512Context sha512Context; -- } ctx; --} USHAContext; -- --/* -- * This structure will hold context information for the HMAC -- * keyed hashing operation. -- */ --typedef struct HMACContext { -- int whichSha; /* which SHA is being used */ -- int hashSize; /* hash size of SHA being used */ -- int blockSize; /* block size of SHA being used */ -- USHAContext shaContext; /* SHA context */ -- unsigned char k_opad[USHA_Max_Message_Block_Size]; -- /* outer padding - key XORd with opad */ --} HMACContext; -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 21] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * Function Prototypes -- */ -- --/* SHA-1 */ --extern int SHA1Reset(SHA1Context *); --extern int SHA1Input(SHA1Context *, const uint8_t *bytes, -- unsigned int bytecount); --extern int SHA1FinalBits(SHA1Context *, const uint8_t bits, -- unsigned int bitcount); --extern int SHA1Result(SHA1Context *, -- uint8_t Message_Digest[SHA1HashSize]); -- --/* SHA-224 */ --extern int SHA224Reset(SHA224Context *); --extern int SHA224Input(SHA224Context *, const uint8_t *bytes, -- unsigned int bytecount); --extern int SHA224FinalBits(SHA224Context *, const uint8_t bits, -- unsigned int bitcount); --extern int SHA224Result(SHA224Context *, -- uint8_t Message_Digest[SHA224HashSize]); -- --/* SHA-256 */ --extern int SHA256Reset(SHA256Context *); --extern int SHA256Input(SHA256Context *, const uint8_t *bytes, -- unsigned int bytecount); --extern int SHA256FinalBits(SHA256Context *, const uint8_t bits, -- unsigned int bitcount); --extern int SHA256Result(SHA256Context *, -- uint8_t Message_Digest[SHA256HashSize]); -- --/* SHA-384 */ --extern int SHA384Reset(SHA384Context *); --extern int SHA384Input(SHA384Context *, const uint8_t *bytes, -- unsigned int bytecount); --extern int SHA384FinalBits(SHA384Context *, const uint8_t bits, -- unsigned int bitcount); --extern int SHA384Result(SHA384Context *, -- uint8_t Message_Digest[SHA384HashSize]); -- --/* SHA-512 */ --extern int SHA512Reset(SHA512Context *); --extern int SHA512Input(SHA512Context *, const uint8_t *bytes, -- unsigned int bytecount); --extern int SHA512FinalBits(SHA512Context *, const uint8_t bits, -- unsigned int bitcount); --extern int SHA512Result(SHA512Context *, -- uint8_t Message_Digest[SHA512HashSize]); -- -- -- --Eastlake 3rd & Hansen Informational [Page 22] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* Unified SHA functions, chosen by whichSha */ --extern int USHAReset(USHAContext *, SHAversion whichSha); --extern int USHAInput(USHAContext *, -- const uint8_t *bytes, unsigned int bytecount); --extern int USHAFinalBits(USHAContext *, -- const uint8_t bits, unsigned int bitcount); --extern int USHAResult(USHAContext *, -- uint8_t Message_Digest[USHAMaxHashSize]); --extern int USHABlockSize(enum SHAversion whichSha); --extern int USHAHashSize(enum SHAversion whichSha); --extern int USHAHashSizeBits(enum SHAversion whichSha); -- --/* -- * HMAC Keyed-Hashing for Message Authentication, RFC2104, -- * for all SHAs. -- * This interface allows a fixed-length text input to be used. -- */ --extern int hmac(SHAversion whichSha, /* which SHA algorithm to use */ -- const unsigned char *text, /* pointer to data stream */ -- int text_len, /* length of data stream */ -- const unsigned char *key, /* pointer to authentication key */ -- int key_len, /* length of authentication key */ -- uint8_t digest[USHAMaxHashSize]); /* caller digest to fill in */ -- --/* -- * HMAC Keyed-Hashing for Message Authentication, RFC2104, -- * for all SHAs. -- * This interface allows any length of text input to be used. -- */ --extern int hmacReset(HMACContext *ctx, enum SHAversion whichSha, -- const unsigned char *key, int key_len); --extern int hmacInput(HMACContext *ctx, const unsigned char *text, -- int text_len); -- --extern int hmacFinalBits(HMACContext *ctx, const uint8_t bits, -- unsigned int bitcount); --extern int hmacResult(HMACContext *ctx, -- uint8_t digest[USHAMaxHashSize]); -- --#endif /* _SHA_H_ */ -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 23] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --8.2. The SHA Code -- -- This code is primarily intended as expository and could be optimized -- further. For example, the assignment rotations through the variables -- a, b, ..., h could be treated as a cycle and the loop unrolled, -- rather than doing the explicit copying. -- -- Note that there are alternative representations of the Ch() and Maj() -- functions controlled by an ifdef. -- --8.2.1. sha1.c -- --/**************************** sha1.c ****************************/ --/******************** See RFC 4634 for details ******************/ --/* -- * Description: -- * This file implements the Secure Hash Signature Standard -- * algorithms as defined in the National Institute of Standards -- * and Technology Federal Information Processing Standards -- * Publication (FIPS PUB) 180-1 published on April 17, 1995, 180-2 -- * published on August 1, 2002, and the FIPS PUB 180-2 Change -- * Notice published on February 28, 2004. -- * -- * A combined document showing all algorithms is available at -- * http://csrc.nist.gov/publications/fips/ -- * fips180-2/fips180-2withchangenotice.pdf -- * -- * The SHA-1 algorithm produces a 160-bit message digest for a -- * given data stream. It should take about 2**n steps to find a -- * message with the same digest as a given message and -- * 2**(n/2) to find any two messages with the same digest, -- * when n is the digest size in bits. Therefore, this -- * algorithm can serve as a means of providing a -- * "fingerprint" for a message. -- * -- * Portability Issues: -- * SHA-1 is defined in terms of 32-bit "words". This code -- * uses (included via "sha.h") to define 32 and 8 -- * bit unsigned integer types. If your C compiler does not -- * support 32 bit unsigned integers, this code is not -- * appropriate. -- * -- * Caveats: -- * SHA-1 is designed to work with messages less than 2^64 bits -- * long. This implementation uses SHA1Input() to hash the bits -- * that are a multiple of the size of an 8-bit character, and then -- * uses SHA1FinalBits() to hash the final few bits of the input. -- */ -- -- -- --Eastlake 3rd & Hansen Informational [Page 24] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --#include "sha.h" --#include "sha-private.h" -- --/* -- * Define the SHA1 circular left shift macro -- */ --#define SHA1_ROTL(bits,word) \ -- (((word) << (bits)) | ((word) >> (32-(bits)))) -- --/* -- * add "length" to the length -- */ --static uint32_t addTemp; --#define SHA1AddLength(context, length) \ -- (addTemp = (context)->Length_Low, \ -- (context)->Corrupted = \ -- (((context)->Length_Low += (length)) < addTemp) && \ -- (++(context)->Length_High == 0) ? 1 : 0) -- --/* Local Function Prototypes */ --static void SHA1Finalize(SHA1Context *context, uint8_t Pad_Byte); --static void SHA1PadMessage(SHA1Context *, uint8_t Pad_Byte); --static void SHA1ProcessMessageBlock(SHA1Context *); -- --/* -- * SHA1Reset -- * -- * Description: -- * This function will initialize the SHA1Context in preparation -- * for computing a new SHA1 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA1Reset(SHA1Context *context) --{ -- if (!context) -- return shaNull; -- -- context->Length_Low = 0; -- context->Length_High = 0; -- context->Message_Block_Index = 0; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 25] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- /* Initial Hash Values: FIPS-180-2 section 5.3.1 */ -- context->Intermediate_Hash[0] = 0x67452301; -- context->Intermediate_Hash[1] = 0xEFCDAB89; -- context->Intermediate_Hash[2] = 0x98BADCFE; -- context->Intermediate_Hash[3] = 0x10325476; -- context->Intermediate_Hash[4] = 0xC3D2E1F0; -- -- context->Computed = 0; -- context->Corrupted = 0; -- -- return shaSuccess; --} -- --/* -- * SHA1Input -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA1Input(SHA1Context *context, -- const uint8_t *message_array, unsigned length) --{ -- if (!length) -- return shaSuccess; -- -- if (!context || !message_array) -- return shaNull; -- -- if (context->Computed) { -- context->Corrupted = shaStateError; -- return shaStateError; -- } -- -- if (context->Corrupted) -- -- -- --Eastlake 3rd & Hansen Informational [Page 26] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- return context->Corrupted; -- -- while (length-- && !context->Corrupted) { -- context->Message_Block[context->Message_Block_Index++] = -- (*message_array & 0xFF); -- -- if (!SHA1AddLength(context, 8) && -- (context->Message_Block_Index == SHA1_Message_Block_Size)) -- SHA1ProcessMessageBlock(context); -- -- message_array++; -- } -- -- return shaSuccess; --} -- --/* -- * SHA1FinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA1FinalBits(SHA1Context *context, const uint8_t message_bits, -- unsigned int length) --{ -- uint8_t masks[8] = { -- /* 0 0b00000000 */ 0x00, /* 1 0b10000000 */ 0x80, -- /* 2 0b11000000 */ 0xC0, /* 3 0b11100000 */ 0xE0, -- /* 4 0b11110000 */ 0xF0, /* 5 0b11111000 */ 0xF8, -- /* 6 0b11111100 */ 0xFC, /* 7 0b11111110 */ 0xFE -- }; -- uint8_t markbit[8] = { -- /* 0 0b10000000 */ 0x80, /* 1 0b01000000 */ 0x40, -- /* 2 0b00100000 */ 0x20, /* 3 0b00010000 */ 0x10, -- /* 4 0b00001000 */ 0x08, /* 5 0b00000100 */ 0x04, -- -- -- --Eastlake 3rd & Hansen Informational [Page 27] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- /* 6 0b00000010 */ 0x02, /* 7 0b00000001 */ 0x01 -- }; -- -- if (!length) -- return shaSuccess; -- -- if (!context) -- return shaNull; -- -- if (context->Computed || (length >= 8) || (length == 0)) { -- context->Corrupted = shaStateError; -- return shaStateError; -- } -- -- if (context->Corrupted) -- return context->Corrupted; -- -- SHA1AddLength(context, length); -- SHA1Finalize(context, -- (uint8_t) ((message_bits & masks[length]) | markbit[length])); -- -- return shaSuccess; --} -- --/* -- * SHA1Result -- * -- * Description: -- * This function will return the 160-bit message digest into the -- * Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 19th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA-1 hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA1Result(SHA1Context *context, -- uint8_t Message_Digest[SHA1HashSize]) --{ -- int i; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 28] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- if (!context || !Message_Digest) -- return shaNull; -- -- if (context->Corrupted) -- return context->Corrupted; -- -- if (!context->Computed) -- SHA1Finalize(context, 0x80); -- -- for (i = 0; i < SHA1HashSize; ++i) -- Message_Digest[i] = (uint8_t) (context->Intermediate_Hash[i>>2] -- >> 8 * ( 3 - ( i & 0x03 ) )); -- -- return shaSuccess; --} -- --/* -- * SHA1Finalize -- * -- * Description: -- * This helper function finishes off the digest calculations. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * sha Error Code. -- * -- */ --static void SHA1Finalize(SHA1Context *context, uint8_t Pad_Byte) --{ -- int i; -- SHA1PadMessage(context, Pad_Byte); -- /* message may be sensitive, clear it out */ -- for (i = 0; i < SHA1_Message_Block_Size; ++i) -- context->Message_Block[i] = 0; -- context->Length_Low = 0; /* and clear length */ -- context->Length_High = 0; -- context->Computed = 1; --} -- --/* -- -- -- --Eastlake 3rd & Hansen Informational [Page 29] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * SHA1PadMessage -- * -- * Description: -- * According to the standard, the message must be padded to an -- * even 512 bits. The first padding bit must be a '1'. The last -- * 64 bits represent the length of the original message. All bits -- * in between should be 0. This helper function will pad the -- * message according to those rules by filling the Message_Block -- * array accordingly. When it returns, it can be assumed that the -- * message digest has been computed. -- * -- * Parameters: -- * context: [in/out] -- * The context to pad -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * Nothing. -- */ --static void SHA1PadMessage(SHA1Context *context, uint8_t Pad_Byte) --{ -- /* -- * Check to see if the current message block is too small to hold -- * the initial padding bits and length. If so, we will pad the -- * block, process it, and then continue padding into a second -- * block. -- */ -- if (context->Message_Block_Index >= (SHA1_Message_Block_Size - 8)) { -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- while (context->Message_Block_Index < SHA1_Message_Block_Size) -- context->Message_Block[context->Message_Block_Index++] = 0; -- -- SHA1ProcessMessageBlock(context); -- } else -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- -- while (context->Message_Block_Index < (SHA1_Message_Block_Size - 8)) -- context->Message_Block[context->Message_Block_Index++] = 0; -- -- /* -- * Store the message length as the last 8 octets -- */ -- context->Message_Block[56] = (uint8_t) (context->Length_High >> 24); -- context->Message_Block[57] = (uint8_t) (context->Length_High >> 16); -- -- -- --Eastlake 3rd & Hansen Informational [Page 30] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- context->Message_Block[58] = (uint8_t) (context->Length_High >> 8); -- context->Message_Block[59] = (uint8_t) (context->Length_High); -- context->Message_Block[60] = (uint8_t) (context->Length_Low >> 24); -- context->Message_Block[61] = (uint8_t) (context->Length_Low >> 16); -- context->Message_Block[62] = (uint8_t) (context->Length_Low >> 8); -- context->Message_Block[63] = (uint8_t) (context->Length_Low); -- -- SHA1ProcessMessageBlock(context); --} -- --/* -- * SHA1ProcessMessageBlock -- * -- * Description: -- * This helper function will process the next 512 bits of the -- * message stored in the Message_Block array. -- * -- * Parameters: -- * None. -- * -- * Returns: -- * Nothing. -- * -- * Comments: -- * Many of the variable names in this code, especially the -- * single character names, were used because those were the -- * names used in the publication. -- */ --static void SHA1ProcessMessageBlock(SHA1Context *context) --{ -- /* Constants defined in FIPS-180-2, section 4.2.1 */ -- const uint32_t K[4] = { -- 0x5A827999, 0x6ED9EBA1, 0x8F1BBCDC, 0xCA62C1D6 -- }; -- int t; /* Loop counter */ -- uint32_t temp; /* Temporary word value */ -- uint32_t W[80]; /* Word sequence */ -- uint32_t A, B, C, D, E; /* Word buffers */ -- -- /* -- * Initialize the first 16 words in the array W -- */ -- for (t = 0; t < 16; t++) { -- W[t] = ((uint32_t)context->Message_Block[t * 4]) << 24; -- W[t] |= ((uint32_t)context->Message_Block[t * 4 + 1]) << 16; -- W[t] |= ((uint32_t)context->Message_Block[t * 4 + 2]) << 8; -- W[t] |= ((uint32_t)context->Message_Block[t * 4 + 3]); -- } -- -- -- --Eastlake 3rd & Hansen Informational [Page 31] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- for (t = 16; t < 80; t++) -- W[t] = SHA1_ROTL(1, W[t-3] ^ W[t-8] ^ W[t-14] ^ W[t-16]); -- -- A = context->Intermediate_Hash[0]; -- B = context->Intermediate_Hash[1]; -- C = context->Intermediate_Hash[2]; -- D = context->Intermediate_Hash[3]; -- E = context->Intermediate_Hash[4]; -- -- for (t = 0; t < 20; t++) { -- temp = SHA1_ROTL(5,A) + SHA_Ch(B, C, D) + E + W[t] + K[0]; -- E = D; -- D = C; -- C = SHA1_ROTL(30,B); -- B = A; -- A = temp; -- } -- -- for (t = 20; t < 40; t++) { -- temp = SHA1_ROTL(5,A) + SHA_Parity(B, C, D) + E + W[t] + K[1]; -- E = D; -- D = C; -- C = SHA1_ROTL(30,B); -- B = A; -- A = temp; -- } -- -- for (t = 40; t < 60; t++) { -- temp = SHA1_ROTL(5,A) + SHA_Maj(B, C, D) + E + W[t] + K[2]; -- E = D; -- D = C; -- C = SHA1_ROTL(30,B); -- B = A; -- A = temp; -- } -- -- for (t = 60; t < 80; t++) { -- temp = SHA1_ROTL(5,A) + SHA_Parity(B, C, D) + E + W[t] + K[3]; -- E = D; -- D = C; -- C = SHA1_ROTL(30,B); -- B = A; -- A = temp; -- } -- -- context->Intermediate_Hash[0] += A; -- context->Intermediate_Hash[1] += B; -- context->Intermediate_Hash[2] += C; -- -- -- --Eastlake 3rd & Hansen Informational [Page 32] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- context->Intermediate_Hash[3] += D; -- context->Intermediate_Hash[4] += E; -- -- context->Message_Block_Index = 0; --} -- --8.2.2. sha224-256.c -- --/*************************** sha224-256.c ***************************/ --/********************* See RFC 4634 for details *********************/ --/* -- * Description: -- * This file implements the Secure Hash Signature Standard -- * algorithms as defined in the National Institute of Standards -- * and Technology Federal Information Processing Standards -- * Publication (FIPS PUB) 180-1 published on April 17, 1995, 180-2 -- * published on August 1, 2002, and the FIPS PUB 180-2 Change -- * Notice published on February 28, 2004. -- * -- * A combined document showing all algorithms is available at -- * http://csrc.nist.gov/publications/fips/ -- * fips180-2/fips180-2withchangenotice.pdf -- * -- * The SHA-224 and SHA-256 algorithms produce 224-bit and 256-bit -- * message digests for a given data stream. It should take about -- * 2**n steps to find a message with the same digest as a given -- * message and 2**(n/2) to find any two messages with the same -- * digest, when n is the digest size in bits. Therefore, this -- * algorithm can serve as a means of providing a -- * "fingerprint" for a message. -- * -- * Portability Issues: -- * SHA-224 and SHA-256 are defined in terms of 32-bit "words". -- * This code uses (included via "sha.h") to define 32 -- * and 8 bit unsigned integer types. If your C compiler does not -- * support 32 bit unsigned integers, this code is not -- * appropriate. -- * -- * Caveats: -- * SHA-224 and SHA-256 are designed to work with messages less -- * than 2^64 bits long. This implementation uses SHA224/256Input() -- * to hash the bits that are a multiple of the size of an 8-bit -- * character, and then uses SHA224/256FinalBits() to hash the -- * final few bits of the input. -- */ -- --#include "sha.h" --#include "sha-private.h" -- -- -- --Eastlake 3rd & Hansen Informational [Page 33] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* Define the SHA shift, rotate left and rotate right macro */ --#define SHA256_SHR(bits,word) ((word) >> (bits)) --#define SHA256_ROTL(bits,word) \ -- (((word) << (bits)) | ((word) >> (32-(bits)))) --#define SHA256_ROTR(bits,word) \ -- (((word) >> (bits)) | ((word) << (32-(bits)))) -- --/* Define the SHA SIGMA and sigma macros */ --#define SHA256_SIGMA0(word) \ -- (SHA256_ROTR( 2,word) ^ SHA256_ROTR(13,word) ^ SHA256_ROTR(22,word)) --#define SHA256_SIGMA1(word) \ -- (SHA256_ROTR( 6,word) ^ SHA256_ROTR(11,word) ^ SHA256_ROTR(25,word)) --#define SHA256_sigma0(word) \ -- (SHA256_ROTR( 7,word) ^ SHA256_ROTR(18,word) ^ SHA256_SHR( 3,word)) --#define SHA256_sigma1(word) \ -- (SHA256_ROTR(17,word) ^ SHA256_ROTR(19,word) ^ SHA256_SHR(10,word)) -- --/* -- * add "length" to the length -- */ --static uint32_t addTemp; --#define SHA224_256AddLength(context, length) \ -- (addTemp = (context)->Length_Low, (context)->Corrupted = \ -- (((context)->Length_Low += (length)) < addTemp) && \ -- (++(context)->Length_High == 0) ? 1 : 0) -- --/* Local Function Prototypes */ --static void SHA224_256Finalize(SHA256Context *context, -- uint8_t Pad_Byte); --static void SHA224_256PadMessage(SHA256Context *context, -- uint8_t Pad_Byte); --static void SHA224_256ProcessMessageBlock(SHA256Context *context); --static int SHA224_256Reset(SHA256Context *context, uint32_t *H0); --static int SHA224_256ResultN(SHA256Context *context, -- uint8_t Message_Digest[], int HashSize); -- --/* Initial Hash Values: FIPS-180-2 Change Notice 1 */ --static uint32_t SHA224_H0[SHA256HashSize/4] = { -- 0xC1059ED8, 0x367CD507, 0x3070DD17, 0xF70E5939, -- 0xFFC00B31, 0x68581511, 0x64F98FA7, 0xBEFA4FA4 --}; -- --/* Initial Hash Values: FIPS-180-2 section 5.3.2 */ --static uint32_t SHA256_H0[SHA256HashSize/4] = { -- 0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A, -- 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19 --}; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 34] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * SHA224Reset -- * -- * Description: -- * This function will initialize the SHA384Context in preparation -- * for computing a new SHA224 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA224Reset(SHA224Context *context) --{ -- return SHA224_256Reset(context, SHA224_H0); --} -- --/* -- * SHA224Input -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA224Input(SHA224Context *context, const uint8_t *message_array, -- unsigned int length) --{ -- return SHA256Input(context, message_array, length); --} -- --/* -- * SHA224FinalBits -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 35] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA224FinalBits( SHA224Context *context, -- const uint8_t message_bits, unsigned int length) --{ -- return SHA256FinalBits(context, message_bits, length); --} -- --/* -- * SHA224Result -- * -- * Description: -- * This function will return the 224-bit message -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 28th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA224Result(SHA224Context *context, -- uint8_t Message_Digest[SHA224HashSize]) --{ -- return SHA224_256ResultN(context, Message_Digest, SHA224HashSize); --} -- --/* -- * SHA256Reset -- -- -- --Eastlake 3rd & Hansen Informational [Page 36] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- * Description: -- * This function will initialize the SHA256Context in preparation -- * for computing a new SHA256 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA256Reset(SHA256Context *context) --{ -- return SHA224_256Reset(context, SHA256_H0); --} -- --/* -- * SHA256Input -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- */ --int SHA256Input(SHA256Context *context, const uint8_t *message_array, -- unsigned int length) --{ -- if (!length) -- return shaSuccess; -- -- if (!context || !message_array) -- return shaNull; -- -- if (context->Computed) { -- context->Corrupted = shaStateError; -- return shaStateError; -- -- -- --Eastlake 3rd & Hansen Informational [Page 37] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- } -- -- if (context->Corrupted) -- return context->Corrupted; -- -- while (length-- && !context->Corrupted) { -- context->Message_Block[context->Message_Block_Index++] = -- (*message_array & 0xFF); -- -- if (!SHA224_256AddLength(context, 8) && -- (context->Message_Block_Index == SHA256_Message_Block_Size)) -- SHA224_256ProcessMessageBlock(context); -- -- message_array++; -- } -- -- return shaSuccess; -- --} -- --/* -- * SHA256FinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA256FinalBits(SHA256Context *context, -- const uint8_t message_bits, unsigned int length) --{ -- uint8_t masks[8] = { -- /* 0 0b00000000 */ 0x00, /* 1 0b10000000 */ 0x80, -- /* 2 0b11000000 */ 0xC0, /* 3 0b11100000 */ 0xE0, -- /* 4 0b11110000 */ 0xF0, /* 5 0b11111000 */ 0xF8, -- /* 6 0b11111100 */ 0xFC, /* 7 0b11111110 */ 0xFE -- }; -- -- -- --Eastlake 3rd & Hansen Informational [Page 38] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- uint8_t markbit[8] = { -- /* 0 0b10000000 */ 0x80, /* 1 0b01000000 */ 0x40, -- /* 2 0b00100000 */ 0x20, /* 3 0b00010000 */ 0x10, -- /* 4 0b00001000 */ 0x08, /* 5 0b00000100 */ 0x04, -- /* 6 0b00000010 */ 0x02, /* 7 0b00000001 */ 0x01 -- }; -- -- if (!length) -- return shaSuccess; -- -- if (!context) -- return shaNull; -- -- if ((context->Computed) || (length >= 8) || (length == 0)) { -- context->Corrupted = shaStateError; -- return shaStateError; -- } -- -- if (context->Corrupted) -- return context->Corrupted; -- -- SHA224_256AddLength(context, length); -- SHA224_256Finalize(context, (uint8_t) -- ((message_bits & masks[length]) | markbit[length])); -- -- return shaSuccess; --} -- --/* -- * SHA256Result -- * -- * Description: -- * This function will return the 256-bit message -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 32nd element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- * Returns: -- * sha Error Code. -- */ --int SHA256Result(SHA256Context *context, uint8_t Message_Digest[]) --{ -- -- -- --Eastlake 3rd & Hansen Informational [Page 39] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- return SHA224_256ResultN(context, Message_Digest, SHA256HashSize); --} -- --/* -- * SHA224_256Finalize -- * -- * Description: -- * This helper function finishes off the digest calculations. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * sha Error Code. -- */ --static void SHA224_256Finalize(SHA256Context *context, -- uint8_t Pad_Byte) --{ -- int i; -- SHA224_256PadMessage(context, Pad_Byte); -- /* message may be sensitive, so clear it out */ -- for (i = 0; i < SHA256_Message_Block_Size; ++i) -- context->Message_Block[i] = 0; -- context->Length_Low = 0; /* and clear length */ -- context->Length_High = 0; -- context->Computed = 1; --} -- --/* -- * SHA224_256PadMessage -- * -- * Description: -- * According to the standard, the message must be padded to an -- * even 512 bits. The first padding bit must be a '1'. The -- * last 64 bits represent the length of the original message. -- * All bits in between should be 0. This helper function will pad -- * the message according to those rules by filling the -- * Message_Block array accordingly. When it returns, it can be -- * assumed that the message digest has been computed. -- * -- * Parameters: -- * context: [in/out] -- -- -- --Eastlake 3rd & Hansen Informational [Page 40] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * The context to pad -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * Nothing. -- */ --static void SHA224_256PadMessage(SHA256Context *context, -- uint8_t Pad_Byte) --{ -- /* -- * Check to see if the current message block is too small to hold -- * the initial padding bits and length. If so, we will pad the -- * block, process it, and then continue padding into a second -- * block. -- */ -- if (context->Message_Block_Index >= (SHA256_Message_Block_Size-8)) { -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- while (context->Message_Block_Index < SHA256_Message_Block_Size) -- context->Message_Block[context->Message_Block_Index++] = 0; -- SHA224_256ProcessMessageBlock(context); -- } else -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- -- while (context->Message_Block_Index < (SHA256_Message_Block_Size-8)) -- context->Message_Block[context->Message_Block_Index++] = 0; -- -- /* -- * Store the message length as the last 8 octets -- */ -- context->Message_Block[56] = (uint8_t)(context->Length_High >> 24); -- context->Message_Block[57] = (uint8_t)(context->Length_High >> 16); -- context->Message_Block[58] = (uint8_t)(context->Length_High >> 8); -- context->Message_Block[59] = (uint8_t)(context->Length_High); -- context->Message_Block[60] = (uint8_t)(context->Length_Low >> 24); -- context->Message_Block[61] = (uint8_t)(context->Length_Low >> 16); -- context->Message_Block[62] = (uint8_t)(context->Length_Low >> 8); -- context->Message_Block[63] = (uint8_t)(context->Length_Low); -- -- SHA224_256ProcessMessageBlock(context); --} -- --/* -- * SHA224_256ProcessMessageBlock -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 41] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Description: -- * This function will process the next 512 bits of the message -- * stored in the Message_Block array. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * -- * Returns: -- * Nothing. -- * -- * Comments: -- * Many of the variable names in this code, especially the -- * single character names, were used because those were the -- * names used in the publication. -- */ --static void SHA224_256ProcessMessageBlock(SHA256Context *context) --{ -- /* Constants defined in FIPS-180-2, section 4.2.2 */ -- static const uint32_t K[64] = { -- 0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, -- 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, -- 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, -- 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, -- 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, -- 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, -- 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, -- 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, -- 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, -- 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, -- 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, -- 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, -- 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2 -- }; -- int t, t4; /* Loop counter */ -- uint32_t temp1, temp2; /* Temporary word value */ -- uint32_t W[64]; /* Word sequence */ -- uint32_t A, B, C, D, E, F, G, H; /* Word buffers */ -- -- /* -- * Initialize the first 16 words in the array W -- */ -- for (t = t4 = 0; t < 16; t++, t4 += 4) -- W[t] = (((uint32_t)context->Message_Block[t4]) << 24) | -- (((uint32_t)context->Message_Block[t4 + 1]) << 16) | -- (((uint32_t)context->Message_Block[t4 + 2]) << 8) | -- (((uint32_t)context->Message_Block[t4 + 3])); -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 42] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- for (t = 16; t < 64; t++) -- W[t] = SHA256_sigma1(W[t-2]) + W[t-7] + -- SHA256_sigma0(W[t-15]) + W[t-16]; -- -- A = context->Intermediate_Hash[0]; -- B = context->Intermediate_Hash[1]; -- C = context->Intermediate_Hash[2]; -- D = context->Intermediate_Hash[3]; -- E = context->Intermediate_Hash[4]; -- F = context->Intermediate_Hash[5]; -- G = context->Intermediate_Hash[6]; -- H = context->Intermediate_Hash[7]; -- -- for (t = 0; t < 64; t++) { -- temp1 = H + SHA256_SIGMA1(E) + SHA_Ch(E,F,G) + K[t] + W[t]; -- temp2 = SHA256_SIGMA0(A) + SHA_Maj(A,B,C); -- H = G; -- G = F; -- F = E; -- E = D + temp1; -- D = C; -- C = B; -- B = A; -- A = temp1 + temp2; -- } -- -- context->Intermediate_Hash[0] += A; -- context->Intermediate_Hash[1] += B; -- context->Intermediate_Hash[2] += C; -- context->Intermediate_Hash[3] += D; -- context->Intermediate_Hash[4] += E; -- context->Intermediate_Hash[5] += F; -- context->Intermediate_Hash[6] += G; -- context->Intermediate_Hash[7] += H; -- -- context->Message_Block_Index = 0; --} -- --/* -- * SHA224_256Reset -- * -- * Description: -- * This helper function will initialize the SHA256Context in -- * preparation for computing a new SHA256 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- -- -- --Eastlake 3rd & Hansen Informational [Page 43] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * H0 -- * The initial hash value to use. -- * -- * Returns: -- * sha Error Code. -- */ --static int SHA224_256Reset(SHA256Context *context, uint32_t *H0) --{ -- if (!context) -- return shaNull; -- -- context->Length_Low = 0; -- context->Length_High = 0; -- context->Message_Block_Index = 0; -- -- context->Intermediate_Hash[0] = H0[0]; -- context->Intermediate_Hash[1] = H0[1]; -- context->Intermediate_Hash[2] = H0[2]; -- context->Intermediate_Hash[3] = H0[3]; -- context->Intermediate_Hash[4] = H0[4]; -- context->Intermediate_Hash[5] = H0[5]; -- context->Intermediate_Hash[6] = H0[6]; -- context->Intermediate_Hash[7] = H0[7]; -- -- context->Computed = 0; -- context->Corrupted = 0; -- -- return shaSuccess; --} -- --/* -- * SHA224_256ResultN -- * -- * Description: -- * This helper function will return the 224-bit or 256-bit message -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 28th/32nd element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * HashSize: [in] -- * The size of the hash, either 28 or 32. -- * -- * Returns: -- -- -- --Eastlake 3rd & Hansen Informational [Page 44] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * sha Error Code. -- */ --static int SHA224_256ResultN(SHA256Context *context, -- uint8_t Message_Digest[], int HashSize) --{ -- int i; -- -- if (!context || !Message_Digest) -- return shaNull; -- -- if (context->Corrupted) -- return context->Corrupted; -- -- if (!context->Computed) -- SHA224_256Finalize(context, 0x80); -- -- for (i = 0; i < HashSize; ++i) -- Message_Digest[i] = (uint8_t) -- (context->Intermediate_Hash[i>>2] >> 8 * ( 3 - ( i & 0x03 ) )); -- -- return shaSuccess; --} -- --8.2.3. sha384-512.c -- --/*************************** sha384-512.c ***************************/ --/********************* See RFC 4634 for details *********************/ --/* -- * Description: -- * This file implements the Secure Hash Signature Standard -- * algorithms as defined in the National Institute of Standards -- * and Technology Federal Information Processing Standards -- * Publication (FIPS PUB) 180-1 published on April 17, 1995, 180-2 -- * published on August 1, 2002, and the FIPS PUB 180-2 Change -- * Notice published on February 28, 2004. -- * -- * A combined document showing all algorithms is available at -- * http://csrc.nist.gov/publications/fips/ -- * fips180-2/fips180-2withchangenotice.pdf -- * -- * The SHA-384 and SHA-512 algorithms produce 384-bit and 512-bit -- * message digests for a given data stream. It should take about -- * 2**n steps to find a message with the same digest as a given -- * message and 2**(n/2) to find any two messages with the same -- * digest, when n is the digest size in bits. Therefore, this -- * algorithm can serve as a means of providing a -- * "fingerprint" for a message. -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 45] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Portability Issues: -- * SHA-384 and SHA-512 are defined in terms of 64-bit "words", -- * but if USE_32BIT_ONLY is #defined, this code is implemented in -- * terms of 32-bit "words". This code uses (included -- * via "sha.h") to define the 64, 32 and 8 bit unsigned integer -- * types. If your C compiler does not support 64 bit unsigned -- * integers, and you do not #define USE_32BIT_ONLY, this code is -- * not appropriate. -- * -- * Caveats: -- * SHA-384 and SHA-512 are designed to work with messages less -- * than 2^128 bits long. This implementation uses -- * SHA384/512Input() to hash the bits that are a multiple of the -- * size of an 8-bit character, and then uses SHA384/256FinalBits() -- * to hash the final few bits of the input. -- * -- */ -- --#include "sha.h" --#include "sha-private.h" -- --#ifdef USE_32BIT_ONLY --/* -- * Define 64-bit arithmetic in terms of 32-bit arithmetic. -- * Each 64-bit number is represented in a 2-word array. -- * All macros are defined such that the result is the last parameter. -- */ -- --/* -- * Define shift, rotate left and rotate right functions -- */ --#define SHA512_SHR(bits, word, ret) ( \ -- /* (((uint64_t)((word))) >> (bits)) */ \ -- (ret)[0] = (((bits) < 32) && ((bits) >= 0)) ? \ -- ((word)[0] >> (bits)) : 0, \ -- (ret)[1] = ((bits) > 32) ? ((word)[0] >> ((bits) - 32)) : \ -- ((bits) == 32) ? (word)[0] : \ -- ((bits) >= 0) ? \ -- (((word)[0] << (32 - (bits))) | \ -- ((word)[1] >> (bits))) : 0 ) -- --#define SHA512_SHL(bits, word, ret) ( \ -- /* (((uint64_t)(word)) << (bits)) */ \ -- (ret)[0] = ((bits) > 32) ? ((word)[1] << ((bits) - 32)) : \ -- ((bits) == 32) ? (word)[1] : \ -- ((bits) >= 0) ? \ -- (((word)[0] << (bits)) | \ -- ((word)[1] >> (32 - (bits)))) : \ -- -- -- --Eastlake 3rd & Hansen Informational [Page 46] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- 0, \ -- (ret)[1] = (((bits) < 32) && ((bits) >= 0)) ? \ -- ((word)[1] << (bits)) : 0 ) -- --/* -- * Define 64-bit OR -- */ --#define SHA512_OR(word1, word2, ret) ( \ -- (ret)[0] = (word1)[0] | (word2)[0], \ -- (ret)[1] = (word1)[1] | (word2)[1] ) -- --/* -- * Define 64-bit XOR -- */ --#define SHA512_XOR(word1, word2, ret) ( \ -- (ret)[0] = (word1)[0] ^ (word2)[0], \ -- (ret)[1] = (word1)[1] ^ (word2)[1] ) -- --/* -- * Define 64-bit AND -- */ --#define SHA512_AND(word1, word2, ret) ( \ -- (ret)[0] = (word1)[0] & (word2)[0], \ -- (ret)[1] = (word1)[1] & (word2)[1] ) -- --/* -- * Define 64-bit TILDA -- */ --#define SHA512_TILDA(word, ret) \ -- ( (ret)[0] = ~(word)[0], (ret)[1] = ~(word)[1] ) -- --/* -- * Define 64-bit ADD -- */ --#define SHA512_ADD(word1, word2, ret) ( \ -- (ret)[1] = (word1)[1], (ret)[1] += (word2)[1], \ -- (ret)[0] = (word1)[0] + (word2)[0] + ((ret)[1] < (word1)[1]) ) -- --/* -- * Add the 4word value in word2 to word1. -- */ --static uint32_t ADDTO4_temp, ADDTO4_temp2; --#define SHA512_ADDTO4(word1, word2) ( \ -- ADDTO4_temp = (word1)[3], \ -- (word1)[3] += (word2)[3], \ -- ADDTO4_temp2 = (word1)[2], \ -- (word1)[2] += (word2)[2] + ((word1)[3] < ADDTO4_temp), \ -- ADDTO4_temp = (word1)[1], \ -- -- -- --Eastlake 3rd & Hansen Informational [Page 47] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- (word1)[1] += (word2)[1] + ((word1)[2] < ADDTO4_temp2), \ -- (word1)[0] += (word2)[0] + ((word1)[1] < ADDTO4_temp) ) -- --/* -- * Add the 2word value in word2 to word1. -- */ --static uint32_t ADDTO2_temp; --#define SHA512_ADDTO2(word1, word2) ( \ -- ADDTO2_temp = (word1)[1], \ -- (word1)[1] += (word2)[1], \ -- (word1)[0] += (word2)[0] + ((word1)[1] < ADDTO2_temp) ) -- --/* -- * SHA rotate ((word >> bits) | (word << (64-bits))) -- */ --static uint32_t ROTR_temp1[2], ROTR_temp2[2]; --#define SHA512_ROTR(bits, word, ret) ( \ -- SHA512_SHR((bits), (word), ROTR_temp1), \ -- SHA512_SHL(64-(bits), (word), ROTR_temp2), \ -- SHA512_OR(ROTR_temp1, ROTR_temp2, (ret)) ) -- --/* -- * Define the SHA SIGMA and sigma macros -- * SHA512_ROTR(28,word) ^ SHA512_ROTR(34,word) ^ SHA512_ROTR(39,word) -- */ --static uint32_t SIGMA0_temp1[2], SIGMA0_temp2[2], -- SIGMA0_temp3[2], SIGMA0_temp4[2]; --#define SHA512_SIGMA0(word, ret) ( \ -- SHA512_ROTR(28, (word), SIGMA0_temp1), \ -- SHA512_ROTR(34, (word), SIGMA0_temp2), \ -- SHA512_ROTR(39, (word), SIGMA0_temp3), \ -- SHA512_XOR(SIGMA0_temp2, SIGMA0_temp3, SIGMA0_temp4), \ -- SHA512_XOR(SIGMA0_temp1, SIGMA0_temp4, (ret)) ) -- --/* -- * SHA512_ROTR(14,word) ^ SHA512_ROTR(18,word) ^ SHA512_ROTR(41,word) -- */ --static uint32_t SIGMA1_temp1[2], SIGMA1_temp2[2], -- SIGMA1_temp3[2], SIGMA1_temp4[2]; --#define SHA512_SIGMA1(word, ret) ( \ -- SHA512_ROTR(14, (word), SIGMA1_temp1), \ -- SHA512_ROTR(18, (word), SIGMA1_temp2), \ -- SHA512_ROTR(41, (word), SIGMA1_temp3), \ -- SHA512_XOR(SIGMA1_temp2, SIGMA1_temp3, SIGMA1_temp4), \ -- SHA512_XOR(SIGMA1_temp1, SIGMA1_temp4, (ret)) ) -- --/* -- * (SHA512_ROTR( 1,word) ^ SHA512_ROTR( 8,word) ^ SHA512_SHR( 7,word)) -- -- -- --Eastlake 3rd & Hansen Informational [Page 48] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- */ --static uint32_t sigma0_temp1[2], sigma0_temp2[2], -- sigma0_temp3[2], sigma0_temp4[2]; --#define SHA512_sigma0(word, ret) ( \ -- SHA512_ROTR( 1, (word), sigma0_temp1), \ -- SHA512_ROTR( 8, (word), sigma0_temp2), \ -- SHA512_SHR( 7, (word), sigma0_temp3), \ -- SHA512_XOR(sigma0_temp2, sigma0_temp3, sigma0_temp4), \ -- SHA512_XOR(sigma0_temp1, sigma0_temp4, (ret)) ) -- --/* -- * (SHA512_ROTR(19,word) ^ SHA512_ROTR(61,word) ^ SHA512_SHR( 6,word)) -- */ --static uint32_t sigma1_temp1[2], sigma1_temp2[2], -- sigma1_temp3[2], sigma1_temp4[2]; --#define SHA512_sigma1(word, ret) ( \ -- SHA512_ROTR(19, (word), sigma1_temp1), \ -- SHA512_ROTR(61, (word), sigma1_temp2), \ -- SHA512_SHR( 6, (word), sigma1_temp3), \ -- SHA512_XOR(sigma1_temp2, sigma1_temp3, sigma1_temp4), \ -- SHA512_XOR(sigma1_temp1, sigma1_temp4, (ret)) ) -- --#undef SHA_Ch --#undef SHA_Maj -- --#ifndef USE_MODIFIED_MACROS --/* -- * These definitions are the ones used in FIPS-180-2, section 4.1.3 -- * Ch(x,y,z) ((x & y) ^ (~x & z)) -- */ --static uint32_t Ch_temp1[2], Ch_temp2[2], Ch_temp3[2]; --#define SHA_Ch(x, y, z, ret) ( \ -- SHA512_AND(x, y, Ch_temp1), \ -- SHA512_TILDA(x, Ch_temp2), \ -- SHA512_AND(Ch_temp2, z, Ch_temp3), \ -- SHA512_XOR(Ch_temp1, Ch_temp3, (ret)) ) --/* -- * Maj(x,y,z) (((x)&(y)) ^ ((x)&(z)) ^ ((y)&(z))) -- */ --static uint32_t Maj_temp1[2], Maj_temp2[2], -- Maj_temp3[2], Maj_temp4[2]; --#define SHA_Maj(x, y, z, ret) ( \ -- SHA512_AND(x, y, Maj_temp1), \ -- SHA512_AND(x, z, Maj_temp2), \ -- SHA512_AND(y, z, Maj_temp3), \ -- SHA512_XOR(Maj_temp2, Maj_temp3, Maj_temp4), \ -- SHA512_XOR(Maj_temp1, Maj_temp4, (ret)) ) -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 49] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --#else /* !USE_32BIT_ONLY */ --/* -- * These definitions are potentially faster equivalents for the ones -- * used in FIPS-180-2, section 4.1.3. -- * ((x & y) ^ (~x & z)) becomes -- * ((x & (y ^ z)) ^ z) -- */ --#define SHA_Ch(x, y, z, ret) ( \ -- (ret)[0] = (((x)[0] & ((y)[0] ^ (z)[0])) ^ (z)[0]), \ -- (ret)[1] = (((x)[1] & ((y)[1] ^ (z)[1])) ^ (z)[1]) ) -- --/* -- * ((x & y) ^ (x & z) ^ (y & z)) becomes -- * ((x & (y | z)) | (y & z)) -- */ --#define SHA_Maj(x, y, z, ret) ( \ -- ret[0] = (((x)[0] & ((y)[0] | (z)[0])) | ((y)[0] & (z)[0])), \ -- ret[1] = (((x)[1] & ((y)[1] | (z)[1])) | ((y)[1] & (z)[1])) ) --#endif /* USE_MODIFIED_MACROS */ -- --/* -- * add "length" to the length -- */ --static uint32_t addTemp[4] = { 0, 0, 0, 0 }; --#define SHA384_512AddLength(context, length) ( \ -- addTemp[3] = (length), SHA512_ADDTO4((context)->Length, addTemp), \ -- (context)->Corrupted = (((context)->Length[3] == 0) && \ -- ((context)->Length[2] == 0) && ((context)->Length[1] == 0) && \ -- ((context)->Length[0] < 8)) ? 1 : 0 ) -- --/* Local Function Prototypes */ --static void SHA384_512Finalize(SHA512Context *context, -- uint8_t Pad_Byte); --static void SHA384_512PadMessage(SHA512Context *context, -- uint8_t Pad_Byte); --static void SHA384_512ProcessMessageBlock(SHA512Context *context); --static int SHA384_512Reset(SHA512Context *context, uint32_t H0[]); --static int SHA384_512ResultN( SHA512Context *context, -- uint8_t Message_Digest[], int HashSize); -- --/* Initial Hash Values: FIPS-180-2 sections 5.3.3 and 5.3.4 */ --static uint32_t SHA384_H0[SHA512HashSize/4] = { -- 0xCBBB9D5D, 0xC1059ED8, 0x629A292A, 0x367CD507, 0x9159015A, -- 0x3070DD17, 0x152FECD8, 0xF70E5939, 0x67332667, 0xFFC00B31, -- 0x8EB44A87, 0x68581511, 0xDB0C2E0D, 0x64F98FA7, 0x47B5481D, -- 0xBEFA4FA4 --}; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 50] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --static uint32_t SHA512_H0[SHA512HashSize/4] = { -- 0x6A09E667, 0xF3BCC908, 0xBB67AE85, 0x84CAA73B, 0x3C6EF372, -- 0xFE94F82B, 0xA54FF53A, 0x5F1D36F1, 0x510E527F, 0xADE682D1, -- 0x9B05688C, 0x2B3E6C1F, 0x1F83D9AB, 0xFB41BD6B, 0x5BE0CD19, -- 0x137E2179 --}; -- --#else /* !USE_32BIT_ONLY */ -- --/* Define the SHA shift, rotate left and rotate right macro */ --#define SHA512_SHR(bits,word) (((uint64_t)(word)) >> (bits)) --#define SHA512_ROTR(bits,word) ((((uint64_t)(word)) >> (bits)) | \ -- (((uint64_t)(word)) << (64-(bits)))) -- --/* Define the SHA SIGMA and sigma macros */ --#define SHA512_SIGMA0(word) \ -- (SHA512_ROTR(28,word) ^ SHA512_ROTR(34,word) ^ SHA512_ROTR(39,word)) --#define SHA512_SIGMA1(word) \ -- (SHA512_ROTR(14,word) ^ SHA512_ROTR(18,word) ^ SHA512_ROTR(41,word)) --#define SHA512_sigma0(word) \ -- (SHA512_ROTR( 1,word) ^ SHA512_ROTR( 8,word) ^ SHA512_SHR( 7,word)) --#define SHA512_sigma1(word) \ -- (SHA512_ROTR(19,word) ^ SHA512_ROTR(61,word) ^ SHA512_SHR( 6,word)) -- --/* -- * add "length" to the length -- */ --static uint64_t addTemp; --#define SHA384_512AddLength(context, length) \ -- (addTemp = context->Length_Low, context->Corrupted = \ -- ((context->Length_Low += length) < addTemp) && \ -- (++context->Length_High == 0) ? 1 : 0) -- --/* Local Function Prototypes */ --static void SHA384_512Finalize(SHA512Context *context, -- uint8_t Pad_Byte); --static void SHA384_512PadMessage(SHA512Context *context, -- uint8_t Pad_Byte); --static void SHA384_512ProcessMessageBlock(SHA512Context *context); --static int SHA384_512Reset(SHA512Context *context, uint64_t H0[]); --static int SHA384_512ResultN(SHA512Context *context, -- uint8_t Message_Digest[], int HashSize); -- --/* Initial Hash Values: FIPS-180-2 sections 5.3.3 and 5.3.4 */ --static uint64_t SHA384_H0[] = { -- 0xCBBB9D5DC1059ED8ll, 0x629A292A367CD507ll, 0x9159015A3070DD17ll, -- 0x152FECD8F70E5939ll, 0x67332667FFC00B31ll, 0x8EB44A8768581511ll, -- 0xDB0C2E0D64F98FA7ll, 0x47B5481DBEFA4FA4ll -- -- -- --Eastlake 3rd & Hansen Informational [Page 51] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --}; --static uint64_t SHA512_H0[] = { -- 0x6A09E667F3BCC908ll, 0xBB67AE8584CAA73Bll, 0x3C6EF372FE94F82Bll, -- 0xA54FF53A5F1D36F1ll, 0x510E527FADE682D1ll, 0x9B05688C2B3E6C1Fll, -- 0x1F83D9ABFB41BD6Bll, 0x5BE0CD19137E2179ll --}; -- --#endif /* USE_32BIT_ONLY */ -- --/* -- * SHA384Reset -- * -- * Description: -- * This function will initialize the SHA384Context in preparation -- * for computing a new SHA384 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA384Reset(SHA384Context *context) --{ -- return SHA384_512Reset(context, SHA384_H0); --} -- --/* -- * SHA384Input -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 52] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- */ --int SHA384Input(SHA384Context *context, -- const uint8_t *message_array, unsigned int length) --{ -- return SHA512Input(context, message_array, length); --} -- --/* -- * SHA384FinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA384FinalBits(SHA384Context *context, -- const uint8_t message_bits, unsigned int length) --{ -- return SHA512FinalBits(context, message_bits, length); --} -- --/* -- * SHA384Result -- * -- * Description: -- * This function will return the 384-bit message -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 48th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 53] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Returns: -- * sha Error Code. -- * -- */ --int SHA384Result(SHA384Context *context, -- uint8_t Message_Digest[SHA384HashSize]) --{ -- return SHA384_512ResultN(context, Message_Digest, SHA384HashSize); --} -- --/* -- * SHA512Reset -- * -- * Description: -- * This function will initialize the SHA512Context in preparation -- * for computing a new SHA512 message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA512Reset(SHA512Context *context) --{ -- return SHA384_512Reset(context, SHA512_H0); --} -- --/* -- * SHA512Input -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- -- -- --Eastlake 3rd & Hansen Informational [Page 54] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- */ --int SHA512Input(SHA512Context *context, -- const uint8_t *message_array, -- unsigned int length) --{ -- if (!length) -- return shaSuccess; -- -- if (!context || !message_array) -- return shaNull; -- -- if (context->Computed) { -- context->Corrupted = shaStateError; -- return shaStateError; -- } -- -- if (context->Corrupted) -- return context->Corrupted; -- -- while (length-- && !context->Corrupted) { -- context->Message_Block[context->Message_Block_Index++] = -- (*message_array & 0xFF); -- -- if (!SHA384_512AddLength(context, 8) && -- (context->Message_Block_Index == SHA512_Message_Block_Size)) -- SHA384_512ProcessMessageBlock(context); -- -- message_array++; -- } -- -- return shaSuccess; --} -- --/* -- * SHA512FinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- -- -- --Eastlake 3rd & Hansen Informational [Page 55] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int SHA512FinalBits(SHA512Context *context, -- const uint8_t message_bits, unsigned int length) --{ -- uint8_t masks[8] = { -- /* 0 0b00000000 */ 0x00, /* 1 0b10000000 */ 0x80, -- /* 2 0b11000000 */ 0xC0, /* 3 0b11100000 */ 0xE0, -- /* 4 0b11110000 */ 0xF0, /* 5 0b11111000 */ 0xF8, -- /* 6 0b11111100 */ 0xFC, /* 7 0b11111110 */ 0xFE -- }; -- uint8_t markbit[8] = { -- /* 0 0b10000000 */ 0x80, /* 1 0b01000000 */ 0x40, -- /* 2 0b00100000 */ 0x20, /* 3 0b00010000 */ 0x10, -- /* 4 0b00001000 */ 0x08, /* 5 0b00000100 */ 0x04, -- /* 6 0b00000010 */ 0x02, /* 7 0b00000001 */ 0x01 -- }; -- -- if (!length) -- return shaSuccess; -- -- if (!context) -- return shaNull; -- -- if ((context->Computed) || (length >= 8) || (length == 0)) { -- context->Corrupted = shaStateError; -- return shaStateError; -- } -- -- if (context->Corrupted) -- return context->Corrupted; -- -- SHA384_512AddLength(context, length); -- SHA384_512Finalize(context, (uint8_t) -- ((message_bits & masks[length]) | markbit[length])); -- -- return shaSuccess; --} -- --/* -- * SHA384_512Finalize -- * -- * Description: -- * This helper function finishes off the digest calculations. -- -- -- --Eastlake 3rd & Hansen Informational [Page 56] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * sha Error Code. -- * -- */ --static void SHA384_512Finalize(SHA512Context *context, -- uint8_t Pad_Byte) --{ -- int_least16_t i; -- SHA384_512PadMessage(context, Pad_Byte); -- /* message may be sensitive, clear it out */ -- for (i = 0; i < SHA512_Message_Block_Size; ++i) -- context->Message_Block[i] = 0; --#ifdef USE_32BIT_ONLY /* and clear length */ -- context->Length[0] = context->Length[1] = 0; -- context->Length[2] = context->Length[3] = 0; --#else /* !USE_32BIT_ONLY */ -- context->Length_Low = 0; -- context->Length_High = 0; --#endif /* USE_32BIT_ONLY */ -- context->Computed = 1; --} -- --/* -- * SHA512Result -- * -- * Description: -- * This function will return the 512-bit message -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 64th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- * Returns: -- -- -- --Eastlake 3rd & Hansen Informational [Page 57] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * sha Error Code. -- * -- */ --int SHA512Result(SHA512Context *context, -- uint8_t Message_Digest[SHA512HashSize]) --{ -- return SHA384_512ResultN(context, Message_Digest, SHA512HashSize); --} -- --/* -- * SHA384_512PadMessage -- * -- * Description: -- * According to the standard, the message must be padded to an -- * even 1024 bits. The first padding bit must be a '1'. The -- * last 128 bits represent the length of the original message. -- * All bits in between should be 0. This helper function will -- * pad the message according to those rules by filling the -- * Message_Block array accordingly. When it returns, it can be -- * assumed that the message digest has been computed. -- * -- * Parameters: -- * context: [in/out] -- * The context to pad -- * Pad_Byte: [in] -- * The last byte to add to the digest before the 0-padding -- * and length. This will contain the last bits of the message -- * followed by another single bit. If the message was an -- * exact multiple of 8-bits long, Pad_Byte will be 0x80. -- * -- * Returns: -- * Nothing. -- * -- */ --static void SHA384_512PadMessage(SHA512Context *context, -- uint8_t Pad_Byte) --{ -- /* -- * Check to see if the current message block is too small to hold -- * the initial padding bits and length. If so, we will pad the -- * block, process it, and then continue padding into a second -- * block. -- */ -- if (context->Message_Block_Index >= (SHA512_Message_Block_Size-16)) { -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- while (context->Message_Block_Index < SHA512_Message_Block_Size) -- context->Message_Block[context->Message_Block_Index++] = 0; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 58] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- SHA384_512ProcessMessageBlock(context); -- } else -- context->Message_Block[context->Message_Block_Index++] = Pad_Byte; -- -- while (context->Message_Block_Index < (SHA512_Message_Block_Size-16)) -- context->Message_Block[context->Message_Block_Index++] = 0; -- -- /* -- * Store the message length as the last 16 octets -- */ --#ifdef USE_32BIT_ONLY -- context->Message_Block[112] = (uint8_t)(context->Length[0] >> 24); -- context->Message_Block[113] = (uint8_t)(context->Length[0] >> 16); -- context->Message_Block[114] = (uint8_t)(context->Length[0] >> 8); -- context->Message_Block[115] = (uint8_t)(context->Length[0]); -- context->Message_Block[116] = (uint8_t)(context->Length[1] >> 24); -- context->Message_Block[117] = (uint8_t)(context->Length[1] >> 16); -- context->Message_Block[118] = (uint8_t)(context->Length[1] >> 8); -- context->Message_Block[119] = (uint8_t)(context->Length[1]); -- -- context->Message_Block[120] = (uint8_t)(context->Length[2] >> 24); -- context->Message_Block[121] = (uint8_t)(context->Length[2] >> 16); -- context->Message_Block[122] = (uint8_t)(context->Length[2] >> 8); -- context->Message_Block[123] = (uint8_t)(context->Length[2]); -- context->Message_Block[124] = (uint8_t)(context->Length[3] >> 24); -- context->Message_Block[125] = (uint8_t)(context->Length[3] >> 16); -- context->Message_Block[126] = (uint8_t)(context->Length[3] >> 8); -- context->Message_Block[127] = (uint8_t)(context->Length[3]); --#else /* !USE_32BIT_ONLY */ -- context->Message_Block[112] = (uint8_t)(context->Length_High >> 56); -- context->Message_Block[113] = (uint8_t)(context->Length_High >> 48); -- context->Message_Block[114] = (uint8_t)(context->Length_High >> 40); -- context->Message_Block[115] = (uint8_t)(context->Length_High >> 32); -- context->Message_Block[116] = (uint8_t)(context->Length_High >> 24); -- context->Message_Block[117] = (uint8_t)(context->Length_High >> 16); -- context->Message_Block[118] = (uint8_t)(context->Length_High >> 8); -- context->Message_Block[119] = (uint8_t)(context->Length_High); -- -- context->Message_Block[120] = (uint8_t)(context->Length_Low >> 56); -- context->Message_Block[121] = (uint8_t)(context->Length_Low >> 48); -- context->Message_Block[122] = (uint8_t)(context->Length_Low >> 40); -- context->Message_Block[123] = (uint8_t)(context->Length_Low >> 32); -- context->Message_Block[124] = (uint8_t)(context->Length_Low >> 24); -- context->Message_Block[125] = (uint8_t)(context->Length_Low >> 16); -- context->Message_Block[126] = (uint8_t)(context->Length_Low >> 8); -- context->Message_Block[127] = (uint8_t)(context->Length_Low); --#endif /* USE_32BIT_ONLY */ -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 59] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- SHA384_512ProcessMessageBlock(context); --} -- --/* -- * SHA384_512ProcessMessageBlock -- * -- * Description: -- * This helper function will process the next 1024 bits of the -- * message stored in the Message_Block array. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * -- * Returns: -- * Nothing. -- * -- * Comments: -- * Many of the variable names in this code, especially the -- * single character names, were used because those were the -- * names used in the publication. -- * -- * -- */ --static void SHA384_512ProcessMessageBlock(SHA512Context *context) --{ -- /* Constants defined in FIPS-180-2, section 4.2.3 */ --#ifdef USE_32BIT_ONLY -- static const uint32_t K[80*2] = { -- 0x428A2F98, 0xD728AE22, 0x71374491, 0x23EF65CD, 0xB5C0FBCF, -- 0xEC4D3B2F, 0xE9B5DBA5, 0x8189DBBC, 0x3956C25B, 0xF348B538, -- 0x59F111F1, 0xB605D019, 0x923F82A4, 0xAF194F9B, 0xAB1C5ED5, -- 0xDA6D8118, 0xD807AA98, 0xA3030242, 0x12835B01, 0x45706FBE, -- 0x243185BE, 0x4EE4B28C, 0x550C7DC3, 0xD5FFB4E2, 0x72BE5D74, -- 0xF27B896F, 0x80DEB1FE, 0x3B1696B1, 0x9BDC06A7, 0x25C71235, -- 0xC19BF174, 0xCF692694, 0xE49B69C1, 0x9EF14AD2, 0xEFBE4786, -- 0x384F25E3, 0x0FC19DC6, 0x8B8CD5B5, 0x240CA1CC, 0x77AC9C65, -- 0x2DE92C6F, 0x592B0275, 0x4A7484AA, 0x6EA6E483, 0x5CB0A9DC, -- 0xBD41FBD4, 0x76F988DA, 0x831153B5, 0x983E5152, 0xEE66DFAB, -- 0xA831C66D, 0x2DB43210, 0xB00327C8, 0x98FB213F, 0xBF597FC7, -- 0xBEEF0EE4, 0xC6E00BF3, 0x3DA88FC2, 0xD5A79147, 0x930AA725, -- 0x06CA6351, 0xE003826F, 0x14292967, 0x0A0E6E70, 0x27B70A85, -- 0x46D22FFC, 0x2E1B2138, 0x5C26C926, 0x4D2C6DFC, 0x5AC42AED, -- 0x53380D13, 0x9D95B3DF, 0x650A7354, 0x8BAF63DE, 0x766A0ABB, -- 0x3C77B2A8, 0x81C2C92E, 0x47EDAEE6, 0x92722C85, 0x1482353B, -- 0xA2BFE8A1, 0x4CF10364, 0xA81A664B, 0xBC423001, 0xC24B8B70, -- 0xD0F89791, 0xC76C51A3, 0x0654BE30, 0xD192E819, 0xD6EF5218, -- 0xD6990624, 0x5565A910, 0xF40E3585, 0x5771202A, 0x106AA070, -- -- -- --Eastlake 3rd & Hansen Informational [Page 60] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- 0x32BBD1B8, 0x19A4C116, 0xB8D2D0C8, 0x1E376C08, 0x5141AB53, -- 0x2748774C, 0xDF8EEB99, 0x34B0BCB5, 0xE19B48A8, 0x391C0CB3, -- 0xC5C95A63, 0x4ED8AA4A, 0xE3418ACB, 0x5B9CCA4F, 0x7763E373, -- 0x682E6FF3, 0xD6B2B8A3, 0x748F82EE, 0x5DEFB2FC, 0x78A5636F, -- 0x43172F60, 0x84C87814, 0xA1F0AB72, 0x8CC70208, 0x1A6439EC, -- 0x90BEFFFA, 0x23631E28, 0xA4506CEB, 0xDE82BDE9, 0xBEF9A3F7, -- 0xB2C67915, 0xC67178F2, 0xE372532B, 0xCA273ECE, 0xEA26619C, -- 0xD186B8C7, 0x21C0C207, 0xEADA7DD6, 0xCDE0EB1E, 0xF57D4F7F, -- 0xEE6ED178, 0x06F067AA, 0x72176FBA, 0x0A637DC5, 0xA2C898A6, -- 0x113F9804, 0xBEF90DAE, 0x1B710B35, 0x131C471B, 0x28DB77F5, -- 0x23047D84, 0x32CAAB7B, 0x40C72493, 0x3C9EBE0A, 0x15C9BEBC, -- 0x431D67C4, 0x9C100D4C, 0x4CC5D4BE, 0xCB3E42B6, 0x597F299C, -- 0xFC657E2A, 0x5FCB6FAB, 0x3AD6FAEC, 0x6C44198C, 0x4A475817 -- }; -- int t, t2, t8; /* Loop counter */ -- uint32_t temp1[2], temp2[2], /* Temporary word values */ -- temp3[2], temp4[2], temp5[2]; -- uint32_t W[2*80]; /* Word sequence */ -- uint32_t A[2], B[2], C[2], D[2], /* Word buffers */ -- E[2], F[2], G[2], H[2]; -- -- /* Initialize the first 16 words in the array W */ -- for (t = t2 = t8 = 0; t < 16; t++, t8 += 8) { -- W[t2++] = ((((uint32_t)context->Message_Block[t8 ])) << 24) | -- ((((uint32_t)context->Message_Block[t8 + 1])) << 16) | -- ((((uint32_t)context->Message_Block[t8 + 2])) << 8) | -- ((((uint32_t)context->Message_Block[t8 + 3]))); -- W[t2++] = ((((uint32_t)context->Message_Block[t8 + 4])) << 24) | -- ((((uint32_t)context->Message_Block[t8 + 5])) << 16) | -- ((((uint32_t)context->Message_Block[t8 + 6])) << 8) | -- ((((uint32_t)context->Message_Block[t8 + 7]))); -- } -- -- for (t = 16; t < 80; t++, t2 += 2) { -- /* W[t] = SHA512_sigma1(W[t-2]) + W[t-7] + -- SHA512_sigma0(W[t-15]) + W[t-16]; */ -- uint32_t *Wt2 = &W[t2-2*2]; -- uint32_t *Wt7 = &W[t2-7*2]; -- uint32_t *Wt15 = &W[t2-15*2]; -- uint32_t *Wt16 = &W[t2-16*2]; -- SHA512_sigma1(Wt2, temp1); -- SHA512_ADD(temp1, Wt7, temp2); -- SHA512_sigma0(Wt15, temp1); -- SHA512_ADD(temp1, Wt16, temp3); -- SHA512_ADD(temp2, temp3, &W[t2]); -- } -- -- A[0] = context->Intermediate_Hash[0]; -- -- -- --Eastlake 3rd & Hansen Informational [Page 61] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- A[1] = context->Intermediate_Hash[1]; -- B[0] = context->Intermediate_Hash[2]; -- B[1] = context->Intermediate_Hash[3]; -- C[0] = context->Intermediate_Hash[4]; -- C[1] = context->Intermediate_Hash[5]; -- D[0] = context->Intermediate_Hash[6]; -- D[1] = context->Intermediate_Hash[7]; -- E[0] = context->Intermediate_Hash[8]; -- E[1] = context->Intermediate_Hash[9]; -- F[0] = context->Intermediate_Hash[10]; -- F[1] = context->Intermediate_Hash[11]; -- G[0] = context->Intermediate_Hash[12]; -- G[1] = context->Intermediate_Hash[13]; -- H[0] = context->Intermediate_Hash[14]; -- H[1] = context->Intermediate_Hash[15]; -- -- for (t = t2 = 0; t < 80; t++, t2 += 2) { -- /* -- * temp1 = H + SHA512_SIGMA1(E) + SHA_Ch(E,F,G) + K[t] + W[t]; -- */ -- SHA512_SIGMA1(E,temp1); -- SHA512_ADD(H, temp1, temp2); -- SHA_Ch(E,F,G,temp3); -- SHA512_ADD(temp2, temp3, temp4); -- SHA512_ADD(&K[t2], &W[t2], temp5); -- SHA512_ADD(temp4, temp5, temp1); -- /* -- * temp2 = SHA512_SIGMA0(A) + SHA_Maj(A,B,C); -- */ -- SHA512_SIGMA0(A,temp3); -- SHA_Maj(A,B,C,temp4); -- SHA512_ADD(temp3, temp4, temp2); -- H[0] = G[0]; H[1] = G[1]; -- G[0] = F[0]; G[1] = F[1]; -- F[0] = E[0]; F[1] = E[1]; -- SHA512_ADD(D, temp1, E); -- D[0] = C[0]; D[1] = C[1]; -- C[0] = B[0]; C[1] = B[1]; -- B[0] = A[0]; B[1] = A[1]; -- SHA512_ADD(temp1, temp2, A); -- } -- -- SHA512_ADDTO2(&context->Intermediate_Hash[0], A); -- SHA512_ADDTO2(&context->Intermediate_Hash[2], B); -- SHA512_ADDTO2(&context->Intermediate_Hash[4], C); -- SHA512_ADDTO2(&context->Intermediate_Hash[6], D); -- SHA512_ADDTO2(&context->Intermediate_Hash[8], E); -- SHA512_ADDTO2(&context->Intermediate_Hash[10], F); -- -- -- --Eastlake 3rd & Hansen Informational [Page 62] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- SHA512_ADDTO2(&context->Intermediate_Hash[12], G); -- SHA512_ADDTO2(&context->Intermediate_Hash[14], H); -- --#else /* !USE_32BIT_ONLY */ -- static const uint64_t K[80] = { -- 0x428A2F98D728AE22ll, 0x7137449123EF65CDll, 0xB5C0FBCFEC4D3B2Fll, -- 0xE9B5DBA58189DBBCll, 0x3956C25BF348B538ll, 0x59F111F1B605D019ll, -- 0x923F82A4AF194F9Bll, 0xAB1C5ED5DA6D8118ll, 0xD807AA98A3030242ll, -- 0x12835B0145706FBEll, 0x243185BE4EE4B28Cll, 0x550C7DC3D5FFB4E2ll, -- 0x72BE5D74F27B896Fll, 0x80DEB1FE3B1696B1ll, 0x9BDC06A725C71235ll, -- 0xC19BF174CF692694ll, 0xE49B69C19EF14AD2ll, 0xEFBE4786384F25E3ll, -- 0x0FC19DC68B8CD5B5ll, 0x240CA1CC77AC9C65ll, 0x2DE92C6F592B0275ll, -- 0x4A7484AA6EA6E483ll, 0x5CB0A9DCBD41FBD4ll, 0x76F988DA831153B5ll, -- 0x983E5152EE66DFABll, 0xA831C66D2DB43210ll, 0xB00327C898FB213Fll, -- 0xBF597FC7BEEF0EE4ll, 0xC6E00BF33DA88FC2ll, 0xD5A79147930AA725ll, -- 0x06CA6351E003826Fll, 0x142929670A0E6E70ll, 0x27B70A8546D22FFCll, -- 0x2E1B21385C26C926ll, 0x4D2C6DFC5AC42AEDll, 0x53380D139D95B3DFll, -- 0x650A73548BAF63DEll, 0x766A0ABB3C77B2A8ll, 0x81C2C92E47EDAEE6ll, -- 0x92722C851482353Bll, 0xA2BFE8A14CF10364ll, 0xA81A664BBC423001ll, -- 0xC24B8B70D0F89791ll, 0xC76C51A30654BE30ll, 0xD192E819D6EF5218ll, -- 0xD69906245565A910ll, 0xF40E35855771202All, 0x106AA07032BBD1B8ll, -- 0x19A4C116B8D2D0C8ll, 0x1E376C085141AB53ll, 0x2748774CDF8EEB99ll, -- 0x34B0BCB5E19B48A8ll, 0x391C0CB3C5C95A63ll, 0x4ED8AA4AE3418ACBll, -- 0x5B9CCA4F7763E373ll, 0x682E6FF3D6B2B8A3ll, 0x748F82EE5DEFB2FCll, -- 0x78A5636F43172F60ll, 0x84C87814A1F0AB72ll, 0x8CC702081A6439ECll, -- 0x90BEFFFA23631E28ll, 0xA4506CEBDE82BDE9ll, 0xBEF9A3F7B2C67915ll, -- 0xC67178F2E372532Bll, 0xCA273ECEEA26619Cll, 0xD186B8C721C0C207ll, -- 0xEADA7DD6CDE0EB1Ell, 0xF57D4F7FEE6ED178ll, 0x06F067AA72176FBAll, -- 0x0A637DC5A2C898A6ll, 0x113F9804BEF90DAEll, 0x1B710B35131C471Bll, -- 0x28DB77F523047D84ll, 0x32CAAB7B40C72493ll, 0x3C9EBE0A15C9BEBCll, -- 0x431D67C49C100D4Cll, 0x4CC5D4BECB3E42B6ll, 0x597F299CFC657E2All, -- 0x5FCB6FAB3AD6FAECll, 0x6C44198C4A475817ll -- }; -- int t, t8; /* Loop counter */ -- uint64_t temp1, temp2; /* Temporary word value */ -- uint64_t W[80]; /* Word sequence */ -- uint64_t A, B, C, D, E, F, G, H; /* Word buffers */ -- -- /* -- * Initialize the first 16 words in the array W -- */ -- for (t = t8 = 0; t < 16; t++, t8 += 8) -- W[t] = ((uint64_t)(context->Message_Block[t8 ]) << 56) | -- ((uint64_t)(context->Message_Block[t8 + 1]) << 48) | -- ((uint64_t)(context->Message_Block[t8 + 2]) << 40) | -- ((uint64_t)(context->Message_Block[t8 + 3]) << 32) | -- ((uint64_t)(context->Message_Block[t8 + 4]) << 24) | -- ((uint64_t)(context->Message_Block[t8 + 5]) << 16) | -- -- -- --Eastlake 3rd & Hansen Informational [Page 63] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- ((uint64_t)(context->Message_Block[t8 + 6]) << 8) | -- ((uint64_t)(context->Message_Block[t8 + 7])); -- -- for (t = 16; t < 80; t++) -- W[t] = SHA512_sigma1(W[t-2]) + W[t-7] + -- SHA512_sigma0(W[t-15]) + W[t-16]; -- -- A = context->Intermediate_Hash[0]; -- B = context->Intermediate_Hash[1]; -- C = context->Intermediate_Hash[2]; -- D = context->Intermediate_Hash[3]; -- E = context->Intermediate_Hash[4]; -- F = context->Intermediate_Hash[5]; -- G = context->Intermediate_Hash[6]; -- H = context->Intermediate_Hash[7]; -- -- for (t = 0; t < 80; t++) { -- temp1 = H + SHA512_SIGMA1(E) + SHA_Ch(E,F,G) + K[t] + W[t]; -- temp2 = SHA512_SIGMA0(A) + SHA_Maj(A,B,C); -- H = G; -- G = F; -- F = E; -- E = D + temp1; -- D = C; -- C = B; -- B = A; -- A = temp1 + temp2; -- } -- -- context->Intermediate_Hash[0] += A; -- context->Intermediate_Hash[1] += B; -- context->Intermediate_Hash[2] += C; -- context->Intermediate_Hash[3] += D; -- context->Intermediate_Hash[4] += E; -- context->Intermediate_Hash[5] += F; -- context->Intermediate_Hash[6] += G; -- context->Intermediate_Hash[7] += H; --#endif /* USE_32BIT_ONLY */ -- -- context->Message_Block_Index = 0; --} -- --/* -- * SHA384_512Reset -- * -- * Description: -- * This helper function will initialize the SHA512Context in -- * preparation for computing a new SHA384 or SHA512 message -- -- -- --Eastlake 3rd & Hansen Informational [Page 64] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * H0 -- * The initial hash value to use. -- * -- * Returns: -- * sha Error Code. -- * -- */ --#ifdef USE_32BIT_ONLY --static int SHA384_512Reset(SHA512Context *context, uint32_t H0[]) --#else /* !USE_32BIT_ONLY */ --static int SHA384_512Reset(SHA512Context *context, uint64_t H0[]) --#endif /* USE_32BIT_ONLY */ --{ -- int i; -- if (!context) -- return shaNull; -- -- context->Message_Block_Index = 0; -- --#ifdef USE_32BIT_ONLY -- context->Length[0] = context->Length[1] = 0; -- context->Length[2] = context->Length[3] = 0; -- -- for (i = 0; i < SHA512HashSize/4; i++) -- context->Intermediate_Hash[i] = H0[i]; --#else /* !USE_32BIT_ONLY */ -- context->Length_High = context->Length_Low = 0; -- -- for (i = 0; i < SHA512HashSize/8; i++) -- context->Intermediate_Hash[i] = H0[i]; --#endif /* USE_32BIT_ONLY */ -- -- context->Computed = 0; -- context->Corrupted = 0; -- -- return shaSuccess; --} -- --/* -- * SHA384_512ResultN -- * -- * Description: -- * This helper function will return the 384-bit or 512-bit message -- -- -- --Eastlake 3rd & Hansen Informational [Page 65] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * digest into the Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 48th/64th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * HashSize: [in] -- * The size of the hash, either 48 or 64. -- * -- * Returns: -- * sha Error Code. -- * -- */ --static int SHA384_512ResultN(SHA512Context *context, -- uint8_t Message_Digest[], int HashSize) --{ -- int i; -- --#ifdef USE_32BIT_ONLY -- int i2; --#endif /* USE_32BIT_ONLY */ -- -- if (!context || !Message_Digest) -- return shaNull; -- -- if (context->Corrupted) -- return context->Corrupted; -- -- if (!context->Computed) -- SHA384_512Finalize(context, 0x80); -- --#ifdef USE_32BIT_ONLY -- for (i = i2 = 0; i < HashSize; ) { -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>24); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>16); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>8); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2++]); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>24); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>16); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2]>>8); -- Message_Digest[i++]=(uint8_t)(context->Intermediate_Hash[i2++]); -- } --#else /* !USE_32BIT_ONLY */ -- for (i = 0; i < HashSize; ++i) -- Message_Digest[i] = (uint8_t) -- -- -- --Eastlake 3rd & Hansen Informational [Page 66] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- (context->Intermediate_Hash[i>>3] >> 8 * ( 7 - ( i % 8 ) )); --#endif /* USE_32BIT_ONLY */ -- -- return shaSuccess; --} -- --8.2.4. usha.c -- --/**************************** usha.c ****************************/ --/******************** See RFC 4634 for details ******************/ --/* -- * Description: -- * This file implements a unified interface to the SHA algorithms. -- */ -- --#include "sha.h" -- --/* -- * USHAReset -- * -- * Description: -- * This function will initialize the SHA Context in preparation -- * for computing a new SHA message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * whichSha: [in] -- * Selects which SHA reset to call -- * -- * Returns: -- * sha Error Code. -- * -- */ --int USHAReset(USHAContext *ctx, enum SHAversion whichSha) --{ -- if (ctx) { -- ctx->whichSha = whichSha; -- switch (whichSha) { -- case SHA1: return SHA1Reset((SHA1Context*)&ctx->ctx); -- case SHA224: return SHA224Reset((SHA224Context*)&ctx->ctx); -- case SHA256: return SHA256Reset((SHA256Context*)&ctx->ctx); -- case SHA384: return SHA384Reset((SHA384Context*)&ctx->ctx); -- case SHA512: return SHA512Reset((SHA512Context*)&ctx->ctx); -- default: return shaBadParam; -- } -- } else { -- return shaNull; -- -- -- --Eastlake 3rd & Hansen Informational [Page 67] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- } --} -- --/* -- * USHAInput -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- * -- */ --int USHAInput(USHAContext *ctx, -- const uint8_t *bytes, unsigned int bytecount) --{ -- if (ctx) { -- switch (ctx->whichSha) { -- case SHA1: -- return SHA1Input((SHA1Context*)&ctx->ctx, bytes, bytecount); -- case SHA224: -- return SHA224Input((SHA224Context*)&ctx->ctx, bytes, -- bytecount); -- case SHA256: -- return SHA256Input((SHA256Context*)&ctx->ctx, bytes, -- bytecount); -- case SHA384: -- return SHA384Input((SHA384Context*)&ctx->ctx, bytes, -- bytecount); -- case SHA512: -- return SHA512Input((SHA512Context*)&ctx->ctx, bytes, -- bytecount); -- default: return shaBadParam; -- } -- } else { -- return shaNull; -- } --} -- -- -- --Eastlake 3rd & Hansen Informational [Page 68] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * USHAFinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The SHA context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- */ --int USHAFinalBits(USHAContext *ctx, -- const uint8_t bits, unsigned int bitcount) --{ -- if (ctx) { -- switch (ctx->whichSha) { -- case SHA1: -- return SHA1FinalBits((SHA1Context*)&ctx->ctx, bits, bitcount); -- case SHA224: -- return SHA224FinalBits((SHA224Context*)&ctx->ctx, bits, -- bitcount); -- case SHA256: -- return SHA256FinalBits((SHA256Context*)&ctx->ctx, bits, -- bitcount); -- case SHA384: -- return SHA384FinalBits((SHA384Context*)&ctx->ctx, bits, -- bitcount); -- case SHA512: -- return SHA512FinalBits((SHA512Context*)&ctx->ctx, bits, -- bitcount); -- default: return shaBadParam; -- } -- } else { -- return shaNull; -- } --} -- --/* -- * USHAResult -- * -- -- -- --Eastlake 3rd & Hansen Informational [Page 69] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Description: -- * This function will return the 160-bit message digest into the -- * Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the 19th element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the SHA-1 hash. -- * Message_Digest: [out] -- * Where the digest is returned. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int USHAResult(USHAContext *ctx, -- uint8_t Message_Digest[USHAMaxHashSize]) --{ -- if (ctx) { -- switch (ctx->whichSha) { -- case SHA1: -- return SHA1Result((SHA1Context*)&ctx->ctx, Message_Digest); -- case SHA224: -- return SHA224Result((SHA224Context*)&ctx->ctx, Message_Digest); -- case SHA256: -- return SHA256Result((SHA256Context*)&ctx->ctx, Message_Digest); -- case SHA384: -- return SHA384Result((SHA384Context*)&ctx->ctx, Message_Digest); -- case SHA512: -- return SHA512Result((SHA512Context*)&ctx->ctx, Message_Digest); -- default: return shaBadParam; -- } -- } else { -- return shaNull; -- } --} -- --/* -- * USHABlockSize -- * -- * Description: -- * This function will return the blocksize for the given SHA -- * algorithm. -- * -- * Parameters: -- * whichSha: -- * which SHA algorithm to query -- -- -- --Eastlake 3rd & Hansen Informational [Page 70] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- * Returns: -- * block size -- * -- */ --int USHABlockSize(enum SHAversion whichSha) --{ -- switch (whichSha) { -- case SHA1: return SHA1_Message_Block_Size; -- case SHA224: return SHA224_Message_Block_Size; -- case SHA256: return SHA256_Message_Block_Size; -- case SHA384: return SHA384_Message_Block_Size; -- default: -- case SHA512: return SHA512_Message_Block_Size; -- } --} -- --/* -- * USHAHashSize -- * -- * Description: -- * This function will return the hashsize for the given SHA -- * algorithm. -- * -- * Parameters: -- * whichSha: -- * which SHA algorithm to query -- * -- * Returns: -- * hash size -- * -- */ --int USHAHashSize(enum SHAversion whichSha) --{ -- switch (whichSha) { -- case SHA1: return SHA1HashSize; -- case SHA224: return SHA224HashSize; -- case SHA256: return SHA256HashSize; -- case SHA384: return SHA384HashSize; -- default: -- case SHA512: return SHA512HashSize; -- } --} -- --/* -- * USHAHashSizeBits -- * -- * Description: -- -- -- --Eastlake 3rd & Hansen Informational [Page 71] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * This function will return the hashsize for the given SHA -- * algorithm, expressed in bits. -- * -- * Parameters: -- * whichSha: -- * which SHA algorithm to query -- * -- * Returns: -- * hash size in bits -- * -- */ --int USHAHashSizeBits(enum SHAversion whichSha) --{ -- switch (whichSha) { -- case SHA1: return SHA1HashSizeBits; -- case SHA224: return SHA224HashSizeBits; -- case SHA256: return SHA256HashSizeBits; -- case SHA384: return SHA384HashSizeBits; -- default: -- case SHA512: return SHA512HashSizeBits; -- } --} -- --8.2.5. sha-private.h -- --/*************************** sha-private.h ***************************/ --/********************** See RFC 4634 for details *********************/ --#ifndef _SHA_PRIVATE__H --#define _SHA_PRIVATE__H --/* -- * These definitions are defined in FIPS-180-2, section 4.1. -- * Ch() and Maj() are defined identically in sections 4.1.1, -- * 4.1.2 and 4.1.3. -- * -- * The definitions used in FIPS-180-2 are as follows: -- */ -- --#ifndef USE_MODIFIED_MACROS --#define SHA_Ch(x,y,z) (((x) & (y)) ^ ((~(x)) & (z))) --#define SHA_Maj(x,y,z) (((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z))) -- --#else /* USE_MODIFIED_MACROS */ --/* -- * The following definitions are equivalent and potentially faster. -- */ -- --#define SHA_Ch(x, y, z) (((x) & ((y) ^ (z))) ^ (z)) --#define SHA_Maj(x, y, z) (((x) & ((y) | (z))) | ((y) & (z))) -- -- -- --Eastlake 3rd & Hansen Informational [Page 72] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --#endif /* USE_MODIFIED_MACROS */ -- --#define SHA_Parity(x, y, z) ((x) ^ (y) ^ (z)) -- --#endif /* _SHA_PRIVATE__H */ -- --8.3 The HMAC Code -- --/**************************** hmac.c ****************************/ --/******************** See RFC 4634 for details ******************/ --/* -- * Description: -- * This file implements the HMAC algorithm (Keyed-Hashing for -- * Message Authentication, RFC2104), expressed in terms of the -- * various SHA algorithms. -- */ -- --#include "sha.h" -- --/* -- * hmac -- * -- * Description: -- * This function will compute an HMAC message digest. -- * -- * Parameters: -- * whichSha: [in] -- * One of SHA1, SHA224, SHA256, SHA384, SHA512 -- * key: [in] -- * The secret shared key. -- * key_len: [in] -- * The length of the secret shared key. -- * message_array: [in] -- * An array of characters representing the message. -- * length: [in] -- * The length of the message in message_array -- * digest: [out] -- * Where the digest is returned. -- * NOTE: The length of the digest is determined by -- * the value of whichSha. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int hmac(SHAversion whichSha, const unsigned char *text, int text_len, -- const unsigned char *key, int key_len, -- uint8_t digest[USHAMaxHashSize]) -- -- -- --Eastlake 3rd & Hansen Informational [Page 73] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --{ -- HMACContext ctx; -- return hmacReset(&ctx, whichSha, key, key_len) || -- hmacInput(&ctx, text, text_len) || -- hmacResult(&ctx, digest); --} -- --/* -- * hmacReset -- * -- * Description: -- * This function will initialize the hmacContext in preparation -- * for computing a new HMAC message digest. -- * -- * Parameters: -- * context: [in/out] -- * The context to reset. -- * whichSha: [in] -- * One of SHA1, SHA224, SHA256, SHA384, SHA512 -- * key: [in] -- * The secret shared key. -- * key_len: [in] -- * The length of the secret shared key. -- * -- * Returns: -- * sha Error Code. -- * -- */ --int hmacReset(HMACContext *ctx, enum SHAversion whichSha, -- const unsigned char *key, int key_len) --{ -- int i, blocksize, hashsize; -- -- /* inner padding - key XORd with ipad */ -- unsigned char k_ipad[USHA_Max_Message_Block_Size]; -- -- /* temporary buffer when keylen > blocksize */ -- unsigned char tempkey[USHAMaxHashSize]; -- -- if (!ctx) return shaNull; -- -- blocksize = ctx->blockSize = USHABlockSize(whichSha); -- hashsize = ctx->hashSize = USHAHashSize(whichSha); -- -- ctx->whichSha = whichSha; -- -- /* -- * If key is longer than the hash blocksize, -- -- -- --Eastlake 3rd & Hansen Informational [Page 74] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * reset it to key = HASH(key). -- */ -- if (key_len > blocksize) { -- USHAContext tctx; -- int err = USHAReset(&tctx, whichSha) || -- USHAInput(&tctx, key, key_len) || -- USHAResult(&tctx, tempkey); -- if (err != shaSuccess) return err; -- -- key = tempkey; -- key_len = hashsize; -- } -- -- /* -- * The HMAC transform looks like: -- * -- * SHA(K XOR opad, SHA(K XOR ipad, text)) -- * -- * where K is an n byte key. -- * ipad is the byte 0x36 repeated blocksize times -- * opad is the byte 0x5c repeated blocksize times -- * and text is the data being protected. -- */ -- -- /* store key into the pads, XOR'd with ipad and opad values */ -- for (i = 0; i < key_len; i++) { -- k_ipad[i] = key[i] ^ 0x36; -- ctx->k_opad[i] = key[i] ^ 0x5c; -- } -- /* remaining pad bytes are '\0' XOR'd with ipad and opad values */ -- for ( ; i < blocksize; i++) { -- k_ipad[i] = 0x36; -- ctx->k_opad[i] = 0x5c; -- } -- -- /* perform inner hash */ -- /* init context for 1st pass */ -- return USHAReset(&ctx->shaContext, whichSha) || -- /* and start with inner pad */ -- USHAInput(&ctx->shaContext, k_ipad, blocksize); --} -- --/* -- * hmacInput -- * -- * Description: -- * This function accepts an array of octets as the next portion -- * of the message. -- -- -- --Eastlake 3rd & Hansen Informational [Page 75] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- * Parameters: -- * context: [in/out] -- * The HMAC context to update -- * message_array: [in] -- * An array of characters representing the next portion of -- * the message. -- * length: [in] -- * The length of the message in message_array -- * -- * Returns: -- * sha Error Code. -- * -- */ --int hmacInput(HMACContext *ctx, const unsigned char *text, -- int text_len) --{ -- if (!ctx) return shaNull; -- /* then text of datagram */ -- return USHAInput(&ctx->shaContext, text, text_len); --} -- --/* -- * HMACFinalBits -- * -- * Description: -- * This function will add in any final bits of the message. -- * -- * Parameters: -- * context: [in/out] -- * The HMAC context to update -- * message_bits: [in] -- * The final bits of the message, in the upper portion of the -- * byte. (Use 0b###00000 instead of 0b00000### to input the -- * three bits ###.) -- * length: [in] -- * The number of bits in message_bits, between 1 and 7. -- * -- * Returns: -- * sha Error Code. -- */ --int hmacFinalBits(HMACContext *ctx, -- const uint8_t bits, -- unsigned int bitcount) --{ -- if (!ctx) return shaNull; -- /* then final bits of datagram */ -- return USHAFinalBits(&ctx->shaContext, bits, bitcount); -- -- -- --Eastlake 3rd & Hansen Informational [Page 76] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --} -- --/* -- * HMACResult -- * -- * Description: -- * This function will return the N-byte message digest into the -- * Message_Digest array provided by the caller. -- * NOTE: The first octet of hash is stored in the 0th element, -- * the last octet of hash in the Nth element. -- * -- * Parameters: -- * context: [in/out] -- * The context to use to calculate the HMAC hash. -- * digest: [out] -- * Where the digest is returned. -- * NOTE 2: The length of the hash is determined by the value of -- * whichSha that was passed to hmacReset(). -- * -- * Returns: -- * sha Error Code. -- * -- */ --int hmacResult(HMACContext *ctx, uint8_t *digest) --{ -- if (!ctx) return shaNull; -- -- /* finish up 1st pass */ -- /* (Use digest here as a temporary buffer.) */ -- return USHAResult(&ctx->shaContext, digest) || -- -- /* perform outer SHA */ -- /* init context for 2nd pass */ -- USHAReset(&ctx->shaContext, ctx->whichSha) || -- -- /* start with outer pad */ -- USHAInput(&ctx->shaContext, ctx->k_opad, ctx->blockSize) || -- -- /* then results of 1st hash */ -- USHAInput(&ctx->shaContext, digest, ctx->hashSize) || -- -- /* finish up 2nd pass */ -- USHAResult(&ctx->shaContext, digest); --} -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 77] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --8.4. The Test Driver -- -- The following code is a main program test driver to exercise the code -- in sha1.c, sha224-256.c, and sha384-512.c. The test driver can also -- be used as a stand-alone program for generating the hashes. -- -- See also [RFC2202], [RFC4231], and [SHAVS]. -- --/**************************** shatest.c ****************************/ --/********************* See RFC 4634 for details ********************/ --/* -- * Description: -- * This file will exercise the SHA code performing -- * the three tests documented in FIPS PUB 180-2 -- * (http://csrc.nist.gov/publications/fips/ -- * fips180-2/fips180-2withchangenotice.pdf) -- * one that calls SHAInput with an exact multiple of 512 bits -- * the seven tests documented for each algorithm in -- * "The Secure Hash Algorithm Validation System (SHAVS)", -- * three of which are bit-level tests -- * (http://csrc.nist.gov/cryptval/shs/SHAVS.pdf) -- * -- * This file will exercise the HMAC SHA1 code performing -- * the seven tests documented in RFCs 2202 and 4231. -- * -- * To run the tests and just see PASSED/FAILED, use the -p option. -- * -- * Other options exercise: -- * hashing an arbitrary string -- * hashing a file's contents -- * a few error test checks -- * printing the results in raw format -- * -- * Portability Issues: -- * None. -- * -- */ -- --#include --#include --#include --#include --#include --#include "sha.h" -- --static int xgetopt(int argc, char **argv, const char *optstring); --extern char *xoptarg; --static int scasecmp(const char *s1, const char *s2); -- -- -- --Eastlake 3rd & Hansen Informational [Page 78] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * Define patterns for testing -- */ --#define TEST1 "abc" --#define TEST2_1 \ -- "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq" --#define TEST2_2a \ -- "abcdefghbcdefghicdefghijdefghijkefghijklfghijklmghijklmn" --#define TEST2_2b \ -- "hijklmnoijklmnopjklmnopqklmnopqrlmnopqrsmnopqrstnopqrstu" --#define TEST2_2 TEST2_2a TEST2_2b --#define TEST3 "a" /* times 1000000 */ --#define TEST4a "01234567012345670123456701234567" --#define TEST4b "01234567012345670123456701234567" -- /* an exact multiple of 512 bits */ --#define TEST4 TEST4a TEST4b /* times 10 */ -- --#define TEST7_1 \ -- "\x49\xb2\xae\xc2\x59\x4b\xbe\x3a\x3b\x11\x75\x42\xd9\x4a\xc8" --#define TEST8_1 \ -- "\x9a\x7d\xfd\xf1\xec\xea\xd0\x6e\xd6\x46\xaa\x55\xfe\x75\x71\x46" --#define TEST9_1 \ -- "\x65\xf9\x32\x99\x5b\xa4\xce\x2c\xb1\xb4\xa2\xe7\x1a\xe7\x02\x20" \ -- "\xaa\xce\xc8\x96\x2d\xd4\x49\x9c\xbd\x7c\x88\x7a\x94\xea\xaa\x10" \ -- "\x1e\xa5\xaa\xbc\x52\x9b\x4e\x7e\x43\x66\x5a\x5a\xf2\xcd\x03\xfe" \ -- "\x67\x8e\xa6\xa5\x00\x5b\xba\x3b\x08\x22\x04\xc2\x8b\x91\x09\xf4" \ -- "\x69\xda\xc9\x2a\xaa\xb3\xaa\x7c\x11\xa1\xb3\x2a" --#define TEST10_1 \ -- "\xf7\x8f\x92\x14\x1b\xcd\x17\x0a\xe8\x9b\x4f\xba\x15\xa1\xd5\x9f" \ -- "\x3f\xd8\x4d\x22\x3c\x92\x51\xbd\xac\xbb\xae\x61\xd0\x5e\xd1\x15" \ -- "\xa0\x6a\x7c\xe1\x17\xb7\xbe\xea\xd2\x44\x21\xde\xd9\xc3\x25\x92" \ -- "\xbd\x57\xed\xea\xe3\x9c\x39\xfa\x1f\xe8\x94\x6a\x84\xd0\xcf\x1f" \ -- "\x7b\xee\xad\x17\x13\xe2\xe0\x95\x98\x97\x34\x7f\x67\xc8\x0b\x04" \ -- "\x00\xc2\x09\x81\x5d\x6b\x10\xa6\x83\x83\x6f\xd5\x56\x2a\x56\xca" \ -- "\xb1\xa2\x8e\x81\xb6\x57\x66\x54\x63\x1c\xf1\x65\x66\xb8\x6e\x3b" \ -- "\x33\xa1\x08\xb0\x53\x07\xc0\x0a\xff\x14\xa7\x68\xed\x73\x50\x60" \ -- "\x6a\x0f\x85\xe6\xa9\x1d\x39\x6f\x5b\x5c\xbe\x57\x7f\x9b\x38\x80" \ -- "\x7c\x7d\x52\x3d\x6d\x79\x2f\x6e\xbc\x24\xa4\xec\xf2\xb3\xa4\x27" \ -- "\xcd\xbb\xfb" --#define TEST7_224 \ -- "\xf0\x70\x06\xf2\x5a\x0b\xea\x68\xcd\x76\xa2\x95\x87\xc2\x8d" --#define TEST8_224 \ -- "\x18\x80\x40\x05\xdd\x4f\xbd\x15\x56\x29\x9d\x6f\x9d\x93\xdf\x62" --#define TEST9_224 \ -- "\xa2\xbe\x6e\x46\x32\x81\x09\x02\x94\xd9\xce\x94\x82\x65\x69\x42" \ -- "\x3a\x3a\x30\x5e\xd5\xe2\x11\x6c\xd4\xa4\xc9\x87\xfc\x06\x57\x00" \ -- "\x64\x91\xb1\x49\xcc\xd4\xb5\x11\x30\xac\x62\xb1\x9d\xc2\x48\xc7" \ -- "\x44\x54\x3d\x20\xcd\x39\x52\xdc\xed\x1f\x06\xcc\x3b\x18\xb9\x1f" \ -- -- -- --Eastlake 3rd & Hansen Informational [Page 79] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "\x3f\x55\x63\x3e\xcc\x30\x85\xf4\x90\x70\x60\xd2" --#define TEST10_224 \ -- "\x55\xb2\x10\x07\x9c\x61\xb5\x3a\xdd\x52\x06\x22\xd1\xac\x97\xd5" \ -- "\xcd\xbe\x8c\xb3\x3a\xa0\xae\x34\x45\x17\xbe\xe4\xd7\xba\x09\xab" \ -- "\xc8\x53\x3c\x52\x50\x88\x7a\x43\xbe\xbb\xac\x90\x6c\x2e\x18\x37" \ -- "\xf2\x6b\x36\xa5\x9a\xe3\xbe\x78\x14\xd5\x06\x89\x6b\x71\x8b\x2a" \ -- "\x38\x3e\xcd\xac\x16\xb9\x61\x25\x55\x3f\x41\x6f\xf3\x2c\x66\x74" \ -- "\xc7\x45\x99\xa9\x00\x53\x86\xd9\xce\x11\x12\x24\x5f\x48\xee\x47" \ -- "\x0d\x39\x6c\x1e\xd6\x3b\x92\x67\x0c\xa5\x6e\xc8\x4d\xee\xa8\x14" \ -- "\xb6\x13\x5e\xca\x54\x39\x2b\xde\xdb\x94\x89\xbc\x9b\x87\x5a\x8b" \ -- "\xaf\x0d\xc1\xae\x78\x57\x36\x91\x4a\xb7\xda\xa2\x64\xbc\x07\x9d" \ -- "\x26\x9f\x2c\x0d\x7e\xdd\xd8\x10\xa4\x26\x14\x5a\x07\x76\xf6\x7c" \ -- "\x87\x82\x73" --#define TEST7_256 \ -- "\xbe\x27\x46\xc6\xdb\x52\x76\x5f\xdb\x2f\x88\x70\x0f\x9a\x73" --#define TEST8_256 \ -- "\xe3\xd7\x25\x70\xdc\xdd\x78\x7c\xe3\x88\x7a\xb2\xcd\x68\x46\x52" --#define TEST9_256 \ -- "\x3e\x74\x03\x71\xc8\x10\xc2\xb9\x9f\xc0\x4e\x80\x49\x07\xef\x7c" \ -- "\xf2\x6b\xe2\x8b\x57\xcb\x58\xa3\xe2\xf3\xc0\x07\x16\x6e\x49\xc1" \ -- "\x2e\x9b\xa3\x4c\x01\x04\x06\x91\x29\xea\x76\x15\x64\x25\x45\x70" \ -- "\x3a\x2b\xd9\x01\xe1\x6e\xb0\xe0\x5d\xeb\xa0\x14\xeb\xff\x64\x06" \ -- "\xa0\x7d\x54\x36\x4e\xff\x74\x2d\xa7\x79\xb0\xb3" --#define TEST10_256 \ -- "\x83\x26\x75\x4e\x22\x77\x37\x2f\x4f\xc1\x2b\x20\x52\x7a\xfe\xf0" \ -- "\x4d\x8a\x05\x69\x71\xb1\x1a\xd5\x71\x23\xa7\xc1\x37\x76\x00\x00" \ -- "\xd7\xbe\xf6\xf3\xc1\xf7\xa9\x08\x3a\xa3\x9d\x81\x0d\xb3\x10\x77" \ -- "\x7d\xab\x8b\x1e\x7f\x02\xb8\x4a\x26\xc7\x73\x32\x5f\x8b\x23\x74" \ -- "\xde\x7a\x4b\x5a\x58\xcb\x5c\x5c\xf3\x5b\xce\xe6\xfb\x94\x6e\x5b" \ -- "\xd6\x94\xfa\x59\x3a\x8b\xeb\x3f\x9d\x65\x92\xec\xed\xaa\x66\xca" \ -- "\x82\xa2\x9d\x0c\x51\xbc\xf9\x33\x62\x30\xe5\xd7\x84\xe4\xc0\xa4" \ -- "\x3f\x8d\x79\xa3\x0a\x16\x5c\xba\xbe\x45\x2b\x77\x4b\x9c\x71\x09" \ -- "\xa9\x7d\x13\x8f\x12\x92\x28\x96\x6f\x6c\x0a\xdc\x10\x6a\xad\x5a" \ -- "\x9f\xdd\x30\x82\x57\x69\xb2\xc6\x71\xaf\x67\x59\xdf\x28\xeb\x39" \ -- "\x3d\x54\xd6" --#define TEST7_384 \ -- "\x8b\xc5\x00\xc7\x7c\xee\xd9\x87\x9d\xa9\x89\x10\x7c\xe0\xaa" --#define TEST8_384 \ -- "\xa4\x1c\x49\x77\x79\xc0\x37\x5f\xf1\x0a\x7f\x4e\x08\x59\x17\x39" --#define TEST9_384 \ -- "\x68\xf5\x01\x79\x2d\xea\x97\x96\x76\x70\x22\xd9\x3d\xa7\x16\x79" \ -- "\x30\x99\x20\xfa\x10\x12\xae\xa3\x57\xb2\xb1\x33\x1d\x40\xa1\xd0" \ -- "\x3c\x41\xc2\x40\xb3\xc9\xa7\x5b\x48\x92\xf4\xc0\x72\x4b\x68\xc8" \ -- "\x75\x32\x1a\xb8\xcf\xe5\x02\x3b\xd3\x75\xbc\x0f\x94\xbd\x89\xfe" \ -- "\x04\xf2\x97\x10\x5d\x7b\x82\xff\xc0\x02\x1a\xeb\x1c\xcb\x67\x4f" \ -- "\x52\x44\xea\x34\x97\xde\x26\xa4\x19\x1c\x5f\x62\xe5\xe9\xa2\xd8" \ -- "\x08\x2f\x05\x51\xf4\xa5\x30\x68\x26\xe9\x1c\xc0\x06\xce\x1b\xf6" \ -- "\x0f\xf7\x19\xd4\x2f\xa5\x21\xc8\x71\xcd\x23\x94\xd9\x6e\xf4\x46" \ -- -- -- --Eastlake 3rd & Hansen Informational [Page 80] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "\x8f\x21\x96\x6b\x41\xf2\xba\x80\xc2\x6e\x83\xa9" --#define TEST10_384 \ -- "\x39\x96\x69\xe2\x8f\x6b\x9c\x6d\xbc\xbb\x69\x12\xec\x10\xff\xcf" \ -- "\x74\x79\x03\x49\xb7\xdc\x8f\xbe\x4a\x8e\x7b\x3b\x56\x21\xdb\x0f" \ -- "\x3e\x7d\xc8\x7f\x82\x32\x64\xbb\xe4\x0d\x18\x11\xc9\xea\x20\x61" \ -- "\xe1\xc8\x4a\xd1\x0a\x23\xfa\xc1\x72\x7e\x72\x02\xfc\x3f\x50\x42" \ -- "\xe6\xbf\x58\xcb\xa8\xa2\x74\x6e\x1f\x64\xf9\xb9\xea\x35\x2c\x71" \ -- "\x15\x07\x05\x3c\xf4\xe5\x33\x9d\x52\x86\x5f\x25\xcc\x22\xb5\xe8" \ -- "\x77\x84\xa1\x2f\xc9\x61\xd6\x6c\xb6\xe8\x95\x73\x19\x9a\x2c\xe6" \ -- "\x56\x5c\xbd\xf1\x3d\xca\x40\x38\x32\xcf\xcb\x0e\x8b\x72\x11\xe8" \ -- "\x3a\xf3\x2a\x11\xac\x17\x92\x9f\xf1\xc0\x73\xa5\x1c\xc0\x27\xaa" \ -- "\xed\xef\xf8\x5a\xad\x7c\x2b\x7c\x5a\x80\x3e\x24\x04\xd9\x6d\x2a" \ -- "\x77\x35\x7b\xda\x1a\x6d\xae\xed\x17\x15\x1c\xb9\xbc\x51\x25\xa4" \ -- "\x22\xe9\x41\xde\x0c\xa0\xfc\x50\x11\xc2\x3e\xcf\xfe\xfd\xd0\x96" \ -- "\x76\x71\x1c\xf3\xdb\x0a\x34\x40\x72\x0e\x16\x15\xc1\xf2\x2f\xbc" \ -- "\x3c\x72\x1d\xe5\x21\xe1\xb9\x9b\xa1\xbd\x55\x77\x40\x86\x42\x14" \ -- "\x7e\xd0\x96" --#define TEST7_512 \ -- "\x08\xec\xb5\x2e\xba\xe1\xf7\x42\x2d\xb6\x2b\xcd\x54\x26\x70" --#define TEST8_512 \ -- "\x8d\x4e\x3c\x0e\x38\x89\x19\x14\x91\x81\x6e\x9d\x98\xbf\xf0\xa0" --#define TEST9_512 \ -- "\x3a\xdd\xec\x85\x59\x32\x16\xd1\x61\x9a\xa0\x2d\x97\x56\x97\x0b" \ -- "\xfc\x70\xac\xe2\x74\x4f\x7c\x6b\x27\x88\x15\x10\x28\xf7\xb6\xa2" \ -- "\x55\x0f\xd7\x4a\x7e\x6e\x69\xc2\xc9\xb4\x5f\xc4\x54\x96\x6d\xc3" \ -- "\x1d\x2e\x10\xda\x1f\x95\xce\x02\xbe\xb4\xbf\x87\x65\x57\x4c\xbd" \ -- "\x6e\x83\x37\xef\x42\x0a\xdc\x98\xc1\x5c\xb6\xd5\xe4\xa0\x24\x1b" \ -- "\xa0\x04\x6d\x25\x0e\x51\x02\x31\xca\xc2\x04\x6c\x99\x16\x06\xab" \ -- "\x4e\xe4\x14\x5b\xee\x2f\xf4\xbb\x12\x3a\xab\x49\x8d\x9d\x44\x79" \ -- "\x4f\x99\xcc\xad\x89\xa9\xa1\x62\x12\x59\xed\xa7\x0a\x5b\x6d\xd4" \ -- "\xbd\xd8\x77\x78\xc9\x04\x3b\x93\x84\xf5\x49\x06" --#define TEST10_512 \ -- "\xa5\x5f\x20\xc4\x11\xaa\xd1\x32\x80\x7a\x50\x2d\x65\x82\x4e\x31" \ -- "\xa2\x30\x54\x32\xaa\x3d\x06\xd3\xe2\x82\xa8\xd8\x4e\x0d\xe1\xde" \ -- "\x69\x74\xbf\x49\x54\x69\xfc\x7f\x33\x8f\x80\x54\xd5\x8c\x26\xc4" \ -- "\x93\x60\xc3\xe8\x7a\xf5\x65\x23\xac\xf6\xd8\x9d\x03\xe5\x6f\xf2" \ -- "\xf8\x68\x00\x2b\xc3\xe4\x31\xed\xc4\x4d\xf2\xf0\x22\x3d\x4b\xb3" \ -- "\xb2\x43\x58\x6e\x1a\x7d\x92\x49\x36\x69\x4f\xcb\xba\xf8\x8d\x95" \ -- "\x19\xe4\xeb\x50\xa6\x44\xf8\xe4\xf9\x5e\xb0\xea\x95\xbc\x44\x65" \ -- "\xc8\x82\x1a\xac\xd2\xfe\x15\xab\x49\x81\x16\x4b\xbb\x6d\xc3\x2f" \ -- "\x96\x90\x87\xa1\x45\xb0\xd9\xcc\x9c\x67\xc2\x2b\x76\x32\x99\x41" \ -- "\x9c\xc4\x12\x8b\xe9\xa0\x77\xb3\xac\xe6\x34\x06\x4e\x6d\x99\x28" \ -- "\x35\x13\xdc\x06\xe7\x51\x5d\x0d\x73\x13\x2e\x9a\x0d\xc6\xd3\xb1" \ -- "\xf8\xb2\x46\xf1\xa9\x8a\x3f\xc7\x29\x41\xb1\xe3\xbb\x20\x98\xe8" \ -- "\xbf\x16\xf2\x68\xd6\x4f\x0b\x0f\x47\x07\xfe\x1e\xa1\xa1\x79\x1b" \ -- "\xa2\xf3\xc0\xc7\x58\xe5\xf5\x51\x86\x3a\x96\xc9\x49\xad\x47\xd7" \ -- "\xfb\x40\xd2" --#define SHA1_SEED "\xd0\x56\x9c\xb3\x66\x5a\x8a\x43\xeb\x6e\xa2\x3d" \ -- -- -- --Eastlake 3rd & Hansen Informational [Page 81] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "\x75\xa3\xc4\xd2\x05\x4a\x0d\x7d" --#define SHA224_SEED "\xd0\x56\x9c\xb3\x66\x5a\x8a\x43\xeb\x6e\xa2" \ -- "\x3d\x75\xa3\xc4\xd2\x05\x4a\x0d\x7d\x66\xa9\xca\x99\xc9\xce\xb0" \ -- "\x27" --#define SHA256_SEED "\xf4\x1e\xce\x26\x13\xe4\x57\x39\x15\x69\x6b" \ -- "\x5a\xdc\xd5\x1c\xa3\x28\xbe\x3b\xf5\x66\xa9\xca\x99\xc9\xce\xb0" \ -- "\x27\x9c\x1c\xb0\xa7" --#define SHA384_SEED "\x82\x40\xbc\x51\xe4\xec\x7e\xf7\x6d\x18\xe3" \ -- "\x52\x04\xa1\x9f\x51\xa5\x21\x3a\x73\xa8\x1d\x6f\x94\x46\x80\xd3" \ -- "\x07\x59\x48\xb7\xe4\x63\x80\x4e\xa3\xd2\x6e\x13\xea\x82\x0d\x65" \ -- "\xa4\x84\xbe\x74\x53" --#define SHA512_SEED "\x47\x3f\xf1\xb9\xb3\xff\xdf\xa1\x26\x69\x9a" \ -- "\xc7\xef\x9e\x8e\x78\x77\x73\x09\x58\x24\xc6\x42\x55\x7c\x13\x99" \ -- "\xd9\x8e\x42\x20\x44\x8d\xc3\x5b\x99\xbf\xdd\x44\x77\x95\x43\x92" \ -- "\x4c\x1c\xe9\x3b\xc5\x94\x15\x38\x89\x5d\xb9\x88\x26\x1b\x00\x77" \ -- "\x4b\x12\x27\x20\x39" -- --#define TESTCOUNT 10 --#define HASHCOUNT 5 --#define RANDOMCOUNT 4 --#define HMACTESTCOUNT 7 -- --#define PRINTNONE 0 --#define PRINTTEXT 1 --#define PRINTRAW 2 --#define PRINTHEX 3 --#define PRINTBASE64 4 -- --#define PRINTPASSFAIL 1 --#define PRINTFAIL 2 -- --#define length(x) (sizeof(x)-1) -- --/* Test arrays for hashes. */ --struct hash { -- const char *name; -- SHAversion whichSha; -- int hashsize; -- struct { -- const char *testarray; -- int length; -- long repeatcount; -- int extrabits; -- int numberExtrabits; -- const char *resultarray; -- } tests[TESTCOUNT]; -- const char *randomtest; -- const char *randomresults[RANDOMCOUNT]; -- -- -- --Eastlake 3rd & Hansen Informational [Page 82] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --} hashes[HASHCOUNT] = { -- { "SHA1", SHA1, SHA1HashSize, -- { -- /* 1 */ { TEST1, length(TEST1), 1, 0, 0, -- "A9993E364706816ABA3E25717850C26C9CD0D89D" }, -- /* 2 */ { TEST2_1, length(TEST2_1), 1, 0, 0, -- "84983E441C3BD26EBAAE4AA1F95129E5E54670F1" }, -- /* 3 */ { TEST3, length(TEST3), 1000000, 0, 0, -- "34AA973CD4C4DAA4F61EEB2BDBAD27316534016F" }, -- /* 4 */ { TEST4, length(TEST4), 10, 0, 0, -- "DEA356A2CDDD90C7A7ECEDC5EBB563934F460452" }, -- /* 5 */ { "", 0, 0, 0x98, 5, -- "29826B003B906E660EFF4027CE98AF3531AC75BA" }, -- /* 6 */ { "\x5e", 1, 1, 0, 0, -- "5E6F80A34A9798CAFC6A5DB96CC57BA4C4DB59C2" }, -- /* 7 */ { TEST7_1, length(TEST7_1), 1, 0x80, 3, -- "6239781E03729919C01955B3FFA8ACB60B988340" }, -- /* 8 */ { TEST8_1, length(TEST8_1), 1, 0, 0, -- "82ABFF6605DBE1C17DEF12A394FA22A82B544A35" }, -- /* 9 */ { TEST9_1, length(TEST9_1), 1, 0xE0, 3, -- "8C5B2A5DDAE5A97FC7F9D85661C672ADBF7933D4" }, -- /* 10 */ { TEST10_1, length(TEST10_1), 1, 0, 0, -- "CB0082C8F197D260991BA6A460E76E202BAD27B3" } -- }, SHA1_SEED, { "E216836819477C7F78E0D843FE4FF1B6D6C14CD4", -- "A2DBC7A5B1C6C0A8BCB7AAA41252A6A7D0690DBC", -- "DB1F9050BB863DFEF4CE37186044E2EEB17EE013", -- "127FDEDF43D372A51D5747C48FBFFE38EF6CDF7B" -- } }, -- { "SHA224", SHA224, SHA224HashSize, -- { -- /* 1 */ { TEST1, length(TEST1), 1, 0, 0, -- "23097D223405D8228642A477BDA255B32AADBCE4BDA0B3F7E36C9DA7" }, -- /* 2 */ { TEST2_1, length(TEST2_1), 1, 0, 0, -- "75388B16512776CC5DBA5DA1FD890150B0C6455CB4F58B1952522525" }, -- /* 3 */ { TEST3, length(TEST3), 1000000, 0, 0, -- "20794655980C91D8BBB4C1EA97618A4BF03F42581948B2EE4EE7AD67" }, -- /* 4 */ { TEST4, length(TEST4), 10, 0, 0, -- "567F69F168CD7844E65259CE658FE7AADFA25216E68ECA0EB7AB8262" }, -- /* 5 */ { "", 0, 0, 0x68, 5, -- "E3B048552C3C387BCAB37F6EB06BB79B96A4AEE5FF27F51531A9551C" }, -- /* 6 */ { "\x07", 1, 1, 0, 0, -- "00ECD5F138422B8AD74C9799FD826C531BAD2FCABC7450BEE2AA8C2A" }, -- /* 7 */ { TEST7_224, length(TEST7_224), 1, 0xA0, 3, -- "1B01DB6CB4A9E43DED1516BEB3DB0B87B6D1EA43187462C608137150" }, -- /* 8 */ { TEST8_224, length(TEST8_224), 1, 0, 0, -- "DF90D78AA78821C99B40BA4C966921ACCD8FFB1E98AC388E56191DB1" }, -- /* 9 */ { TEST9_224, length(TEST9_224), 1, 0xE0, 3, -- "54BEA6EAB8195A2EB0A7906A4B4A876666300EEFBD1F3B8474F9CD57" }, -- -- -- --Eastlake 3rd & Hansen Informational [Page 83] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- /* 10 */ { TEST10_224, length(TEST10_224), 1, 0, 0, -- "0B31894EC8937AD9B91BDFBCBA294D9ADEFAA18E09305E9F20D5C3A4" } -- }, SHA224_SEED, { "100966A5B4FDE0B42E2A6C5953D4D7F41BA7CF79FD" -- "2DF431416734BE", "1DCA396B0C417715DEFAAE9641E10A2E99D55A" -- "BCB8A00061EB3BE8BD", "1864E627BDB2319973CD5ED7D68DA71D8B" -- "F0F983D8D9AB32C34ADB34", "A2406481FC1BCAF24DD08E6752E844" -- "709563FB916227FED598EB621F" -- } }, -- { "SHA256", SHA256, SHA256HashSize, -- { -- /* 1 */ { TEST1, length(TEST1), 1, 0, 0, "BA7816BF8F01CFEA4141" -- "40DE5DAE2223B00361A396177A9CB410FF61F20015AD" }, -- /* 2 */ { TEST2_1, length(TEST2_1), 1, 0, 0, "248D6A61D20638B8" -- "E5C026930C3E6039A33CE45964FF2167F6ECEDD419DB06C1" }, -- /* 3 */ { TEST3, length(TEST3), 1000000, 0, 0, "CDC76E5C9914FB92" -- "81A1C7E284D73E67F1809A48A497200E046D39CCC7112CD0" }, -- /* 4 */ { TEST4, length(TEST4), 10, 0, 0, "594847328451BDFA" -- "85056225462CC1D867D877FB388DF0CE35F25AB5562BFBB5" }, -- /* 5 */ { "", 0, 0, 0x68, 5, "D6D3E02A31A84A8CAA9718ED6C2057BE" -- "09DB45E7823EB5079CE7A573A3760F95" }, -- /* 6 */ { "\x19", 1, 1, 0, 0, "68AA2E2EE5DFF96E3355E6C7EE373E3D" -- "6A4E17F75F9518D843709C0C9BC3E3D4" }, -- /* 7 */ { TEST7_256, length(TEST7_256), 1, 0x60, 3, "77EC1DC8" -- "9C821FF2A1279089FA091B35B8CD960BCAF7DE01C6A7680756BEB972" }, -- /* 8 */ { TEST8_256, length(TEST8_256), 1, 0, 0, "175EE69B02BA" -- "9B58E2B0A5FD13819CEA573F3940A94F825128CF4209BEABB4E8" }, -- /* 9 */ { TEST9_256, length(TEST9_256), 1, 0xA0, 3, "3E9AD646" -- "8BBBAD2AC3C2CDC292E018BA5FD70B960CF1679777FCE708FDB066E9" }, -- /* 10 */ { TEST10_256, length(TEST10_256), 1, 0, 0, "97DBCA7D" -- "F46D62C8A422C941DD7E835B8AD3361763F7E9B2D95F4F0DA6E1CCBC" }, -- }, SHA256_SEED, { "83D28614D49C3ADC1D6FC05DB5F48037C056F8D2A4CE44" -- "EC6457DEA5DD797CD1", "99DBE3127EF2E93DD9322D6A07909EB33B6399" -- "5E529B3F954B8581621BB74D39", "8D4BE295BB64661CA3C7EFD129A2F7" -- "25B33072DBDDE32385B9A87B9AF88EA76F", "40AF5D3F9716B040DF9408" -- "E31536B70FF906EC51B00447CA97D7DD97C12411F4" -- } }, -- { "SHA384", SHA384, SHA384HashSize, -- { -- /* 1 */ { TEST1, length(TEST1), 1, 0, 0, -- "CB00753F45A35E8BB5A03D699AC65007272C32AB0EDED163" -- "1A8B605A43FF5BED8086072BA1E7CC2358BAECA134C825A7" }, -- /* 2 */ { TEST2_2, length(TEST2_2), 1, 0, 0, -- "09330C33F71147E83D192FC782CD1B4753111B173B3B05D2" -- "2FA08086E3B0F712FCC7C71A557E2DB966C3E9FA91746039" }, -- /* 3 */ { TEST3, length(TEST3), 1000000, 0, 0, -- "9D0E1809716474CB086E834E310A4A1CED149E9C00F24852" -- "7972CEC5704C2A5B07B8B3DC38ECC4EBAE97DDD87F3D8985" }, -- /* 4 */ { TEST4, length(TEST4), 10, 0, 0, -- -- -- --Eastlake 3rd & Hansen Informational [Page 84] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "2FC64A4F500DDB6828F6A3430B8DD72A368EB7F3A8322A70" -- "BC84275B9C0B3AB00D27A5CC3C2D224AA6B61A0D79FB4596" }, -- /* 5 */ { "", 0, 0, 0x10, 5, -- "8D17BE79E32B6718E07D8A603EB84BA0478F7FCFD1BB9399" -- "5F7D1149E09143AC1FFCFC56820E469F3878D957A15A3FE4" }, -- /* 6 */ { "\xb9", 1, 1, 0, 0, -- "BC8089A19007C0B14195F4ECC74094FEC64F01F90929282C" -- "2FB392881578208AD466828B1C6C283D2722CF0AD1AB6938" }, -- /* 7 */ { TEST7_384, length(TEST7_384), 1, 0xA0, 3, -- "D8C43B38E12E7C42A7C9B810299FD6A770BEF30920F17532" -- "A898DE62C7A07E4293449C0B5FA70109F0783211CFC4BCE3" }, -- /* 8 */ { TEST8_384, length(TEST8_384), 1, 0, 0, -- "C9A68443A005812256B8EC76B00516F0DBB74FAB26D66591" -- "3F194B6FFB0E91EA9967566B58109CBC675CC208E4C823F7" }, -- /* 9 */ { TEST9_384, length(TEST9_384), 1, 0xE0, 3, -- "5860E8DE91C21578BB4174D227898A98E0B45C4C760F0095" -- "49495614DAEDC0775D92D11D9F8CE9B064EEAC8DAFC3A297" }, -- /* 10 */ { TEST10_384, length(TEST10_384), 1, 0, 0, -- "4F440DB1E6EDD2899FA335F09515AA025EE177A79F4B4AAF" -- "38E42B5C4DE660F5DE8FB2A5B2FBD2A3CBFFD20CFF1288C0" } -- }, SHA384_SEED, { "CE44D7D63AE0C91482998CF662A51EC80BF6FC68661A3C" -- "57F87566112BD635A743EA904DEB7D7A42AC808CABE697F38F", "F9C6D2" -- "61881FEE41ACD39E67AA8D0BAD507C7363EB67E2B81F45759F9C0FD7B503" -- "DF1A0B9E80BDE7BC333D75B804197D", "D96512D8C9F4A7A4967A366C01" -- "C6FD97384225B58343A88264847C18E4EF8AB7AEE4765FFBC3E30BD485D3" -- "638A01418F", "0CA76BD0813AF1509E170907A96005938BC985628290B2" -- "5FEF73CF6FAD68DDBA0AC8920C94E0541607B0915A7B4457F7" -- } }, -- { "SHA512", SHA512, SHA512HashSize, -- { -- /* 1 */ { TEST1, length(TEST1), 1, 0, 0, -- "DDAF35A193617ABACC417349AE20413112E6FA4E89A97EA2" -- "0A9EEEE64B55D39A2192992A274FC1A836BA3C23A3FEEBBD" -- "454D4423643CE80E2A9AC94FA54CA49F" }, -- /* 2 */ { TEST2_2, length(TEST2_2), 1, 0, 0, -- "8E959B75DAE313DA8CF4F72814FC143F8F7779C6EB9F7FA1" -- "7299AEADB6889018501D289E4900F7E4331B99DEC4B5433A" -- "C7D329EEB6DD26545E96E55B874BE909" }, -- /* 3 */ { TEST3, length(TEST3), 1000000, 0, 0, -- "E718483D0CE769644E2E42C7BC15B4638E1F98B13B204428" -- "5632A803AFA973EBDE0FF244877EA60A4CB0432CE577C31B" -- "EB009C5C2C49AA2E4EADB217AD8CC09B" }, -- /* 4 */ { TEST4, length(TEST4), 10, 0, 0, -- "89D05BA632C699C31231DED4FFC127D5A894DAD412C0E024" -- "DB872D1ABD2BA8141A0F85072A9BE1E2AA04CF33C765CB51" -- "0813A39CD5A84C4ACAA64D3F3FB7BAE9" }, -- /* 5 */ { "", 0, 0, 0xB0, 5, -- "D4EE29A9E90985446B913CF1D1376C836F4BE2C1CF3CADA0" -- -- -- --Eastlake 3rd & Hansen Informational [Page 85] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "720A6BF4857D886A7ECB3C4E4C0FA8C7F95214E41DC1B0D2" -- "1B22A84CC03BF8CE4845F34DD5BDBAD4" }, -- /* 6 */ { "\xD0", 1, 1, 0, 0, -- "9992202938E882E73E20F6B69E68A0A7149090423D93C81B" -- "AB3F21678D4ACEEEE50E4E8CAFADA4C85A54EA8306826C4A" -- "D6E74CECE9631BFA8A549B4AB3FBBA15" }, -- /* 7 */ { TEST7_512, length(TEST7_512), 1, 0x80, 3, -- "ED8DC78E8B01B69750053DBB7A0A9EDA0FB9E9D292B1ED71" -- "5E80A7FE290A4E16664FD913E85854400C5AF05E6DAD316B" -- "7359B43E64F8BEC3C1F237119986BBB6" }, -- /* 8 */ { TEST8_512, length(TEST8_512), 1, 0, 0, -- "CB0B67A4B8712CD73C9AABC0B199E9269B20844AFB75ACBD" -- "D1C153C9828924C3DDEDAAFE669C5FDD0BC66F630F677398" -- "8213EB1B16F517AD0DE4B2F0C95C90F8" }, -- /* 9 */ { TEST9_512, length(TEST9_512), 1, 0x80, 3, -- "32BA76FC30EAA0208AEB50FFB5AF1864FDBF17902A4DC0A6" -- "82C61FCEA6D92B783267B21080301837F59DE79C6B337DB2" -- "526F8A0A510E5E53CAFED4355FE7C2F1" }, -- /* 10 */ { TEST10_512, length(TEST10_512), 1, 0, 0, -- "C665BEFB36DA189D78822D10528CBF3B12B3EEF726039909" -- "C1A16A270D48719377966B957A878E720584779A62825C18" -- "DA26415E49A7176A894E7510FD1451F5" } -- }, SHA512_SEED, { "2FBB1E7E00F746BA514FBC8C421F36792EC0E11FF5EFC3" -- "78E1AB0C079AA5F0F66A1E3EDBAEB4F9984BE14437123038A452004A5576" -- "8C1FD8EED49E4A21BEDCD0", "25CBE5A4F2C7B1D7EF07011705D50C62C5" -- "000594243EAFD1241FC9F3D22B58184AE2FEE38E171CF8129E29459C9BC2" -- "EF461AF5708887315F15419D8D17FE7949", "5B8B1F2687555CE2D7182B" -- "92E5C3F6C36547DA1C13DBB9EA4F73EA4CBBAF89411527906D35B1B06C1B" -- "6A8007D05EC66DF0A406066829EAB618BDE3976515AAFC", "46E36B007D" -- "19876CDB0B29AD074FE3C08CDD174D42169D6ABE5A1414B6E79707DF5877" -- "6A98091CF431854147BB6D3C66D43BFBC108FD715BDE6AA127C2B0E79F" -- } -- } --}; -- --/* Test arrays for HMAC. */ --struct hmachash { -- const char *keyarray[5]; -- int keylength[5]; -- const char *dataarray[5]; -- int datalength[5]; -- const char *resultarray[5]; -- int resultlength[5]; --} hmachashes[HMACTESTCOUNT] = { -- { /* 1 */ { -- "\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b" -- "\x0b\x0b\x0b\x0b\x0b" -- }, { 20 }, { -- -- -- --Eastlake 3rd & Hansen Informational [Page 86] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "\x48\x69\x20\x54\x68\x65\x72\x65" /* "Hi There" */ -- }, { 8 }, { -- /* HMAC-SHA-1 */ -- "B617318655057264E28BC0B6FB378C8EF146BE00", -- /* HMAC-SHA-224 */ -- "896FB1128ABBDF196832107CD49DF33F47B4B1169912BA4F53684B22", -- /* HMAC-SHA-256 */ -- "B0344C61D8DB38535CA8AFCEAF0BF12B881DC200C9833DA726E9376C2E32" -- "CFF7", -- /* HMAC-SHA-384 */ -- "AFD03944D84895626B0825F4AB46907F15F9DADBE4101EC682AA034C7CEB" -- "C59CFAEA9EA9076EDE7F4AF152E8B2FA9CB6", -- /* HMAC-SHA-512 */ -- "87AA7CDEA5EF619D4FF0B4241A1D6CB02379F4E2CE4EC2787AD0B30545E1" -- "7CDEDAA833B7D6B8A702038B274EAEA3F4E4BE9D914EEB61F1702E696C20" -- "3A126854" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- }, -- { /* 2 */ { -- "\x4a\x65\x66\x65" /* "Jefe" */ -- }, { 4 }, { -- "\x77\x68\x61\x74\x20\x64\x6f\x20\x79\x61\x20\x77\x61\x6e\x74" -- "\x20\x66\x6f\x72\x20\x6e\x6f\x74\x68\x69\x6e\x67\x3f" -- /* "what do ya want for nothing?" */ -- }, { 28 }, { -- /* HMAC-SHA-1 */ -- "EFFCDF6AE5EB2FA2D27416D5F184DF9C259A7C79", -- /* HMAC-SHA-224 */ -- "A30E01098BC6DBBF45690F3A7E9E6D0F8BBEA2A39E6148008FD05E44", -- /* HMAC-SHA-256 */ -- "5BDCC146BF60754E6A042426089575C75A003F089D2739839DEC58B964EC" -- "3843", -- /* HMAC-SHA-384 */ -- "AF45D2E376484031617F78D2B58A6B1B9C7EF464F5A01B47E42EC3736322" -- "445E8E2240CA5E69E2C78B3239ECFAB21649", -- /* HMAC-SHA-512 */ -- "164B7A7BFCF819E2E395FBE73B56E0A387BD64222E831FD610270CD7EA25" -- "05549758BF75C05A994A6D034F65F8F0E6FDCAEAB1A34D4A6B4B636E070A" -- "38BCE737" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- }, -- { /* 3 */ -- { -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa" -- }, { 20 }, { -- -- -- --Eastlake 3rd & Hansen Informational [Page 87] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd" -- "\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd" -- "\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd\xdd" -- "\xdd\xdd\xdd\xdd\xdd" -- }, { 50 }, { -- /* HMAC-SHA-1 */ -- "125D7342B9AC11CD91A39AF48AA17B4F63F175D3", -- /* HMAC-SHA-224 */ -- "7FB3CB3588C6C1F6FFA9694D7D6AD2649365B0C1F65D69D1EC8333EA", -- /* HMAC-SHA-256 */ -- "773EA91E36800E46854DB8EBD09181A72959098B3EF8C122D9635514CED5" -- "65FE", -- /* HMAC-SHA-384 */ -- "88062608D3E6AD8A0AA2ACE014C8A86F0AA635D947AC9FEBE83EF4E55966" -- "144B2A5AB39DC13814B94E3AB6E101A34F27", -- /* HMAC-SHA-512 */ -- "FA73B0089D56A284EFB0F0756C890BE9B1B5DBDD8EE81A3655F83E33B227" -- "9D39BF3E848279A722C806B485A47E67C807B946A337BEE8942674278859" -- "E13292FB" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- }, -- { /* 4 */ { -- "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f" -- "\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19" -- }, { 25 }, { -- "\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd" -- "\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd" -- "\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd\xcd" -- "\xcd\xcd\xcd\xcd\xcd" -- }, { 50 }, { -- /* HMAC-SHA-1 */ -- "4C9007F4026250C6BC8414F9BF50C86C2D7235DA", -- /* HMAC-SHA-224 */ -- "6C11506874013CAC6A2ABC1BB382627CEC6A90D86EFC012DE7AFEC5A", -- /* HMAC-SHA-256 */ -- "82558A389A443C0EA4CC819899F2083A85F0FAA3E578F8077A2E3FF46729" -- "665B", -- /* HMAC-SHA-384 */ -- "3E8A69B7783C25851933AB6290AF6CA77A9981480850009CC5577C6E1F57" -- "3B4E6801DD23C4A7D679CCF8A386C674CFFB", -- /* HMAC-SHA-512 */ -- "B0BA465637458C6990E5A8C5F61D4AF7E576D97FF94B872DE76F8050361E" -- "E3DBA91CA5C11AA25EB4D679275CC5788063A5F19741120C4F2DE2ADEBEB" -- "10A298DD" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- }, -- -- -- --Eastlake 3rd & Hansen Informational [Page 88] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- { /* 5 */ { -- "\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c" -- "\x0c\x0c\x0c\x0c\x0c" -- }, { 20 }, { -- "Test With Truncation" -- }, { 20 }, { -- /* HMAC-SHA-1 */ -- "4C1A03424B55E07FE7F27BE1", -- /* HMAC-SHA-224 */ -- "0E2AEA68A90C8D37C988BCDB9FCA6FA8", -- /* HMAC-SHA-256 */ -- "A3B6167473100EE06E0C796C2955552B", -- /* HMAC-SHA-384 */ -- "3ABF34C3503B2A23A46EFC619BAEF897", -- /* HMAC-SHA-512 */ -- "415FAD6271580A531D4179BC891D87A6" -- }, { 12, 16, 16, 16, 16 } -- }, -- { /* 6 */ { -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- }, { 80, 131 }, { -- "Test Using Larger Than Block-Size Key - Hash Key First" -- }, { 54 }, { -- /* HMAC-SHA-1 */ -- "AA4AE5E15272D00E95705637CE8A3B55ED402112", -- /* HMAC-SHA-224 */ -- "95E9A0DB962095ADAEBE9B2D6F0DBCE2D499F112F2D2B7273FA6870E", -- /* HMAC-SHA-256 */ -- "60E431591EE0B67F0D8A26AACBF5B77F8E0BC6213728C5140546040F0EE3" -- "7F54", -- /* HMAC-SHA-384 */ -- "4ECE084485813E9088D2C63A041BC5B44F9EF1012A2B588F3CD11F05033A" -- "C4C60C2EF6AB4030FE8296248DF163F44952", -- /* HMAC-SHA-512 */ -- "80B24263C7C1A3EBB71493C1DD7BE8B49B46D1F41B4AEEC1121B013783F8" -- "F3526B56D037E05F2598BD0FD2215D6A1E5295E64F73F63F0AEC8B915A98" -- "5D786598" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- }, -- -- -- --Eastlake 3rd & Hansen Informational [Page 89] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- { /* 7 */ { -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa" -- }, { 80, 131 }, { -- "Test Using Larger Than Block-Size Key and " -- "Larger Than One Block-Size Data", -- "\x54\x68\x69\x73\x20\x69\x73\x20\x61\x20\x74\x65\x73\x74\x20" -- "\x75\x73\x69\x6e\x67\x20\x61\x20\x6c\x61\x72\x67\x65\x72\x20" -- "\x74\x68\x61\x6e\x20\x62\x6c\x6f\x63\x6b\x2d\x73\x69\x7a\x65" -- "\x20\x6b\x65\x79\x20\x61\x6e\x64\x20\x61\x20\x6c\x61\x72\x67" -- "\x65\x72\x20\x74\x68\x61\x6e\x20\x62\x6c\x6f\x63\x6b\x2d\x73" -- "\x69\x7a\x65\x20\x64\x61\x74\x61\x2e\x20\x54\x68\x65\x20\x6b" -- "\x65\x79\x20\x6e\x65\x65\x64\x73\x20\x74\x6f\x20\x62\x65\x20" -- "\x68\x61\x73\x68\x65\x64\x20\x62\x65\x66\x6f\x72\x65\x20\x62" -- "\x65\x69\x6e\x67\x20\x75\x73\x65\x64\x20\x62\x79\x20\x74\x68" -- "\x65\x20\x48\x4d\x41\x43\x20\x61\x6c\x67\x6f\x72\x69\x74\x68" -- "\x6d\x2e" -- /* "This is a test using a larger than block-size key and a " -- "larger than block-size data. The key needs to be hashed " -- "before being used by the HMAC algorithm." */ -- }, { 73, 152 }, { -- /* HMAC-SHA-1 */ -- "E8E99D0F45237D786D6BBAA7965C7808BBFF1A91", -- /* HMAC-SHA-224 */ -- "3A854166AC5D9F023F54D517D0B39DBD946770DB9C2B95C9F6F565D1", -- /* HMAC-SHA-256 */ -- "9B09FFA71B942FCB27635FBCD5B0E944BFDC63644F0713938A7F51535C3A" -- "35E2", -- /* HMAC-SHA-384 */ -- "6617178E941F020D351E2F254E8FD32C602420FEB0B8FB9ADCCEBB82461E" -- "99C5A678CC31E799176D3860E6110C46523E", -- /* HMAC-SHA-512 */ -- "E37B6A775DC87DBAA4DFA9F96E5E3FFDDEBD71F8867289865DF5A32D20CD" -- "C944B6022CAC3C4982B10D5EEB55C3E4DE15134676FB6DE0446065C97440" -- "FA8C6A58" -- }, { SHA1HashSize, SHA224HashSize, SHA256HashSize, -- SHA384HashSize, SHA512HashSize } -- } --}; -- --/* -- -- -- --Eastlake 3rd & Hansen Informational [Page 90] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * Check the hash value against the expected string, expressed in hex -- */ --static const char hexdigits[] = "0123456789ABCDEF"; --int checkmatch(const unsigned char *hashvalue, -- const char *hexstr, int hashsize) --{ -- int i; -- for (i = 0; i < hashsize; ++i) { -- if (*hexstr++ != hexdigits[(hashvalue[i] >> 4) & 0xF]) -- return 0; -- if (*hexstr++ != hexdigits[hashvalue[i] & 0xF]) return 0; -- } -- return 1; --} -- --/* -- * Print the string, converting non-printable characters to "." -- */ --void printstr(const char *str, int len) --{ -- for ( ; len-- > 0; str++) -- putchar(isprint((unsigned char)*str) ? *str : '.'); --} -- --/* -- * Print the string, converting non-printable characters to hex "## ". -- */ --void printxstr(const char *str, int len) --{ -- for ( ; len-- > 0; str++) -- printf("%c%c ", hexdigits[(*str >> 4) & 0xF], -- hexdigits[*str & 0xF]); --} -- --/* -- * Print a usage message. -- */ --void usage(const char *argv0) --{ -- fprintf(stderr, -- "Usage:\n" -- "Common options: [-h hash] [-w|-x] [-H]\n" -- "Standard tests:\n" -- "\t%s [-m] [-l loopcount] [-t test#] [-e]\n" -- "\t\t[-r randomseed] [-R randomloop-count] " -- "[-p] [-P|-X]\n" -- "Hash a string:\n" -- "\t%s [-S expectedresult] -s hashstr [-k key]\n" -- -- -- --Eastlake 3rd & Hansen Informational [Page 91] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- "Hash a file:\n" -- "\t%s [-S expectedresult] -f file [-k key]\n" -- "Hash a file, ignoring whitespace:\n" -- "\t%s [-S expectedresult] -F file [-k key]\n" -- "Additional bits to add in: [-B bitcount -b bits]\n" -- "-h\thash to test: " -- "0|SHA1, 1|SHA224, 2|SHA256, 3|SHA384, 4|SHA512\n" -- "-m\tperform hmac test\n" -- "-k\tkey for hmac test\n" -- "-t\ttest case to run, 1-10\n" -- "-l\thow many times to run the test\n" -- "-e\ttest error returns\n" -- "-p\tdo not print results\n" -- "-P\tdo not print PASSED/FAILED\n" -- "-X\tprint FAILED, but not PASSED\n" -- "-r\tseed for random test\n" -- "-R\thow many times to run random test\n" -- "-s\tstring to hash\n" -- "-S\texpected result of hashed string, in hex\n" -- "-w\toutput hash in raw format\n" -- "-x\toutput hash in hex format\n" -- "-B\t# extra bits to add in after string or file input\n" -- "-b\textra bits to add (high order bits of #, 0# or 0x#)\n" -- "-H\tinput hashstr or randomseed is in hex\n" -- , argv0, argv0, argv0, argv0); -- exit(1); --} -- --/* -- * Print the results and PASS/FAIL. -- */ --void printResult(uint8_t *Message_Digest, int hashsize, -- const char *hashname, const char *testtype, const char *testname, -- const char *resultarray, int printResults, int printPassFail) --{ -- int i, k; -- if (printResults == PRINTTEXT) { -- putchar('\t'); -- for (i = 0; i < hashsize ; ++i) { -- putchar(hexdigits[(Message_Digest[i] >> 4) & 0xF]); -- putchar(hexdigits[Message_Digest[i] & 0xF]); -- putchar(' '); -- } -- putchar('\n'); -- } else if (printResults == PRINTRAW) { -- fwrite(Message_Digest, 1, hashsize, stdout); -- } else if (printResults == PRINTHEX) { -- for (i = 0; i < hashsize ; ++i) { -- -- -- --Eastlake 3rd & Hansen Informational [Page 92] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- putchar(hexdigits[(Message_Digest[i] >> 4) & 0xF]); -- putchar(hexdigits[Message_Digest[i] & 0xF]); -- } -- putchar('\n'); -- } -- -- if (printResults && resultarray) { -- printf(" Should match:\n\t"); -- for (i = 0, k = 0; i < hashsize; i++, k += 2) { -- putchar(resultarray[k]); -- putchar(resultarray[k+1]); -- putchar(' '); -- } -- putchar('\n'); -- } -- -- if (printPassFail && resultarray) { -- int ret = checkmatch(Message_Digest, resultarray, hashsize); -- if ((printPassFail == PRINTPASSFAIL) || !ret) -- printf("%s %s %s: %s\n", hashname, testtype, testname, -- ret ? "PASSED" : "FAILED"); -- } --} -- --/* -- * Exercise a hash series of functions. The input is the testarray, -- * repeated repeatcount times, followed by the extrabits. If the -- * result is known, it is in resultarray in uppercase hex. -- */ --int hash(int testno, int loopno, int hashno, -- const char *testarray, int length, long repeatcount, -- int numberExtrabits, int extrabits, const unsigned char *keyarray, -- int keylen, const char *resultarray, int hashsize, int printResults, -- int printPassFail) --{ -- USHAContext sha; -- HMACContext hmac; -- int err, i; -- uint8_t Message_Digest[USHAMaxHashSize]; -- char buf[20]; -- -- if (printResults == PRINTTEXT) { -- printf("\nTest %d: Iteration %d, Repeat %ld\n\t'", testno+1, -- loopno, repeatcount); -- printstr(testarray, length); -- printf("'\n\t'"); -- printxstr(testarray, length); -- printf("'\n"); -- -- -- --Eastlake 3rd & Hansen Informational [Page 93] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- printf(" Length=%d bytes (%d bits), ", length, length * 8); -- printf("ExtraBits %d: %2.2x\n", numberExtrabits, extrabits); -- } -- -- memset(&sha, '\343', sizeof(sha)); /* force bad data into struct */ -- memset(&hmac, '\343', sizeof(hmac)); -- err = keyarray ? hmacReset(&hmac, hashes[hashno].whichSha, -- keyarray, keylen) : -- USHAReset(&sha, hashes[hashno].whichSha); -- if (err != shaSuccess) { -- fprintf(stderr, "hash(): %sReset Error %d.\n", -- keyarray ? "hmac" : "sha", err); -- return err; -- } -- -- for (i = 0; i < repeatcount; ++i) { -- err = keyarray ? hmacInput(&hmac, (const uint8_t *) testarray, -- length) : -- USHAInput(&sha, (const uint8_t *) testarray, -- length); -- if (err != shaSuccess) { -- fprintf(stderr, "hash(): %sInput Error %d.\n", -- keyarray ? "hmac" : "sha", err); -- return err; -- } -- } -- -- if (numberExtrabits > 0) { -- err = keyarray ? hmacFinalBits(&hmac, (uint8_t) extrabits, -- numberExtrabits) : -- USHAFinalBits(&sha, (uint8_t) extrabits, -- numberExtrabits); -- if (err != shaSuccess) { -- fprintf(stderr, "hash(): %sFinalBits Error %d.\n", -- keyarray ? "hmac" : "sha", err); -- return err; -- } -- } -- -- err = keyarray ? hmacResult(&hmac, Message_Digest) : -- USHAResult(&sha, Message_Digest); -- if (err != shaSuccess) { -- fprintf(stderr, "hash(): %s Result Error %d, could not " -- "compute message digest.\n", keyarray ? "hmac" : "sha", err); -- return err; -- } -- -- sprintf(buf, "%d", testno+1); -- -- -- --Eastlake 3rd & Hansen Informational [Page 94] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- printResult(Message_Digest, hashsize, hashes[hashno].name, -- keyarray ? "hmac standard test" : "sha standard test", buf, -- resultarray, printResults, printPassFail); -- -- return err; --} -- --/* -- * Exercise a hash series of functions. The input is a filename. -- * If the result is known, it is in resultarray in uppercase hex. -- */ --int hashfile(int hashno, const char *hashfilename, int bits, -- int bitcount, int skipSpaces, const unsigned char *keyarray, -- int keylen, const char *resultarray, int hashsize, -- int printResults, int printPassFail) --{ -- USHAContext sha; -- HMACContext hmac; -- int err, nread, c; -- unsigned char buf[4096]; -- uint8_t Message_Digest[USHAMaxHashSize]; -- unsigned char cc; -- FILE *hashfp = (strcmp(hashfilename, "-") == 0) ? stdin : -- fopen(hashfilename, "r"); -- -- if (!hashfp) { -- fprintf(stderr, "cannot open file '%s'\n", hashfilename); -- return shaStateError; -- } -- -- memset(&sha, '\343', sizeof(sha)); /* force bad data into struct */ -- memset(&hmac, '\343', sizeof(hmac)); -- err = keyarray ? hmacReset(&hmac, hashes[hashno].whichSha, -- keyarray, keylen) : -- USHAReset(&sha, hashes[hashno].whichSha); -- -- if (err != shaSuccess) { -- fprintf(stderr, "hashfile(): %sReset Error %d.\n", -- keyarray ? "hmac" : "sha", err); -- return err; -- } -- -- if (skipSpaces) -- while ((c = getc(hashfp)) != EOF) { -- if (!isspace(c)) { -- cc = (unsigned char)c; -- err = keyarray ? hmacInput(&hmac, &cc, 1) : -- USHAInput(&sha, &cc, 1); -- -- -- --Eastlake 3rd & Hansen Informational [Page 95] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- if (err != shaSuccess) { -- fprintf(stderr, "hashfile(): %sInput Error %d.\n", -- keyarray ? "hmac" : "sha", err); -- if (hashfp != stdin) fclose(hashfp); -- return err; -- } -- } -- } -- else -- while ((nread = fread(buf, 1, sizeof(buf), hashfp)) > 0) { -- err = keyarray ? hmacInput(&hmac, buf, nread) : -- USHAInput(&sha, buf, nread); -- if (err != shaSuccess) { -- fprintf(stderr, "hashfile(): %s Error %d.\n", -- keyarray ? "hmacInput" : "shaInput", err); -- if (hashfp != stdin) fclose(hashfp); -- return err; -- } -- } -- -- if (bitcount > 0) -- err = keyarray ? hmacFinalBits(&hmac, bits, bitcount) : -- USHAFinalBits(&sha, bits, bitcount); -- if (err != shaSuccess) { -- fprintf(stderr, "hashfile(): %s Error %d.\n", -- keyarray ? "hmacResult" : "shaResult", err); -- if (hashfp != stdin) fclose(hashfp); -- return err; -- } -- -- err = keyarray ? hmacResult(&hmac, Message_Digest) : -- USHAResult(&sha, Message_Digest); -- if (err != shaSuccess) { -- fprintf(stderr, "hashfile(): %s Error %d.\n", -- keyarray ? "hmacResult" : "shaResult", err); -- if (hashfp != stdin) fclose(hashfp); -- return err; -- } -- -- printResult(Message_Digest, hashsize, hashes[hashno].name, "file", -- hashfilename, resultarray, printResults, printPassFail); -- -- if (hashfp != stdin) fclose(hashfp); -- return err; --} -- --/* -- * Exercise a hash series of functions through multiple permutations. -- -- -- --Eastlake 3rd & Hansen Informational [Page 96] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * The input is an initial seed. That seed is replicated 3 times. -- * For 1000 rounds, the previous three results are used as the input. -- * This result is then checked, and used to seed the next cycle. -- * If the result is known, it is in resultarrays in uppercase hex. -- */ --void randomtest(int hashno, const char *seed, int hashsize, -- const char **resultarrays, int randomcount, -- int printResults, int printPassFail) --{ -- int i, j; char buf[20]; -- unsigned char SEED[USHAMaxHashSize], MD[1003][USHAMaxHashSize]; -- -- /* INPUT: Seed - A random seed n bits long */ -- memcpy(SEED, seed, hashsize); -- if (printResults == PRINTTEXT) { -- printf("%s random test seed= '", hashes[hashno].name); -- printxstr(seed, hashsize); -- printf("'\n"); -- } -- -- for (j = 0; j < randomcount; j++) { -- /* MD0 = MD1 = MD2 = Seed; */ -- memcpy(MD[0], SEED, hashsize); -- memcpy(MD[1], SEED, hashsize); -- memcpy(MD[2], SEED, hashsize); -- for (i=3; i<1003; i++) { -- /* Mi = MDi-3 || MDi-2 || MDi-1; */ -- USHAContext Mi; -- memset(&Mi, '\343', sizeof(Mi)); /* force bad data into struct */ -- USHAReset(&Mi, hashes[hashno].whichSha); -- USHAInput(&Mi, MD[i-3], hashsize); -- USHAInput(&Mi, MD[i-2], hashsize); -- USHAInput(&Mi, MD[i-1], hashsize); -- /* MDi = SHA(Mi); */ -- USHAResult(&Mi, MD[i]); -- } -- -- /* MDj = Seed = MDi; */ -- memcpy(SEED, MD[i-1], hashsize); -- -- /* OUTPUT: MDj */ -- sprintf(buf, "%d", j); -- printResult(SEED, hashsize, hashes[hashno].name, "random test", -- buf, resultarrays ? resultarrays[j] : 0, printResults, -- (j < RANDOMCOUNT) ? printPassFail : 0); -- } --} -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 97] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --/* -- * Look up a hash name. -- */ --int findhash(const char *argv0, const char *opt) --{ -- int i; -- const char *names[HASHCOUNT][2] = { -- { "0", "sha1" }, { "1", "sha224" }, { "2", "sha256" }, -- { "3", "sha384" }, { "4", "sha512" } -- }; -- -- for (i = 0; i < HASHCOUNT; i++) -- if ((strcmp(opt, names[i][0]) == 0) || -- (scasecmp(opt, names[i][1]) == 0)) -- return i; -- -- fprintf(stderr, "%s: Unknown hash name: '%s'\n", argv0, opt); -- usage(argv0); -- return 0; --} -- --/* -- * Run some tests that should invoke errors. -- */ --void testErrors(int hashnolow, int hashnohigh, int printResults, -- int printPassFail) --{ -- USHAContext usha; -- uint8_t Message_Digest[USHAMaxHashSize]; -- int hashno, err; -- -- for (hashno = hashnolow; hashno <= hashnohigh; hashno++) { -- memset(&usha, '\343', sizeof(usha)); /* force bad data */ -- USHAReset(&usha, hashno); -- USHAResult(&usha, Message_Digest); -- err = USHAInput(&usha, (const unsigned char *)"foo", 3); -- if (printResults == PRINTTEXT) -- printf ("\nError %d. Should be %d.\n", err, shaStateError); -- if ((printPassFail == PRINTPASSFAIL) || -- ((printPassFail == PRINTFAIL) && (err != shaStateError))) -- printf("%s se: %s\n", hashes[hashno].name, -- (err == shaStateError) ? "PASSED" : "FAILED"); -- -- err = USHAFinalBits(&usha, 0x80, 3); -- if (printResults == PRINTTEXT) -- printf ("\nError %d. Should be %d.\n", err, shaStateError); -- if ((printPassFail == PRINTPASSFAIL) || -- ((printPassFail == PRINTFAIL) && (err != shaStateError))) -- -- -- --Eastlake 3rd & Hansen Informational [Page 98] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- printf("%s se: %s\n", hashes[hashno].name, -- (err == shaStateError) ? "PASSED" : "FAILED"); -- -- err = USHAReset(0, hashes[hashno].whichSha); -- if (printResults == PRINTTEXT) -- printf("\nError %d. Should be %d.\n", err, shaNull); -- if ((printPassFail == PRINTPASSFAIL) || -- ((printPassFail == PRINTFAIL) && (err != shaNull))) -- printf("%s usha null: %s\n", hashes[hashno].name, -- (err == shaNull) ? "PASSED" : "FAILED"); -- -- switch (hashno) { -- case SHA1: err = SHA1Reset(0); break; -- case SHA224: err = SHA224Reset(0); break; -- case SHA256: err = SHA256Reset(0); break; -- case SHA384: err = SHA384Reset(0); break; -- case SHA512: err = SHA512Reset(0); break; -- } -- if (printResults == PRINTTEXT) -- printf("\nError %d. Should be %d.\n", err, shaNull); -- if ((printPassFail == PRINTPASSFAIL) || -- ((printPassFail == PRINTFAIL) && (err != shaNull))) -- printf("%s sha null: %s\n", hashes[hashno].name, -- (err == shaNull) ? "PASSED" : "FAILED"); -- } --} -- --/* replace a hex string in place with its value */ --int unhexStr(char *hexstr) --{ -- char *o = hexstr; -- int len = 0, nibble1 = 0, nibble2 = 0; -- if (!hexstr) return 0; -- for ( ; *hexstr; hexstr++) { -- if (isalpha((int)(unsigned char)(*hexstr))) { -- nibble1 = tolower(*hexstr) - 'a' + 10; -- } else if (isdigit((int)(unsigned char)(*hexstr))) { -- nibble1 = *hexstr - '0'; -- } else { -- printf("\nError: bad hex character '%c'\n", *hexstr); -- } -- if (!*++hexstr) break; -- if (isalpha((int)(unsigned char)(*hexstr))) { -- nibble2 = tolower(*hexstr) - 'a' + 10; -- } else if (isdigit((int)(unsigned char)(*hexstr))) { -- nibble2 = *hexstr - '0'; -- } else { -- printf("\nError: bad hex character '%c'\n", *hexstr); -- -- -- --Eastlake 3rd & Hansen Informational [Page 99] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- } -- *o++ = (char)((nibble1 << 4) | nibble2); -- len++; -- } -- return len; --} -- --int main(int argc, char **argv) --{ -- int i, err; -- int loopno, loopnohigh = 1; -- int hashno, hashnolow = 0, hashnohigh = HASHCOUNT - 1; -- int testno, testnolow = 0, testnohigh; -- int ntestnohigh = 0; -- int printResults = PRINTTEXT; -- int printPassFail = 1; -- int checkErrors = 0; -- char *hashstr = 0; -- int hashlen = 0; -- const char *resultstr = 0; -- char *randomseedstr = 0; -- int runHmacTests = 0; -- char *hmacKey = 0; -- int hmaclen = 0; -- int randomcount = RANDOMCOUNT; -- const char *hashfilename = 0; -- const char *hashFilename = 0; -- int extrabits = 0, numberExtrabits = 0; -- int strIsHex = 0; -- -- while ((i = xgetopt(argc, argv, "b:B:ef:F:h:Hk:l:mpPr:R:s:S:t:wxX")) -- != -1) -- switch (i) { -- case 'b': extrabits = strtol(xoptarg, 0, 0); break; -- case 'B': numberExtrabits = atoi(xoptarg); break; -- case 'e': checkErrors = 1; break; -- case 'f': hashfilename = xoptarg; break; -- case 'F': hashFilename = xoptarg; break; -- case 'h': hashnolow = hashnohigh = findhash(argv[0], xoptarg); -- break; -- case 'H': strIsHex = 1; break; -- case 'k': hmacKey = xoptarg; hmaclen = strlen(xoptarg); break; -- case 'l': loopnohigh = atoi(xoptarg); break; -- case 'm': runHmacTests = 1; break; -- case 'P': printPassFail = 0; break; -- case 'p': printResults = PRINTNONE; break; -- case 'R': randomcount = atoi(xoptarg); break; -- case 'r': randomseedstr = xoptarg; break; -- -- -- --Eastlake 3rd & Hansen Informational [Page 100] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- case 's': hashstr = xoptarg; hashlen = strlen(hashstr); break; -- case 'S': resultstr = xoptarg; break; -- case 't': testnolow = ntestnohigh = atoi(xoptarg) - 1; break; -- case 'w': printResults = PRINTRAW; break; -- case 'x': printResults = PRINTHEX; break; -- case 'X': printPassFail = 2; break; -- default: usage(argv[0]); -- } -- -- if (strIsHex) { -- hashlen = unhexStr(hashstr); -- unhexStr(randomseedstr); -- hmaclen = unhexStr(hmacKey); -- } -- testnohigh = (ntestnohigh != 0) ? ntestnohigh: -- runHmacTests ? (HMACTESTCOUNT-1) : (TESTCOUNT-1); -- if ((testnolow < 0) || -- (testnohigh >= (runHmacTests ? HMACTESTCOUNT : TESTCOUNT)) || -- (hashnolow < 0) || (hashnohigh >= HASHCOUNT) || -- (hashstr && (testnolow == testnohigh)) || -- (randomcount < 0) || -- (resultstr && (!hashstr && !hashfilename && !hashFilename)) || -- ((runHmacTests || hmacKey) && randomseedstr) || -- (hashfilename && hashFilename)) -- usage(argv[0]); -- -- /* -- * Perform SHA/HMAC tests -- */ -- for (hashno = hashnolow; hashno <= hashnohigh; ++hashno) { -- if (printResults == PRINTTEXT) -- printf("Hash %s\n", hashes[hashno].name); -- err = shaSuccess; -- -- for (loopno = 1; (loopno <= loopnohigh) && (err == shaSuccess); -- ++loopno) { -- if (hashstr) -- err = hash(0, loopno, hashno, hashstr, hashlen, 1, -- numberExtrabits, extrabits, (const unsigned char *)hmacKey, -- hmaclen, resultstr, hashes[hashno].hashsize, printResults, -- printPassFail); -- -- else if (randomseedstr) -- randomtest(hashno, randomseedstr, hashes[hashno].hashsize, 0, -- randomcount, printResults, printPassFail); -- -- else if (hashfilename) -- err = hashfile(hashno, hashfilename, extrabits, -- -- -- --Eastlake 3rd & Hansen Informational [Page 101] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- numberExtrabits, 0, -- (const unsigned char *)hmacKey, hmaclen, -- resultstr, hashes[hashno].hashsize, -- printResults, printPassFail); -- -- else if (hashFilename) -- err = hashfile(hashno, hashFilename, extrabits, -- numberExtrabits, 1, -- (const unsigned char *)hmacKey, hmaclen, -- resultstr, hashes[hashno].hashsize, -- printResults, printPassFail); -- -- else /* standard tests */ { -- for (testno = testnolow; -- (testno <= testnohigh) && (err == shaSuccess); ++testno) { -- if (runHmacTests) { -- err = hash(testno, loopno, hashno, -- hmachashes[testno].dataarray[hashno] ? -- hmachashes[testno].dataarray[hashno] : -- hmachashes[testno].dataarray[1] ? -- hmachashes[testno].dataarray[1] : -- hmachashes[testno].dataarray[0], -- hmachashes[testno].datalength[hashno] ? -- hmachashes[testno].datalength[hashno] : -- hmachashes[testno].datalength[1] ? -- hmachashes[testno].datalength[1] : -- hmachashes[testno].datalength[0], -- 1, 0, 0, -- (const unsigned char *)( -- hmachashes[testno].keyarray[hashno] ? -- hmachashes[testno].keyarray[hashno] : -- hmachashes[testno].keyarray[1] ? -- hmachashes[testno].keyarray[1] : -- hmachashes[testno].keyarray[0]), -- hmachashes[testno].keylength[hashno] ? -- hmachashes[testno].keylength[hashno] : -- hmachashes[testno].keylength[1] ? -- hmachashes[testno].keylength[1] : -- hmachashes[testno].keylength[0], -- hmachashes[testno].resultarray[hashno], -- hmachashes[testno].resultlength[hashno], -- printResults, printPassFail); -- } else { -- err = hash(testno, loopno, hashno, -- hashes[hashno].tests[testno].testarray, -- hashes[hashno].tests[testno].length, -- hashes[hashno].tests[testno].repeatcount, -- hashes[hashno].tests[testno].numberExtrabits, -- -- -- --Eastlake 3rd & Hansen Informational [Page 102] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- hashes[hashno].tests[testno].extrabits, 0, 0, -- hashes[hashno].tests[testno].resultarray, -- hashes[hashno].hashsize, -- printResults, printPassFail); -- } -- } -- -- if (!runHmacTests) { -- randomtest(hashno, hashes[hashno].randomtest, -- hashes[hashno].hashsize, hashes[hashno].randomresults, -- RANDOMCOUNT, printResults, printPassFail); -- } -- } -- } -- } -- -- /* Test some error returns */ -- if (checkErrors) { -- testErrors(hashnolow, hashnohigh, printResults, printPassFail); -- } -- -- return 0; --} -- --/* -- * Compare two strings, case independently. -- * Equivalent to strcasecmp() found on some systems. -- */ --int scasecmp(const char *s1, const char *s2) --{ -- for (;;) { -- char u1 = tolower(*s1++); -- char u2 = tolower(*s2++); -- if (u1 != u2) -- return u1 - u2; -- if (u1 == '\0') -- return 0; -- } --} -- --/* -- * This is a copy of getopt provided for those systems that do not -- * have it. The name was changed to xgetopt to not conflict on those -- * systems that do have it. Similarly, optarg, optind and opterr -- * were renamed to xoptarg, xoptind and xopterr. -- * -- * Copyright 1990, 1991, 1992 by the Massachusetts Institute of -- * Technology and UniSoft Group Limited. -- -- -- --Eastlake 3rd & Hansen Informational [Page 103] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- * -- * Permission to use, copy, modify, distribute, and sell this software -- * and its documentation for any purpose is hereby granted without fee, -- * provided that the above copyright notice appear in all copies and -- * that both that copyright notice and this permission notice appear in -- * supporting documentation, and that the names of MIT and UniSoft not -- * be used in advertising or publicity pertaining to distribution of -- * the software without specific, written prior permission. MIT and -- * UniSoft make no representations about the suitability of this -- * software for any purpose. It is provided "as is" without express -- * or implied warranty. -- * -- * $XConsortium: getopt.c,v 1.2 92/07/01 11:59:04 rws Exp $ -- * NB: Reformatted to match above style. -- */ -- --char *xoptarg; --int xoptind = 1; --int xopterr = 1; -- --static int xgetopt(int argc, char **argv, const char *optstring) --{ -- static int avplace; -- char *ap; -- char *cp; -- int c; -- -- if (xoptind >= argc) -- return EOF; -- -- ap = argv[xoptind] + avplace; -- -- /* At beginning of arg but not an option */ -- if (avplace == 0) { -- if (ap[0] != '-') -- return EOF; -- else if (ap[1] == '-') { -- /* Special end of options option */ -- xoptind++; -- return EOF; -- } else if (ap[1] == '\0') -- return EOF; /* single '-' is not allowed */ -- } -- -- /* Get next letter */ -- avplace++; -- c = *++ap; -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 104] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- -- cp = strchr(optstring, c); -- if (cp == NULL || c == ':') { -- if (xopterr) -- fprintf(stderr, "Unrecognised option -- %c\n", c); -- return '?'; -- } -- -- if (cp[1] == ':') { -- /* There should be an option arg */ -- avplace = 0; -- if (ap[1] == '\0') { -- /* It is a separate arg */ -- if (++xoptind >= argc) { -- if (xopterr) -- fprintf(stderr, "Option requires an argument\n"); -- return '?'; -- } -- xoptarg = argv[xoptind++]; -- } else { -- /* is attached to option letter */ -- xoptarg = ap + 1; -- ++xoptind; -- } -- } else { -- /* If we are out of letters then go to next arg */ -- if (ap[1] == '\0') { -- ++xoptind; -- avplace = 0; -- } -- -- xoptarg = NULL; -- } -- return c; --} -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 105] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --9. Security Considerations -- -- This document is intended to provides the Internet community -- convenient access to source code that implements the United States of -- America Federal Information Processing Standard Secure Hash -- Algorithms (SHAs) [FIPS180-2] and HMACs based upon these one-way hash -- functions. See license in Section 1.1. No independent assertion of -- the security of this hash function by the authors for any particular -- use is intended. -- --10. Normative References -- -- [FIPS180-2] "Secure Hash Standard", United States of America, -- National Institute of Standards and Technology, Federal -- Information Processing Standard (FIPS) 180-2, -- http://csrc.nist.gov/publications/fips/fips180-2/ -- fips180-2withchangenotice.pdf. -- -- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- -- Hashing for Message Authentication", RFC 2104, February -- 1997. -- --11. Informative References -- -- [RFC2202] Cheng, P. and R. Glenn, "Test Cases for HMAC-MD5 and -- HMAC-SHA-1", RFC 2202, September 1997. -- -- [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm -- 1 (SHA1)", RFC 3174, September 2001. -- -- [RFC3874] Housley, R., "A 224-bit One-way Hash Function: SHA-224", -- RFC 3874, September 2004. -- -- [RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker, -- "Randomness Requirements for Security", BCP 106, RFC -- 4086, June 2005. -- -- [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- -- 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC -- 4231, December 2005. -- -- [SHAVS] "The Secure Hash Algorithm Validation System (SHAVS)", -- http://csrc.nist.gov/cryptval/shs/SHAVS.pdf. -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 106] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --Authors' Addresses -- -- Donald E. Eastlake, 3rd -- Motorola Laboratories -- 155 Beaver Street -- Milford, MA 01757 USA -- -- Phone: +1-508-786-7554 (w) -- EMail: donald.eastlake@motorola.com -- -- -- Tony Hansen -- AT&T Laboratories -- 200 Laurel Ave. -- Middletown, NJ 07748 USA -- -- Phone: +1-732-420-8934 (w) -- EMail: tony+shs@maillennium.att.com -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 107] -- --RFC 4634 SHAs and HMAC-SHAs July 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Eastlake 3rd & Hansen Informational [Page 108] -- diff --cc doc/rfc/rfc4641.txt index 0a013bcba5a,0a013bcba5a..00000000000 deleted file mode 100644,100644 --- a/doc/rfc/rfc4641.txt +++ /dev/null @@@ -1,1963 -1,1963 +1,0 @@@ -- -- -- -- -- -- --Network Working Group O. Kolkman --Request for Comments: 4641 R. Gieben --Obsoletes: 2541 NLnet Labs --Category: Informational September 2006 -- -- -- DNSSEC Operational Practices -- --Status of This Memo -- -- This memo provides information for the Internet community. It does -- not specify an Internet standard of any kind. Distribution of this -- memo is unlimited. -- --Copyright Notice -- -- Copyright (C) The Internet Society (2006). -- --Abstract -- -- This document describes a set of practices for operating the DNS with -- security extensions (DNSSEC). The target audience is zone -- administrators deploying DNSSEC. -- -- The document discusses operational aspects of using keys and -- signatures in the DNS. It discusses issues of key generation, key -- storage, signature generation, key rollover, and related policies. -- -- This document obsoletes RFC 2541, as it covers more operational -- ground and gives more up-to-date requirements with respect to key -- sizes and the new DNSSEC specification. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 1] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --Table of Contents -- -- 1. Introduction ....................................................3 -- 1.1. The Use of the Term 'key' ..................................4 -- 1.2. Time Definitions ...........................................4 -- 2. Keeping the Chain of Trust Intact ...............................5 -- 3. Keys Generation and Storage .....................................6 -- 3.1. Zone and Key Signing Keys ..................................6 -- 3.1.1. Motivations for the KSK and ZSK Separation ..........6 -- 3.1.2. KSKs for High-Level Zones ...........................7 -- 3.2. Key Generation .............................................8 -- 3.3. Key Effectivity Period .....................................8 -- 3.4. Key Algorithm ..............................................9 -- 3.5. Key Sizes ..................................................9 -- 3.6. Private Key Storage .......................................11 -- 4. Signature Generation, Key Rollover, and Related Policies .......12 -- 4.1. Time in DNSSEC ............................................12 -- 4.1.1. Time Considerations ................................12 -- 4.2. Key Rollovers .............................................14 -- 4.2.1. Zone Signing Key Rollovers .........................14 -- 4.2.1.1. Pre-Publish Key Rollover ..................15 -- 4.2.1.2. Double Signature Zone Signing Key -- Rollover ..................................17 -- 4.2.1.3. Pros and Cons of the Schemes ..............18 -- 4.2.2. Key Signing Key Rollovers ..........................18 -- 4.2.3. Difference Between ZSK and KSK Rollovers ...........20 -- 4.2.4. Automated Key Rollovers ............................21 -- 4.3. Planning for Emergency Key Rollover .......................21 -- 4.3.1. KSK Compromise .....................................22 -- 4.3.1.1. Keeping the Chain of Trust Intact .........22 -- 4.3.1.2. Breaking the Chain of Trust ...............23 -- 4.3.2. ZSK Compromise .....................................23 -- 4.3.3. Compromises of Keys Anchored in Resolvers ..........24 -- 4.4. Parental Policies .........................................24 -- 4.4.1. Initial Key Exchanges and Parental Policies -- Considerations .....................................24 -- 4.4.2. Storing Keys or Hashes? ............................25 -- 4.4.3. Security Lameness ..................................25 -- 4.4.4. DS Signature Validity Period .......................26 -- 5. Security Considerations ........................................26 -- 6. Acknowledgments ................................................26 -- 7. References .....................................................27 -- 7.1. Normative References ......................................27 -- 7.2. Informative References ....................................28 -- Appendix A. Terminology ...........................................30 -- Appendix B. Zone Signing Key Rollover How-To ......................31 -- Appendix C. Typographic Conventions ...............................32 -- -- -- -- --Kolkman & Gieben Informational [Page 2] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --1. Introduction -- -- This document describes how to run a DNS Security (DNSSEC)-enabled -- environment. It is intended for operators who have knowledge of the -- DNS (see RFC 1034 [1] and RFC 1035 [2]) and want to deploy DNSSEC. -- See RFC 4033 [4] for an introduction to DNSSEC, RFC 4034 [5] for the -- newly introduced Resource Records (RRs), and RFC 4035 [6] for the -- protocol changes. -- -- During workshops and early operational deployment tests, operators -- and system administrators have gained experience about operating the -- DNS with security extensions (DNSSEC). This document translates -- these experiences into a set of practices for zone administrators. -- At the time of writing, there exists very little experience with -- DNSSEC in production environments; this document should therefore -- explicitly not be seen as representing 'Best Current Practices'. -- -- The procedures herein are focused on the maintenance of signed zones -- (i.e., signing and publishing zones on authoritative servers). It is -- intended that maintenance of zones such as re-signing or key -- rollovers be transparent to any verifying clients on the Internet. -- -- The structure of this document is as follows. In Section 2, we -- discuss the importance of keeping the "chain of trust" intact. -- Aspects of key generation and storage of private keys are discussed -- in Section 3; the focus in this section is mainly on the private part -- of the key(s). Section 4 describes considerations concerning the -- public part of the keys. Since these public keys appear in the DNS -- one has to take into account all kinds of timing issues, which are -- discussed in Section 4.1. Section 4.2 and Section 4.3 deal with the -- rollover, or supercession, of keys. Finally, Section 4.4 discusses -- considerations on how parents deal with their children's public keys -- in order to maintain chains of trust. -- -- The typographic conventions used in this document are explained in -- Appendix C. -- -- Since this is a document with operational suggestions and there are -- no protocol specifications, the RFC 2119 [7] language does not apply. -- -- This document obsoletes RFC 2541 [12] to reflect the evolution of the -- underlying DNSSEC protocol since then. Changes in the choice of -- cryptographic algorithms, DNS record types and type names, and the -- parent-child key and signature exchange demanded a major rewrite and -- additional information and explanation. -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 3] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --1.1. The Use of the Term 'key' -- -- It is assumed that the reader is familiar with the concept of -- asymmetric keys on which DNSSEC is based (public key cryptography -- [17]). Therefore, this document will use the term 'key' rather -- loosely. Where it is written that 'a key is used to sign data' it is -- assumed that the reader understands that it is the private part of -- the key pair that is used for signing. It is also assumed that the -- reader understands that the public part of the key pair is published -- in the DNSKEY Resource Record and that it is the public part that is -- used in key exchanges. -- --1.2. Time Definitions -- -- In this document, we will be using a number of time-related terms. -- The following definitions apply: -- -- o "Signature validity period" The period that a signature is valid. -- It starts at the time specified in the signature inception field -- of the RRSIG RR and ends at the time specified in the expiration -- field of the RRSIG RR. -- -- o "Signature publication period" Time after which a signature (made -- with a specific key) is replaced with a new signature (made with -- the same key). This replacement takes place by publishing the -- relevant RRSIG in the master zone file. After one stops -- publishing an RRSIG in a zone, it may take a while before the -- RRSIG has expired from caches and has actually been removed from -- the DNS. -- -- o "Key effectivity period" The period during which a key pair is -- expected to be effective. This period is defined as the time -- between the first inception time stamp and the last expiration -- date of any signature made with this key, regardless of any -- discontinuity in the use of the key. The key effectivity period -- can span multiple signature validity periods. -- -- o "Maximum/Minimum Zone Time to Live (TTL)" The maximum or minimum -- value of the TTLs from the complete set of RRs in a zone. Note -- that the minimum TTL is not the same as the MINIMUM field in the -- SOA RR. See [11] for more information. -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 4] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --2. Keeping the Chain of Trust Intact -- -- Maintaining a valid chain of trust is important because broken chains -- of trust will result in data being marked as Bogus (as defined in [4] -- Section 5), which may cause entire (sub)domains to become invisible -- to verifying clients. The administrators of secured zones have to -- realize that their zone is, to verifying clients, part of a chain of -- trust. -- -- As mentioned in the introduction, the procedures herein are intended -- to ensure that maintenance of zones, such as re-signing or key -- rollovers, will be transparent to the verifying clients on the -- Internet. -- -- Administrators of secured zones will have to keep in mind that data -- published on an authoritative primary server will not be immediately -- seen by verifying clients; it may take some time for the data to be -- transferred to other secondary authoritative nameservers and clients -- may be fetching data from caching non-authoritative servers. In this -- light, note that the time for a zone transfer from master to slave is -- negligible when using NOTIFY [9] and incremental transfer (IXFR) [8]. -- It increases when full zone transfers (AXFR) are used in combination -- with NOTIFY. It increases even more if you rely on full zone -- transfers based on only the SOA timing parameters for refresh. -- -- For the verifying clients, it is important that data from secured -- zones can be used to build chains of trust regardless of whether the -- data came directly from an authoritative server, a caching -- nameserver, or some middle box. Only by carefully using the -- available timing parameters can a zone administrator ensure that the -- data necessary for verification can be obtained. -- -- The responsibility for maintaining the chain of trust is shared by -- administrators of secured zones in the chain of trust. This is most -- obvious in the case of a 'key compromise' when a trade-off between -- maintaining a valid chain of trust and replacing the compromised keys -- as soon as possible must be made. Then zone administrators will have -- to make a trade-off, between keeping the chain of trust intact -- -- thereby allowing for attacks with the compromised key -- or -- deliberately breaking the chain of trust and making secured -- subdomains invisible to security-aware resolvers. Also see Section -- 4.3. -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 5] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --3. Keys Generation and Storage -- -- This section describes a number of considerations with respect to the -- security of keys. It deals with the generation, effectivity period, -- size, and storage of private keys. -- --3.1. Zone and Key Signing Keys -- -- The DNSSEC validation protocol does not distinguish between different -- types of DNSKEYs. All DNSKEYs can be used during the validation. In -- practice, operators use Key Signing and Zone Signing Keys and use the -- so-called Secure Entry Point (SEP) [3] flag to distinguish between -- them during operations. The dynamics and considerations are -- discussed below. -- -- To make zone re-signing and key rollover procedures easier to -- implement, it is possible to use one or more keys as Key Signing Keys -- (KSKs). These keys will only sign the apex DNSKEY RRSet in a zone. -- Other keys can be used to sign all the RRSets in a zone and are -- referred to as Zone Signing Keys (ZSKs). In this document, we assume -- that KSKs are the subset of keys that are used for key exchanges with -- the parent and potentially for configuration as trusted anchors -- -- the SEP keys. In this document, we assume a one-to-one mapping -- between KSK and SEP keys and we assume the SEP flag to be set on all -- KSKs. -- --3.1.1. Motivations for the KSK and ZSK Separation -- -- Differentiating between the KSK and ZSK functions has several -- advantages: -- -- o No parent/child interaction is required when ZSKs are updated. -- -- o The KSK can be made stronger (i.e., using more bits in the key -- material). This has little operational impact since it is only -- used to sign a small fraction of the zone data. Also, the KSK is -- only used to verify the zone's key set, not for other RRSets in -- the zone. -- -- o As the KSK is only used to sign a key set, which is most probably -- updated less frequently than other data in the zone, it can be -- stored separately from and in a safer location than the ZSK. -- -- o A KSK can have a longer key effectivity period. -- -- For almost any method of key management and zone signing, the KSK is -- used less frequently than the ZSK. Once a key set is signed with the -- KSK, all the keys in the key set can be used as ZSKs. If a ZSK is -- -- -- --Kolkman & Gieben Informational [Page 6] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- compromised, it can be simply dropped from the key set. The new key -- set is then re-signed with the KSK. -- -- Given the assumption that for KSKs the SEP flag is set, the KSK can -- be distinguished from a ZSK by examining the flag field in the DNSKEY -- RR. If the flag field is an odd number it is a KSK. If it is an -- even number it is a ZSK. -- -- The Zone Signing Key can be used to sign all the data in a zone on a -- regular basis. When a Zone Signing Key is to be rolled, no -- interaction with the parent is needed. This allows for signature -- validity periods on the order of days. -- -- The Key Signing Key is only to be used to sign the DNSKEY RRs in a -- zone. If a Key Signing Key is to be rolled over, there will be -- interactions with parties other than the zone administrator. These -- can include the registry of the parent zone or administrators of -- verifying resolvers that have the particular key configured as secure -- entry points. Hence, the key effectivity period of these keys can -- and should be made much longer. Although, given a long enough key, -- the key effectivity period can be on the order of years, we suggest -- planning for a key effectivity on the order of a few months so that a -- key rollover remains an operational routine. -- --3.1.2. KSKs for High-Level Zones -- -- Higher-level zones are generally more sensitive than lower-level -- zones. Anyone controlling or breaking the security of a zone thereby -- obtains authority over all of its subdomains (except in the case of -- resolvers that have locally configured the public key of a subdomain, -- in which case this, and only this, subdomain wouldn't be affected by -- the compromise of the parent zone). Therefore, extra care should be -- taken with high-level zones, and strong keys should be used. -- -- The root zone is the most critical of all zones. Someone controlling -- or compromising the security of the root zone would control the -- entire DNS namespace of all resolvers using that root zone (except in -- the case of resolvers that have locally configured the public key of -- a subdomain). Therefore, the utmost care must be taken in the -- securing of the root zone. The strongest and most carefully handled -- keys should be used. The root zone private key should always be kept -- off-line. -- -- Many resolvers will start at a root server for their access to and -- authentication of DNS data. Securely updating the trust anchors in -- an enormous population of resolvers around the world will be -- extremely difficult. -- -- -- -- --Kolkman & Gieben Informational [Page 7] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --3.2. Key Generation -- -- Careful generation of all keys is a sometimes overlooked but -- absolutely essential element in any cryptographically secure system. -- The strongest algorithms used with the longest keys are still of no -- use if an adversary can guess enough to lower the size of the likely -- key space so that it can be exhaustively searched. Technical -- suggestions for the generation of random keys will be found in RFC -- 4086 [14]. One should carefully assess if the random number -- generator used during key generation adheres to these suggestions. -- -- Keys with a long effectivity period are particularly sensitive as -- they will represent a more valuable target and be subject to attack -- for a longer time than short-period keys. It is strongly recommended -- that long-term key generation occur off-line in a manner isolated -- from the network via an air gap or, at a minimum, high-level secure -- hardware. -- --3.3. Key Effectivity Period -- -- For various reasons, keys in DNSSEC need to be changed once in a -- while. The longer a key is in use, the greater the probability that -- it will have been compromised through carelessness, accident, -- espionage, or cryptanalysis. Furthermore, when key rollovers are too -- rare an event, they will not become part of the operational habit and -- there is risk that nobody on-site will remember the procedure for -- rollover when the need is there. -- -- From a purely operational perspective, a reasonable key effectivity -- period for Key Signing Keys is 13 months, with the intent to replace -- them after 12 months. An intended key effectivity period of a month -- is reasonable for Zone Signing Keys. -- -- For key sizes that match these effectivity periods, see Section 3.5. -- -- As argued in Section 3.1.2, securely updating trust anchors will be -- extremely difficult. On the other hand, the "operational habit" -- argument does also apply to trust anchor reconfiguration. If a short -- key effectivity period is used and the trust anchor configuration has -- to be revisited on a regular basis, the odds that the configuration -- tends to be forgotten is smaller. The trade-off is against a system -- that is so dynamic that administrators of the validating clients will -- not be able to follow the modifications. -- -- Key effectivity periods can be made very short, as in a few minutes. -- But when replacing keys one has to take the considerations from -- Section 4.1 and Section 4.2 into account. -- -- -- -- --Kolkman & Gieben Informational [Page 8] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --3.4. Key Algorithm -- -- There are currently three different types of algorithms that can be -- used in DNSSEC: RSA, DSA, and elliptic curve cryptography. The -- latter is fairly new and has yet to be standardized for usage in -- DNSSEC. -- -- RSA has been developed in an open and transparent manner. As the -- patent on RSA expired in 2000, its use is now also free. -- -- DSA has been developed by the National Institute of Standards and -- Technology (NIST). The creation of signatures takes roughly the same -- time as with RSA, but is 10 to 40 times as slow for verification -- [17]. -- -- We suggest the use of RSA/SHA-1 as the preferred algorithm for the -- key. The current known attacks on RSA can be defeated by making your -- key longer. As the MD5 hashing algorithm is showing cracks, we -- recommend the usage of SHA-1. -- -- At the time of publication, it is known that the SHA-1 hash has -- cryptanalysis issues. There is work in progress on addressing these -- issues. We recommend the use of public key algorithms based on -- hashes stronger than SHA-1 (e.g., SHA-256), as soon as these -- algorithms are available in protocol specifications (see [19] and -- [20]) and implementations. -- --3.5. Key Sizes -- -- When choosing key sizes, zone administrators will need to take into -- account how long a key will be used, how much data will be signed -- during the key publication period (see Section 8.10 of [17]), and, -- optionally, how large the key size of the parent is. As the chain of -- trust really is "a chain", there is not much sense in making one of -- the keys in the chain several times larger then the others. As -- always, it's the weakest link that defines the strength of the entire -- chain. Also see Section 3.1.1 for a discussion of how keys serving -- different roles (ZSK vs. KSK) may need different key sizes. -- -- Generating a key of the correct size is a difficult problem; RFC 3766 -- [13] tries to deal with that problem. The first part of the -- selection procedure in Section 1 of the RFC states: -- -- 1. Determine the attack resistance necessary to satisfy the -- security requirements of the application. Do this by -- estimating the minimum number of computer operations that the -- attacker will be forced to do in order to compromise the -- -- -- -- --Kolkman & Gieben Informational [Page 9] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- security of the system and then take the logarithm base two of -- that number. Call that logarithm value "n". -- -- A 1996 report recommended 90 bits as a good all-around choice -- for system security. The 90 bit number should be increased by -- about 2/3 bit/year, or about 96 bits in 2005. -- -- [13] goes on to explain how this number "n" can be used to calculate -- the key sizes in public key cryptography. This culminated in the -- table given below (slightly modified for our purpose): -- -- +-------------+-----------+--------------+ -- | System | | | -- | requirement | Symmetric | RSA or DSA | -- | for attack | key size | modulus size | -- | resistance | (bits) | (bits) | -- | (bits) | | | -- +-------------+-----------+--------------+ -- | 70 | 70 | 947 | -- | 80 | 80 | 1228 | -- | 90 | 90 | 1553 | -- | 100 | 100 | 1926 | -- | 150 | 150 | 4575 | -- | 200 | 200 | 8719 | -- | 250 | 250 | 14596 | -- +-------------+-----------+--------------+ -- -- The key sizes given are rather large. This is because these keys are -- resilient against a trillionaire attacker. Assuming this rich -- attacker will not attack your key and that the key is rolled over -- once a year, we come to the following recommendations about KSK -- sizes: 1024 bits for low-value domains, 1300 bits for medium-value -- domains, and 2048 bits for high-value domains. -- -- Whether a domain is of low, medium, or high value depends solely on -- the views of the zone owner. One could, for instance, view leaf -- nodes in the DNS as of low value, and top-level domains (TLDs) or the -- root zone of high value. The suggested key sizes should be safe for -- the next 5 years. -- -- As ZSKs can be rolled over more easily (and thus more often), the key -- sizes can be made smaller. But as said in the introduction of this -- paragraph, making the ZSKs' key sizes too small (in relation to the -- KSKs' sizes) doesn't make much sense. Try to limit the difference in -- size to about 100 bits. -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 10] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- Note that nobody can see into the future and that these key sizes are -- only provided here as a guide. Further information can be found in -- [16] and Section 7.5 of [17]. It should be noted though that [16] is -- already considered overly optimistic about what key sizes are -- considered safe. -- -- One final note concerning key sizes. Larger keys will increase the -- sizes of the RRSIG and DNSKEY records and will therefore increase the -- chance of DNS UDP packet overflow. Also, the time it takes to -- validate and create RRSIGs increases with larger keys, so don't -- needlessly double your key sizes. -- --3.6. Private Key Storage -- -- It is recommended that, where possible, zone private keys and the -- zone file master copy that is to be signed be kept and used in off- -- line, non-network-connected, physically secure machines only. -- Periodically, an application can be run to add authentication to a -- zone by adding RRSIG and NSEC RRs. Then the augmented file can be -- transferred. -- -- When relying on dynamic update to manage a signed zone [10], be aware -- that at least one private key of the zone will have to reside on the -- master server. This key is only as secure as the amount of exposure -- the server receives to unknown clients and the security of the host. -- Although not mandatory, one could administer the DNS in the following -- way. The master that processes the dynamic updates is unavailable -- from generic hosts on the Internet, it is not listed in the NS RR -- set, although its name appears in the SOA RRs MNAME field. The -- nameservers in the NS RRSet are able to receive zone updates through -- NOTIFY, IXFR, AXFR, or an out-of-band distribution mechanism. This -- approach is known as the "hidden master" setup. -- -- The ideal situation is to have a one-way information flow to the -- network to avoid the possibility of tampering from the network. -- Keeping the zone master file on-line on the network and simply -- cycling it through an off-line signer does not do this. The on-line -- version could still be tampered with if the host it resides on is -- compromised. For maximum security, the master copy of the zone file -- should be off-net and should not be updated based on an unsecured -- network mediated communication. -- -- In general, keeping a zone file off-line will not be practical and -- the machines on which zone files are maintained will be connected to -- a network. Operators are advised to take security measures to shield -- unauthorized access to the master copy. -- -- -- -- -- --Kolkman & Gieben Informational [Page 11] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- For dynamically updated secured zones [10], both the master copy and -- the private key that is used to update signatures on updated RRs will -- need to be on-line. -- --4. Signature Generation, Key Rollover, and Related Policies -- --4.1. Time in DNSSEC -- -- Without DNSSEC, all times in the DNS are relative. The SOA fields -- REFRESH, RETRY, and EXPIRATION are timers used to determine the time -- elapsed after a slave server synchronized with a master server. The -- Time to Live (TTL) value and the SOA RR minimum TTL parameter [11] -- are used to determine how long a forwarder should cache data after it -- has been fetched from an authoritative server. By using a signature -- validity period, DNSSEC introduces the notion of an absolute time in -- the DNS. Signatures in DNSSEC have an expiration date after which -- the signature is marked as invalid and the signed data is to be -- considered Bogus. -- --4.1.1. Time Considerations -- -- Because of the expiration of signatures, one should consider the -- following: -- -- o We suggest the Maximum Zone TTL of your zone data to be a fraction -- of your signature validity period. -- -- If the TTL would be of similar order as the signature validity -- period, then all RRSets fetched during the validity period -- would be cached until the signature expiration time. Section -- 7.1 of [4] suggests that "the resolver may use the time -- remaining before expiration of the signature validity period of -- a signed RRSet as an upper bound for the TTL". As a result, -- query load on authoritative servers would peak at signature -- expiration time, as this is also the time at which records -- simultaneously expire from caches. -- -- To avoid query load peaks, we suggest the TTL on all the RRs in -- your zone to be at least a few times smaller than your -- signature validity period. -- -- o We suggest the signature publication period to end at least one -- Maximum Zone TTL duration before the end of the signature validity -- period. -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 12] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- Re-signing a zone shortly before the end of the signature -- validity period may cause simultaneous expiration of data from -- caches. This in turn may lead to peaks in the load on -- authoritative servers. -- -- o We suggest the Minimum Zone TTL to be long enough to both fetch -- and verify all the RRs in the trust chain. In workshop -- environments, it has been demonstrated [18] that a low TTL (under -- 5 to 10 minutes) caused disruptions because of the following two -- problems: -- -- 1. During validation, some data may expire before the -- validation is complete. The validator should be able to -- keep all data until it is completed. This applies to all -- RRs needed to complete the chain of trust: DSes, DNSKEYs, -- RRSIGs, and the final answers, i.e., the RRSet that is -- returned for the initial query. -- -- 2. Frequent verification causes load on recursive nameservers. -- Data at delegation points, DSes, DNSKEYs, and RRSIGs -- benefit from caching. The TTL on those should be -- relatively long. -- -- o Slave servers will need to be able to fetch newly signed zones -- well before the RRSIGs in the zone served by the slave server pass -- their signature expiration time. -- -- When a slave server is out of sync with its master and data in -- a zone is signed by expired signatures, it may be better for -- the slave server not to give out any answer. -- -- Normally, a slave server that is not able to contact a master -- server for an extended period will expire a zone. When that -- happens, the server will respond differently to queries for -- that zone. Some servers issue SERVFAIL, whereas others turn -- off the 'AA' bit in the answers. The time of expiration is set -- in the SOA record and is relative to the last successful -- refresh between the master and the slave servers. There exists -- no coupling between the signature expiration of RRSIGs in the -- zone and the expire parameter in the SOA. -- -- If the server serves a DNSSEC zone, then it may well happen -- that the signatures expire well before the SOA expiration timer -- counts down to zero. It is not possible to completely prevent -- this from happening by tweaking the SOA parameters. However, -- the effects can be minimized where the SOA expiration time is -- equal to or shorter than the signature validity period. The -- consequence of an authoritative server not being able to update -- -- -- --Kolkman & Gieben Informational [Page 13] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- a zone, whilst that zone includes expired signatures, is that -- non-secure resolvers will continue to be able to resolve data -- served by the particular slave servers while security-aware -- resolvers will experience problems because of answers being -- marked as Bogus. -- -- We suggest the SOA expiration timer being approximately one -- third or one fourth of the signature validity period. It will -- allow problems with transfers from the master server to be -- noticed before the actual signature times out. We also suggest -- that operators of nameservers that supply secondary services -- develop 'watch dogs' to spot upcoming signature expirations in -- zones they slave, and take appropriate action. -- -- When determining the value for the expiration parameter one has -- to take the following into account: What are the chances that -- all my secondaries expire the zone? How quickly can I reach an -- administrator of secondary servers to load a valid zone? These -- questions are not DNSSEC specific but may influence the choice -- of your signature validity intervals. -- --4.2. Key Rollovers -- -- A DNSSEC key cannot be used forever (see Section 3.3). So key -- rollovers -- or supercessions, as they are sometimes called -- are a -- fact of life when using DNSSEC. Zone administrators who are in the -- process of rolling their keys have to take into account that data -- published in previous versions of their zone still lives in caches. -- When deploying DNSSEC, this becomes an important consideration; -- ignoring data that may be in caches may lead to loss of service for -- clients. -- -- The most pressing example of this occurs when zone material signed -- with an old key is being validated by a resolver that does not have -- the old zone key cached. If the old key is no longer present in the -- current zone, this validation fails, marking the data "Bogus". -- Alternatively, an attempt could be made to validate data that is -- signed with a new key against an old key that lives in a local cache, -- also resulting in data being marked "Bogus". -- --4.2.1. Zone Signing Key Rollovers -- -- For "Zone Signing Key rollovers", there are two ways to make sure -- that during the rollover data still cached can be verified with the -- new key sets or newly generated signatures can be verified with the -- keys still in caches. One schema, described in Section 4.2.1.2, uses -- -- -- -- -- --Kolkman & Gieben Informational [Page 14] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- double signatures; the other uses key pre-publication (Section -- 4.2.1.1). The pros, cons, and recommendations are described in -- Section 4.2.1.3. -- --4.2.1.1. Pre-Publish Key Rollover -- -- This section shows how to perform a ZSK rollover without the need to -- sign all the data in a zone twice -- the "pre-publish key rollover". -- This method has advantages in the case of a key compromise. If the -- old key is compromised, the new key has already been distributed in -- the DNS. The zone administrator is then able to quickly switch to -- the new key and remove the compromised key from the zone. Another -- major advantage is that the zone size does not double, as is the case -- with the double signature ZSK rollover. A small "how-to" for this -- kind of rollover can be found in Appendix B. -- -- Pre-publish key rollover involves four stages as follows: -- -- ---------------------------------------------------------------- -- initial new DNSKEY new RRSIGs DNSKEY removal -- ---------------------------------------------------------------- -- SOA0 SOA1 SOA2 SOA3 -- RRSIG10(SOA0) RRSIG10(SOA1) RRSIG11(SOA2) RRSIG11(SOA3) -- -- DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1 -- DNSKEY10 DNSKEY10 DNSKEY10 DNSKEY11 -- DNSKEY11 DNSKEY11 -- RRSIG1 (DNSKEY) RRSIG1 (DNSKEY) RRSIG1(DNSKEY) RRSIG1 (DNSKEY) -- RRSIG10(DNSKEY) RRSIG10(DNSKEY) RRSIG11(DNSKEY) RRSIG11(DNSKEY) -- ---------------------------------------------------------------- -- -- Pre-Publish Key Rollover -- -- initial: Initial version of the zone: DNSKEY 1 is the Key Signing -- Key. DNSKEY 10 is used to sign all the data of the zone, the Zone -- Signing Key. -- -- new DNSKEY: DNSKEY 11 is introduced into the key set. Note that no -- signatures are generated with this key yet, but this does not -- secure against brute force attacks on the public key. The minimum -- duration of this pre-roll phase is the time it takes for the data -- to propagate to the authoritative servers plus TTL value of the -- key set. -- -- new RRSIGs: At the "new RRSIGs" stage (SOA serial 2), DNSKEY 11 is -- used to sign the data in the zone exclusively (i.e., all the -- signatures from DNSKEY 10 are removed from the zone). DNSKEY 10 -- remains published in the key set. This way data that was loaded -- -- -- --Kolkman & Gieben Informational [Page 15] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- into caches from version 1 of the zone can still be verified with -- key sets fetched from version 2 of the zone. The minimum time -- that the key set including DNSKEY 10 is to be published is the -- time that it takes for zone data from the previous version of the -- zone to expire from old caches, i.e., the time it takes for this -- zone to propagate to all authoritative servers plus the Maximum -- Zone TTL value of any of the data in the previous version of the -- zone. -- -- DNSKEY removal: DNSKEY 10 is removed from the zone. The key set, now -- only containing DNSKEY 1 and DNSKEY 11, is re-signed with the -- DNSKEY 1. -- -- The above scheme can be simplified by always publishing the "future" -- key immediately after the rollover. The scheme would look as follows -- (we show two rollovers); the future key is introduced in "new DNSKEY" -- as DNSKEY 12 and again a newer one, numbered 13, in "new DNSKEY -- (II)": -- -- ---------------------------------------------------------------- -- initial new RRSIGs new DNSKEY -- ---------------------------------------------------------------- -- SOA0 SOA1 SOA2 -- RRSIG10(SOA0) RRSIG11(SOA1) RRSIG11(SOA2) -- -- DNSKEY1 DNSKEY1 DNSKEY1 -- DNSKEY10 DNSKEY10 DNSKEY11 -- DNSKEY11 DNSKEY11 DNSKEY12 -- RRSIG1(DNSKEY) RRSIG1 (DNSKEY) RRSIG1(DNSKEY) -- RRSIG10(DNSKEY) RRSIG11(DNSKEY) RRSIG11(DNSKEY) -- ---------------------------------------------------------------- -- -- ---------------------------------------------------------------- -- new RRSIGs (II) new DNSKEY (II) -- ---------------------------------------------------------------- -- SOA3 SOA4 -- RRSIG12(SOA3) RRSIG12(SOA4) -- -- DNSKEY1 DNSKEY1 -- DNSKEY11 DNSKEY12 -- DNSKEY12 DNSKEY13 -- RRSIG1(DNSKEY) RRSIG1(DNSKEY) -- RRSIG12(DNSKEY) RRSIG12(DNSKEY) -- ---------------------------------------------------------------- -- -- Pre-Publish Key Rollover, Showing Two Rollovers -- -- -- -- -- --Kolkman & Gieben Informational [Page 16] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- Note that the key introduced in the "new DNSKEY" phase is not used -- for production yet; the private key can thus be stored in a -- physically secure manner and does not need to be 'fetched' every time -- a zone needs to be signed. -- --4.2.1.2. Double Signature Zone Signing Key Rollover -- -- This section shows how to perform a ZSK key rollover using the double -- zone data signature scheme, aptly named "double signature rollover". -- -- During the "new DNSKEY" stage the new version of the zone file will -- need to propagate to all authoritative servers and the data that -- exists in (distant) caches will need to expire, requiring at least -- the Maximum Zone TTL. -- -- Double signature ZSK rollover involves three stages as follows: -- -- ---------------------------------------------------------------- -- initial new DNSKEY DNSKEY removal -- ---------------------------------------------------------------- -- SOA0 SOA1 SOA2 -- RRSIG10(SOA0) RRSIG10(SOA1) RRSIG11(SOA2) -- RRSIG11(SOA1) -- -- DNSKEY1 DNSKEY1 DNSKEY1 -- DNSKEY10 DNSKEY10 DNSKEY11 -- DNSKEY11 -- RRSIG1(DNSKEY) RRSIG1(DNSKEY) RRSIG1(DNSKEY) -- RRSIG10(DNSKEY) RRSIG10(DNSKEY) RRSIG11(DNSKEY) -- RRSIG11(DNSKEY) -- ---------------------------------------------------------------- -- -- Double Signature Zone Signing Key Rollover -- -- initial: Initial Version of the zone: DNSKEY 1 is the Key Signing -- Key. DNSKEY 10 is used to sign all the data of the zone, the Zone -- Signing Key. -- -- new DNSKEY: At the "New DNSKEY" stage (SOA serial 1) DNSKEY 11 is -- introduced into the key set and all the data in the zone is signed -- with DNSKEY 10 and DNSKEY 11. The rollover period will need to -- continue until all data from version 0 of the zone has expired -- from remote caches. This will take at least the Maximum Zone TTL -- of version 0 of the zone. -- -- DNSKEY removal: DNSKEY 10 is removed from the zone. All the -- signatures from DNSKEY 10 are removed from the zone. The key set, -- now only containing DNSKEY 11, is re-signed with DNSKEY 1. -- -- -- --Kolkman & Gieben Informational [Page 17] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- At every instance, RRSIGs from the previous version of the zone can -- be verified with the DNSKEY RRSet from the current version and the -- other way around. The data from the current version can be verified -- with the data from the previous version of the zone. The duration of -- the "new DNSKEY" phase and the period between rollovers should be at -- least the Maximum Zone TTL. -- -- Making sure that the "new DNSKEY" phase lasts until the signature -- expiration time of the data in initial version of the zone is -- recommended. This way all caches are cleared of the old signatures. -- However, this duration could be considerably longer than the Maximum -- Zone TTL, making the rollover a lengthy procedure. -- -- Note that in this example we assumed that the zone was not modified -- during the rollover. New data can be introduced in the zone as long -- as it is signed with both keys. -- --4.2.1.3. Pros and Cons of the Schemes -- -- Pre-publish key rollover: This rollover does not involve signing the -- zone data twice. Instead, before the actual rollover, the new key -- is published in the key set and thus is available for -- cryptanalysis attacks. A small disadvantage is that this process -- requires four steps. Also the pre-publish scheme involves more -- parental work when used for KSK rollovers as explained in Section -- 4.2.3. -- -- Double signature ZSK rollover: The drawback of this signing scheme is -- that during the rollover the number of signatures in your zone -- doubles; this may be prohibitive if you have very big zones. An -- advantage is that it only requires three steps. -- --4.2.2. Key Signing Key Rollovers -- -- For the rollover of a Key Signing Key, the same considerations as for -- the rollover of a Zone Signing Key apply. However, we can use a -- double signature scheme to guarantee that old data (only the apex key -- set) in caches can be verified with a new key set and vice versa. -- Since only the key set is signed with a KSK, zone size considerations -- do not apply. -- -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 18] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- -------------------------------------------------------------------- -- initial new DNSKEY DS change DNSKEY removal -- -------------------------------------------------------------------- -- Parent: -- SOA0 --------> SOA1 --------> -- RRSIGpar(SOA0) --------> RRSIGpar(SOA1) --------> -- DS1 --------> DS2 --------> -- RRSIGpar(DS) --------> RRSIGpar(DS) --------> -- -- -- Child: -- SOA0 SOA1 --------> SOA2 -- RRSIG10(SOA0) RRSIG10(SOA1) --------> RRSIG10(SOA2) -- --------> -- DNSKEY1 DNSKEY1 --------> DNSKEY2 -- DNSKEY2 --------> -- DNSKEY10 DNSKEY10 --------> DNSKEY10 -- RRSIG1 (DNSKEY) RRSIG1 (DNSKEY) --------> RRSIG2 (DNSKEY) -- RRSIG2 (DNSKEY) --------> -- RRSIG10(DNSKEY) RRSIG10(DNSKEY) --------> RRSIG10(DNSKEY) -- -------------------------------------------------------------------- -- -- Stages of Deployment for a Double Signature Key Signing Key Rollover -- -- initial: Initial version of the zone. The parental DS points to -- DNSKEY1. Before the rollover starts, the child will have to -- verify what the TTL is of the DS RR that points to DNSKEY1 -- it -- is needed during the rollover and we refer to the value as TTL_DS. -- -- new DNSKEY: During the "new DNSKEY" phase, the zone administrator -- generates a second KSK, DNSKEY2. The key is provided to the -- parent, and the child will have to wait until a new DS RR has been -- generated that points to DNSKEY2. After that DS RR has been -- published on all servers authoritative for the parent's zone, the -- zone administrator has to wait at least TTL_DS to make sure that -- the old DS RR has expired from caches. -- -- DS change: The parent replaces DS1 with DS2. -- -- DNSKEY removal: DNSKEY1 has been removed. -- -- The scenario above puts the responsibility for maintaining a valid -- chain of trust with the child. It also is based on the premise that -- the parent only has one DS RR (per algorithm) per zone. An -- alternative mechanism has been considered. Using an established -- trust relation, the interaction can be performed in-band, and the -- removal of the keys by the child can possibly be signaled by the -- parent. In this mechanism, there are periods where there are two DS -- -- -- --Kolkman & Gieben Informational [Page 19] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- RRs at the parent. Since at the moment of writing the protocol for -- this interaction has not been developed, further discussion is out of -- scope for this document. -- --4.2.3. Difference Between ZSK and KSK Rollovers -- -- Note that KSK rollovers and ZSK rollovers are different in the sense -- that a KSK rollover requires interaction with the parent (and -- possibly replacing of trust anchors) and the ensuing delay while -- waiting for it. -- -- A zone key rollover can be handled in two different ways: pre-publish -- (Section 4.2.1.1) and double signature (Section 4.2.1.2). -- -- As the KSK is used to validate the key set and because the KSK is not -- changed during a ZSK rollover, a cache is able to validate the new -- key set of the zone. The pre-publish method would also work for a -- KSK rollover. The records that are to be pre-published are the -- parental DS RRs. The pre-publish method has some drawbacks for KSKs. -- We first describe the rollover scheme and then indicate these -- drawbacks. -- -- -------------------------------------------------------------------- -- initial new DS new DNSKEY DS/DNSKEY removal -- -------------------------------------------------------------------- -- Parent: -- SOA0 SOA1 --------> SOA2 -- RRSIGpar(SOA0) RRSIGpar(SOA1) --------> RRSIGpar(SOA2) -- DS1 DS1 --------> DS2 -- DS2 --------> -- RRSIGpar(DS) RRSIGpar(DS) --------> RRSIGpar(DS) -- -- -- Child: -- SOA0 --------> SOA1 SOA1 -- RRSIG10(SOA0) --------> RRSIG10(SOA1) RRSIG10(SOA1) -- --------> -- DNSKEY1 --------> DNSKEY2 DNSKEY2 -- --------> -- DNSKEY10 --------> DNSKEY10 DNSKEY10 -- RRSIG1 (DNSKEY) --------> RRSIG2(DNSKEY) RRSIG2 (DNSKEY) -- RRSIG10(DNSKEY) --------> RRSIG10(DNSKEY) RRSIG10(DNSKEY) -- -------------------------------------------------------------------- -- -- Stages of Deployment for a Pre-Publish Key Signing Key Rollover -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 20] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- When the child zone wants to roll, it notifies the parent during the -- "new DS" phase and submits the new key (or the corresponding DS) to -- the parent. The parent publishes DS1 and DS2, pointing to DNSKEY1 -- and DNSKEY2, respectively. During the rollover ("new DNSKEY" phase), -- which can take place as soon as the new DS set propagated through the -- DNS, the child replaces DNSKEY1 with DNSKEY2. Immediately after that -- ("DS/DNSKEY removal" phase), it can notify the parent that the old DS -- record can be deleted. -- -- The drawbacks of this scheme are that during the "new DS" phase the -- parent cannot verify the match between the DS2 RR and DNSKEY2 using -- the DNS -- as DNSKEY2 is not yet published. Besides, we introduce a -- "security lame" key (see Section 4.4.3). Finally, the child-parent -- interaction consists of two steps. The "double signature" method -- only needs one interaction. -- --4.2.4. Automated Key Rollovers -- -- As keys must be renewed periodically, there is some motivation to -- automate the rollover process. Consider the following: -- -- o ZSK rollovers are easy to automate as only the child zone is -- involved. -- -- o A KSK rollover needs interaction between parent and child. Data -- exchange is needed to provide the new keys to the parent; -- consequently, this data must be authenticated and integrity must -- be guaranteed in order to avoid attacks on the rollover. -- --4.3. Planning for Emergency Key Rollover -- -- This section deals with preparation for a possible key compromise. -- Our advice is to have a documented procedure ready for when a key -- compromise is suspected or confirmed. -- -- When the private material of one of your keys is compromised it can -- be used for as long as a valid trust chain exists. A trust chain -- remains intact for -- -- o as long as a signature over the compromised key in the trust chain -- is valid, -- -- o as long as a parental DS RR (and signature) points to the -- compromised key, -- -- o as long as the key is anchored in a resolver and is used as a -- starting point for validation (this is generally the hardest to -- update). -- -- -- --Kolkman & Gieben Informational [Page 21] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- While a trust chain to your compromised key exists, your namespace is -- vulnerable to abuse by anyone who has obtained illegitimate -- possession of the key. Zone operators have to make a trade-off if -- the abuse of the compromised key is worse than having data in caches -- that cannot be validated. If the zone operator chooses to break the -- trust chain to the compromised key, data in caches signed with this -- key cannot be validated. However, if the zone administrator chooses -- to take the path of a regular rollover, the malicious key holder can -- spoof data so that it appears to be valid. -- --4.3.1. KSK Compromise -- -- A zone containing a DNSKEY RRSet with a compromised KSK is vulnerable -- as long as the compromised KSK is configured as trust anchor or a -- parental DS points to it. -- -- A compromised KSK can be used to sign the key set of an attacker's -- zone. That zone could be used to poison the DNS. -- -- Therefore, when the KSK has been compromised, the trust anchor or the -- parental DS should be replaced as soon as possible. It is local -- policy whether to break the trust chain during the emergency -- rollover. The trust chain would be broken when the compromised KSK -- is removed from the child's zone while the parent still has a DS -- pointing to the compromised KSK (the assumption is that there is only -- one DS at the parent. If there are multiple DSes this does not apply -- -- however the chain of trust of this particular key is broken). -- -- Note that an attacker's zone still uses the compromised KSK and the -- presence of a parental DS would cause the data in this zone to appear -- as valid. Removing the compromised key would cause the attacker's -- zone to appear as valid and the child's zone as Bogus. Therefore, we -- advise not to remove the KSK before the parent has a DS to a new KSK -- in place. -- --4.3.1.1. Keeping the Chain of Trust Intact -- -- If we follow this advice, the timing of the replacement of the KSK is -- somewhat critical. The goal is to remove the compromised KSK as soon -- as the new DS RR is available at the parent. And also make sure that -- the signature made with a new KSK over the key set with the -- compromised KSK in it expires just after the new DS appears at the -- parent, thus removing the old cruft in one swoop. -- -- The procedure is as follows: -- -- 1. Introduce a new KSK into the key set, keep the compromised KSK in -- the key set. -- -- -- --Kolkman & Gieben Informational [Page 22] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- 2. Sign the key set, with a short validity period. The validity -- period should expire shortly after the DS is expected to appear -- in the parent and the old DSes have expired from caches. -- -- 3. Upload the DS for this new key to the parent. -- -- 4. Follow the procedure of the regular KSK rollover: Wait for the DS -- to appear in the authoritative servers and then wait as long as -- the TTL of the old DS RRs. If necessary re-sign the DNSKEY RRSet -- and modify/extend the expiration time. -- -- 5. Remove the compromised DNSKEY RR from the zone and re-sign the -- key set using your "normal" validity interval. -- -- An additional danger of a key compromise is that the compromised key -- could be used to facilitate a legitimate DNSKEY/DS rollover and/or -- nameserver changes at the parent. When that happens, the domain may -- be in dispute. An authenticated out-of-band and secure notify -- mechanism to contact a parent is needed in this case. -- -- Note that this is only a problem when the DNSKEY and or DS records -- are used for authentication at the parent. -- --4.3.1.2. Breaking the Chain of Trust -- -- There are two methods to break the chain of trust. The first method -- causes the child zone to appear 'Bogus' to validating resolvers. The -- other causes the child zone to appear 'insecure'. These are -- described below. -- -- In the method that causes the child zone to appear 'Bogus' to -- validating resolvers, the child zone replaces the current KSK with a -- new one and re-signs the key set. Next it sends the DS of the new -- key to the parent. Only after the parent has placed the new DS in -- the zone is the child's chain of trust repaired. -- -- An alternative method of breaking the chain of trust is by removing -- the DS RRs from the parent zone altogether. As a result, the child -- zone would become insecure. -- --4.3.2. ZSK Compromise -- -- Primarily because there is no parental interaction required when a -- ZSK is compromised, the situation is less severe than with a KSK -- compromise. The zone must still be re-signed with a new ZSK as soon -- as possible. As this is a local operation and requires no -- communication between the parent and child, this can be achieved -- fairly quickly. However, one has to take into account that just as -- -- -- --Kolkman & Gieben Informational [Page 23] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- with a normal rollover the immediate disappearance of the old -- compromised key may lead to verification problems. Also note that as -- long as the RRSIG over the compromised ZSK is not expired the zone -- may be still at risk. -- --4.3.3. Compromises of Keys Anchored in Resolvers -- -- A key can also be pre-configured in resolvers. For instance, if -- DNSSEC is successfully deployed the root key may be pre-configured in -- most security aware resolvers. -- -- If trust-anchor keys are compromised, the resolvers using these keys -- should be notified of this fact. Zone administrators may consider -- setting up a mailing list to communicate the fact that a SEP key is -- about to be rolled over. This communication will of course need to -- be authenticated, e.g., by using digital signatures. -- -- End-users faced with the task of updating an anchored key should -- always validate the new key. New keys should be authenticated out- -- of-band, for example, through the use of an announcement website that -- is secured using secure sockets (TLS) [21]. -- --4.4. Parental Policies -- --4.4.1. Initial Key Exchanges and Parental Policies Considerations -- -- The initial key exchange is always subject to the policies set by the -- parent. When designing a key exchange policy one should take into -- account that the authentication and authorization mechanisms used -- during a key exchange should be as strong as the authentication and -- authorization mechanisms used for the exchange of delegation -- information between parent and child. That is, there is no implicit -- need in DNSSEC to make the authentication process stronger than it -- was in DNS. -- -- Using the DNS itself as the source for the actual DNSKEY material, -- with an out-of-band check on the validity of the DNSKEY, has the -- benefit that it reduces the chances of user error. A DNSKEY query -- tool can make use of the SEP bit [3] to select the proper key from a -- DNSSEC key set, thereby reducing the chance that the wrong DNSKEY is -- sent. It can validate the self-signature over a key; thereby -- verifying the ownership of the private key material. Fetching the -- DNSKEY from the DNS ensures that the chain of trust remains intact -- once the parent publishes the DS RR indicating the child is secure. -- -- Note: the out-of-band verification is still needed when the key -- material is fetched via the DNS. The parent can never be sure -- whether or not the DNSKEY RRs have been spoofed. -- -- -- --Kolkman & Gieben Informational [Page 24] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --4.4.2. Storing Keys or Hashes? -- -- When designing a registry system one should consider which of the -- DNSKEYs and/or the corresponding DSes to store. Since a child zone -- might wish to have a DS published using a message digest algorithm -- not yet understood by the registry, the registry can't count on being -- able to generate the DS record from a raw DNSKEY. Thus, we recommend -- that registry systems at least support storing DS records. -- -- It may also be useful to store DNSKEYs, since having them may help -- during troubleshooting and, as long as the child's chosen message -- digest is supported, the overhead of generating DS records from them -- is minimal. Having an out-of-band mechanism, such as a registry -- directory (e.g., Whois), to find out which keys are used to generate -- DS Resource Records for specific owners and/or zones may also help -- with troubleshooting. -- -- The storage considerations also relate to the design of the customer -- interface and the method by which data is transferred between -- registrant and registry; Will the child zone administrator be able to -- upload DS RRs with unknown hash algorithms or does the interface only -- allow DNSKEYs? In the registry-registrar model, one can use the -- DNSSEC extensions to the Extensible Provisioning Protocol (EPP) [15], -- which allows transfer of DS RRs and optionally DNSKEY RRs. -- --4.4.3. Security Lameness -- -- Security lameness is defined as what happens when a parent has a DS -- RR pointing to a non-existing DNSKEY RR. When this happens, the -- child's zone may be marked "Bogus" by verifying DNS clients. -- -- As part of a comprehensive delegation check, the parent could, at key -- exchange time, verify that the child's key is actually configured in -- the DNS. However, if a parent does not understand the hashing -- algorithm used by child, the parental checks are limited to only -- comparing the key id. -- -- Child zones should be very careful in removing DNSKEY material, -- specifically SEP keys, for which a DS RR exists. -- -- Once a zone is "security lame", a fix (e.g., removing a DS RR) will -- take time to propagate through the DNS. -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 25] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --4.4.4. DS Signature Validity Period -- -- Since the DS can be replayed as long as it has a valid signature, a -- short signature validity period over the DS minimizes the time a -- child is vulnerable in the case of a compromise of the child's -- KSK(s). A signature validity period that is too short introduces the -- possibility that a zone is marked "Bogus" in case of a configuration -- error in the signer. There may not be enough time to fix the -- problems before signatures expire. Something as mundane as operator -- unavailability during weekends shows the need for DS signature -- validity periods longer than 2 days. We recommend an absolute -- minimum for a DS signature validity period of a few days. -- -- The maximum signature validity period of the DS record depends on how -- long child zones are willing to be vulnerable after a key compromise. -- On the other hand, shortening the DS signature validity interval -- increases the operational risk for the parent. Therefore, the parent -- may have policy to use a signature validity interval that is -- considerably longer than the child would hope for. -- -- A compromise between the operational constraints of the parent and -- minimizing damage for the child may result in a DS signature validity -- period somewhere between a week and months. -- -- In addition to the signature validity period, which sets a lower -- bound on the number of times the zone owner will need to sign the -- zone data and which sets an upper bound to the time a child is -- vulnerable after key compromise, there is the TTL value on the DS -- RRs. Shortening the TTL means that the authoritative servers will -- see more queries. But on the other hand, a short TTL lowers the -- persistence of DS RRSets in caches thereby increasing the speed with -- which updated DS RRSets propagate through the DNS. -- --5. Security Considerations -- -- DNSSEC adds data integrity to the DNS. This document tries to assess -- the operational considerations to maintain a stable and secure DNSSEC -- service. Not taking into account the 'data propagation' properties -- in the DNS will cause validation failures and may make secured zones -- unavailable to security-aware resolvers. -- --6. Acknowledgments -- -- Most of the ideas in this document were the result of collective -- efforts during workshops, discussions, and tryouts. -- -- At the risk of forgetting individuals who were the original -- contributors of the ideas, we would like to acknowledge people who -- -- -- --Kolkman & Gieben Informational [Page 26] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- were actively involved in the compilation of this document. In -- random order: Rip Loomis, Olafur Gudmundsson, Wesley Griffin, Michael -- Richardson, Scott Rose, Rick van Rein, Tim McGinnis, Gilles Guette -- Olivier Courtay, Sam Weiler, Jelte Jansen, Niall O'Reilly, Holger -- Zuleger, Ed Lewis, Hilarie Orman, Marcos Sanz, and Peter Koch. -- -- Some material in this document has been copied from RFC 2541 [12]. -- -- Mike StJohns designed the key exchange between parent and child -- mentioned in the last paragraph of Section 4.2.2 -- -- Section 4.2.4 was supplied by G. Guette and O. Courtay. -- -- Emma Bretherick, Adrian Bedford, and Lindy Foster corrected many of -- the spelling and style issues. -- -- Kolkman and Gieben take the blame for introducing all miscakes (sic). -- -- While working on this document, Kolkman was employed by the RIPE NCC -- and Gieben was employed by NLnet Labs. -- --7. References -- --7.1. Normative References -- -- [1] Mockapetris, P., "Domain names - concepts and facilities", STD -- 13, RFC 1034, November 1987. -- -- [2] Mockapetris, P., "Domain names - implementation and -- specification", STD 13, RFC 1035, November 1987. -- -- [3] Kolkman, O., Schlyter, J., and E. Lewis, "Domain Name System -- KEY (DNSKEY) Resource Record (RR) Secure Entry Point (SEP) -- Flag", RFC 3757, May 2004. -- -- [4] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "DNS Security Introduction and Requirements", RFC 4033, March -- 2005. -- -- [5] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Resource Records for the DNS Security Extensions", RFC 4034, -- March 2005. -- -- [6] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, -- "Protocol Modifications for the DNS Security Extensions", RFC -- 4035, March 2005. -- -- -- -- -- --Kolkman & Gieben Informational [Page 27] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --7.2. Informative References -- -- [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement -- Levels", BCP 14, RFC 2119, March 1997. -- -- [8] Ohta, M., "Incremental Zone Transfer in DNS", RFC 1995, August -- 1996. -- -- [9] Vixie, P., "A Mechanism for Prompt Notification of Zone Changes -- (DNS NOTIFY)", RFC 1996, August 1996. -- -- [10] Wellington, B., "Secure Domain Name System (DNS) Dynamic -- Update", RFC 3007, November 2000. -- -- [11] Andrews, M., "Negative Caching of DNS Queries (DNS NCACHE)", -- RFC 2308, March 1998. -- -- [12] Eastlake, D., "DNS Security Operational Considerations", RFC -- 2541, March 1999. -- -- [13] Orman, H. and P. Hoffman, "Determining Strengths For Public -- Keys Used For Exchanging Symmetric Keys", BCP 86, RFC 3766, -- April 2004. -- -- [14] Eastlake, D., Schiller, J., and S. Crocker, "Randomness -- Requirements for Security", BCP 106, RFC 4086, June 2005. -- -- [15] Hollenbeck, S., "Domain Name System (DNS) Security Extensions -- Mapping for the Extensible Provisioning Protocol (EPP)", RFC -- 4310, December 2005. -- -- [16] Lenstra, A. and E. Verheul, "Selecting Cryptographic Key -- Sizes", The Journal of Cryptology 14 (255-293), 2001. -- -- [17] Schneier, B., "Applied Cryptography: Protocols, Algorithms, and -- Source Code in C", ISBN (hardcover) 0-471-12845-7, ISBN -- (paperback) 0-471-59756-2, Published by John Wiley & Sons Inc., -- 1996. -- -- [18] Rose, S., "NIST DNSSEC workshop notes", June 2001. -- -- [19] Jansen, J., "Use of RSA/SHA-256 DNSKEY and RRSIG Resource -- Records in DNSSEC", Work in Progress, January 2006. -- -- [20] Hardaker, W., "Use of SHA-256 in DNSSEC Delegation Signer (DS) -- Resource Records (RRs)", RFC 4509, May 2006. -- -- -- -- -- --Kolkman & Gieben Informational [Page 28] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- [21] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., and -- T. Wright, "Transport Layer Security (TLS) Extensions", RFC -- 4366, April 2006. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 29] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --Appendix A. Terminology -- -- In this document, there is some jargon used that is defined in other -- documents. In most cases, we have not copied the text from the -- documents defining the terms but have given a more elaborate -- explanation of the meaning. Note that these explanations should not -- be seen as authoritative. -- -- Anchored key: A DNSKEY configured in resolvers around the globe. -- This key is hard to update, hence the term anchored. -- -- Bogus: Also see Section 5 of [4]. An RRSet in DNSSEC is marked -- "Bogus" when a signature of an RRSet does not validate against a -- DNSKEY. -- -- Key Signing Key or KSK: A Key Signing Key (KSK) is a key that is used -- exclusively for signing the apex key set. The fact that a key is -- a KSK is only relevant to the signing tool. -- -- Key size: The term 'key size' can be substituted by 'modulus size' -- throughout the document. It is mathematically more correct to use -- modulus size, but as this is a document directed at operators we -- feel more at ease with the term key size. -- -- Private and public keys: DNSSEC secures the DNS through the use of -- public key cryptography. Public key cryptography is based on the -- existence of two (mathematically related) keys, a public key and a -- private key. The public keys are published in the DNS by use of -- the DNSKEY Resource Record (DNSKEY RR). Private keys should -- remain private. -- -- Key rollover: A key rollover (also called key supercession in some -- environments) is the act of replacing one key pair with another at -- the end of a key effectivity period. -- -- Secure Entry Point (SEP) key: A KSK that has a parental DS record -- pointing to it or is configured as a trust anchor. Although not -- required by the protocol, we recommend that the SEP flag [3] is -- set on these keys. -- -- Self-signature: This only applies to signatures over DNSKEYs; a -- signature made with DNSKEY x, over DNSKEY x is called a self- -- signature. Note: without further information, self-signatures -- convey no trust. They are useful to check the authenticity of the -- DNSKEY, i.e., they can be used as a hash. -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 30] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- Singing the zone file: The term used for the event where an -- administrator joyfully signs its zone file while producing melodic -- sound patterns. -- -- Signer: The system that has access to the private key material and -- signs the Resource Record sets in a zone. A signer may be -- configured to sign only parts of the zone, e.g., only those RRSets -- for which existing signatures are about to expire. -- -- Zone Signing Key (ZSK): A key that is used for signing all data in a -- zone. The fact that a key is a ZSK is only relevant to the -- signing tool. -- -- Zone administrator: The 'role' that is responsible for signing a zone -- and publishing it on the primary authoritative server. -- --Appendix B. Zone Signing Key Rollover How-To -- -- Using the pre-published signature scheme and the most conservative -- method to assure oneself that data does not live in caches, here -- follows the "how-to". -- -- Step 0: The preparation: Create two keys and publish both in your key -- set. Mark one of the keys "active" and the other "published". -- Use the "active" key for signing your zone data. Store the -- private part of the "published" key, preferably off-line. The -- protocol does not provide for attributes to mark a key as active -- or published. This is something you have to do on your own, -- through the use of a notebook or key management tool. -- -- Step 1: Determine expiration: At the beginning of the rollover make a -- note of the highest expiration time of signatures in your zone -- file created with the current key marked as active. Wait until -- the expiration time marked in Step 1 has passed. -- -- Step 2: Then start using the key that was marked "published" to sign -- your data (i.e., mark it "active"). Stop using the key that was -- marked "active"; mark it "rolled". -- -- Step 3: It is safe to engage in a new rollover (Step 1) after at -- least one signature validity period. -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 31] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --Appendix C. Typographic Conventions -- -- The following typographic conventions are used in this document: -- -- Key notation: A key is denoted by DNSKEYx, where x is a number or an -- identifier, x could be thought of as the key id. -- -- RRSet notations: RRs are only denoted by the type. All other -- information -- owner, class, rdata, and TTL--is left out. Thus: -- "example.com 3600 IN A 192.0.2.1" is reduced to "A". RRSets are a -- list of RRs. A example of this would be "A1, A2", specifying the -- RRSet containing two "A" records. This could again be abbreviated to -- just "A". -- -- Signature notation: Signatures are denoted as RRSIGx(RRSet), which -- means that RRSet is signed with DNSKEYx. -- -- Zone representation: Using the above notation we have simplified the -- representation of a signed zone by leaving out all unnecessary -- details such as the names and by representing all data by "SOAx" -- -- SOA representation: SOAs are represented as SOAx, where x is the -- serial number. -- -- Using this notation the following signed zone: -- -- example.net. 86400 IN SOA ns.example.net. bert.example.net. ( -- 2006022100 ; serial -- 86400 ; refresh ( 24 hours) -- 7200 ; retry ( 2 hours) -- 3600000 ; expire (1000 hours) -- 28800 ) ; minimum ( 8 hours) -- 86400 RRSIG SOA 5 2 86400 20130522213204 ( -- 20130422213204 14 example.net. -- cmL62SI6iAX46xGNQAdQ... ) -- 86400 NS a.iana-servers.net. -- 86400 NS b.iana-servers.net. -- 86400 RRSIG NS 5 2 86400 20130507213204 ( -- 20130407213204 14 example.net. -- SO5epiJei19AjXoUpFnQ ... ) -- 86400 DNSKEY 256 3 5 ( -- EtRB9MP5/AvOuVO0I8XDxy0... ) ; id = 14 -- 86400 DNSKEY 257 3 5 ( -- gsPW/Yy19GzYIY+Gnr8HABU... ) ; id = 15 -- 86400 RRSIG DNSKEY 5 2 86400 20130522213204 ( -- 20130422213204 14 example.net. -- J4zCe8QX4tXVGjV4e1r9... ) -- -- -- -- --Kolkman & Gieben Informational [Page 32] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- -- 86400 RRSIG DNSKEY 5 2 86400 20130522213204 ( -- 20130422213204 15 example.net. -- keVDCOpsSeDReyV6O... ) -- 86400 RRSIG NSEC 5 2 86400 20130507213204 ( -- 20130407213204 14 example.net. -- obj3HEp1GjnmhRjX... ) -- a.example.net. 86400 IN TXT "A label" -- 86400 RRSIG TXT 5 3 86400 20130507213204 ( -- 20130407213204 14 example.net. -- IkDMlRdYLmXH7QJnuF3v... ) -- 86400 NSEC b.example.com. TXT RRSIG NSEC -- 86400 RRSIG NSEC 5 3 86400 20130507213204 ( -- 20130407213204 14 example.net. -- bZMjoZ3bHjnEz0nIsPMM... ) -- ... -- -- is reduced to the following representation: -- -- SOA2006022100 -- RRSIG14(SOA2006022100) -- DNSKEY14 -- DNSKEY15 -- -- RRSIG14(KEY) -- RRSIG15(KEY) -- -- The rest of the zone data has the same signature as the SOA record, -- i.e., an RRSIG created with DNSKEY 14. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 33] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --Authors' Addresses -- -- Olaf M. Kolkman -- NLnet Labs -- Kruislaan 419 -- Amsterdam 1098 VA -- The Netherlands -- -- EMail: olaf@nlnetlabs.nl -- URI: http://www.nlnetlabs.nl -- -- -- R. (Miek) Gieben -- -- EMail: miek@miek.nl -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 34] -- --RFC 4641 DNSSEC Operational Practices September 2006 -- -- --Full Copyright Statement -- -- Copyright (C) The Internet Society (2006). -- -- This document is subject to the rights, licenses and restrictions -- contained in BCP 78, and except as set forth therein, the authors -- retain all their rights. -- -- This document and the information contained herein are provided on an -- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS -- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET -- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, -- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -- --Intellectual Property -- -- The IETF takes no position regarding the validity or scope of any -- Intellectual Property Rights or other rights that might be claimed to -- pertain to the implementation or use of the technology described in -- this document or the extent to which any license under such rights -- might or might not be available; nor does it represent that it has -- made any independent effort to identify any such rights. Information -- on the procedures with respect to rights in RFC documents can be -- found in BCP 78 and BCP 79. -- -- Copies of IPR disclosures made to the IETF Secretariat and any -- assurances of licenses to be made available, or the result of an -- attempt made to obtain a general license or permission for the use of -- such proprietary rights by implementers or users of this -- specification can be obtained from the IETF on-line IPR repository at -- http://www.ietf.org/ipr. -- -- The IETF invites any interested party to bring to its attention any -- copyrights, patents or patent applications, or other proprietary -- rights that may cover technology that may be required to implement -- this standard. Please address the information to the IETF at -- ietf-ipr@ietf.org. -- --Acknowledgement -- -- Funding for the RFC Editor function is provided by the IETF -- Administrative Support Activity (IASA). -- -- -- -- -- -- -- --Kolkman & Gieben Informational [Page 35] --