path: root/programs/lwdnsq/lwdnsq.xml.in

<?xml version='1.0'?> <!-- -*- docbook -*- -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article>
  <articleinfo>
    <title>lwdnsq</title>

    <author>
      <firstname>Michael</firstname>
      <surname>Richardson</surname>
      <affiliation>
         <address><email>mcr@sandelman.ottawa.on.ca</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>2003</year>
      <holder>Michael Richardson</holder>
    </copyright>
  </articleinfo>

  <section>
    <title>Reference</title>

<refentry id="ipsec_lwdnsq">

<refmeta>
<refentrytitle>ipsec lwdnsq</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>

<refnamediv>
<refname>lwdnsq</refname>
<refpurpose>lookup items in DNS to help pluto (and others)</refpurpose>
</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>
  <command>ipsec lwdnsq</command>
  <arg choice="opt"><option>--prompt</option></arg>
  <arg choice="opt"><option>--serial</option></arg>
</cmdsynopsis>

<cmdsynopsis>
  <command>ipsec lwdnsq</command>
  <arg choice="opt"><option>--help</option></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The
<command>ipsec lwdnsq</command>
is a helper program that does DNS lookups for other programs. It implements
an asynchronous interface on stdin/stdout, with an ASCII driven command
language.
</para>

<para>
If stdin is a tty or if the
<option>--prompt</option>
option is given, then it issues a prompt to the user. Otherwise, it is
silent, except for results.
</para>

<para>
The program will accept multiple queries concurrently, with each result
being marked with the ID provided on the output. The IDs are strings.
</para>

<para>
If the
<option>--serial</option>
option is given, then the program will not attempt to execute concurrent
queries, but will serialize all input and output.
</para>

</refsect1>

<refsect1><title>QUERY LANGUAGE</title>

<para>
There are eleven command that the program understands. This is to lookup
different types of records in both the forward and reverse maps. Every query
includes a queryid, which is returned in the output, on every single line to
identify the transaction. 
</para>

<refsect2><title>KEY <option>queryid</option> <option>FQDN</option></title>
<para>
This request looks up the KEY resource record for the given <option>FQDN.</option>.
</para>
</refsect2>

<refsect2>
<title>KEY4 <option>queryid</option> <option>A.B.C.D</option></title>
<para>
This request looks up the KEY resource record found in the reverse map for
the IP version 4 address <option>A.B.C.D</option>, i.e. it looks
up D.C.B.A.in-addr.arpa.   
</para>
</refsect2>

<refsect2>
<title>KEY6 <option>queryid</option> <option>A:B::C:D</option></title>
<para>
This request looks up the KEY resource record found in the reverse map
for the IPv6 address <option>A:B::C:D</option>, i.e.
it looks the 32-nibble long entry in ip6.arpa (and ip6.int).
</para>
</refsect2>

<refsect2>
<title>TXT4 <option>queryid</option> <option>A.B.C.D</option></title>
<para>
This request looks up the TXT resource record found in the reverse map for
the IP version 4 address <option>A.B.C.D</option>, i.e. it looks
up D.C.B.A.in-addr.arpa.   
</para>
</refsect2>

<refsect2>
<title>TXT6 <option>queryid</option> <option>A:B::C:D</option></title>
<para>
This request looks up the TXT resource record found in the reverse map
for the IPv6 address <option>A:B::C:D</option>, i.e.
it looks the 32-nibble long entry in ip6.arpa (and ip6.int).
</para>
</refsect2>

<refsect2>
<title>KEY <option>queryid</option> <option>FQDN</option></title>
<para>
This request looks up the IPSECKEY resource record for the given
<option>FQDN.</option>. See note about IPSECKEY processing, below.
</para>
</refsect2>

<refsect2>
<title>IPSECKEY4 <option>queryid</option> <option>A.B.C.D</option></title>
<para>
This request looks up the IPSECKEY resource record found in the reverse map for
the IP version 4 address <option>A.B.C.D</option>, i.e. it looks
up D.C.B.A.in-addr.arpa. See special note about IPSECKEY processing, below.
</para>
</refsect2>

<refsect2>
<title>IPSECKEY6 <option>queryid</option> <option>A:B::C:D</option></title>
<para>
This request looks up the IPSECKEY resource record found in the reverse map
for the IPv6 address <option>A:B::C:D</option>, i.e.
it looks the 32-nibble long entry in ip6.arpa (and ip6.int). See
special note about IPSECKEY processing, below.
</para>
</refsect2>

<refsect2>
<title>OE4 <option>queryid</option> <option>A.B.C.D</option></title>
<para>
This request looks an appropriate record for Opportunistic
Encryption for the given IP address. This attempts to look for the
delegation record. This may be one of IPSECKEY, KEY, or TXT
record. Unless configured otherwise, (see OE4 Directives, below), then
a query type of ANY will be used to retrieve all relevant records, and
all will be returned.
</para>
</refsect2>

<refsect2>
<title>OE6 <option>queryid</option> <option>A:B::C:D</option></title>
<para>
This request looks an appropriate record for Opportunistic
Encryption for the given IPv6 address. This attempts to look for the
delegation record. This may be one of IPSECKEY, KEY, or TXT
record. Unless configured otherwise, (see OE Directives, below), then
a query type of ALL will be used to retrieve all relevant records, and
all will be returned.
i.e. it looks the 32-nibble long entry in ip6.arpa (and ip6.int). 
</para>
</refsect2>

<refsect2>
<title>A <option>queryid</option> <option>FQDN</option></title>
<para>
This request looks up the A (IPv4) resource record for the given
<option>FQDN.</option>. 
</para>
</refsect2>

