dnssec-settime.docbook revision d7be2b79ed0934483d550e17e2bd09de4eaff8f5
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews [<!ENTITY mdash "—">]>
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - Copyright (C) 2009-2011 Internet Systems Consortium, Inc. ("ISC")
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - Permission to use, copy, modify, and/or distribute this software for any
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - purpose with or without fee is hereby granted, provided that the above
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - copyright notice and this permission notice appear in all copies.
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
bf8267aa453e5d2a735ed732a043b77a0b355b20Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer<!-- $Id: dnssec-settime.docbook,v 1.15 2011/11/03 20:21:37 each Exp $ -->
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <refentryinfo>
8aee18709f238406719768b8a6b843a15c5075f8Mark Andrews </refentryinfo>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt <refentrytitle><application>dnssec-settime</application></refentrytitle>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt <refnamediv>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt <refname><application>dnssec-settime</application></refname>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt <refpurpose>Set the key timing metadata for a DNSSEC key</refpurpose>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt </refnamediv>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
30a60d2aff0ec1810262a8b8efc532e28b32bd57Evan Hunt </copyright>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <refsynopsisdiv>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <cmdsynopsis>
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <arg><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
c634c94d673f1bab17e7f65d332f989b683e712cDavid Lawrence <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
c634c94d673f1bab17e7f65d332f989b683e712cDavid Lawrence <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
28002bd7cb4baa0eab9f47e1e51069c5ea7ea5d4Andreas Gustafsson <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
1d32b1df372d6be6bac6450739b9e5ea23819995Evan Hunt </cmdsynopsis>
1d32b1df372d6be6bac6450739b9e5ea23819995Evan Hunt </refsynopsisdiv>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer reads a DNSSEC private key file and sets the key timing metadata
c634c94d673f1bab17e7f65d332f989b683e712cDavid Lawrence as specified by the <option>-P</option>, <option>-A</option>,
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <option>-R</option>, <option>-I</option>, and <option>-D</option>
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer options. The metadata can then be used by
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer <command>dnssec-signzone</command> or other signing software to
c634c94d673f1bab17e7f65d332f989b683e712cDavid Lawrence determine when a key is to be published, whether it should be
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer used for signing a zone, etc.
c634c94d673f1bab17e7f65d332f989b683e712cDavid Lawrence If none of these options is set on the command line,
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer then <command>dnssec-settime</command> simply prints the key timing
c3c6770e537ea916265c78d0294ad108233e17c1Michael Sawyer metadata already stored in the key.
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt When key metadata fields are changed, both files of a key
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt pair (<filename>Knnnn.+aaa+iiiii.key</filename> and
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <filename>Knnnn.+aaa+iiiii.private</filename>) are regenerated.
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt Metadata fields are stored in the private file. A human-readable
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt description of the metadata is also placed in comments in the key
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt file. The private file's permissions are always set to be
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt inaccessible to anyone other than the owner (mode 0600).
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <variablelist>
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt <varlistentry>
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt Force an update of an old-format key with no metadata fields.
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt Without this option, <command>dnssec-settime</command> will
9069215eac23e32f4ef1c8e44ad7ff2865cfcdacEvan Hunt fail when attempting to update a legacy key. With this option,
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt the key will be recreated in the new format, but with the
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt original key data retained. The key's creation date will be
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt set to the present time. If no other values are specified,
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt then the key's publication and activation dates will also
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt be set to the present time.
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt </varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <term>-K <replaceable class="parameter">directory</replaceable></term>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt Sets the directory in which the key files are to reside.
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt </varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <term>-L <replaceable class="parameter">ttl</replaceable></term>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt Sets the default TTL to use for this key when it is converted
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt into a DNSKEY RR. If the key is imported into a zone,
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt this is the TTL that will be used for it, unless there was
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt already a DNSKEY RRset in place, in which case the existing TTL
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt would take precedence. Setting the default TTL to
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <literal>0</literal> or <literal>none</literal> removes it.
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt </varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt <varlistentry>
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt Emit usage message and exit.
b5b934a0bb46aded1552a17473652b5a7f4a3274Evan Hunt </varlistentry>
47e70d820ed07895a25e5b3520adf953114ac01eEvan Hunt <varlistentry>
47e70d820ed07895a25e5b3520adf953114ac01eEvan Hunt <term>-v <replaceable class="parameter">level</replaceable></term>
47e70d820ed07895a25e5b3520adf953114ac01eEvan Hunt Sets the debugging level.
47e70d820ed07895a25e5b3520adf953114ac01eEvan Hunt </varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <term>-E <replaceable class="parameter">engine</replaceable></term>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt Use the given OpenSSL engine. When compiled with PKCS#11 support
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt it defaults to pkcs11; the empty name resets it to no engine.
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt </varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt </variablelist>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt If the argument begins with a '+' or '-', it is interpreted as
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt an offset from the present time. For convenience, if such an offset
2a6d60615cf07b164533dbb6bb1dce84ed2d037dEvan Hunt is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
2a6d60615cf07b164533dbb6bb1dce84ed2d037dEvan Hunt then the offset is computed in years (defined as 365 24-hour days,
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt ignoring leap years), months (defined as 30 24-hour days), weeks,
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt days, hours, or minutes, respectively. Without a suffix, the offset
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt is computed in seconds. To unset a date, use 'none'.
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <variablelist>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <term>-P <replaceable class="parameter">date/offset</replaceable></term>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt Sets the date on which a key is to be published to the zone.
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt After that date, the key will be included in the zone but will
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt not be used to sign it.
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt </varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <term>-A <replaceable class="parameter">date/offset</replaceable></term>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt Sets the date on which the key is to be activated. After that
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt date, the key will be included in the zone and used to sign
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt </varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <varlistentry>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt <term>-R <replaceable class="parameter">date/offset</replaceable></term>
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt Sets the date on which the key is to be revoked. After that
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt date, the key will be flagged as revoked. It will be included
6de9744cf9c64be2145f663e4051196a4eaa9d45Evan Hunt in the zone and will be used to sign it.
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt </varlistentry>
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt <varlistentry>
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt <term>-I <replaceable class="parameter">date/offset</replaceable></term>
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt Sets the date on which the key is to be retired. After that
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt date, the key will still be included in the zone, but it
cba23be7ba724b527f6a60c14caaeca9502fbc79Evan Hunt will not be used to sign it.
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews </varlistentry>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <varlistentry>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <term>-D <replaceable class="parameter">date/offset</replaceable></term>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews Sets the date on which the key is to be deleted. After that
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews date, the key will no longer be included in the zone. (It
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews may remain in the key repository, however.)
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews </varlistentry>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <varlistentry>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews <term>-S <replaceable class="parameter">predecessor key</replaceable></term>
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews Select a key for which the key being modified will be an
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews explicit successor. The name, algorithm, size, and type of the
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews predecessor key must exactly match those of the key being
a69070d8fab55dbc63ba9f96c9d3e34f0ea9119aMark Andrews modified. The activation date of the successor key will be set
c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer to the inactivation date of the predecessor. The publication
c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer date will be set to the activation date minus the prepublication
c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer interval, which defaults to 30 days.
c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer </varlistentry>
c5272fb3303425f794dab68f734f6a2a45dce01eMichael Sawyer <varlistentry>
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer <term>-i <replaceable class="parameter">interval</replaceable></term>
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer Sets the prepublication interval for a key. If set, then
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer the publication and activation dates must be separated by at least
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer this much time. If the activation date is specified but the
2de413d956c9f065958aaeebf5cd3a420e55939cMichael Sawyer publication date isn't, then the publication date will default
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer to this much time before the activation date; conversely, if
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer the publication date is specified but activation date isn't,
6b9c29ec578de7fda057bd3b893ccda176378b1bMichael Sawyer then activation will be set to this much time after publication.
1b003261c2dd3e32778337c7a2788e4829066bd9Andreas Gustafsson If the key is being set to be an explicit successor to another
1b003261c2dd3e32778337c7a2788e4829066bd9Andreas Gustafsson key, then the default prepublication interval is 30 days;
1b003261c2dd3e32778337c7a2788e4829066bd9Andreas Gustafsson otherwise it is zero.
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson As with date offsets, if the argument is followed by one of
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson interval is measured in years, months, weeks, days, hours,
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson or minutes, respectively. Without a suffix, the interval is
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson measured in seconds.
3ad7f12f7439471a0922ed3952221e93aef9db69Andreas Gustafsson </varlistentry>
0759eb6a0dab024873df528b0ffad804ea31615dMichael Sawyer </variablelist>
dc9c461b27df798ba7c3d9ba1446840c5f85553bMichael Sawyer <command>dnssec-settime</command> can also be used to print the
dc9c461b27df798ba7c3d9ba1446840c5f85553bMichael Sawyer timing metadata associated with a key.
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <variablelist>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <varlistentry>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson Print times in UNIX epoch format.
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson </varlistentry>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <varlistentry>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <term>-p <replaceable class="parameter">C/P/A/R/I/D/all</replaceable></term>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson Print a specific metadata value or set of metadata values.
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson The <option>-p</option> option may be followed by one or more
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson of the following letters to indicate which value or values to print:
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <option>C</option> for the creation date,
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <option>A</option> for the activation date,
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <option>R</option> for the revocation date,
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <option>I</option> for the inactivation date, or
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson To print all of the metadata, use <option>-p all</option>.
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson </varlistentry>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson </variablelist>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson </citerefentry>,
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <citerefentry>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson </citerefentry>,
5337a9e53c7df1ef40d70528f2360c5e4cb9a7d1Andreas Gustafsson <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
8aee18709f238406719768b8a6b843a15c5075f8Mark Andrews <para><corpauthor>Internet Systems Consortium</corpauthor>
8aee18709f238406719768b8a6b843a15c5075f8Mark Andrews - Local variables:
8aee18709f238406719768b8a6b843a15c5075f8Mark Andrews - mode: sgml