[1611] overall documentation update

src/lib/datasrc/zone.h

@@ -58,78 +58,8 @@ public:
     /// Note: the codes are tentative.  We may need more, or we may find
     /// some of them unnecessary as we implement more details.
     ///
-    /// Some are synonyms of others in terms of RCODE returned to user.
-    /// But they help the logic to decide if it should ask for a NSEC
-    /// that covers something or not (for example, in case of NXRRSET,
-    /// the directly returned NSEC is sufficient, but with wildcard one,
-    /// we need to add one proving there's no exact match and this is
-    /// actually the best wildcard we have). Data sources that don't
-    /// support DNSSEC don't need to distinguish them.
-    ///
-    /// In case of CNAME, if the CNAME is a wildcard (i.e., its owner name
-    /// starts with the label "*"), WILDCARD_CNAME will be returned instead
-    /// of CNAME.
-    ///
-    /// In case of NXDOMAIN, the returned NSEC covers the queried domain
-    /// that proves that the query name does not exist in the zone.  Note that
-    /// this does not necessarily prove it doesn't even match a wildcard
-    /// (even if the result of NXDOMAIN can only happen when there's no
-    /// matching wildcard either).  It is caller's responsibility to provide
-    /// a proof that there is no matching wildcard if that proof is necessary.
-    ///
-    /// Various variants of "no data" cases are complicated, when involves
-    /// DNSSEC and wildcard processing.  Referring to Section 3.1.3 of
-    /// RFC4035, we need to consider the following cases:
-    /// -# (Normal) no data: there is a matching non-wildcard name with a
-    ///    different RR type.  This is the "No Data" case of the RFC.
-    /// -# (Normal) empty non terminal: there is no matching (exact or
-    ///    wildcard) name, but there is a subdomain with an RR of the query
-    ///    name.  This is one case of "Name Error" of the RFC.
-    /// -# Wildcard empty non terminal: similar to 2a, but the empty name
-    ///    is a wildcard, and matches the query name by wildcard expansion.
-    ///    This is a special case of "Name Error" of the RFC.
-    /// -# Wildcard no data: there is no exact match name, but there is a
-    ///    wildcard name that matches the query name with a different type
-    ///    of RR.  This is the "Wildcard No Data" case of the RFC.
-    ///
-    /// In any case, \c find() will result in \c NXRRSET with no RRset
-    /// unless the \c FIND_DNSSEC option is specified.  The rest of the
-    /// discussion only applies to the case where this option is specified.
-    ///
-    /// In case 1, \c find() will result in NXRRSET, and return NSEC of the
-    /// matching name.
-    ///
-    /// In case 2, \c find() will result in NXRRSET, and return NSEC for the
-    /// interval where the empty nonterminal lives. The end of the interval
-    /// is the subdomain causing existence of the empty nonterminal (if
-    /// there's sub.x.example.com, and no record in x.example.com, then
-    /// x.example.com exists implicitly - is the empty nonterminal and
-    /// sub.x.example.com is the subdomain causing it).  Note that this NSEC
-    /// proves not only the existence of empty non terminal name but also
-    /// the non existence of possibly matching wildcard name, because
-    /// there can be no better wildcard match than the exact matching empty
-    /// name.
-    ///
-    /// In case 3, \c find() will result in WILDCARD_NXRRSET, and return NSEC
-    /// for the interval where the wildcard empty nonterminal lives.
-    /// Cases 2 and 3 are especially complicated and confusing.  See the
-    /// examples below.
-    ///
-    /// In case 4, \c find() will result in WILDCARD_NXRRSET, and return
-    /// NSEC of the matching wildcard name.
-    ///
-    /// Examples: if zone "example.com" has the following record:
-    /// \code
-    /// a.example.com. NSEC a.b.example.com.
-    /// \endcode
-    /// a call to \c find() for "b.example.com." with the FIND_DNSSEC option
-    /// will result in NXRRSET, and this NSEC will be returned.
-    /// Likewise, if zone "example.org" has the following record,
-    /// \code
-    /// a.example.org. NSEC x.*.b.example.org.
-    /// \endcode
-    /// a call to \c find() for "y.b.example.org" with FIND_DNSSEC will
-    /// result in NXRRSET_NXRRSET, and this NSEC will be returned.
+    /// See the description of \c find() for further details of how
+    /// these results should be interpreted.
     enum Result {
         SUCCESS,                ///< An exact match is found.
         DELEGATION,             ///< The search encounters a zone cut.
@@ -196,7 +126,7 @@ public:
 
         /// Return true when the underlying zone is signed with NSEC.
         ///
-        /// The \c find() implementation allow this to return false if
+        /// The \c find() implementation allows this to return false if
         /// \c FIND_DNSSEC isn't specified regardless of whether the zone
         /// is signed or which of NSEC/NSEC3 is used.
         ///
@@ -209,7 +139,7 @@ public:
 
         /// Return true when the underlying zone is signed with NSEC3.
         ///
-        /// The \c find() implementation allow this to return false if
+        /// The \c find() implementation allows this to return false if
         /// \c FIND_DNSSEC isn't specified regardless of whether the zone
         /// is signed or which of NSEC/NSEC3 is used.
         bool isNSEC3Signed() const {
@@ -274,17 +204,10 @@ public:
     ///
     /// - If the search name belongs under a zone cut, it returns the code
     ///   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 if the zone is signed with NSEC.
+    /// - If there is no matching name, it returns the code of \c NXDOMAIN.
     /// - 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 if the zone is signed with NSEC.
-    /// - 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).
+    ///   returns the code of \c NXRRSET.  This case includes the search name
+    ///   matches an empty node of the zone.
     /// - 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.
@@ -293,6 +216,16 @@ public:
     /// - If the search name matches a delegation point of DNAME, it returns
     ///   the code of \c DNAME and that DNAME RR.
     ///
+    /// No RRset will be returned in the \c NXDOMAIN and \c NXRRSET cases
+    /// (\c rrset member of \c FindResult will be NULL), unless DNSSEC data
+    /// are required.  See below for the cases with DNSSEC.
+    ///
+    /// The returned \c FindResult object can also provide supplemental
+    /// information about the search result via its methods returning a
+    /// boolean value.  Such information may be useful for the caller if
+    /// the caller wants to collect additional DNSSEC proofs based on the
+    /// search result.
+    ///
     /// The \c options parameter specifies customized behavior of the search.
     /// Their semantics is as follows (they are or bit-field):
     ///
@@ -322,6 +255,86 @@ public:
     /// future version.  In any case applications shouldn't call this method
     /// for an out-of-zone name.
     ///
+    /// <b>DNSSEC considerations:</b>
+    /// The result when DNSSEC data are required can be very complicated,
+    /// especially if it involves negative result or wildcard match.
+    /// Specifically, if an application calls this method for DNS query
+    /// processing with DNSSEC data, and if the search result code is
+    /// either \c NXDOMAIN or \c NXRRRSET, and/or \c isWildcard() returns
+    /// true, then the application will need to find additional NSEC or
+    /// NSEC3 records for supplemental proofs.  This method helps the
+    /// application for such post search processing.
+    ///
+    /// First, it tells the application whether the zone is signed with
+    /// NSEC or NSEC3 via the \c isNSEC(3)Signed() method.  Any sanely signed
+    /// zone should be signed with either (and only one) of these two types
+    /// of RRs; however, the application should expect that the zone could
+    /// be broken and these methods could both return false.  But this method
+    /// should ensure that not both of these methods return true.
+    ///
+    /// In case it's signed with NSEC3, there is no further information
+    /// returned from this method.
+    ///
+    /// In case it's signed with NSEC, this method will possibly return
+    /// a related NSEC RRset in the \c rrset member of \c FindResult.
+    /// What kind of NSEC is returned depends on the result code
+    /// (\c NXDOMAIN or \c NXRRSET) and on whether it's a wildcard match:
+    ///
+    /// - In case of NXDOMAIN, the returned NSEC covers the queried domain
+    ///   that proves that the query name does not exist in the zone.  Note
+    ///   that this does not necessarily prove it doesn't even match a
+    ///   wildcard (even if the result of NXDOMAIN can only happen when
+    ///   there's no matching wildcard either).  It is caller's
+    ///   responsibility to provide a proof that there is no matching
+    ///   wildcard if that proof is necessary.
+    /// - In case of NXRRSET, we need to consider the following cases
+    ///   referring to Section 3.1.3 of RFC4035:
+    ///
+    /// -# (Normal) no data: there is a matching non-wildcard name with a
+    ///    different RR type.  This is the "No Data" case of the RFC.
+    /// -# (Normal) empty non terminal: there is no matching (exact or
+    ///    wildcard) name, but there is a subdomain with an RR of the query
+    ///    name.  This is one case of "Name Error" of the RFC.
+    /// -# Wildcard empty non terminal: similar to 2a, but the empty name
+    ///    is a wildcard, and matches the query name by wildcard expansion.
+    ///    This is a special case of "Name Error" of the RFC.
+    /// -# Wildcard no data: there is no exact match name, but there is a
+    ///    wildcard name that matches the query name with a different type
+    ///    of RR.  This is the "Wildcard No Data" case of the RFC.
+    ///
+    /// In case 1, \c find() returns NSEC of the matching name.
+    ///
+    /// In case 2, \c find() will return NSEC for the interval where the
+    /// empty nonterminal lives. The end of the interval is the subdomain
+    /// causing existence of the empty nonterminal (if there's
+    /// sub.x.example.com, and no record in x.example.com, then
+    /// x.example.com exists implicitly - is the empty nonterminal and
+    /// sub.x.example.com is the subdomain causing it).  Note that this NSEC
+    /// proves not only the existence of empty non terminal name but also
+    /// the non existence of possibly matching wildcard name, because
+    /// there can be no better wildcard match than the exact matching empty
+    /// name.
+    ///
+    /// In case 3, \c find() will return NSEC for the interval where the
+    /// wildcard empty nonterminal lives.   Cases 2 and 3 are especially
+    /// complicated and confusing.  See the examples below.
+    ///
+    /// In case 4, \c find() will return NSEC of the matching wildcard name.
+    ///
+    /// Examples: if zone "example.com" has the following record:
+    /// \code
+    /// a.example.com. NSEC a.b.example.com.
+    /// \endcode
+    /// a call to \c find() for "b.example.com." with the FIND_DNSSEC option
+    /// will result in NXRRSET, and this NSEC will be returned.
+    /// Likewise, if zone "example.org" has the following record,
+    /// \code
+    /// a.example.org. NSEC x.*.b.example.org.
+    /// \endcode
+    /// a call to \c find() for "y.b.example.org" with FIND_DNSSEC will
+    /// result in NXRRSET and this NSEC; \c isWildcard() on the returned
+    /// \c FindResult object will return true.
+    ///
     /// \exception std::bad_alloc Memory allocation such as for constructing
     ///  the resulting RRset fails
     /// \exception DataSourceError Derived class specific exception, e.g.
@@ -346,12 +359,12 @@ public:
     ///
     /// This function works almost exactly in the same way as the find one. The
     /// only difference is, when the lookup is successful (eg. the code is
-    /// SUCCESS or WILDCARD), all the RRsets residing in the named node are
+    /// SUCCESS), all the RRsets residing in the named node are
     /// copied into the \c target parameter and the rrset member of the result
     /// is NULL. All the other (unsuccessful) cases are handled the same,
-    /// including returning delegations, NSEC/NSEC3 proofs, etc. The options
-    /// parameter works the same way and it should conform to the same exception
-    /// restrictions.
+    /// including returning delegations, NSEC/NSEC3 availability and NSEC
+    /// proofs, wildcard information etc. The options parameter works the
+    /// same way and it should conform to the same exception restrictions.
     ///
     /// \param name \see find, parameter name
     /// \param target the successfull result is returned through this

src/lib/python/isc/datasrc/finder_inc.cc

@@ -47,7 +47,7 @@ Return the RR class of the zone.\n\
 // - NULL->None
 // - exceptions
 const char* const ZoneFinder_find_doc = "\
-find(name, type, options=FIND_DEFAULT) -> (integer, RRset)\n\
+find(name, type, options=FIND_DEFAULT) -> (integer, RRset, flags)\n\
 \n\
 Search the zone for a given pair of domain name and RR type.\n\
 \n\
@@ -58,12 +58,10 @@ answer for the search key. Specifically,\n\
 \n\
 - If the search name belongs under a zone cut, it returns the code of\n\
   DELEGATION and the NS RRset at the zone cut.\n\
-- If there is no matching name, it returns the code of NXDOMAIN, and,\n\
-  if DNSSEC is requested, the NSEC RRset that proves the non-\n\
-  existence.\n\
+- If there is no matching name, it returns the code of NXDOMAIN.\n\
 - If there is a matching name but no RRset of the search type, it\n\
-  returns the code of NXRRSET, and, if DNSSEC is required, the NSEC\n\
-  RRset for that name.\n\
+  returns the code of NXRRSET. This case includes the search name\n\
+  matches an empty node of the zone.\n\
 - If there is a CNAME RR of the searched name but there is no RR of\n\
   the searched type of the name (so this type is different from\n\
   CNAME), it returns the code of CNAME and that CNAME RR. Note that if\n\
@@ -72,6 +70,16 @@ answer for the search key. Specifically,\n\
 - If the search name matches a delegation point of DNAME, it returns\n\
   the code of DNAME and that DNAME RR.\n\
 \n\
+No RRset will be returned in the NXDOMAIN and NXRRSET cases (rrset\n\
+member of FindResult will be None), unless DNSSEC data are required.\n\
+See below for the cases with DNSSEC.\n\
+\n\
+The returned FindResult object can also provide supplemental\n\
+information about the search result via its methods returning a\n\
+boolean value. Such information may be useful for the caller if the\n\
+caller wants to collect additional DNSSEC proofs based on the search\n\
+result.\n\
+\n\
 The options parameter specifies customized behavior of the search.\n\
 Their semantics is as follows (they are or bit-field):\n\
 \n\
@@ -96,6 +104,91 @@ should be equal to or a subdomain of the zone origin. Otherwise this\n\
 method will return NXDOMAIN with an empty RRset. But such a case\n\
 should rather be considered a caller's bug.\n\
 \n\
+Note: For this reason it's probably better to throw an exception than\n\
+returning NXDOMAIN. This point should be revisited in a near future\n\
+version. In any case applications shouldn't call this method for an\n\
+out-of-zone name.\n\
+\n\
+DNSSEC considerations: The result when DNSSEC data are required can be\n\
+very complicated, especially if it involves negative result or\n\
+wildcard match. Specifically, if an application calls this method for\n\
+DNS query processing with DNSSEC data, and if the search result code\n\
+is either NXDOMAIN or NXRRRSET, and/or RESULT_WILDCARD\n\
+flag is set in the returned flags value,\n\
+then the application will need to find additional NSEC or NSEC3\n\
+records for supplemental proofs. This method helps the application for\n\
+such post search processing.\n\
+\n\
+First, it tells the application whether the zone is signed with NSEC\n\
+or NSEC3 via the RESULT_NSEC_SIGNED and RESULT_NSEC3_SIGNED flags\n\
+in the returned flags value. Any sanely signed zone\n\
+should be signed with either (and only one) of these two types of RRs;\n\
+however, the application should expect that the zone could be broken\n\
+and these methods could both return false. But this method should\n\
+ensure that not both of these methods return true.\n\
+\n\
+In case it's signed with NSEC3, there is no further information\n\
+returned from this method.\n\
+\n\
+In case it's signed with NSEC, this method will possibly return a\n\
+related NSEC RRset in the rrset member of FindResult. What kind of\n\
+NSEC is returned depends on the result code (NXDOMAIN or NXRRSET) and\n\
+on whether it's a wildcard match:\n\
+\n\
+- In case of NXDOMAIN, the returned NSEC covers the queried domain\n\
+  that proves that the query name does not exist in the zone. Note\n\
+  that this does not necessarily prove it doesn't even match a\n\
+  wildcard (even if the result of NXDOMAIN can only happen when\n\
+  there's no matching wildcard either). It is caller's responsibility\n\
+  to provide a proof that there is no matching wildcard if that proof\n\
+  is necessary.\n\
+- In case of NXRRSET, we need to consider the following cases\n\
+  referring to Section 3.1.3 of RFC4035:\n\
+\n\
+1. (Normal) no data: there is a matching non-wildcard name with a\n\
+   different RR type. This is the \"No Data\" case of the RFC.\n\
+2. (Normal) empty non terminal: there is no matching (exact or\n\
+   wildcard) name, but there is a subdomain with an RR of the query\n\
+   name. This is one case of \"Name Error\" of the RFC.\n\
+3. Wildcard empty non terminal: similar to 2, but the empty name is\n\
+   a wildcard, and matches the query name by wildcard expansion. This\n\
+   is a special case of \"Name Error\" of the RFC.\n\
+4. Wildcard no data: there is no exact match name, but there is a\n\
+   wildcard name that matches the query name with a different type of RR.\n\
+   This is the \"Wildcard No Data\" case of the RFC.\n\
+\n\
+In case 1, find() returns NSEC of the matching name.\n\
+\n\
+In case 2, find() will return NSEC for the interval where the empty\n\
+nonterminal lives. The end of the interval is the subdomain causing\n\
+existence of the empty nonterminal (if there's sub.x.example.com, and\n\
+no record in x.example.com, then x.example.com exists implicitly - is\n\
+the empty nonterminal and sub.x.example.com is the subdomain causing\n\
+it). Note that this NSEC proves not only the existence of empty non\n\
+terminal name but also the non existence of possibly matching wildcard\n\
+name, because there can be no better wildcard match than the exact\n\
+matching empty name.\n\
+\n\
+In case 3, find() will return NSEC for the interval where the wildcard\n\
+empty nonterminal lives. Cases 2 and 3 are especially complicated and\n\
+confusing. See the examples below.\n\
+\n\
+In case 4, find() will return NSEC of the matching wildcard name.\n\
+\n\
+Examples: if zone \"example.com\" has the following record:\n\
+\n\
+a.example.com. NSEC a.b.example.com.\n\
+\n\
+a call to  find() for \"b.example.com.\" with the FIND_DNSSEC option\n\
+will result in NXRRSET, and this NSEC will be returned.\n\
+Likewise, if zone \"example.org\" has the following record,\n\
+\n\
+a.example.org. NSEC x.*.b.example.org.\n\
+\n\
+a call to  find() for \"y.b.example.org\" with FIND_DNSSEC will\n\
+result in NXRRSET and this NSEC;  isWildcard() on the returned\n\
+FindResult object will return true.\n\
+\n\
 This method raises an isc.datasrc.Error exception if there is an\n\
 internal error in the datasource.\n\
 \n\
@@ -104,28 +197,34 @@ Parameters:\n\
   type       The RR type to be searched for.\n\
   options    The search options.\n\
 \n\
-Return Value(s): A tuple of a result code (integer) and an RRset object\n\
-enclosing the search result (see above).\n\
+Return Value(s): A tuple of a result code (integer), an RRset object\n\
+and supplemental integer.\n\
 ";
 
-const char* const ZoneFinder_find_all_doc = "\
-find_all(isc.dns.Name, options=FIND_DEFAULT) -> (integer, RRset) | (integer, [RRset])\
+const char* const ZoneFinder_findAll_doc = "\
+find_all(isc.dns.Name, options=FIND_DEFAULT) ->\n\
+   (integer, RRset, flags) | (integer, [RRset], flags)\
 \n\
-This acts mostly the same as the find method. The main difference is,\n\
-when the lookup is successful (eg. the first part of the result is either\n\
-SUCCESS or WILDCARD), the second part is list of all RRsets in the given name\n\
-instead of a single RRset as in case of find.\n\
+Finds all RRsets in the given name.\n\
 \n\
-This method raises an isc.datasrc.Error exception if there is an\n\
-internal error in the datasource.\n\
+This function works almost exactly in the same way as the find one.\n\
+The only difference is, when the lookup is successful (eg. the code is\n\
+SUCCESS), all the RRsets residing in the named node are returned in the\n\
+second element of the returned tuple. All\n\
+the other (unsuccessful) cases are handled the same, including\n\
+returning delegations, NSEC/NSEC3 availability and NSEC proofs,\n\
+wildcard information etc. The options parameter works the same way and\n\
+it should conform to the same exception restrictions.\n\
 \n\
 Parameters:\n\
-  name       The domain name to be searched for.\n\
+  target     the successfull result is returned through this\n\
   options    The search options.\n\
 \n\
-Return Value(s): A tuple of a result code (integer) and an either RRset object,\n\
-for cases where the result is some kind of delegation, CNAME or similar, or list\n\
-of RRset objects, containing all the results.\n\
+Return Value(s): A tuple of a result code (integer), an either\n\
+RRset object or a list of RRsets, and flags (integer).\n\
+In the second element a single RRset is returned for cases where the\n\
+result is some kind of delegation, CNAME or similar; in other cases\n\
+a list of RRsets is returned, containing all the results.\n\
 ";
 
 const char* const ZoneFinder_find_previous_name_doc = "\

src/lib/python/isc/datasrc/finder_python.cc

@@ -286,7 +286,7 @@ PyMethodDef ZoneFinder_methods[] = {
        ZoneFinder_getOrigin_doc },
     { "get_class", ZoneFinder_getClass, METH_NOARGS, ZoneFinder_getClass_doc },
     { "find", ZoneFinder_find, METH_VARARGS, ZoneFinder_find_doc },
-    { "find_all", ZoneFinder_find_all, METH_VARARGS, ZoneFinder_find_all_doc },
+    { "find_all", ZoneFinder_find_all, METH_VARARGS, ZoneFinder_findAll_doc },
     { "find_previous_name", ZoneFinder_findPreviousName, METH_VARARGS,
       ZoneFinder_find_previous_name_doc },
     { NULL, NULL, 0, NULL }

src/lib/python/isc/datasrc/updater_python.cc

@@ -217,7 +217,7 @@ PyMethodDef ZoneUpdater_methods[] = {
       METH_NOARGS, ZoneFinder_getClass_doc },
     { "find", ZoneUpdater_find, METH_VARARGS, ZoneFinder_find_doc },
     { "find_all", ZoneUpdater_find_all, METH_VARARGS,
-      ZoneFinder_find_all_doc },
+      ZoneFinder_findAll_doc },
     { NULL, NULL, 0, NULL }
 };