[1431] documentation update

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));

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
         ///

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
     ///

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<isc::dns::ConstRRsetPtr> &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