-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdesign_notes.txt
39 lines (22 loc) · 3.95 KB
/
design_notes.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
$Id$
Notes on Auditor design and implementation
------------------------------------------
These notes attempt to provide an introduction to the auditor design and implementation. They are intended for developers who need to extend or maintain the auditor software.
Auditor Design
--------------
The auditor runs in several stages. The controller is the lib/kasp_auditor.rb KASPAuditor class. This is started by the kasp_auditor command (which is built from kasp_auditor.in by the configure script).
KASPAuditor loads the configuration file for the system (conf.xml). It then uses the Parse (parse.rb) class to load the zonelist.xml file to ascertain which zones need to be loaded. Each zone's configuration is then loaded from the kasp.xml file. Salt has to be loaded from the signconf/<zone>.xml file, as it is generated by the enforcer.
Once the configuration has been loaded, the KASPAuditor then runs checks on one zone at a time. The process for checking a single zone is now described.
Two zone files must be loaded - the unsigned file and the signed file. Because these files could be very large, they can't be loaded into memory. In order to process them one domain at a time, they must first be sorted into canonical order.
The Preparser class (preparser.rb) does this by the normalise_zone_and_add_prepended_names() and sort() methods. Temporary .sorted files are created in the auditor's WorkingDirectory. Record, name and label sort separators are used - the input files should be checked to make sure that these strings do not appear. If errors are found during the sort then the audit is not performed.
The Preparser also normalises all records - all relative names are expanded to fully qualified domain names, and TTL and Class information are added if missing. BIND style zone file notation is respected and expanded.
Having loaded the configuration and sorted the signed and unsigned files, the auditor is now ready to start actually auditing. This is done by the Auditor class (auditor.rb).
The zone is processed one top-level subdomain of the zone at a time. This may include several subdomains of the subdomain (and may, pathologically, include pretty much the entire zone). This subdomain is loaded from both the signed and unsigned (canonically sorted) files, and then compared. Missing records in either zone are flagged, and then the DNSKEY, RRSIG, NSEC etc. checks are performed.
It is not possible to check the types covered at NSEC3 names while running through the zone - the auditor needs to know the data for both the owner name, and the hashed owner name (at which the NSEC3 record appears) before it can check that the data are correct. So, it builds up more temporary files as it runs (which all have "nsec" in the name). These files are checked once the main auditor run is complete.
Key Tracking
------------
The auditor is also specified to track keys over time, to ensure that they are prepublished for the necessary time, and do not exceed their policy-defined lifetime. It does this by storing data in the <WorkingDirectory>/tracker/ folder (one file for each zone). This file stores the last zone SOA serial, along with keys, their current state (active, prepublished, retired), and the time at which they were seen to enter that state.
Once the auditing run is complete, the auditor will call the KeyTracker (key_tracker.rb), passing data on the keys and SOAs it has seen in the zone. The KeyTracker then loads the stored data for the zone (if it is there) and updates it, reporting any resulting errors or warnings.
Interface to Signer
-------------------
The Auditor is currently called once by the signer for each newly signed zone. The auditor writes warnings/errors/info to the configured syslog utility, and returns an error code to the signer. 0 means OK, 1 means unexpected fatal error, and 3 means an error in the zone which should prevent the zone from being published. If only warnings are produced, then the zone will be published (with a return value of 0 from the auditor).