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
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 an optional element containing the password to the HSM. OpenDNSSEC have this stored en-claire in the configuration file. If the PIN is not present in the configuration file, then it must be entered by using the command ods-hsmutil login.
- <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. (If the backup is not done then the old key will remain in use.)
- <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:
The section is bracketed by the <Enforcer> .. </Enforcer> tags.
- <Privileges> The Enforcer can drop its privileges if specified.
- <PidFile> The location of the pidfile. Introduced in 1.4.6.
- <WorkerThreads> This option is not supported in the stable 1.4 release. If it used it is silently ignored. Multiple worker threads were supported in early beta versions of 1.4 and this option was left in the conf.xml file for compatibility. It will be removed in 2.0.
- <Datastore> The database used by the Enforcer is specified by the <Datastore> tag. OpenDNSSEC supports SQLite and MySQL (MySQL is the recommended choice for production environments), 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.
- <DelegationSignerSubmitCommand> 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.
Key Identifier: If the command defined here ends with " --cka_id" then that will be stripped off the command and "; <CKA_ID>" will be added to the output.
An example script for the <DelegationSignerSubmitCommand> command is available: which is a simple mail script (from 1.4 the eppclient is no longer supported). 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:
- <Privileges> the Signer Engine can drop its privileges if specified.
- <PidFile> the Signer Engine pidfile location. Introduced in 1.4.6.
- <SocketFile> the command handler socket file location. Introduced in 1.4.6.
- <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.
- <Listener>is an element that is needed when you use DNS adapters. Within this element, you can specify a number of interfaces the Signer Engine has to listen to for DNS traffic, such as queries, NOTIFY messages and zone transfer requests.
- <Interface> has two optional elements: <Address> and <Port>.
- Note that if no IP address is given, the Signer Engine defaults to both local IPv4 and IPv6 address.
- The default port is 53.
- <Interface> has two optional elements: <Address> and <Port>.
- <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 has been removed from OpenDNSSEC since 1.4.0.
As there are no more elements, the </Configuration> tag closes the file.