dnssec-settime.docbook revision eec29cfd40361662b25bad50e1b94f7738a8fea0
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User [<!ENTITY mdash "—">]>
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC")
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - Permission to use, copy, modify, and/or distribute this software for any
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - purpose with or without fee is hereby granted, provided that the above
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - copyright notice and this permission notice appear in all copies.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User - PERFORMANCE OF THIS SOFTWARE.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User<!-- $Id: dnssec-settime.docbook,v 1.6 2009/10/16 15:37:01 jreed Exp $ -->
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refentryinfo>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <refentrytitle><application>dnssec-settime</application></refentrytitle>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <refname><application>dnssec-settime</application></refname>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refpurpose>Set the key timing metadata for a DNSSEC key</refpurpose>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </refnamediv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refsynopsisdiv>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <cmdsynopsis>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
9d557856c2a19ec95ee73245f60a92f8675cf5baTinderbox User <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </cmdsynopsis>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </refsynopsisdiv>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User reads a DNSSEC private key file and sets the key timing metadata
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User as specified by the <option>-P</option>, <option>-A</option>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <option>-R</option>, <option>-I</option>, and <option>-D</option>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User options. The metadata can then be used by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <command>dnssec-signzone</command> or other signing software to
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User determine when a key is to be published, whether it should be
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User used for signing a zone, etc.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User If none of these options is set on the command line,
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User then <command>dnssec-settime</command> simply prints the key timing
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User metadata already stored in the key.
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User When key metadata fields are changed, both files of a key
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User pair (<filename>Knnnn.+aaa+iiiii.key</filename> and
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <filename>Knnnn.+aaa+iiiii.private</filename>) are regenerated.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Metadata fields are stored in the private file. A human-readable
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User description of the metadata is also placed in comments in the key
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <variablelist>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Force an update of an old-format key with no metadata fields.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Without this option, <command>dnssec-settime</command> will
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User fail when attempting to update a legacy key. With this option,
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User the key will be recreated in the new format, but with the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User original key data retained. The key's creation date will be
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User set to the present time.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <term>-K <replaceable class="parameter">directory</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Sets the directory in which the key files are to reside.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Emit usage message and exit.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-v <replaceable class="parameter">level</replaceable></term>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Sets the debugging level.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-E <replaceable class="parameter">engine</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Use the given OpenSSL engine. When compiled with PKCS#11 support
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User it defaults to pcks11, the empty name resets it to no engine.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </variablelist>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User If the argument begins with a '+' or '-', it is interpreted as
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User an offset from the present time. For convenience, if such an offset
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User then the offset is computed in years (defined as 365 24-hour days,
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User ignoring leap years), months (defined as 30 24-hour days), weeks,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User days, hours, or minutes, respectively. Without a suffix, the offset
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User is computed in seconds. To unset a date, use 'none'.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <variablelist>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-P <replaceable class="parameter">date/offset</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Sets the date on which a key is to be published to the zone.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User After that date, the key will be included in the zone but will
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User not be used to sign it.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <term>-A <replaceable class="parameter">date/offset</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Sets the date on which the key is to be activated. After that
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User date, the key will be included in the zone and used to sign
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-R <replaceable class="parameter">date/offset</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Sets the date on which the key is to be revoked. After that
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User date, the key will be flagged as revoked. It will be included
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User in the zone and will be used to sign it.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-I <replaceable class="parameter">date/offset</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Sets the date on which the key is to be retired. After that
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User date, the key will still be included in the zone, but it
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User will not be used to sign it.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-D <replaceable class="parameter">date/offset</replaceable></term>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Sets the date on which the key is to be deleted. After that
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User date, the key will no longer be included in the zone. (It
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User may remain in the key repository, however.)
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </variablelist>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <command>dnssec-settime</command> can also be used to print the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User timing metadata associated with a key.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <variablelist>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Print times in UNIX epoch format.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varlistentry>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <term>-p <replaceable class="parameter">C/P/A/R/U/D/all</replaceable></term>
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User Print a specific metadata value or set of metadata values.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User The <option>-p</option> option may be followed by one or more
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User of the following letters to indicate which value or values to print:
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User <option>U</option> for the unpublication date, or
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User To print all of the metadata, use <option>-p all</option>.
9a5087bf58f651bfff841192aba5afd06760d6ceTinderbox User </varlistentry>