$Id$ This is a collection of tools, that together implement a pipelined DNSSEC signer. These tools are used by the OpenDNSSEC signer engine to create signed DNSSEC zones from unsigned zone data. It is work in progress. There are no man pages (yet?), so the pipeline is described below BUILD INSTRUCTIONS ------------------ The signer make will also build these tools. However, if you wish to compile them on your own, you can use: autoreconf ./configure --with-ldns= make (make install) USAGE INSTRUCTIONS ------------------ Currently, the complete signer is implemented as a series of separate tools, that each read in a (part of a) zone in BIND-style text format, and output that zone with the necessary changes, again in text format. To simply sign a zone, the following steps are needed: 1 Zone Reading (sorting, stripping, and optional NSEC3PARAM addition) 2 NSEC Addition 3 RRSIG Addition 4 Finalization If DNSKEY records need to be added, this can be done with create_dnskey, see Other tools below. Step 3 can be called again on its own output, so that zones can be re-signed. 1 Sorting --------- Apart from the quicksorter, and the extra tools described below, the other tools in the pipeline all expect that the data they receive is sorted for their needs. In a normal signing operation, this means that the zone must be sorted in canonical form, ie. the names must be sorted, and within each name the resource records must be sorted. In the case of NSEC3 denial-of-existence, the names must be sorted in 'nsec3'-space, and within each name, the resource records must be sorted in canonical order. To achieve this, the tool 'quicksorter' can be used. Use 'quicksorter -h' to see the specific options. The quicksorter tool will also filter out glue records, and flag empty non-terminals. Glue records will be given to the output in the form ; glue: So that later steps will ignore these records (; means comments in default zone format). The finalizer at step 4 will remove the comment part so that the final output zone will have the glue data again. There are two types of empty non-terminals (ENTs), 'normal' ENTs, and 'NS' ENTs. NS ENTs are empty non-terminals that lead to a name where only NS Resource records exist (while normal ENTs lead to ojne where other data is present). Normally, the quicksorter will ignore empty non-terminals. However, if the zone is sorted in NSEC3 space, empty non-terminals will be marked and passed on, so the nsecifier can create NSEC3 records for them. They will be of the form: ; Empty non-terminal: If NSEC3 opt-out is also used, NS ENTs are also marked; ; Empty non-terminal to NS: (These ENTs should *not* get an NSEC3 record). 3 NSEC Addition --------------- To create a fully signed zone, NSEC(3) records must be added. This is done by the zone reader. Depending on the signer configuration, NSEC or NSEC3 records are added. 4 RRSIG Addition ---------------- And finally, the signature resource records must be added this is done with the tool 'signer'. It has the following command-line arguments: -c : The OpenDNSSEC configuration file that contains the HSM modules etc. -f : From this file, commands and input RRsets are read. If this argument is not given, stdin is used -h: Show a usage screen -p: : If this file is given and exists it should point to a previous output file of the signer tool. Previously generated RRSIGs that do not need to be regenerated (yet) are read from this file, to speed up re-signing operations. This MUST be the DIRECT output of the signer, NOT the output from the finalizer. -w: : The signed zone file will be written to this file. This MUST NOT be the same file as either the file for the -f or the -p flag, since the signer will write output before reading in all input. -r: Makes the signer print the number of signatures it created to stderr. On success, this should always be 1 or more, since the SOA record is always re-signed. Specific signing commands are passed in-line; with the following commands: :add_ksk adds a KSK to be used to generate signatures for the DNSKEY RRset :add_zsk adds a KSK to be used to generate signatures for all non-DNSKEY RRsets :inception sets the inception date for signatures :expiration sets the expiration date for signatures :expiration_denial sets the expiration date for signatures for NSEC and NSEC3 records if not set, the value from :expiration will be used for denial sigs :expiration_keys sets the expiration date for signatures for DNSKEY records if not set, the value from :expiration will be used for key sigs :jitter sets the jitter value for expiration dates :refresh sets the refresh date; signatures with an expiration date before this value are dropped and regenerated :origin sets the zone name for the current zone (mandatory) :soa_ttl sets the TTL for the SOA record, this will override the TTL of the SOA in the input file :soa_serial sets the serial value for the SOA record, this will override the serial value of the SOA in the input file :soa_minimum sets the minimum value for the SOA record, this will override the minimum value of the SOA in the input file :stop stop the signer (it will also stop if EOL is read in the input file) If an input line starts with ';', it is read as a comment, and will simply be copied to the output. Lines starting with ';' in a previously signed zone are dropped. Otherwise, the input lines are parsed as Resource Records. The signer will read an RRset from the input file, and check whether the input file has signatures for the keys that are specified. If a previously signed zone file is given, it will simultaneously be parsed for existing RRSIG records. If there are no RRSIG records for a specific key, or if the expiration date of said signatures falls before the 'refresh' value, new signatures are generated. This tool will also add some statistics to the file (sign time and signature counts). Finalizer --------- Due to the sorting at the beginning of step 1, the SOA resource record will not be the first in the zone file anymore. Some DNS servers cannot cope with that, so one of the tasks of the finalizer is to place the SOA record as the very first one in its output. It will also re-add the glue records that are passed to it in the form ; Glue: The string "; Glue: " will be removed, readding it to zone. It will also re-add the records that were set aside as being opt-out records (stored in a seperate file .optout). Other tools ----------- There is a tool to create a DNSKEY RR from a PKCS11 key id and algorithm, called 'create_dnskey'. It takes the same arguments as 'signer', but just prints out a DNSKEY RR for each key specified. There is a tool to get the SOA SERIAL from a zone file, called 'get_serial'. Use 'get_serial -h' to see the specific options.