kasp.xml

Elements of the kasp.xml file

Preamble

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: kasp.xml.in 1154 2009-06-24 13:02:25Z jakob $ -->

Each XML file starts with a standard element "<?xml...". As with any XML file, comments are included between the delimiters "<!--"
and "-->".

Policy Description

<KASP>

The enclosing element of the XML file is the element <KASP> which, with the closing element </KASP>, brackets one or more policies.

...
	<Policy name="default">

Each policy is included in the <Policy>...</Policy> elements. Each policy has a "name" attribute giving the name of the policy. The name is used to link a policy and the zones signed using it; each policy must have a unique name.

The policy named "default" is special, as it is associated with all zones that do not have a policy explicitly associated with them.

...
		<Description>A default policy that will amaze you and your friends</Description>

A policy can have a description associated with it. Unlike XML comments, the description can be understood by programs and may be used to document the policy, e.g. a future GUI may display a list of policies along with their description and ask you to select one for editing.

Signatures

The next section of the file is the Signatures section, which lists the parameters for the signatures created using the policy.

...
		<Signatures>
			<Resign>PT2H</Resign>
			<Refresh>P3D</Refresh>
			<Validity>
					<Default>P14D</Default>
					<Denial>P14D</Denial>
			</Validity>
			<Jitter>PT12H</Jitter>
			<InceptionOffset>PT300S</InceptionOffset>
		</Signatures>

Here:

• <Resign> is the re-sign interval, which is the interval between runs of the Signer Engine.
• <Refresh> is the refresh interval, detailing when a signature should be refreshed. As signatures are typically valid for much longer than the interval between runs of the signer, there is no need to re-generate the signatures each time the signer is run if there is no change to the data being signed. The signature will be refreshed when the time until the signature expiration is closer than the refresh interval. Set it to zero if you want to refresh the signatures each re-sign interval.
• <Validity> groups two elements of information related to how long the signatures are valid for - <Default> is the validity interval for all RRSIG records except those related to NSEC or NSEC3 records. In this case, the validity period is given by the value in the <Denial> element.
• <Jitter> is the value added to or extracted from the expiration time of signatures to ensure that not all signatures expire at the same time. The actual value of the <Jitter> element is the -j + r %2j, where j is the jitter value and r a random duration, uniformly ranging between -j and j, is added to signature validity period to get the signature expiration time.
• <InceptionOffset> is a duration subtracted from the time at which a record is signed to give the start time of the record. This is required to allow for clock skew between the signing system and the system on which the signature is checked. Without it, the possibility exists that the checking system could retrieve a signature whose start time is later than the current time.

The relationship between these elements is shown below. 

...

		<Denial>
			<NSEC3>
				<TTL>PT3600S</TTL>
				<OptOut/>
				<Resalt>P100D</Resalt>
				<Hash>
					<Algorithm>1</Algorithm>
					<Iterations>5</Iterations>
					<Salt length="8"/>
				</Hash>
			</NSEC3>
		</Denial>

...
		<Keys>

Common Parameters

The section starts with a number of parameters relating to both zone-signing keys (ZSK) and key-signing keys (KSK):

...
			<TTL>PT3600S</TTL>
			<RetireSafety>PT3600S</RetireSafety>
                        <PublishSafety>PT3600S</PublishSafety>
			<ShareKeys/>
			<Purge>P14D</Purge>

• <TTL> is the time-to-live value for the DNSKEY resource records.
• <PublishSafety> and <RetireSafety> are the publish and retire safety margins for the keys. These intervals are safety margins added to calculated timing values to give some extra time to cover unforeseen events, e.g. in case external events prevent zone publication.

If multiple zones are associated with a policy, the presence of <ShareKeys/> indicates that a key can be shared between zones. E.g. if you have 10 zones then you will only use one set of keys instead of 10 sets. This will save space in your HSM. If this tag is absent, keys are not shared between zones.

If <Purge> is present, keys marked as dead will be automatically purged from the database after this interval.

Key-Signing Keys

Parameters for key-signing keys are held in the <KSK> section:

...
			<KSK>
				<Algorithm length="2048">8</Algorithm>
				<Lifetime>P1Y</Lifetime>
				<Repository>softHSM</Repository>
				<!-- <Standby>1</Standby> (Experimental) -->
				<ManualRollover/>
			</KSK>

