- PERFORMANCE OF THIS SOFTWARE.
-->
-<!-- $Id: dnssec-signzone.docbook,v 1.31.44.6 2009/06/09 01:47:19 each Exp $ -->
+<!-- $Id: dnssec-signzone.docbook,v 1.44 2009/12/03 23:18:16 each Exp $ -->
<refentry id="man.dnssec-signzone">
<refentryinfo>
- <date>June 08, 2009</date>
+ <date>June 05, 2009</date>
</refentryinfo>
<refmeta>
<arg><option>-a</option></arg>
<arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<arg><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
+ <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
<arg><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
<arg><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
<arg><option>-g</option></arg>
<arg><option>-h</option></arg>
+ <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
<arg><option>-k <replaceable class="parameter">key</replaceable></option></arg>
<arg><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
<arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
<arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
<arg><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
<arg><option>-p</option></arg>
+ <arg><option>-P</option></arg>
<arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
+ <arg><option>-S</option></arg>
<arg><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
+ <arg><option>-T <replaceable class="parameter">ttl</replaceable></option></arg>
<arg><option>-t</option></arg>
+ <arg><option>-u</option></arg>
<arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
+ <arg><option>-x</option></arg>
<arg><option>-z</option></arg>
<arg><option>-3 <replaceable class="parameter">salt</replaceable></option></arg>
<arg><option>-H <replaceable class="parameter">iterations</replaceable></option></arg>
</varlistentry>
<varlistentry>
- <term>-k <replaceable class="parameter">key</replaceable></term>
+ <term>-C</term>
<listitem>
<para>
- Treat specified key as a key signing key ignoring any
- key flags. This option may be specified multiple times.
+ Compatibility mode: Generate a
+ <filename>keyset-<replaceable>zonename</replaceable></filename>
+ file in addition to
+ <filename>dsset-<replaceable>zonename</replaceable></filename>
+ when signing a zone, for use by older versions of
+ <command>dnssec-signzone</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-l <replaceable class="parameter">domain</replaceable></term>
+ <term>-d <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
- Generate a DLV set in addition to the key (DNSKEY) and DS sets.
- The domain is appended to the name of the records.
+ Look for <filename>dsset-</filename> or
+ <filename>keyset-</filename> files in <option>directory</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-d <replaceable class="parameter">directory</replaceable></term>
+ <term>-E <replaceable class="parameter">engine</replaceable></term>
<listitem>
<para>
- Look for <filename>keyset</filename> files in
- <option>directory</option> as the directory
+ Uses a crypto hardware (OpenSSL engine) for the crypto operations
+ it supports, for instance signing with private keys from
+ a secure key store. When compiled with PKCS#11 support
+ it defaults to pkcs11; the empty name resets it to no engine.
</para>
</listitem>
</varlistentry>
<term>-g</term>
<listitem>
<para>
- Generate DS records for child zones from keyset files.
- Existing DS records will be removed.
+ Generate DS records for child zones from
+ <filename>dsset-</filename> or <filename>keyset-</filename>
+ file. Existing DS records will be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-K <replaceable class="parameter">directory</replaceable></term>
+ <listitem>
+ <para>
+ Key repository: Specify a directory to search for DNSSEC keys.
+ If not specified, defaults to the current directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-k <replaceable class="parameter">key</replaceable></term>
+ <listitem>
+ <para>
+ Treat specified key as a key signing key ignoring any
+ key flags. This option may be specified multiple times.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-l <replaceable class="parameter">domain</replaceable></term>
+ <listitem>
+ <para>
+ Generate a DLV set in addition to the key (DNSKEY) and DS sets.
+ The domain is appended to the name of the records.
</para>
</listitem>
</varlistentry>
the start time. A time relative to the current time is
indicated with now+N. If no <option>end-time</option> is
specified, 30 days from the start time is used as a default.
+ <option>end-time</option> must be later than
+ <option>start-time</option>.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>-P</term>
+ <listitem>
+ <para>
+ Disable post sign verification tests.
+ </para>
+ <para>
+ The post sign verification test ensures that for each algorithm
+ in use there is at least one non revoked self signed KSK key,
+ that all revoked KSK keys are self signed, and that all records
+ in the zone are signed by the algorithm.
+ This option skips these tests.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-r <replaceable class="parameter">randomdev</replaceable></term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>-S</term>
+ <listitem>
+ <para>
+ Smart signing: Instructs <command>dnssec-signzone</command> to
+ search the key repository for keys that match the zone being
+ signed, and to include them in the zone if appropriate.
+ </para>
+ <para>
+ When a key is found, its timing metadata is examined to
+ determine how it should be used, according to the following
+ rules. Each successive rule takes priority over the prior
+ ones:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ If no timing metadata has been set for the key, the key is
+ published in the zone and used to sign the zone.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <para>
+ If the key's publication date is set and is in the past, the
+ key is published in the zone.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <para>
+ If the key's activation date is set and in the past, the
+ key is published (regardless of publication date) and
+ used to sign the zone.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <para>
+ If the key's revocation date is set and in the past, and the
+ key is published, then the key is revoked, and the revoked key
+ is used to sign the zone.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <para>
+ If either of the key's unpublication or deletion dates are set
+ and in the past, the key is NOT published or used to sign the
+ zone, regardless of any other metadata.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-T <replaceable class="parameter">ttl</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the TTL to be used for new DNSKEY records imported
+ into the zone from the key repository. If not specified,
+ the default is the minimum TTL value from the zone's SOA
+ record. This option is ignored when signing without
+ <option>-S</option>, since DNSKEY records are not imported
+ from the key repository in that case. It is also ignored if
+ there are any pre-existing DNSKEY records at the zone apex,
+ in which case new records' TTL values will be set to match
+ them.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-t</term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>-u</term>
+ <listitem>
+ <para>
+ Update NSEC/NSEC3 chain when re-signing a previously signed
+ zone. With this option, a zone signed with NSEC can be
+ switched to NSEC3, or a zone signed with NSEC3 can
+ be switch to NSEC or to NSEC3 with different parameters.
+ Without this option, <command>dnssec-signzone</command> will
+ retain the existing chain when re-signing.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-v <replaceable class="parameter">level</replaceable></term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>-x</term>
+ <listitem>
+ <para>
+ Only sign the DNSKEY RRset with key-signing keys, and omit
+ signatures from zone-signing keys. (This is similar to the
+ <command>dnssec-dnskey-kskonly yes;</command> zone option in
+ <command>named</command>.)
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-z</term>
<listitem>
<para>
- Ignore KSK flag on key when determining what to sign.
+ Ignore KSK flag on key when determining what to sign. This
+ causes KSK-flagged keys to sign all records, not just the
+ DNSKEY RRset. (This is similar to the
+ <command>update-check-ksk no;</command> zone option in
+ <command>named</command>.)
</para>
</listitem>
</varlistentry>
<term>-3 <replaceable class="parameter">salt</replaceable></term>
<listitem>
<para>
- Generate a NSEC3 chain with the given hex encoded salt.
+ Generate an NSEC3 chain with the given hex encoded salt.
A dash (<replaceable class="parameter">salt</replaceable>) can
be used to indicate that no salt is to be used when generating the NSEC3 chain.
</para>
<term>-H <replaceable class="parameter">iterations</replaceable></term>
<listitem>
<para>
- When generating a NSEC3 chain use this many interations. The
- default is 100.
+ When generating an NSEC3 chain, use this many interations. The
+ default is 10.
</para>
</listitem>
</varlistentry>
<term>-A</term>
<listitem>
<para>
- When generating a NSEC3 chain set the OPTOUT flag on all
+ When generating an NSEC3 chain set the OPTOUT flag on all
NSEC3 records and do not generate NSEC3 records for insecure
delegations.
</para>
+ <para>
+ Using this option twice (i.e., <option>-AA</option>)
+ turns the OPTOUT flag off for all records. This is useful
+ when using the <option>-u</option> option to modify an NSEC3
+ chain which previously had OPTOUT set.
+ </para>
</listitem>
</varlistentry>
<para>
The following command signs the <userinput>example.com</userinput>
zone with the DSA key generated by <command>dnssec-keygen</command>
- (Kexample.com.+003+17247). The zone's keys must be in the master
- file (<filename>db.example.com</filename>). This invocation looks
- for <filename>keyset</filename> files, in the current directory,
- so that DS records can be generated from them (<command>-g</command>).
+ (Kexample.com.+003+17247). Because the <command>-S</command> option
+ is not being used, the zone's keys must be in the master file
+ (<filename>db.example.com</filename>). This invocation looks
+ for <filename>dsset</filename> files, in the current directory,
+ so that DS records can be imported from them (<command>-g</command>).
</para>
<programlisting>% dnssec-signzone -g -o example.com db.example.com \
Kexample.com.+003+17247
%</programlisting>
</refsect1>
- <refsect1>
- <title>KNOWN BUGS</title>
- <para>
- <command>dnssec-signzone</command> was designed so that it could
- sign a zone partially, using only a subset of the DNSSEC keys
- needed to produce a fully-signed zone. This permits a zone
- administrator, for example, to sign a zone with one key on one
- machine, move the resulting partially-signed zone to a second
- machine, and sign it again with a second key.
- </para>
- <para>
- An unfortunate side-effect of this flexibility is that
- <command>dnssec-signzone</command> does not check to make sure
- it's signing a zone with any valid keys at all. An attempt to
- sign a zone without any keys will appear to succeed, producing
- a "signed" zone with no signatures. There is no warning issued
- when a zone is not fully signed.
- </para>
-
- <para>
- This will be corrected in a future release. In the meantime, ISC
- recommends examining the output of <command>dnssec-signzone</command>
- to confirm that the zone is properly signed by all keys before
- using it.
- </para>
- </refsect1>
-
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>