DNS ZoneManager for GXFS

The DNS Zone Management is the component responsible for managing the DNS zone file and used for anchoring the trust framework DID information into the zone file. It is also responsible for resigning the zone file based on DNSSEC for every new update in the zone file. The zone manager service was designed to serve the TSPA only. It manages a zone file by:

• Creating an intermediate database for NS, A, PTR and URI records
• Providing auth mechanism to protect endpoints
• Exposing secure endpoints for managing PTR records (associated with trust frameworks) and URI records (associated with trust lists)
• Updating records and resigning zone file
• Using DNSSEC to provide and additional security layer to the DNS service

The implementation was done based on LIGHTest zone manager.

Requirements

• OS: Unix based
• Docker v24.0.7
• Domain setup see #Reference (see config file)
• Web server (e.g. nginx)

Setup

1. Define the environment setup.

Define the primary and secondary servers including DNS names and IP addresses. The primary server will host and run the zone manager service as well as the zone file. You can do this by copying and editing the configuration file:

cp config.sample.conf config.conf
vim config.conf # add your configuration

Define the identity provider settings for the Oauth authentication of endpoints. For this, three variables must be defined in a file called auth.conf: KEYCLOAK_URL, REALM and CLIENT_ID. You can do this by:

cp auth.sample.conf auth.conf
vim auth.conf # add your configuration

You can find a sample keycloack realm configuration file in the docs folder.

2. Build and run Docker container Build the Docker image

docker build -t zonemanager .

3. Run the container

Before running the container, please make sure that you configure your host dns resolver and proxy so requests are properly forwarded to the container. The NSD server in the zone manager container listens by default on port 53 and 53/udp.

The Zone Manager container must be run including the mapping of two ports:

• ZM Server port: listens for API REST calls, by default on 16001
• NSD server port: listens for nsd resolutions queries by default on 53 and 53/udp

Please make sure you map the correct host ports:

docker run -p 16001:16001 -p 53:53 -p 53:53/udp zonemanager

4. Optionally, run tests once the zone manager server is up

See the test folder for details. The tests include getting a valid token from the configured identity provider. If you have not set your IdP, please do so now (see step 1). To run the tests:

From the unittest folder run:

python3 -m unittest unittests.py

Reference

System overview

The zone manager is meant to have the TSPA as its only client. The TSPA can perform CRUD operations in relation to Trust Frameworks and Trust Lists. The Zone Manager takes every operation request and updates the zone file accordingly. It takes care of adding and deleting records to the zone file and its required signig.

A simple description of the flow: At startup, the Zone Manager sets up the DNS server (NSD or KNOT) and creates a data base with the base SOA, NS and A type resource records wich are then formatted, signed and used to create a zone file. A Trust Framework creation request can then be initialized by the TSPA. When this happens, the Zone Manager converts the Trust Framework's URL into a PTR record, stores in the data base and anchors it in the DNS system by updating the zone file accordingly. In the case of creation of Trust List DID, the process is similar with only difference being that the DID are stored as URI type records in the database as well as in the zone file.

This is repeated every time a CRUD operation in relation to Trust Framework URLs and Trust List DIDs.

The current Zone Manager implementation includes a simple UI that allows the administrator to visualize the zone data. See the user interface folder

Deployment notes

Zone file persistance

Please note that when the docker container is run, a new zone file gets created. This will be stored inside the container in the path defined by the environment variable VAR_PATH in the setup script file run by docker when the image is built. This zone file is not persisted in the host machine. If you want to provide persistency for this file please do so by defining volumes in the Dockerfile.