KASP Auditor README ------------------- The KASP auditor is written to check the output of the signer. The auditor and its tools are part of the OpenDNSSEC project. For more information, visit http://www.opendnssec.org The Auditor requirements may be found at : https://wiki.opendnssec.org/display/OpenDNSSEC/Auditor+Requirements As of OpenDNSSEC version 1.1, a Partial Auditor is available. The Partial Auditor requirements may be found at : https://wiki.opendnssec.org/display/OpenDNSSEC/Partial+Auditor+Requirements CONTENTS Introduction Partial Auditor Dependencies Installation Testing Running Manually Offline Full Auditing ------------------------------------------------------------------- Introduction ------------------------------------------------------------------- The KASP Auditor checks the output of the signer against the policy used to sign the zone (obtained from the KASP). The signer calls the auditor once the zone(s) have been signed. The auditor runs in two stages : first, the signed and unsigned zones are sorted into canonical order, and then the sorted files are audited. Upon completion, the auditor signals any errors to the caller. Errors and warnings are written to the configured log facility. Checks performed include : DNSKEY, NSEC(3), RRSIG and NSEC3PARAM checks. More details are available on the OpenDNSSEC website : https://wiki.opendnssec.org/display/OpenDNSSEC/Auditor+Requirements ------------------------------------------------------------------- Partial Auditor ------------------------------------------------------------------- Very large zones (for example, those with more than 1 million resource records) can take a long time to process with the full auditor. For these zones, a Partial Auditor is provided. The partial auditor does not perform a canonical sort of the zone, and does not check the signature for every RRSet. It compares the number of non-DNSSEC resource records in the signed and unsigned zones, rather than comparing every non-DNSSEC resource record. A sample of domains is fully checked (for correctly generated signatures and NSEC types), rather than every domain. The NSEC loop check is omitted (although the NSEC3 loop is still checked). All other checks (including key rollover checks and checks on every NSEC, NSEC3, RRSIG and DNSKEY record) are still performed. For full details please see : https://wiki.opendnssec.org/display/OpenDNSSEC/Partial+Auditor+Requirements To enable the partial auditor, replace the tag in the Policy in kasp.xml with . ------------------------------------------------------------------- Dependencies ------------------------------------------------------------------- To run the auditor, it is necessary to install dnsruby. It is presumed that Ruby is already installed on the target system, and that the system is online. To install dnsruby, run the following command : gem install dnsruby Ruby gems will download the dnsruby gem from rubyforge.org and install it to the target system. Depending on how Ruby is installed on the target system, it may be necessary to run the above command as root. Version 1.51 or greater of dnsruby is required. ------------------------------------------------------------------- Installation ------------------------------------------------------------------- From the base directory /auditor : autoreconf --install ./configure make make install --prefix= Installation directory. All files will be installed relative to this path, and default search paths will be relative to the prefix. Defaults to /usr/local The auditor invocation script, will be installed in /bin The Ruby libraries will be installed in /lib/opendnssec ------------------------------------------------------------------- Testing ------------------------------------------------------------------- To run the auditor test files, run the command : ruby test_scripts/auditor_test.rb If you wish to test the auditor locally before installing it, then run the following command from /auditor : ruby -I lib test_scripts/auditor_test.rb ------------------------------------------------------------------- Running Manually ------------------------------------------------------------------- Although the auditor is designed to be run by the signer, it can also be run manually : ods-auditor [--conf path/to/conf.xml] [--kasp path/to/kasp.xml] [--zone zone_to_audit] [--full] [--partial] [--signed path/to/temp/signed.zone] [--unsigned path/to/unsigned/zone] e.g. ods-auditor --conf /etc/opendnssec/conf.xml All zones will be audited by default. If --zone is specified, then only that zone will be audited. If --signed is specified for the zone, then the auditor will use that file as the signed output file, instead of the file specified in the zonelist. The --unsigned option works similarly for the unsigned zone file. If --full is specified, then the full auditor will be run without regard to the specified Audit type in the kasp.xml Policy. The --partial flag specifies that the partial auditor should be run. These two options cannot be used together. ------------------------------------------------------------------- Offline Full Auditing ------------------------------------------------------------------- If you are signing a very large zone, you may wish to enable partial auditing to ensure that the sign/audit cycle completes by a certain time. However, you may also wish to perform some off-line full audits from time to time, to ensure that everything is still running smoothly. To do this, take a copy of the signed and unsigned zone files (to make sure that the data doesn't change while the full audit is being performed). Then run the auditor : ods-auditor --full -z your.zone --signed /path/to/signed/file --unsigned path/to/unsigned/file Note that the auditor expects to be run (in either full or partial mode) every time the zone is signed. If it is only run from time to time, then it may generate false errors regarding key tracking. This is because it has not been able to check the lifetimes of keys which "suddenly" appear in the zone since the auditor has last run. ------------------------------------------------------------------ Known Issues ------------------------------------------------------------------ The auditor is known to take a long time to sort through very large zones. If your zone is very large, and needs to be signed very often, then you may need to use the partial auditor. The signer currently starts one Ruby Virtual Machine for each zone which is to be audited. If you have many thousands of zones, this may consume excessive resource : the element should be removed if this is the case. Any problems, please contact alex@nominet.org.uk