• <Algorithm> determines the algorithm used for the key (the numbers reserved for each algorithm can be found in the appropriate IANA registry).

  Once a zone is signed, changes to the algorithm require a rollover which is not currently handled by OpenDNSSEC. Attempts to change the algorithm on a policy will result in a warning message and a request for confirmation.

• <Lifetime> determines how long the key is used for before it is rolled.
• <Repository> determines the location of the keys. Keys are stored in "repositories" (currently, only hardware security modules (HSMs) or devices conforming to the PKCS#11 interface), which are defined in the conf.xml. In the example above, the key is stored in softHSM - the example configuration file distributed with OpenDNSSEC defines this as being the software emulation of an HSM distributed as part of OpenDNSSEC.
• <Standby> Experimental (we are currently not supporting offline HSM, which is needed to get the security level needed to fulfill the idea behind standby keys. Will be fixed in a future version) Determines the number of standby keys held in the zone. These keys allow the currently active key to be immediately retired should it be compromised, so enhancing the security of the system. (Without an standby key, additional time is required to allow information about the new key to reach validator caches - see http://tools.ietf.org/html/draft-ietf-dnsop-dnssec-key-timing-02 for timing details.)
• <ManualRollover/> is an optional tag. This tag indicate that the key rollover will only be initiated on the command by the operator. There is still a second step for the KSK, where the key needs to be published to the parent before the rollover is completed. Read more in the chapter "Running OpenDNSSEC". The ZSK rollover will although be fully automatic if this tag is not present.

Zone-Signing Keys

Parameters for zone-signing keys are held in the <ZSK> section, and have the same meaning as for the KSK:

...
			<ZSK>
				<Algorithm length="1024">8</Algorithm>
				<Lifetime>P90D</Lifetime>
				<Repository>softHSM</Repository>
				<!-- <Standby>1</Standby> (Experimental) -->
			</ZSK>

The ZSK information completes the contents of the <Keys> section.

...
		</Keys>

Zone Information

General information concerning the zones can be found in the <Zone> section:

...
		<Zone>
			<PropagationDelay>PT9999S</PropagationDelay>
			<SOA>
				<TTL>PT3600S</TTL>
				<Minimum>PT3600S</Minimum>
				<Serial>unixtime</Serial>
			</SOA>
		</Zone>

• <PropagationDelay> is the amount of time needed for information changes at the master server for the zone to work its way through to all the secondary nameservers.

• The <SOA> element gives values of parameters for the SOA record in the signed zone. 

  These values will override values set for the SOA record in the input zone file and the serial in signed and unsigned zone is likely to go out of sync.

  The values are:

  • <TTL> - TTL of the SOA record.
  • <Minimum> - value for the SOA's "minimum" parameter.
  • <Serial> - the format of the serial number in the signed zone. This is one of:
    • counter - use an increasing counter (but use the serial from the unsigned zone if possible)
    • datecounter - use increasing counter in YYYYMMDDxx format (xx is incremented within each day)
    • unixtime - the serial number is set to the "Unix time" (seconds since 00:00 on 1 January 1970 (UTC)) at which the signer is run.
    • keep - keep the serial from the unsigned zone (do not resign unless it has been incremented)

Parent Zone Information

If a DNSSEC zone is in a chain of trust, digest information about the KSKs used in the zone will be stored in DS records in the parent zone. To properly roll keys, timing information about the parent zone must be configured in the <Parent> section:

...
		<Parent>
			<PropagationDelay>PT9999S</PropagationDelay>
			<DS>
				<TTL>PT3600S</TTL>
			</DS>
			<SOA>
				<TTL>PT3600S</TTL>
				<Minimum>PT3600S</Minimum>
			</SOA>
		</Parent>

• <PropagationDelay> is the interval between the time a new KSK is published in the zone and the time that the DS record appears in the parent zone.
• The <DS> tag holds information about the DS record in the parent. It contains a single element, <TTL>, which should be set to the TTL of the DS record in the parent zone.
• <SOA> gives information about parameters of the parent's SOA record, used by KASP in its calculations. As before, <TTL> is the TTL of the SOA record and <Minimum> is the value of the "minimum" parameter.

This is the last section of the policy specification, so the next element is the policy closing tag:

...
	</Policy>

If there are any additional policies, they could be entered here, starting with <Policy> and ending with </Policy>. However, in this case there are no additional policies, so the file is ended by closing the <KASP> tag:

</KASP>