vendor/ldns/1.6.13

10 files changed, 290 insertions, 0 deletions

diff --git a/contrib/python/docs/source/examples/example1.rst b/contrib/python/docs/source/examples/example1.rst
new file mode 100644
index 000000000000..b44141759f5a
--- /dev/null
+++ b/contrib/python/docs/source/examples/example1.rst
@@ -0,0 +1,68 @@
+Resolving the MX records
+==============================
+
+This basic example shows how to create a resolver which asks for MX records which contain the information about mail servers.
+
+::
+
+	#!/usr/bin/python
+	#
+	# MX is a small program that prints out the mx records for a particular domain
+	#
+	import ldns
+	
+	resolver = ldns.ldns_resolver.new_frm_file("/etc/resolv.conf")
+
+	dname = ldns.ldns_dname("nic.cz")
+	
+	pkt = resolver.query(dname, ldns.LDNS_RR_TYPE_MX, ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
+	if (pkt):
+		mx = pkt.rr_list_by_type(ldns.LDNS_RR_TYPE_MX, ldns.LDNS_SECTION_ANSWER)
+		if (mx):
+			mx.sort()
+			print mx
+
+Resolving step by step
+------------------------
+
+First of all we import :mod:`ldns` extension module which make LDNS functions and classes accessible::
+
+	import ldns
+
+If importing fails, it means that Python cannot find the module or ldns library.
+
+Then we create the resolver by :meth:`ldns.ldns_resolver.new_frm_file` constructor ::
+
+	resolver = ldns.ldns_resolver.new_frm_file("/etc/resolv.conf")
+
+and domain name variable dname::
+
+	dname = ldns.ldns_dname("nic.cz")
+
+To create a resolver you may also use::
+
+	resolver = ldns.ldns_resolver.new_frm_file(None)
+
+which behaves in the same manner as the command above.
+
+In the third step we tell the resolver to query for our domain, type MX, of class IN::
+	
+	pkt = resolver.query(dname, ldns.LDNS_RR_TYPE_MX, ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
+
+The function should return a packet if everything goes well and this packet will contain resource records we asked for. 
+Note that there exists a simplier way. Instead of using a dname variable, we can use a string which will be automatically converted.
+::
+
+	pkt = resolver.query("fit.vutbr.cz", ldns.LDNS_RR_TYPE_MX, ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
+
+Now, we test whether the resolver returns a packet and then get all RRs of type MX from the answer packet and store them in list mx::
+
+	if (pkt):
+		mx = pkt.rr_list_by_type(ldns.LDNS_RR_TYPE_MX, ldns.LDNS_SECTION_ANSWER)
+
+If this list is not empty, we sort and print the content to stdout::
+
+	if (mx):
+		mx.sort()
+		print mx
+
diff --git a/contrib/python/docs/source/examples/example2.py b/contrib/python/docs/source/examples/example2.py
new file mode 100755
index 000000000000..7dabb9179025
--- /dev/null
+++ b/contrib/python/docs/source/examples/example2.py
@@ -0,0 +1,45 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+import ldns
+import sys
+
+debug = True
+
+# Check args
+argc = len(sys.argv)
+name = "www.nic.cz"
+if argc < 2:
+   print("Usage:", sys.argv[0], "domain [resolver_addr]")
+   sys.exit(1)
+else:
+   name = sys.argv[1]
+
+# Create resolver
+resolver = ldns.ldns_resolver.new_frm_file("/etc/resolv.conf")
+resolver.set_dnssec(True)
+
+# Custom resolver
+if argc > 2:
+   # Clear previous nameservers
+   ns = resolver.pop_nameserver()
+   while ns != None:
+      ns = resolver.pop_nameserver()
+   ip = ldns.ldns_rdf.new_frm_str(sys.argv[2], ldns.LDNS_RDF_TYPE_A)
+   resolver.push_nameserver(ip)
+
+# Resolve DNS name
+pkt = resolver.query(name, ldns.LDNS_RR_TYPE_A, ldns.LDNS_RR_CLASS_IN)
+if pkt and pkt.answer():
+
+   # Debug
+   if debug:
+      print("NS returned:", pkt.get_rcode(), "(AA: %d AD: %d)" % ( pkt.ad(), pkt.ad() ))
+
+   # SERVFAIL indicated bogus name
+   if pkt.get_rcode() is ldns.LDNS_RCODE_SERVFAIL:
+      print(name, "is bogus")
+
+   # Check AD (Authenticated) bit
+   if pkt.get_rcode() is ldns.LDNS_RCODE_NOERROR:
+      if pkt.ad(): print(name, "is secure")
+      else:        print(name, "is insecure")
diff --git a/contrib/python/docs/source/examples/example2.rst b/contrib/python/docs/source/examples/example2.rst
new file mode 100644
index 000000000000..b1734386e7de
--- /dev/null
+++ b/contrib/python/docs/source/examples/example2.rst
@@ -0,0 +1,100 @@
+.. _ex_dnssec:
+
+Querying DNS-SEC validators
+===========================
+
+This basic example shows how to query validating resolver and
+evaluate answer.
+
+Resolving step by step
+------------------------
+
+For DNS queries, we need to initialize ldns resolver (covered in previous example).
+   
+::
+   
+   # Create resolver
+   resolver = ldns.ldns_resolver.new_frm_file("/etc/resolv.conf")
+   resolver.set_dnssec(True)
+
+   # Custom resolver
+   if argc > 2:
+      # Clear previous nameservers
+      ns = resolver.pop_nameserver()
+      while ns != None:
+         ns = resolver.pop_nameserver()
+      ip = ldns.ldns_rdf.new_frm_str(sys.argv[2], ldns.LDNS_RDF_TYPE_A)
+      resolver.push_nameserver(ip)
+
+Note the second line :meth:`resolver.set_dnssec`, which enables DNSSEC OK bit
+in queries in order to get meaningful results.
+
+As we have resolver initialized, we can start querying for domain names :
+
+::
+   
+   # Resolve DNS name
+   pkt = resolver.query(name, ldns.LDNS_RR_TYPE_A, ldns.LDNS_RR_CLASS_IN)
+   if pkt and pkt.answer():
+
+Now we evaluate result, where two flags are crucial :
+
+ * Return code
+ * AD flag (authenticated)
+
+When return code is `SERVFAIL`, it means that validating resolver marked requested
+name as **bogus** (or bad configuration).
+
+**AD** flag is set if domain name is authenticated **(secure)** or false if
+it's insecure.
+
+Complete source code
+--------------------
+
+ .. literalinclude:: ../../../examples/ldns-dnssec.py
+    :language: python
+
+
+Testing
+-------
+
+In order to get meaningful results, you have to enter IP address of validating
+resolver or setup your own (see howto).
+
+Execute `./example2.py` with options `domain name` and `resolver IP`,
+example:
+
+::
+
+   user@localhost# ./example2.py www.dnssec.cz 127.0.0.1 # Secure (Configured Unbound running on localhost)
+   user@localhost# ./example2.py www.rhybar.cz 127.0.0.1 # Bogus
+
+Howto setup Unbound as validating resolver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install Unbound according to instructions.
+Modify following options in `unbound.conf` (located in `/etc` or `/usr/local/etc`)/
+
+
+Uncomment `module-config` and set `validator` before iterator.
+
+::
+
+   module-config: "validator iterator"
+
+Download DLV keys and update path in `unbound.conf`::
+
+   # DLV keys
+   # Download from http://ftp.isc.org/www/dlv/dlv.isc.org.key
+   dlv-anchor-file: "/usr/local/etc/unbound/dlv.isc.org.key"
+
+Update trusted keys (`.cz` for example)::
+
+   # Trusted keys
+   # For current key, see www.dnssec.cz
+   trusted-keys-file: "/usr/local/etc/unbound/trusted.key"
+   
+Now you should have well configured Unbound, so run it::
+
+   user@localhost# unbound -dv
+   
diff --git a/contrib/python/docs/source/examples/example3.rst b/contrib/python/docs/source/examples/example3.rst
new file mode 100644
index 000000000000..91f5e9d1448c
--- /dev/null
+++ b/contrib/python/docs/source/examples/example3.rst
@@ -0,0 +1,7 @@
+High-level functions
+===========================
+
+This basic example shows how to get name by addr and vice versa.
+
+.. literalinclude:: ../../../examples/ldns-higher.py
+   :language: python
diff --git a/contrib/python/docs/source/examples/example4.rst b/contrib/python/docs/source/examples/example4.rst
new file mode 100644
index 000000000000..2f41f76bde71
--- /dev/null
+++ b/contrib/python/docs/source/examples/example4.rst
@@ -0,0 +1,7 @@
+AXFR client with IDN support
+===============================
+
+This example shows how to get AXFR working and how to get involved Internationalized Domain Names (IDN)
+
+.. literalinclude:: ../../../examples/ldns-axfr.py
+   :language: python
diff --git a/contrib/python/docs/source/examples/example5.rst b/contrib/python/docs/source/examples/example5.rst
new file mode 100644
index 000000000000..787c169265d7
--- /dev/null
+++ b/contrib/python/docs/source/examples/example5.rst
@@ -0,0 +1,14 @@
+Examine the results
+===============================
+
+This example shows how to go through the obtained results
+
+.. literalinclude:: ../../../examples/ldns-mx2.py
+   :language: python
+
+This snippet of code prints::
+
+   nic.cz.   1761   IN   MX   20 mx.cznic.org.
+   nic.cz.   1761   IN   MX   10 mail.nic.cz.
+   nic.cz.   1761   IN   MX   15 mail4.nic.cz.
+
diff --git a/contrib/python/docs/source/examples/example6.rst b/contrib/python/docs/source/examples/example6.rst
new file mode 100644
index 000000000000..d0fd68998017
--- /dev/null
+++ b/contrib/python/docs/source/examples/example6.rst
@@ -0,0 +1,12 @@
+Read zone file
+===============================
+
+This example shows how to read the content of a zone file
+
+.. literalinclude:: ../../../examples/ldns-zone.py
+   :language: python
+
+Zone file ``zone.txt``:
+
+.. literalinclude:: ../../../examples/zone.txt
+
diff --git a/contrib/python/docs/source/examples/example7.rst b/contrib/python/docs/source/examples/example7.rst
new file mode 100644
index 000000000000..3e3e2dc22e52
--- /dev/null
+++ b/contrib/python/docs/source/examples/example7.rst
@@ -0,0 +1,8 @@
+Generate public/private key pair
+=======================================
+
+This example shows how generate keys for DNSSEC (i.e. for signing a zone file according DNSSECbis).
+
+.. literalinclude:: ../../../examples/ldns-keygen.py
+   :language: python
+
diff --git a/contrib/python/docs/source/examples/example8.rst b/contrib/python/docs/source/examples/example8.rst
new file mode 100644
index 000000000000..6fc550a86045
--- /dev/null
+++ b/contrib/python/docs/source/examples/example8.rst
@@ -0,0 +1,17 @@
+Signing of a zone file
+===============================
+
+This example shows how to sign the content of the given zone file
+
+.. literalinclude:: ../../../examples/ldns-signzone.py
+   :language: python
+
+In order to be able sign a zone file, you have to generate a key-pair using ``ldns-keygen.py``. Don't forget to modify tag number.
+
+Signing consists of three steps
+
+1. In the first step, the content of a zone file is readed and parsed. This can be done using :class:`ldns.ldns_zone` class.
+
+2. In the second step, the private and public key is readed and public key is inserted into zone (as DNSKEY). 
+
+3. In the last step, the DNSSEC zone instace is created and all the RRs from zone file are copied here. Then, all the records are signed using :meth:`ldns.ldns_zone.sign` method. If the signing was successfull, the content of DNSSEC zone is written to a file.
diff --git a/contrib/python/docs/source/examples/index.rst b/contrib/python/docs/source/examples/index.rst
new file mode 100644
index 000000000000..8f7f381c3294
--- /dev/null
+++ b/contrib/python/docs/source/examples/index.rst
@@ -0,0 +1,12 @@
+Tutorials
+==============================
+
+Here you can find a set of simple applications which utilizes the ldns library in Python environment. 
+
+`Tutorials`
+
+.. toctree::
+	:maxdepth: 1
+	:glob:
+
+	example*