1. Introduction
2. Basic theory of operation
3. Quick build & install
4. Configuration settings
5. Informative scenarios

1. Introduction

autotrust is a program written by NLnet Labs. It takes care of keeping your 
DNSSEC trust anchors up to date. It is RFC 5011 compliant, except for the query 
intervals and the retry timers. autotrust is meant to run from commandline or in 
a cron job. If we want to follow the values recommended by RFC5011, autotrust 
should run as daemon. 

The source code is available for download from:

         http://www.nlnetlabs.nl/projects/autotrust 

2. Basic theory of operation

autotrust makes use of ldns and libunbound. ldns is a library to simplify DNS
programming. libunbound is a library that can be used to obtain information from 
the DNS. The library performs public-key validation of results with DNSSEC.

When starting autotrust, it will read the trust anchors and trust anchor 
information from file. It than queries DNSKEYs for every zone that it has trust 
anchors configured for. If the answer to such query is validated, it will 
perform the update mechanism for that zone. If it saw an self-signed 
revoked DNSKEY, it will perform the update mechanism for that key.

autotrust is assumed to have valid trust anchors configured. Without them, 
queries cannot be validated and the program will do nothing spectacular. 

If trust anchors are updated, autotrust can signal the security-aware, 
validating resolver. It will send a SIGHUP signal, telling the resolver to 
reload its configuration.

3. Quick build & install

Step 1:
Make sure you have ldns 1.3.0+ and Unbound 1.0.0+ installed on your computer. 

Step 2: 
Unpack the source with:
	> gtar -xzvf autotrust-0.2.1.tar.gz
or, if you build from Subversion, run:
	> autoreconf && libtoolize

Step 3:
Run: 
	> ./configure

- You can give up a directory where ldns is installed with --with-ldns=<path>.
- You can give up a directory where libunbound is installed with 
  --with-libunbound=<path>.
- You can give up a prefix where the binaries should be installed with 
  --prefix=<path>. Default, they will go in /usr/local/sbin and /usr/local/man.
- You can give up the source directory  with --srcdir=<path>.

Step 4:
Make sure you have unbound.h and ldns/ldns.h in your path. If it is not in your 
default path, you can use the configuration options described in step 3.

Step 5:
	> make

Step 6: 
	> make install

Step 7:
Make sure you have the libraries in your library path.

	> LD_LIBRARY_PATH=<ldns_path>/lib:<libunbound_path>/lib && \
	  export LD_LIBRARY_PATH

Step 8:

Configure your trust anchors. By default, this should go in a file called 
trust-anchor.file. You can of course configure a different filename.

example trust-anchor.file:

	zoidberg.nlnetlabs.nl. DNSKEY 257 3 5 AwE...5zoHCf

You can put your trust anchors also in a BIND9 format:

example trusted-keys.file:

	trusted-keys {
	zoidberg.nlnetlabs.nl.   257 3 5 "Awe...5zoHCf" ;
	};

You can put your trust anchors also in the config file:

	trust-anchor: "zoidberg.nlnetlabs.nl. DNSKEY 257 3 5 AwE...5zoHCf"


Step 9:
Run the program:
	> autotrust
Run with -h to see usage.

4. Configuration settings

Configuration settings can be given on the commandline or in a configuration 
file. For available settings, look at the autotrust.conf.

5. Informative scenarios

Once installed, autotrust can be called from anyplace. Just make sure it can 
reach the configured trust anchor file(s), and has network access. By default, 
autotrust don't know where to find trust anchor files, so you have to specify 
them in the configuration file.

The following scenario's are described in section 6 of RFC 5011. They are 
adapted to suit the autotrust implementation.

5.1 Adding a new trust anchor (Pre-publish a DNSKEY)

Assume an existing trust anchor key set CurSet:
 1) Generate a new key pair
 2) Create corresponding DNSKEY record (with the SEP and zone bits set)
 3) Add the DNSKEY to the RRSet (but don't add it to CurSet).
 4) Sign the DNSKEY RRset with the keys in CurSet.
 5) Wait until resolvers go off.
 6) Add hold-down time is MAX(30 days, the expiration time of the original TTL).

In version 0.x, autotrust has no knowledge of query intervals and retry times. 
The resolver operator should run autotrust at appropriate times, for 
example put it in a cron job. Section 2.3 of RFC 5011 gives you an indication of 
what intervals to use.

5.2 Deleting a trust anchor

Assume an existing trust anchor key set CurSet, from which you want to delete A:
 1) Revoke A
 2) Sign the DNSKEY RRset with CurSet (including A)

Currently, few authoritative nameservers have methods for revoking a DNSKEY. In 
the trunk of ldns, an example program ldns-revoke can be found, which works with 
the latest ldns 1.3.0 release. 

Currently, if a trust anchor is deleted at the authoritative side, it just won't 
be published anymore. autotrust version 0.x is in that case RFC compliant and 
will put the key forever in MISSING state. There will be a configuration option 
where trust anchor keys at the resolver will be removed if they remain too long 
in the MISSING state. 

If the operator has ways to revoke a key, he should publish the REVOKED key A 
for at least 30 days (remove hold-down time).

5.3 Key Roll-Over (with a pre-published key)

Assume an existing trust anchor key set CurSet, from which you want to roll 
the active key A to the stand-by key B:
 1) Generate a new key pair C (which will be the new stand-by key)
 2) Generate corresponding DNSKEY record and add it to the RRSet.
 3) Revoke A.
 4) Sign it with CurSet, that includes A and B, but occludes C.

Again, the operator should publish the REVOKED key A for at least 30 days.

5.4 Key Roll-Over (double sign)

Double Sign Key Roll-Over becomes operational more difficult with revoking keys 
than it is now. This is because you need to publish two signature expiration 
times, one normal and one for revoking.

Current situation:
1.		2.		3.
SOA0		SOA1		SOA2
RRSIG1(SOA)	RRSIG1(SOA)	RRSIG2(SOA)
		RRSIG2(SOA)

DNSKEY1		DNSKEY1		DNSKEY2
RRSIG1(DNSKEY)	DNSKEY2		RRSIG2(DNSKEY)
		RRSIG1(DNSKEY)
		RRSIG2(DNSKEY)

New situation:
1.		2.		3.		4.
SOA0		SOA1		SOA2		SOA3
RRSIG1(SOA)	RRSIG1(SOA)	RRSIG2(SOA)	RRSIG2(SOA)
		RRSIG2(SOA)	

DNSKEY1		DNSKEY1		DNSKEY1 (R)	DNSKEY2
RRSIG1(DNSKEY)	DNSKEY2		DNSKEY2		RRSIG2(DNSKEY)
		RRSIG1(DNSKEY)	RRSIG1(DNSKEY)
		RRSIG2(DNSKEY)	RRSIG2(DNSKEY)

That is, it is not recommended to do Double Sign Key Roll-Over when making use 
of revocation mechanisms.

5.5 Emergency Key Roll-Over (key compromised)

When the active key is compromised, this has the same mechanism as in 5.3.
When the stand by key is compromised, you also have to follow the mechanism in 
5.3, with the exception that you revoke B instead of A.

5.6 Trust Point Deletion 

TODO
