Cleanup for merge to master

Author: MelindaShore

.gitignore

@@ -2,6 +2,7 @@ build/
 _build/
 *~
 getdns.so
+getdns.cpython-34m.so
 *.save
 doc/_build/
 doc/_build/*

context.c

@@ -875,7 +875,7 @@ context_set_dns_transport_list(getdns_context *context, PyObject *py_value)
         long transport;
         if ((py_transport = PyList_GetItem(py_value, (Py_ssize_t)i)) != NULL)  {
             transport = PyLong_AsLong(py_transport);
-            if ((transport < GETDNS_TRANSPORT_UDP) || (transport > GETDNS_TRANSPORT_STARTTLS))  {
+            if ((transport < GETDNS_TRANSPORT_UDP) || (transport > GETDNS_TRANSPORT_TLS))  {
                 PyErr_SetString(getdns_error, GETDNS_RETURN_INVALID_PARAMETER_TEXT);
                 return -1;
             }
@@ -947,6 +947,19 @@ context_getattro(PyObject *self, PyObject *nameobj)
         }
     }
 
+    if (!strncmp(attrname, "suffix", strlen("suffix")))  {
+        PyObject *py_suffix;
+        getdns_list *suffix;
+
+        if ((ret = getdns_context_get_suffix(context, &suffix)) != GETDNS_RETURN_GOOD)  {
+            PyErr_SetString(getdns_error, getdns_get_errorstr_by_id(ret));
+            return NULL;
+        }
+        if ((py_suffix = glist_to_plist(suffix)) == NULL)
+            PyErr_SetString(getdns_error, GETDNS_RETURN_INVALID_PARAMETER_TEXT);
+        return py_suffix;
+    }
+
     api_info = getdns_context_get_api_information(context);
     if (!strncmp(attrname, "resolution_type", strlen("resolution_type")))  {
         uint32_t resolution_type;
@@ -1198,18 +1211,6 @@ context_getattro(PyObject *self, PyObject *nameobj)
             PyErr_SetString(getdns_error, GETDNS_RETURN_INVALID_PARAMETER_TEXT);
         return py_namespaces;
     }
-    if (!strncmp(attrname, "suffix", strlen("suffix")))  {
-        PyObject *py_suffix;
-        getdns_list *suffix;
-        if ((ret = getdns_dict_get_list(all_context, "suffix",
-                                        &suffix)) != GETDNS_RETURN_GOOD)  {
-            PyErr_SetString(getdns_error, getdns_get_errorstr_by_id(ret));
-            return NULL;
-        }
-        if ((py_suffix = glist_to_plist(suffix)) == NULL)
-            PyErr_SetString(getdns_error, GETDNS_RETURN_INVALID_PARAMETER_TEXT);
-        return py_suffix;
-    }
     if (!strncmp(attrname, "upstream_recursive_servers", strlen("upstream_recursive_servers")))  {
         PyObject *py_upstream_servers;
         getdns_list *upstream_list;

doc/conf.py

@@ -48,9 +48,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = 'v0.5.0'
+version = 'v0.6.0'
 # The full version, including alpha/beta/rc tags.
-release = 'v0.5.0'
+release = 'v0.6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/functions.rst

@@ -10,7 +10,8 @@
 getdns contexts
 ---------------
 
-This section describes the *getdns* Context object, as well as its
+This section describes the *getdns* Context object, as well
+as its
 as its methods and attributes.
 
 .. py:class:: Context([set_from_os])
@@ -22,12 +23,14 @@ as its methods and attributes.
    attributes described below.
 
    Context() takes one optional constructor argument.
-   ``set_from_os`` is an integer and may take the value either
+   ``set_from_os`` is an integer and may take the value
+   either
    0 or 1.  If 1, which most developers will want, getdns
    will populate the context with default values for the
    platform on which it's running.
 
-  The :class:`Context` class has the following public read/write attributes:
+  The :class:`Context` class has the following public
+  read/write attributes:
 
   .. py:attribute:: append_name
 
@@ -37,7 +40,8 @@ as its methods and attributes.
    ``getdns.APPEND_NAME_ALWAYS``,
    ``getdns.APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE``,
    ``getdns.APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE``,
-   or ``getdns.APPEND_NAME_NEVER``. This controls whether or not
+   or ``getdns.APPEND_NAME_NEVER``. This controls whether or
+   not
    to append the suffix given by :attr:`suffix`.
 
   .. py:attribute:: dns_root_servers
@@ -53,8 +57,10 @@ as its methods and attributes.
 
    For example, the addresses list could look like
 
-   >>> addrs = [ { 'address_data': '2001:7b8:206:1::4:53', 'address_type': 'IPv6' },
-   ...         { 'address_data': '65.22.9.1', 'address_type': 'IPv4' } ]
+   >>> addrs = [ { 'address_data': '2001:7b8:206:1::4:53',
+       'address_type': 'IPv6' },
+   ...         { 'address_data': '65.22.9.1',
+       'address_type': 'IPv4' } ]
    >>> mycontext.dns_root_servers = addrs
 
   .. py:attribute:: dns_transport_list
@@ -63,8 +69,7 @@ as its methods and attributes.
    lookups, ordered by preference (first choice as list
    element 0, second as list element 1, and so on).  The
    possible values are ``getdns.TRANSPORT_UDP``,
-   ``getdns.TRANSPORT_TCP``, ``getdns.TRANSPORT_TLS``,
-   and ``getdns.TRANSPORT_STARTTLS``. 
+   ``getdns.TRANSPORT_TCP``, and ``getdns.TRANSPORT_TLS``.
 
   .. py:attribute:: dnssec_allowed_skew
 
@@ -84,11 +89,13 @@ as its methods and attributes.
 
   .. py:attribute:: edns_do_bit
 
-   Its value must be an integer valued either 0 or 1.  The default is 0.
+   Its value must be an integer valued either 0 or 1.  The
+   default is 0.
 
   .. py:attribute:: edns_extended_rcode
 
-   Its value must be an integer between 0 and 255, inclusive.
+   Its value must be an integer between 0 and 255,
+   inclusive.
    The default is 0.
 
   .. py:attribute:: edns_maximum_udp_payload_size
@@ -98,15 +105,18 @@ as its methods and attributes.
 
   .. py:attribute:: edns_version
 
-   Its value must be an integer between 0 and 255, inclusive.
+   Its value must be an integer between 0 and 255,
+   inclusive.
    The default is 0.
 
   .. py:attribute:: follow_redirects
 
    Specifies whether or not DNS queries follow
-   redirects.  The value must be one of ``getdns.REDIRECTS_FOLLOW`` for
+   redirects.  The value must be one of
+   ``getdns.REDIRECTS_FOLLOW`` for
    normal following of redirects though CNAME and DNAME; or
-   ``getdns.REDIRECTS_DO_NOT_FOLLOW`` to cause any lookups that
+   ``getdns.REDIRECTS_DO_NOT_FOLLOW`` to cause any lookups
+   that
    would have gone through CNAME and DNAME to return the
    CNAME or DNAME, not the eventual target.
 
@@ -122,30 +132,36 @@ as its methods and attributes.
 
   .. py:attribute:: limit_outstanding_queries
 
-   Specifies `limit` (an integer value) on the number of outstanding DNS
+   Specifies `limit` (an integer value) on the number of
+   outstanding DNS
    queries. The API will block itself from sending more
    queries if it is about to exceed this value, and instead
    keep those queries in an internal queue. The a value of 0
-   indicates that the number of outstanding DNS queries is unlimited.
+   indicates that the number of outstanding DNS queries is
+   unlimited.
 
   .. py:attribute:: namespaces
 
    The `namespaces` attribute takes an ordered list of
-   namespaces that will be queried. (*Important: this context
+   namespaces that will be queried. (*Important: this
+   context
    setting is ignored for the getdns.general() function;
    it is used for the other
    functions.*) The allowed values are
-   ``getdns.NAMESPACE_DNS``, ``getdns.NAMESPACE_LOCALNAMES``, 
+   ``getdns.NAMESPACE_DNS``,
+   ``getdns.NAMESPACE_LOCALNAMES``, 
    ``getdns.NAMESPACE_NETBIOS``,
-   ``getdns.NAMESPACE_MDNS``, and ``getdns.NAMESPACE_NIS``. When a
+   ``getdns.NAMESPACE_MDNS``, and
+   ``getdns.NAMESPACE_NIS``. When a
    normal lookup is done, the API does the lookups in the
    order given and stops when it gets the first result; a
    different method with the same result would be to run the
    queries in parallel and return when it gets the first
    result. Because lookups might be done over different
    mechanisms because of the different namespaces, there can
    be information leakage that is similar to that seen with
-   POSIX *getaddrinfo()*. The default is determined by the OS.
+   POSIX *getaddrinfo()*. The default is determined by the
+   OS.
 
   .. py:attribute:: resolution_type
 
@@ -166,22 +182,28 @@ as its methods and attributes.
 
   .. py:attribute:: timeout
    
-   Its value must be an integer specifying a timeout for a query, expressed 
+   Its value must be an integer specifying a timeout for a
+   query, expressed 
    in milliseconds.
 
   .. py:attribute:: tls_authentication
 
    The mechanism to be used for authenticating the TLS
-   server when using a TLS transport.  May be ``getdns.AUTHENTICATION_HOSTNAME`` or
+   server when using a TLS transport.  May be
+   ``getdns.AUTHENTICATION_REQUIRED`` or
    ``getdns.AUTHENTICATION_NONE``.
+   (getdns.AUTHENTICATION_HOSTNAME remains as an alias for
+   getdns.AUTHENTICATION_REQUIRED but is deprecated and will
+   be removed in a future release)
 
   .. py:attribute:: tls_query_padding_blocksize
 
-   Optional padding blocksize for queries when using TLS.  Used to
+   Optional padding blocksize for queries when using TLS.
+   Used to
    increase the difficulty for observers to guess traffic
    content.
 
-  .. py:attribute:: upstream_recursive_servers
+   .. py:attribute:: upstream_recursive_servers
 
    A list of dicts defining where a stub resolver will send queries.
    Each dict in the list contains at least two names: address_type
@@ -193,11 +215,19 @@ as its methods and attributes.
    tsig_algorithm (a bindata) that is the name of the TSIG hash
    algorithm, and tsig_secret (a bindata) that is the TSIG key.
 
+   There is also now support for pinning an upstream's
+   certificate's public keys, with pinsets (when using TLS
+   for transport.  Add an element to the
+   upstream_recursive_server list entry, called
+   'tls_pubkey_pinset', which is a list of public key pins.
+   (See the example code in our examples directory).
+                    
   .. py:attribute:: version_string
 
     The libgetdns version, retrieved from the underlying
     getdns library.
-                    
+
+
   The :class:`Context` class includes public methods to execute a DNS query, as well as a
   method to return the entire set of context attributes as a Python dictionary.  :class:`Context`
   methods are described below:
@@ -253,7 +283,7 @@ as its methods and attributes.
 
    * ``version_string``
    * ``implementation_string``
-   * ``resolver_type``
+   * ``resolution_type``
    * ``all_context``
 
    ``all_context`` is a dictionary containing the following keys:
@@ -263,13 +293,13 @@ as its methods and attributes.
    * ``dnssec_allowed_skew``
    * ``edns_do_bit``
    * ``edns_extended_rcode``
-   * ``edns_maximum_udp_payload_size``
    * ``edns_version``
    * ``follow_redirects``
    * ``limit_outstanding_queries``
    * ``namespaces``
    * ``suffix``
    * ``timeout``
+   * ``tls_authentication``
    * ``upstream_recursive_servers``
 
   .. py:method:: get_supported_attributes()
@@ -301,13 +331,7 @@ The extensions currently supported by :py:mod:`getdns` are:
    * ``add_opt_parameters``
    * ``add_warning_for_bad_dns``
    * ``specify_class``
-   * ``return_call_debugging``
-
-Extensions that are optionally built (see above) include
-
-   * ``edns-cookies``
-
-``edns-cookies`` also takes the value ``getdns.EXTENSION_TRUE``.
+   * ``return_call_reporting``
 
 Extensions for DNSSEC
 ^^^^^^^^^^^^^^^^^^^^^
@@ -407,6 +431,9 @@ record sets the resource record appropriately, making the
 needed changes to the settings from the ``add_opt_parameters``
 extension.
 
+The ``client_subnet.py`` program in our example directory
+shows how to pack and send an OPT record.
+
 Getting Warnings for Responses that Violate the DNS Standard
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -444,9 +471,9 @@ Extensions relating to the API
 
 An application might want to see debugging information for
 queries, such as the length of time it takes for each query
-to return to the API.  Use the ``return_call_debugging``
+to return to the API.  Use the ``return_call_reporting``
 extension. The extension's value is set to
-``getdns.EXTENSION_TRUE`` to add the name ``call_debugging`` (a
+``getdns.EXTENSION_TRUE`` to add the name ``call_reporting`` (a
 list) to the top level of the ``response`` object. Each member
 of the list is a dict that represents one call made for the
 call to the API. Each member has the following names:
@@ -543,21 +570,3 @@ This is an example callback function:
             print 'Unknown error'
 
 
-Utility methods
----------------
-
-At the present time we support one utility method.
-
-.. py:method:: get_errorstr_by_id(id)
-
-   ``getdns.get_errorstr_by_id`` returns a string containing
-   text describing a getdns return code, helping to make
-   reporting errors to users a little easier.  For example:
-
-.. code-block:: python
-
-    if results.replies_full['status'] != getdns.RESPSTATUS_GOOD:
-        print(getdns.get_errorstr_by_id(id=results.replies_full['status'])
-        sys.exit(1)
-
-   

doc/index.rst

@@ -18,18 +18,18 @@ getdns implementation developed as a joint project between
 and `NLnet Labs <http://nlnetlabs.nl/>`_.
 
 We have tried to keep this interface as Pythonic as we can
-while staying true to the getdns architecture.  With this 
-release we are moving towards a design that is more consistent with
+while staying true to the getdns architecture, including
+trying to maintain consistency with
 Python object design.
 
 Dependencies
 ============
 
 This version of getdns has been built and tested against Python
-2.7.  We also expect these other prerequisites to be
+2.7 and Python 3.4.  We also expect these other prerequisites to be
 installed:
 
-* `libgetdns <http://getdnsapi.net/>`_, version 0.5.0 or later
+* `libgetdns <http://getdnsapi.net/>`_, version 0.9.0 or later
 * `libunbound
   <http://www.nlnetlabs.nl/projects/unbound/>`_, version
   1.4.16 or later
@@ -53,7 +53,8 @@ Building
 ========
 
 The code repository for getdns is available at:
-`<https://github.com/getdnsapi/getdns-python-bindings>`_.  If you are building from source you will
+`<https://github.com/getdnsapi/getdns-python-bindings>`_.  
+If you are building from source you will
 need the Python development package for Python 2.7.  On
 Linux systems this is typically something along the lines of
 "python-dev" or "python2.7-dev", available through your
@@ -214,13 +215,17 @@ Module-level attributes and methods
 
 .. py:method:: ulabel_to_alabel()
 
-   Converts a ulabel to an alabel.  Takes one argument (the ulabel)
+   Converts a ulabel to an alabel.  Takes one argument (the
+   ulabel)
 
 .. py:method:: alabel_to_ulabel()
 
    Converts an alabel to a ulabel.  Takes one argument (the
    alabel)
 
+.. py:method:: root_trust_anchor()
+
+   Returns the default root trust anchor for DNSSEC.
 
 Known issues
 ============