<refsect2>
<title>AAAA <option>queryid</option> <option>FQDN</option></title>
<para>
This request looks up the AAAA (IPv6) resource record for the given
<option>FQDN.</option>. 
</para>
</refsect2>

</refsect1>

<refsect1><title>Replies to queries</title>

<para>
All replies from the queries are in the following format:
<programlisting>
&lt;ID&gt; &lt;TIME&gt; &lt;TTL&gt; &lt;TYPE&gt; &lt;TYPE-SPECIFIC&gt; \n
</programlisting>

<variablelist>

<varlistentry><term><parameter>ID</parameter></term>
<listitem>
<para>
this is the <option>queryid</option> value that was provided in
the query. It is repeated on every line to permit the replies to be
properly associated with the query. When the response is not ascribable to 
particular query (such as for a mis-formed query), then the query ID "0" will
be used.
</para>
</listitem>
</varlistentry>

<varlistentry><term><parameter>TIME</parameter></term>
<listitem>
<para>
this is the current time in seconds since epoch.
</para>
</listitem>
</varlistentry>

<varlistentry><term><parameter>TTL</parameter></term>
<listitem>
<para>
for answers which have a time to live, this is the current value. The
answer is valid for this number of seconds. If there is no useful
value here, then the number 0 is used.
</para>
</listitem>
</varlistentry>


<varlistentry><term><parameter>TYPE</parameter></term>
<listitem>
<para>
This is the type of the record that is being returned. The types are
described in the next section. The TYPE specific data that follows is
specific to the type.
</para>
</listitem>
</varlistentry>
</variablelist>

</para>

<para>
The replies are limited to 4096 bytes, a value defined as
<constant>LWDNSQ_RESULT_LEN_MAX</constant>. This is defined in
<filename>freeswan.h</filename>.
</para>

<para>All of the replies which include resource records use the
standard presentation format (with no line feeds or carriage returns)
in their answer.</para>

<refsect2>
<title>START</title>
<para>
This reply indicates that a query has been received and has been
started. It serves as an anchor point for timing, as well as an acknowledgement.
</para>
</refsect2>

<refsect2>
<title>DONE</title>
<para>
This reply indicates that a query is entirely over, and no further
information from this query will be sent.
</para>
</refsect2>

<refsect2>
<title>RETRY</title>
<para>
This reply indicates that a query is entirely over, but that no 
data was found. The records may exist, but appropriate servers could
not be reached.
</para>
</refsect2>

<refsect2>
<title>FATAL</title>
<para>
This reply indicates that a query is entirely over, and that no
data of the type requested could be found. There were no timeouts, and
all servers were available and confirmed non-existances. There may be
NXT records returned prior to this.
</para>
</refsect2>

<refsect2>
<title>CNAME</title>
<para>
This is an interim reply, and indicates that a CNAME was found (and
followed) while performing the query. The value of the CNAME is
present in the type specific section.
</para>
</refsect2>

<refsect2>
<title>CNAMEFROM</title>
<para>
This is an interim reply, and indicates that a CNAME was found. The
original name that was queries for was not the canonical name, and
this reply indicates the name that was actually followed.
</para>
</refsect2>

<refsect2>
<title>NAME</title>
<para>
This is an interim reply. The original name that was queries for was
not the canonical name. This reply indicates the canonical name.
</para>
</refsect2>

<refsect2>
<title>DNSSEC</title>
<para>
This is an interim reply. It is followed either by "OKAY" or "not
present.
It indicates if DNSSEC was available on the reply.
</para>
</refsect2>

<refsect2>
<title>TXT and AD-TXT</title>
<para>
This is an interim reply. If there are TXT resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>

<refsect2>
<title>A and AD-A</title>
<para>
This is an interim reply. If there are A resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>

<refsect2>
<title>AAAA and AD-AAAA</title>
<para>
This is an interim reply. If there are AAAA resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>

<refsect2>
<title>PTR and AD-PTR</title>
<para>
This is an interim reply. If there are PTR resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>

<refsect2>
<title>KEY and AD-KEY</title>
<para>
This is an interim reply. If there are KEY resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>


<refsect2>
<title>IPSECKEY and AD-IPSECKEY</title>
<para>
This is an interim reply. If there are IPSEC resource records in the
reply, then each one is presented using this type. If preceeded by
AD-, then this record was signed with DNSSEC.
</para>
</refsect2>


</refsect1>

<refsect1><title>Special IPSECKEY processing</title>

<para>
At the time of this writing, the IPSECKEY resource record is not
entirely specified. In particular no resource record number has been
assigned. This program assumes that it is resource record number
45. If the file 
@IPSEC_CONFDDIR@/lwdnsq.conf
exists, and contains a line like
<programlisting>
ipseckey_rr=<option>number</option>
</programlisting>
then this number will be used instead. The file is read only once at
startup.
</para>
</refsect1>

<refsect1><title>OE Directives</title>

<para>
If the file
@IPSEC_CONFDDIR@/lwdnsq.conf
exists, and contains a line like
<programlisting>
queryany=false
</programlisting>
then instead of doing an ALL query when looking for OE delegation
records, lwdnsq will do a series of queries. It will first look for
IPSECKEY, and then TXT record. If it finds neither, it will then look
for KEY records of all kinds, although they do not contain delegation
information.
</para>
</refsect1>

<refsect1><title>Special IPSECKEY processing</title>

<programlisting>
/etc/ipsec.d/lwdnsq.conf
</programlisting>

</refsect1>

</refentry>
</section>
</article>