Credns is a software program aimed at fortifying DNSSEC by performing
validation in the DNS notify/transfer-chain. Currently credns is a fork
of the NSD_3_2 branch that has been extended with the possibility to
assess zones (received or updated by AXFR or IXFR) by running an external
verifier. Only zones that are deemed correct by the verifier will be
notified to (public) slave servers and offered for transfer.

An external verifier can be configured per zone. When a zone with a verifier
is received or updated via an (incremental) zone transfer, it will be
submitted to this external verifier for evaluation. When the verifier deems
the updated zone to be correct, it has to indicate this by exiting with status
code 0. The zone will then be served. Other exit status codes will discard the
update and credns will continue to serve the zone before the update.

A verifier is specified with the "verifier:" option in the "zone:" clause.

The zone can be provided to the verifier in two ways. 

     1. The complete zone can be fed to the standard input of the verifier.

	This modus operandi is enabled by default and can be configured with
	the "verifier-feed-zone:" option in the "server:" and the "zone:"
	clause. The option in the "server:" clause sets the default for all
	verifier-enabled zones which can in turn deviate from the general
	setting with their own option.

	Examples for verifiers that read from the standard input are:
	"lds-verify-zone -V2" (-V2 to suppress copying of the zone to stdout)
       	or "validns -" (don't forget the dash (-) to read the zone from stdin).

     2. The zone can be served to the verifier.

	This is disabled by default and can be enabled by configuring ip-
	addresses, with the "verify-ip-address" option in the "server:" clause,
	on which the zone to be assessed will be served.  Addresses can
	optionally contain a port number, but when not given will use the value
	specified by the "verify-port" option, which, when not given, will be
	5347.

	For example to validate the SOA of a zone example.com by querying,
	with a certain DS record as the trust anchor (in file example.com.ds),
       	the "verifier:" option could have the following value:
	"drill -S -k example.com.ds @localhost -p 5347 example.com SOA"


A verifier is informed about the domain name of the zone to be verified, and
the accessibility of the system submitting the zone via environment variables.

	VERIFY_ZONE 
		will contain the domain name of the zone to be verified.

	VERIFY_ZONE_ON_STDIN 
		will contain the value "yes" when the zone is fed to the
		standard input of the verifier.

	VERIFY_IP_ADDRESSES
		will contain a list of <ip-address>@<port>s on which the zone
		to be verified can be queried.

	VERIFY_IPV6_ADDRESS and VERIFY_IPV6_PORT
		will contain the first configured IPv6 address (and port) for
		querying the zone (if configured and when supported).

	VERIFY_IPV4_ADDRESS and VERIFY_IPV4_PORT
		the first configured IPv4 address and port (again when
		configured and supported), and 

	VERIFY_IP_ADDRESS and VERIFY_PORT
		the first address and port with a preference for IPv6.

For each zone one verifier will be run at the same time, but when multiple
to-be-verified zones are received, multiple verifiers may be run
simultaneously. The number of verifiers that may be run simultaneously is
configured with the "verifier-count:" option in the "server:" clause and
defaults to 1.

The time a verifier may take can be configured with the "verifier-timeout:"
option in the "server:" clause (to make the general default) or in the "zone:"
clause to set it for a specific zone. When the time the verifier takes exceeds
the timeout value, the zone to be verified will be considered bad.  By default
the value is 0, which means that the verifier may take as long as it needs.


A minimal credns setup
=======================

Suppose you have a hidden master for example.com on 10.0.0.1 and a public slave
on 10.20.0.1.  We will configure credns listening on 10.10.0.1 in between
those two validating with ldns-verify-zone.

In the configuration file /etc/credns/credns.conf we configure the address
this credns instance is listening on for all its zones in the server section:

	server:
		ip-address: 10.10.0.1
		username: credns

The username has to be an existing user identify which credns can run as.
The zone sections starts with the name.

	zone:
		name: example.com

In the zone section we allow notifies from the hidden master and indicate that
we transfer the zone from that master as well.

		allow-notify: 10.0.0.1 NOKEY
		request-xfr: 10.0.0.1 NOKEY

Then we configure that we use ldns-verify-zone to validate the zone:

		verifier: ldns-verify-zone -V2

And when validated successfully the zone is notified and offered for transfer
to the public slave:

		notify: 10.20.0.1 NOKEY
		provide-xfr: 10.20.0.1 NOKEY


We are ready to startup credns:

		# crednsc start

credns will now (after some initial setup) request transfer from the hidden
master: 10.0.0.1. It will pass the zonefile for assessment to ldns-verify-zone.
Then, when the zone is valid, it notifies the public slave on 10.20.0.1 and
offers the newly loaded and validated zone for transfer.

The syslog now contain messages reflecting this sequence of affairs:

	credns[<m1pid>]: new database created (/var/db/credns/credns.db)
	credns[<m1pid>]: credns started (credns 0.2.10), pid <m1pid>
	credns[<c1pid>]: adding 1 udp handlers to netio.
	credns[<c1pid>]: udp socket 10.10.0.1:domain added to netio
	credns[<c1pid>]: adding 1 tcp handlers to netio.
	credns[<c1pid>]: tcp socket 10.10.0.1:domain added to netio
	credns[<m1pid>]: signal received, reloading...
	credns[<m2pid>]: memory recyclebin holds 1208 bytes
	credns[<m2pid>]: Zone example.com has changed.
	credns[<m2pid>]: Zone is verified and complete
	credns[<m2pid>]: Zone example.com verified successfully.
	credns[<m2pid>]: Zone verifying done... Good: 1, Bad: 0.
	credns[<c2pid>]: adding 1 udp handlers to netio.
	credns[<c2pid>]: udp socket 10.10.0.1:domain added to netio
	credns[<c2pid>]: adding 1 tcp handlers to netio.
	credns[<c2pid>]: tcp socket 10.10.0.1:domain added to netio
	credns[<xfrdpid>]: Zone example.com serial 0 is updated to <serial>.


Credns is not NSD
==================
WARNING!  Because credns is implemented as a fork of NSD3, it currently
functions as a complete authoritative DNS nameserver and will actually answer
queries for zones that were deemed correct by a verifier.  However, this
functionality is not necessary for credns type operation and should disappear
in future releases. It is recommended not to rely on credns's ability to
answer queries to the public. In future releases credns might well be
answering queries to verifiers only. Credns has a different orientation as
NSD and might develop into an entirely different direction.

Credns will not install the zonec utility.

