CapeSoft Logo

CapeSoft NetTalk
DNS API Server

Download Latest Version
Installed Version Latest Version

NetTalk DNS API Server

Introduction

NetTalk 14 introduces support for LetsEncrypt DNS Challenges for getting certificates. This is useful for Intranet servers and other Web Servers that cannot perform HTTP (over port 80) challenges.

DNS Challenges are fantastic and can be used directly from an Intranet server (as long as it has out-going internet connections.) However if it talks directly to the DNS service then it needs credentials for that DNS service. Populating your DNS credentials on each customer site is not ideal.

This DNS API Web Server acts as an intermediary. It sits as a man-in-the-middle, between the Intranet web Server and the DNS Provider. Each customer has their own credentials to this server, and in turn this server contains the credentials to the API of your DNS provider. This offers you more control, and does not expose your DNS credentials to your customer server.

This DNS Web Server is a normal web server that you deploy on the internet. Source code for this server ships with NetTalk (\Examples\NetTalk14\NetDns\apiServer.)

As a normal web server this server will need to get it's own certificate. That can be done in the normal way using either the HTTP or DNS challenges. It WON'T use the API Challenge itself. This document does not cover that process, and no part of this document is referring to that process. (That process is documented in Building Secure Web Sites.) This document discusses setting up the server so that it can be used by clients. (The clients in this case being your web servers on customer LAN's)

In order to understand this document, it's important to have a clear understanding of how servers are made secure. That's documented at Building Secure Web Sites. Pay special attention to the section Getting a Certificate via an API. That discusses the API client, this side is the API server.

Terminology

There are several people involved, server servers, and several situations. In order to be clear here are some definitions.
Term Description
API Server The NetTalk DNS API Server as deployed by you (the developer) on a computer attached to the internet. You can start with the supplied app, but you can modify the app to your needs.
Web Server Your program, which you are selling to your customer, which they are going to run on their premises.


You The primary application developer.
Customer Your customer, who wants to run an Intranet server on their LAN. (In this document they'll be known as Fred's Bakery)
Support You, or your employee, responsible for helping the customer install the server (or installing the server for the customer.) In this document this person will be called Joshua.


Domain A domain you have purchased via a DNS Provider (DNSimple). In this document the example for this domain is EcoTimeLan.Com . You will sign up to DNSimple and purchase your own domain.
DNS Provider The name of the DNS registrar that holds your domain, and which has an API that NetTalk can use. (At the time of writing this only DNSimple is supported.)


Setting Up Your API Server

Compile and Deploy

To Add API support to your Web Server see Getting a Certificate via an API.

The API Server is a regular NetTalk Web server. Deploy it to the internet in the normal way.

It needs to listen on a secure port, and hence needs a certificate. Since this is running on a public, internet web server it can make use of the HTTP or DNS challenges in the normal way.

Security

Connect to your server through your browser, and go to the Security menu. Set your security policies there (Policies item). Part of the Policies will be setting up your DNS Provider settings.

Add yourself as the first user (Users item).  Make sure to add yourself as a SysAdmin level user.

Add other team members (Joshua) as Operator Level users. Joshua will only have on task, so their access rights can be minimal.

Add one or more customer credentials as users. This will be a user of Level API. You can choose to create a single user, or a user per customer. This matches the User ID and Password on the API Challenge tab at the customer's site.

Advanced: The API Server allows you to configure multiple domains on the Security / Tenants menu. If you are selling multiple Web Server products, and you wish to brand them differently, you can do so. Each tenant has different (unique) users.

Operations

Your Support person has minimal work to do when adding a new customer

Install your Web Server at the customer site

  1. Make a note of the LAN IP Address of the server. You'll need it in step 7 below.

Add DNS record for Customer

  1. Login
  2. Go to the Set DNS Record menu option
  3. Enter a unique domain name for this customer (they don't include the root domain part.) For example, FredsBakery
  4. Click the Check Value button
  5. If the chosen name already exists then choose a new name (if this is a new customer).
  6. Once you see the message "No current record for this name exists", then click the Next button
  7. Enter the LAN IP Address. This is the IP address on the Customer's network where your Web server is installed. It can be an IPv4 or IPv6 address. It will usually be something like
    192.168.x.x
    169.254.x.x
    10.x.x.x
    127.x.x.x

    (where x is a 3 digit number from 0 to 255)
  8. Once the IP address is entered click on the Write IP Address to DNS button.

Configure the Web Server at the customer site

  1. On the Certificates tab, set the Challenge Method to API
  2. Set the Domains to be the DNS record you created above. In our example fredsbakery.ecotimelan.com . This is the full domain name including the root domain.
  3. Set the other fields on the Certificates tab as usual.
  4. On the API Challenge Tab set the API Server URL. This is the root domain of your API server. For example https://ecotimelan.com
    Note that the Customers domain is NOT included in this name.
  5. Set the User ID and Password for your API User.
  6. On the Certificates tab, click on the Check / Get Certificates button.

Customer

Your server is now up and running. The customer accesses the server from other machines on the LAN, by entering the new domain address in their browser.
For example

https://fredsbakery.ecotimelan.com

That address works from anywhere inside the LAN.

Hint: It's still a good idea for your web server to listen on port 80. Any traffic on this port will automatically be redirected to the secure port. Since some browsers still default to HTTP (and not HTTPS) this can help the users by not requiring them to enter the HTTPS part of the URL.

Client Software

In addition to the above automatic approaches, here is some other information that the developer might find useful.

There are two primary ways to make use of this API server.

Directly from a Web Server

Support for this server is built in to the NetTalk Web Server. This is the approach discussed above. For more information on activating this see Getting a Certificate via an API. As long as the server is able to get the certificate from the web (it allows outgoing connections on port 443) this is the simplest approach.

From a stand-alone Client program

An example of a stand-alone client is in your \Examples\NetTalk\NetDNS\ApiClient folder. Since the Domain Validation is done by the API server, not the web server, this program can run on any computer - it doesn't have to run on the server. This means certificates can be retrieved using this program and deployed to the server via some other means.

In other words using this program on some "other" computer allows intranet servers who cannot access the internet, to get certificates.
[End of this document]
Return to NetTalk Documentation Index