The overall configuration of OpenDNSSEC is defined by the contents of the file /etc/opendnssec/conf.xml. In this configuration file you specify logging facilities (only syslog is supported now), system paths, key repositories, privileges, and the database where all key and zone information is stored.
Date/time durations are as specified here.
The elements of the conf.xml file
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: conf.xml.in 1143 2009-06-24 12:10:40Z jakob $ -->
Each XML file starts with a standard element "<?xml...". As with any XML file, comments are included between the delimiters "<!--"
The enclosing element of the XML file is the element <Configuration> which, with the closing element </Configuration>, brackets the configuration information.
OpenDNSSEC stores its keys in "repositories". There must be at least one repository, although the system can be configured to run with multiple repositories.
There are a number of reasons for running with multiple repositories, including:
- Temporarily running with multiple repositories whilst a switch is made from one repository to another, e.g. when replacing hardware.
- The chosen type of repository has a limit on the number of keys that can be stored, and multiple repositories are needed to handle the chosen number of keys.
- Different types of repository are needed for different security levels, e.g. a key-signing key may require a higher level of security than a zone-signing key.
In practice, all repositories are "HSM"s (hardware security modules) or an emulation of one.
The software emulation of an HSM - SoftHSM - must be installed separately but is part of the OpenDNSSEC project, and its definition is shown below. The element names will be explained later.
As indicated, any number of repositories can be specified in the configuration file:
(The example above is commented out by the XML comment delimiters.)
- <Repository> - the definition of a repository is bracketed by the <Repository> and </Repository> elements. The name attribute must be supplied and must be unique. It is this name that is used in the kasp.xml file to identify which repository holds the keys. This field is limited to 30 characters.
- <Module> identifies the dynamic-link library that controls the repository. Each type of HSM will have its own library.
- <TokenLabel> identifies the "token" within the HSM that is being used - essentially a form of sub-repository. The token label is also used where there are two repositories of the same type, in that each repository should contain a different token label sub-repository. OpenDNSSEC will automatically go to the right HSM based on this. This field is limited to 32 characters.
- <PIN> is the password to the HSM. OpenDNSSEC have this stored en-claire in the configuration file. Later versions will allow the option of requiring the password to be typed in when OpenDNSSEC is started.
- <Capacity> indicates the maximum number of keys the HSM can store. It is an optional element - if there is no (realistic) limit to the number of keys, remove it.
- <RequireBackup> is an optional element that specifies that keys from this repository may not be used until they are backed up. If backup has been done, then use ods-ksmutil to notify OpenDNSSEC about this. The backup notification is needed for OpenDNSSEC to be able to complete a key rollover.
- <SkipPublicKey> is an optional element which specifies that the public key objects should not be stored or handled in the HSM. The public key is needed in order to create the DNSKEY RR. In theory, the public part of the key is also available in the private key object. However, the PKCS#11 API does not require the HSM to behave in this way. We have not seen a HSM where we cannot do this, but you should remove this flag if you are having any problem with it. The benefit of adding this flag is that you save space in your HSM, because you are only storing the private key object.
The list of repositories ends with the closing tag.
These are the configuration that is shared among the components of OpenDNSSEC.
All components of OpenDNSSEC logs errors, warnings and progress information. This is configurable and defined in the <Logging> element. Currently, the only syslog() feature configurable via the OpenDNSSEC configuration file is the facility name under which messages are logged. This can be any of the names listed in the operating system's syslog header file (usually /usr/include/sys/syslog.h, but the location is system dependent). <Verbosity> controls the level of logging, 0 will disable logging and 3 (default level) will provide informational log messages. You can set it higher to get debug log messages.
Although any facility listed there can be used, it is recommended that one of the "local" facilities (usually "local0" through "local7") be used.
Then you also have pointers to where the policy and zone list files can be found. There are also an optional element where you specify the path of the zone fetch configuration used for inbound AXFR.
The KASP enforcer component of OpenDNSSEC - which deals with key rollover and key generation - has its own section in the configuration file:
<!-- <PidFile>/var/run/opendnssec/enforcerd.pid</PidFile> -->
<!-- <ManualKeyGeneration/> -->
<!-- <RolloverNotification>P14D</RolloverNotification> -->
<!-- <DelegationSignerSubmitCommand>/usr/local/sbin/eppclient</DelegationSignerSubmitCommand> -->
The section is bracketed by the <Enforcer> .. </Enforcer> tags.
The Enforcer can drop its privileges if specified.
You can configure the Enforcer pidfile location with <PidFile>. This is introduced in version 1.3.18.
The database used by the Enforcer is specified by the <Datastore> tag. OpenDNSSEC supports SQLite and MySQL, the choice being indicated by one of two mutually exclusive tags:
If SQLite is the database in use, the <Datastore> tag must contain a single <SQLite> tag which specifies the database file in use (as shown above).
If MySQL is in use, then the <Datastore> contains a single <MySQL> tag, which in turn contains elements that describe the database connection. The following XML elements shows this:
- <Host> is the name of the system on which the database resides. It is optional - if omitted, the database is assumed to run on the same system as OpenDNSSEC. The "port" attribute gives the port to which the MySQL connection is made. It too is optional, and defaults to 3306 if omitted.
- <Database> is the name of the database holding the KASP Enforcer data.
- <Username> is the username needed to connect to the database.
- <Password> is the password associated with the username.
Other Enforcer Parameters
- <Interval> is how often the Enforcer runs to check whether keys are coming up for expiry and should be rolled. The more frequently this is run, the closer will the usage of keys reflect the policy set for it. However, if the key lifetimes are in the order of months, an <Interval> of the order of a day to a week is sufficient.
- <ManualKeyGeneration/> will disable the automatic key generation in the Enforcer. The user have to generate the keys itself with the ods-ksmutil key generate command.
- <RolloverNotification> specifies how long before a KSK rollover the Enforcer should start logging messages about the future rollover.
Configure the <DelegationSignerSubmitCommand> if you want to have a program/script receiving the new KSK during a key rollover. This will make it possible to create a fully automatic KSK rollover, where OpenDNSSEC feed your program/script on stdin with the current set of DNSKEYs that we want to have in the parent as DS RRs.
There are two examples available: an eppclient and a simple mail script. Remember that the ods-ksmutil key ds-seen must be given in order to complete the rollover. This should only be done when the new DS RRs are available on the parents public nameservers.
The Signer Engine of OpenDNSSEC - the part that constructs signature records to include in to the zone file - also has its own section in the configuration file:
Delimited by the <Signer> .. </Signer> tags, the components are:
- <WorkingDirectory> defines the location in which the Signer Engine will create temporary files.
- <WorkerThreads> specify the number of workers. One worker can handle one zone a time. When it is finished with the zone it takes the next one in queue.
- <SignerThreads> specify the number of threads that are dedicated to signing RRsets. Usually set to the number of parallel operations your HSM can handle. If the element is omitted from the configuration, the number of signer threads is equal to the number of workers.
- <NotifyCommand> optional element that will tell the Signer Engine to call this command when the zone has been signed. Will expand the following variables: %zone (the name of the zone that was signed) and %zonefile (the filename of the signed zone).
The Auditor can check a signed zone against the policy and the unsigned zone. This is to verify that the everything is done correctly.
Delimited by the <Auditor> .. </Auditor> tags, the components are:
- <Privileges> the Auditor can drop its privileges if specified.
- <WorkingDirectory> defines the location in which the Auditor will create temporary files.
As there are no more elements, the </Configuration> tag closes the file.
For the auditor to be used you will also need to add the Audit tag to the policy in kasp.xml.