Documentation and Testing Workgroup > Documentation Priorities > DNS Configuration Guide

Introduction

The Direct specifications require specific configuration of DNS for successful operation. This guide presumes basic understanding of Direct terminology and concepts; prior reading of the Direct Project Overview is recommended.

Overview


The Direct system uses DNS to distribute certificates to encrypt messages and check signatures (unless you have decided to distribute certificates in some other manner, out of band). These certificates are CERT records associated with the hostname part of the Direct address - direct.example.com, for instance. There could also be CERTs associated with the specific user, say drbob@direct.example.com, whose certificate is obtained by looking for the CERT record for drbob.direct.example.com. To streamline the provisioning and management of health addresses, which also means provisioning and managing certificates, the HISP reference implementations have a built-in DNS server that can respond to CERT queries, and also have the capability of exporting CERT records in the BIND zonefile format.

Many organizations will want to have their HISP manage DNS entries for the Health Domain Name (direct.example.com in our example. Organizations managing their own HISP infrastructure will need to also host the DNS server component.

Organizations Wanting the HISP to Manage CERT Records


To make this work, we need to tell the world to make these CERT requests against the HISP's DNS server. The way to do that is by using an NS record, pointing from e.g. direct.example.com to the HISP.

1) Determine Your HISP's Nameserver Hostname


The HISP "Nameserver Hostname" is the hostname the HISP uses to accept Direct protocol requests, such as the sending of messages, or DNS lookups for certificates. If you are your own HISP, then this is the hostname of your server, but avoid using temporary hostnames. If you are a customer of a third-party HISP, ask them for this address, and make sure it is the address that HISP is using to respond to DNS queries for certificates for your domain. The hostname we'll use in the rest of this guide will be ns.example-hisp.com. There actually might be more than one "Nameserver Hostname" given to you by your HISP, for redundancy and failover reasons; if so, then repeat the following steps for each one.

2) Configure the NS Record (on an External DNS Provider)


Most people who register domain names choose to use the domain name registrar to perform "name service" for the domain as well. For example, to add a new hostname to your domain, you would go to the web-based tools each registrar provides to add that hostname and its corresponding IP address by creating an "A" record. Now we need to do the same thing with the "NS" record for your Direct address domain (e.g. direct.example.com) to your HISP (e.g. inbound.example-hisp.com).

Every registrar does this slightly differently; registrar-specific details are available here: Gandi.net, GoDaddy, Network Solutions. [feel free to add more to the wiki]

Or 2) Configure the NS Record (on Your Own DNS Server)


If, on the other hand you host your own DNS, then the details on how to do this are specific to your DNS server. In BIND's zone file format, you want to create a record that looks like:
direct.example.com. IN NS inbound.example-hisp.com.

Other details are provided behind the following links: Microsoft DNS Server, TinyDNS, [feel free to add more to the wiki]

3) Test Your NS Record


You can test to see if you have the basic configuration right, using a number of different tools that let you query by DNS type. One of the web-based ways to test this is to use the Zone Edit NSLookup Tool. Enter your Direct hostname, and query for type "NS", and the result should point you at your HISP's Canonical Address. Note that you can use the command-line "dig" tool to do this too, as in:
dig -t ns direct.example.com

This should again should give you a result pointing at the HISP. Note that it might take some time for your DNS changes to become publicly visible, especially if you are using a hosted DNS service.

Once you are ready to test your setup at the HISP, you can test for proper lookup for CERTs for particular addresses. Use the first example if you have an organizational certificate, and the second if you have individual certificates.

dig -t cert direct.example.com
dig -t cert drbob.direct.example.com

Hosting Your Own CERT DNS Service


This section provides an overview for running your own DNS service that responds to CERT queries.

Running the Built-In DNS Service


The reference implementations include a DNS Service that responds to a set of DNS record requests, including MX, CERT, SOA, A, etc. This service is in two parts; the first hooks into the configuration services and back-end components, and hosts a web service interface providing information for DNS requests, and the second component is the DNS Server proper.

The DNS Server must be hosted such that it has a public IP address and hostname. This typically means that the server will be sitting on a DMZ. Security risk and threat assessment are out of scope for this document, but the services are designed to provide strong isolation and minimize security risks when properly configured.

Typically this means:

  • Hosting the server on a machine that has very limited privileges, exposed ports, etc
  • Configuring the back-end web service such that the DNS server machine can access only the web service for DNS queries

This means that, in the unlikely event that an attacker compromises the JVM or CLR and accesses the host machine, access behind the DMZ will be limited to web services providing the same information publicly available in any case through the DNS service.

More detail is available at ...<point to C#/Java documentation >

When the service is running and available at a public IP address and hostname, you must point the NS record for the Health Domain Name to the DNS server. Assuming you have the name server running at ns.direct.example.com, then in BIND's zone file format, you want to create a record that looks like:
direct.example.com. IN NS ns.direct.example.com.

If you are not using BIND, follow your DNS server's instructions for configuring NS records.

Exporting Resource Records to a BIND Server


If your organization does not wish to run the DNS service, it will need to export records to its main DNS service. This should only be done for certificates that change infrequently, as any change in certificate information (expiry, new issuance, etc) will require a re-export. It is recommended that this use be limited to organizational certificates.

The reference implementations contain export functions that can export DNS records in BIND zone file format. The details about how to incorporate those zone files into your DNS server environment are beyond the scope of this document.

In order to export records ...