From: JINMEI Tatuya Date: Fri, 20 Jan 2012 07:48:28 +0000 (-0800) Subject: [1431] documentation update X-Git-Tag: trac2351_base~275^2~10^2~7 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c95f08240cfb08954c361f36fa0877b0cc3385d7;p=thirdparty%2Fkea.git [1431] documentation update --- diff --git a/src/bin/auth/tests/query_unittest.cc b/src/bin/auth/tests/query_unittest.cc index 4c21456f19..ab3dace0a9 100644 --- a/src/bin/auth/tests/query_unittest.cc +++ b/src/bin/auth/tests/query_unittest.cc @@ -245,7 +245,7 @@ public: virtual ZoneFinder::FindNSEC3Result findNSEC3(const Name& name, bool recursive, - ConstRRsetPtr known_enclosure = ConstRRsetPtr()); + ConstRRsetPtr known_encloser = ConstRRsetPtr()); // If false is passed, it makes the zone broken as if it didn't have the // SOA. @@ -424,23 +424,23 @@ MockZoneFinder::findNSEC3Helper(const Name& name, bool recursive) { ZoneFinder::FindNSEC3Result MockZoneFinder::findNSEC3(const Name& name, bool recursive, - ConstRRsetPtr known_enclosure) + ConstRRsetPtr known_encloser) { - if (!known_enclosure || known_enclosure->getName() == name) { + if (!known_encloser || known_encloser->getName() == name) { return (findNSEC3Helper(name, recursive)); } - // If it's recursive mode and we are given a know enclosure that is a + // If it's recursive mode and we are given a know encloser that is a // real ancestor of name, we may possibly be able to skip some intermediate // level. The split below returns the immediate child of the owner name // of the known ancestor toward the query name. if (!recursive) { - isc_throw(isc::InvalidParameter, "Enclosure cannot be an ancestor " + isc_throw(isc::InvalidParameter, "Encloser cannot be an ancestor " "in non recursive mode"); } return (findNSEC3Helper(name.split( name.getLabelCount() - - known_enclosure->getName().getLabelCount() - + known_encloser->getName().getLabelCount() - 1), true)); } @@ -640,7 +640,7 @@ MockZoneFinder::find(const Name& name, const RRType& type, // than the origin) if ((options & FIND_DNSSEC) != 0) { if (use_nsec3_) { - // In many cases the closest enclosure should be the apex name. + // In many cases the closest encloser should be the apex name. // So for now we always return it. return (FindResult(NXDOMAIN, RRsetPtr(new RRset(Name("example.com"), @@ -1521,7 +1521,7 @@ TEST_F(QueryTest, findNSEC3) { apex_nsec3), isc::InvalidParameter); - // Non existent name. The closest provable enclosure is the apex, + // Non existent name. The closest provable encloser is the apex, // and next closer is the query name. nsec3Check(true, string(nsec3_apex_txt) + string(nsec3_www_txt), mock_finder->findNSEC3(Name("nxdomain.example.com"), true)); diff --git a/src/lib/datasrc/database.h b/src/lib/datasrc/database.h index 3f15ad9865..ed706f082b 100644 --- a/src/lib/datasrc/database.h +++ b/src/lib/datasrc/database.h @@ -757,7 +757,7 @@ public: /// TBD virtual FindNSEC3Result findNSEC3(const isc::dns::Name& name, bool recursive, - const isc::dns::ConstRRsetPtr known_enclosure); + const isc::dns::ConstRRsetPtr known_encloser); /// \brief The zone ID /// diff --git a/src/lib/datasrc/memory_datasrc.h b/src/lib/datasrc/memory_datasrc.h index f7e4abc739..1c9d9704a8 100644 --- a/src/lib/datasrc/memory_datasrc.h +++ b/src/lib/datasrc/memory_datasrc.h @@ -86,7 +86,7 @@ public: /// TBD virtual FindNSEC3Result findNSEC3(const isc::dns::Name& name, bool recursive, - const isc::dns::ConstRRsetPtr known_enclosure); + const isc::dns::ConstRRsetPtr known_encloser); /// \brief Imelementation of the ZoneFinder::findPreviousName method /// diff --git a/src/lib/datasrc/zone.h b/src/lib/datasrc/zone.h index b3deeeffad..6e53f6752d 100644 --- a/src/lib/datasrc/zone.h +++ b/src/lib/datasrc/zone.h @@ -229,10 +229,20 @@ public: /// of \c DELEGATION and the NS RRset at the zone cut. /// - If there is no matching name, it returns the code of \c NXDOMAIN, /// and, if DNSSEC is requested, the NSEC RRset that proves the - /// non-existence. + /// non-existence if the zone is signed with NSEC; if it's signed with + /// NSEC3, an empty NSEC3 RRset (an RRset that doesn't have RDATA) + /// whose name is the closest encloser of the given name. /// - If there is a matching name but no RRset of the search type, it /// returns the code of \c NXRRSET, and, if DNSSEC is required, - /// the NSEC RRset for that name. + /// the NSEC RRset for that name if the zone is signed with NSEC; + /// if it's signed with NSEC3, an empty NSEC3 RRset whose name is the + /// given name. + /// - If there is no matching name but there is a matching wild card name, + /// but it doesn't have a requested type of RR, and if DNSSEC is + /// required, then it returns the code of \c WILDCARD_NXRRSET. + /// If the zone is signed with NSEC, it returns corresponding NSEC + /// (see the description of \c Result); if it's signed with NSEC3, + /// it returns an empty NSEC3 RRset whose name is the matching wildcard. /// - If there is a CNAME RR of the searched name but there is no /// RR of the searched type of the name (so this type is different from /// CNAME), it returns the code of \c CNAME and that CNAME RR. @@ -309,7 +319,11 @@ public: std::vector &target, const FindOptions options = FIND_DEFAULT) = 0; - /// TBD + /// A helper structure to represent the search result of \c findNSEC3(). + /// + /// The idea is similar to that of \c FindResult, but \c findNSEC3() has + /// special interface and semantics, we use a different structure to + /// represent the result. struct FindNSEC3Result { FindNSEC3Result(bool param_matched, isc::dns::ConstRRsetPtr param_closest_proof, @@ -317,15 +331,104 @@ public: matched(param_matched), closest_proof(param_closest_proof), next_proof(param_next_proof) {} + + /// true iff closest_proof is a matching NSEC3 const bool matched; + + /// Either the NSEC3 for the closest provable encloser of the given + /// name or NSEC3 that covers the name const isc::dns::ConstRRsetPtr closest_proof; + + /// When non NULL, NSEC3 for the next closer name. const isc::dns::ConstRRsetPtr next_proof; }; - /// TBD + /// Search the zone for the NSEC3 RR(s) that prove existence or non + /// existence of a give name. + /// + /// It searches the NSEC3 namespace of the zone (how that namespace is + /// implemented can vary in specific data source implementation) for NSEC3 + /// RRs that match or cover the NSEC3 hash value for the given name. + /// + /// If \c recursive is false, it will first look for the NSEC3 that has + /// a matching hash. If it doesn't exist, it identifies the covering NSEC3 + /// for the hash. In either case the search stops at that point and the + /// found NSEC3 RR(set) will be returned in the closest_proof member of + /// \c FindNSEC3Result. \c matched is true or false depending on + /// the found NSEC3 is a matched one or covering one. \c next_proof + /// is always NULL. + /// + /// If \c recursive is true, it will continue the search toward the zone + /// apex (origin name) until it finds a provable encloser, that is, + /// an ancestor of \c name that has a matching NSEC3. This is the closest + /// provable encloser of \c name as defined in RFC5155. In this case, + /// if the found encloser is not equal to \c name, the search should + /// have seen a covering NSEC3 for the immediate child of the found + /// encloser. That child name is the next closer name as defined in + /// RFC5155. In this case, this method returns the NSEC3 for the + /// closest encloser in \c closest_proof, and the NSEC3 for the next + /// closer name in \c next_proof of \c FindNSEC3Result. This set of + /// NSEC3 RRs provide the closest encloser proof as defined in RFC5155. + /// If, on the other hand, the found closest name is equal to \c name, + /// this method simply returns it in \c closest_proof. \c next_proof + /// is set to NULL. In all cases \c matched is set to true. + /// + /// When looking for NSEC3, this method retrieves NSEC3 parameters from + /// the corresponding zone to calculate hash values. Actual implementation + /// of how to do this will defer in different data sources. If the + /// NSEC3 parameters are not available \c DataSourceError exception + /// will be thrown. + /// + /// \note This implicitly means this method assumes the zone does not + /// have more than one set of parameters. This assumption should be + /// reasonable in actual deployment and will help simplify the interface + /// and implementation. But if there's a real need for supporting + /// multiple sets of parameters in a single zone, we will have to + /// extend this method so that, e.g., the caller can specify the parameter + /// set. + /// + /// This method takes an optional parameter \c known_encloser. If it's + /// non NULL, its owner name must be the closest encloser of \c name. + /// Its RR type is expected to be NSEC3, but other attributes other than + /// the owner name is not important for this method and will generally be + /// ignored. When this parameter is provided, the actual implementation + /// of the derived class can use it as a hint for identifying the closest + /// provable encloser (it can be helpful if \c name is known to be non + /// existent and possibly contains many labels below the closest encloser). + /// The underlying data source may also specialize the RRset to hold + /// some information specific to the data source implementation to allow + /// further optimization. Whether or not this parameter is non NULL, + /// the result of this method should be the same; this parameter is only + /// provided to possibly enable some implementation specific optimization. + /// When it's non NULL, however, its owner name must be equal to \c name + /// when \c recursive is false and must be a real (non equal) super domain + /// of \c name when \c recursive is true; otherwise + /// \c isc::InvalidParameter exception will be thrown. + /// + /// In general, this method expects the zone is properly signed with NSEC3 + /// RRs. Specifically, it assumes at least the apex node has a matching + /// NSEC3 RR. So the search must always succeed; if the assumption isn't + /// met, \c DataSourceError exception will be thrown. + /// + /// \exception InvalidParameter name is not a subdomain of the zone origin; + /// known_encloser does not meet the requirement (see above) + /// \exception DataSourceError The zone isn't properly signed with NSEC3 + /// (NSEC3 parameters cannot be found; no NSEC3s are available, etc). + /// \exception std::bad_alloc The underlying implementation involves + /// memory allocation and it fails + /// + /// \param name The name for which NSEC3 RRs are to be found. It must + /// be a subdomain of the zone. + /// \param recursive Whether or not search should continue until it finds + /// a provable encloser (see above). + /// \param known_encloser If non NULL, specifies the closest encloser + /// (may or may not be provable) of \c name via its owner name. + /// + /// \return The search result and whether or not the closest_proof is + /// a matching NSEC3, in the form of \c FindNSEC3Result object. virtual FindNSEC3Result findNSEC3(const isc::dns::Name& name, bool recursive, - const isc::dns::ConstRRsetPtr known_enclosure = + const isc::dns::ConstRRsetPtr known_encloser = isc::dns::ConstRRsetPtr()) = 0; /// \brief Get previous name in the zone