1. Introduction
2. Installation
3. Theory of operation
4. Configuration
5. Troubleshooting
5. Informative scenarios
1. Introduction
autotrust is a program that takes care of keeping your DNSSEC trust anchors up
to date. A trust anchor is a public key that is conï¬gured at a validating,
security-aware DNS resolver as the entry point for a chain of authority. In the
ideal case, validating name servers would only need one of these trust anchors
to be conï¬gured. During DNSSEC deployment, you will probably want to conï¬gure
multiple trust anchors.
Currently, there are two well-known resolvers that implement DNSSEC, BIND9 and
Unbound. autotrust can update the trust anchor files that these resolvers have
configured. Therefore, it follows the algorithm described in RFC 5011:
http://tools.ietf.org/html/rfc5011
The tool is intended for DNS resolver administrators to relieve DNSSEC
administration. However, it can run in absence of a resolver.
2. Installation
2a. Dependencies
autotrust makes use of ldns and libunbound. ldns is a library to simplify DNS
programming. libunbound is a library that facilitates DNS resolving.
Make sure you have ldns 1.3.0+ and Unbound 1.0.0+ installed on your machine.
They might already be available in your distribution's packaging system.
Otherwise, you can get ldns here:
http://www.nlnetlabs.nl/projects/ldns
Unbound is available at:
http://www.unbound.net
2b. Unpack
Unpack the source with:
> gtar -xzvf autotrust-@version@.tar.gz
or, if you build from Subversion, run:
> autoreconf && libtoolize
2c. Configure
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>.
- You can give up the config directory with --config-dir=<path>. This is where
the autotrust sample configuration and pidfile go. By default, the config dir
is /var/lib/autotrust.
- You can configure with --enable-checking. This will output way more messages
to the logfile for debugging purposes.
2d. Libraries
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.
> LD_LIBRARY_PATH=<ldns_path>/lib:<libunbound_path>/lib && \
export LD_LIBRARY_PATH
2e. Make
Run:
> make
2f. Install
Run:
> make install
2g. Configure your trust anchors.
Assume you have obtained the key-signing keys of zoidberg.nlnetlabs.nl..
To conï¬gure those key as a trust anchor you will have to include those keys in
a trust anchor file. For example, the file 'example.anchors' with one single
trust anchor may look like:
zoidberg.nlnetlabs.nl. DNSKEY 257 3 5 AwE...5zoHCf
example.anchors may be provided to Unbound as a configured trust anchor file.
You can put your trust anchors also in a BIND9 format, example.keys:
trusted-keys {
zoidberg.nlnetlabs.nl. 257 3 5 "Awe...5zoHCf" ;
};
Whether you use the trust anchor format or the trusted keys format, the files
should go in the autotrust configuration file:
trust-anchor-file: example.anchors
trusted-keys-file: example.keys
Multiple trust anchor files may be configured. They may be overwritten upon
execution of autotrust. That is, if autotrust validates new trust anchors, they
are added to the appropriate trust anchor files; if it invalidates trust
anchors, they are removed from the files.
2h. Configuration
Create a configuration file, for example in /var/lib/autotrust/autotrust.conf,
see section 4.
2i. Run
Run the program:
> autotrust
autotrust now did one single refresh for every configured trust point. To ensure
that the trust anchors are kept up to date, you should put the call into a cron
job. The cron should run not more than once a hour and at least every 15 days.
You can also run the program as a daemon, with -d. This way, your trust anchors
will be kept up to date without manual or cronual intervention. This way, it is
ensured that trust points are refreshed at the appropriate times.
2j. Stop
If you run autotrust as daemon, it can be stopped with a SIGTERM signal:
> kill -TERM `cat /var/lib/autotrust/autotrust.pid`
Replace /var/lib/autotrust/autotrust.pid if you have configured a different
pidfile.
3. Theory of operation
When starting autotrust, it will read the trust anchors and trust anchor
information from the configuration 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.
State is kept in the file autotrust.state. If trust anchors move to the state
VALID/MISSING or move from the state VALID/MISSING, trust anchor files will be
updated. In other words, configured trust anchors (possible in use by a
resolver) will change. Note that the MISSING state is a exceptional state, that
does not invalidate the trust anchor.
If autotrust runs in presence of a resolver, it can send SIGHUP signal there,
telling the resolver the trust anchors have been updated. As a result, the
resolver should reload its configuration.
Note: A SIGHUP might not be good enough to reload trust anchors in BIND9. Should
we seek a different solution?
4. Configuration
Configuration options can be set through a configuration file. A configuration
option in a file looks like:
option: some value
option: "some value"
A value may be quoted or not. The two options above are identical. For available
options, look at the autotrust.conf.sample.
5. Troubleshooting
If you encounter bugs, unexpected behavior or anything, you can address them to
autotrust-users@nlnetlabs.nl
Or enter a bugreport:
http://www.nlnetlabs.nl/bugs/
6. 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.
6.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.2.1 and below, 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.
6.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).
6.3 Key Roll-Over (double sign)
Double Sign Key Roll-Over will take one TTL longer than in the current case.
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) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYB
RRSIGA(DNSKEY) DNSKEYB RRSIGB(DNSKEY)
RRSIGA(DNSKEY)
RRSIGB(DNSKEY)
New situation:
1. 2. 3. 4.
SOA0 SOA1 SOA2 SOA3
RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYA (REV) DNSKEYB
RRSIGA(DNSKEY) DNSKEYB DNSKEYB RRSIGB(DNSKEY)
RRSIGA(DNSKEY) RRSIGA(DNSKEY)
RRSIGB(DNSKEY) RRSIGB(DNSKEY)
Again, the operator should publish the REVOKED key A for at least 30 days.
6.4 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.
This also introduces a new step in the key rollover scheme.
Current situation:
0. 1. 2. 3.
SOA0 SOA1 SOA2 SOA3
RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYA DNSKEYB
RRSIGA(DNSKEY) DNSKEYB DNSKEYB RRSIGB(DNSKEY)
RRSIGA(DNSKEY) RRSIGB(DNSKEY)
New situation:
0. 1. 2. 3. 4.
SOA0 SOA1 SOA2 SOA3 SOA4
RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYA DNSKEYA (REV) DNSKEYB
RRSIGA(DNSKEY) DNSKEYB DNSKEYB DNSKEYB RRSIGB(DNSKEY)
RRSIGA(DNSKEY) RRSIGB(DNSKEY) RRSIGA(DNSKEY)
RRSIGB(DNSKEY)
In the case of continuous pre-publishing:
0. 1. 2.
SOA0 SOA1 SOA2
RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYB
DNSKEYB DNSKEYB DNSKEYC
RRSIGA(DNSKEY) DNSKEYC RRSIGB(DNSKEY)
RRSIGB(DNSKEY)
It would become:
0. 1. 2. 3.
SOA0 SOA1 SOA2 SOA3
RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA) RRSIG1(SOA)
DNSKEY1 DNSKEY1 DNSKEY1 DNSKEY1
DNSKEYA DNSKEYA DNSKEYA (REV) DNSKEYB
DNSKEYB DNSKEYB DNSKEYC
RRSIGA(DNSKEY) DNSKEYC RRSIGB(DNSKEY)
RRSIGB(DNSKEY)
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.
6.5 Emergency Key Roll-Over (key compromised)
When the active key is compromised, this has the same mechanism as in 6.3.
When the stand by key is compromised, you also have to follow the mechanism in
6.3, with the exception that you revoke B instead of A.
The extra TTL introduced by the REVOKED bit is not beneficial when an emergency
key rollover is needed. In the case of continious pre-publishing, we could
revoke DNSKEYA in version 1. However, you are running the risk your zone becomes
bogus. The question is if this is worse than your zone is vulnerable for
spoofing.
6.6 Trust Point Deletion
[TODO] This will be in a future release, when trust point deletion is implemented.
