summaryrefslogtreecommitdiffstats
path: root/bin/dnssec/dnssec-keyfromlabel.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--bin/dnssec/dnssec-keyfromlabel.rst262
1 files changed, 262 insertions, 0 deletions
diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst
new file mode 100644
index 0000000..57ab9c8
--- /dev/null
+++ b/bin/dnssec/dnssec-keyfromlabel.rst
@@ -0,0 +1,262 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. _man_dnssec-keyfromlabel:
+
+dnssec-keyfromlabel - DNSSEC key generation tool
+------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`dnssec-keyfromlabel` {**-l** label} [**-3**] [**-a** algorithm] [**-A** date/offset] [**-c** class] [**-D** date/offset] [**-D** sync date/offset] [**-E** engine] [**-f** flag] [**-G**] [**-I** date/offset] [**-i** interval] [**-k**] [**-K** directory] [**-L** ttl] [**-n** nametype] [**-P** date/offset] [**-P** sync date/offset] [**-p** protocol] [**-R** date/offset] [**-S** key] [**-t** type] [**-v** level] [**-V**] [**-y**] {name}
+
+Description
+~~~~~~~~~~~
+
+``dnssec-keyfromlabel`` generates a pair of key files that reference a
+key object stored in a cryptographic hardware service module (HSM). The
+private key file can be used for DNSSEC signing of zone data as if it
+were a conventional signing key created by ``dnssec-keygen``, but the
+key material is stored within the HSM and the actual signing takes
+place there.
+
+The ``name`` of the key is specified on the command line. This must
+match the name of the zone for which the key is being generated.
+
+Options
+~~~~~~~
+
+``-a algorithm``
+ This option selects the cryptographic algorithm. The value of ``algorithm`` must
+ be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512,
+ ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448.
+
+ These values are case-insensitive. In some cases, abbreviations are
+ supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for
+ ECDSAP384SHA384. If RSASHA1 is specified along with the ``-3``
+ option, then NSEC3RSASHA1 is used instead.
+
+ This option is mandatory except when using the
+ ``-S`` option, which copies the algorithm from the predecessory key.
+
+ .. versionchanged:: 9.12.0
+ The default value RSASHA1 for newly generated keys was removed.
+
+``-3``
+ This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this
+ option is used with an algorithm that has both NSEC and NSEC3
+ versions, then the NSEC3 version is used; for example,
+ ``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm.
+
+``-E engine``
+ This option specifies the cryptographic hardware to use.
+
+ When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
+ engine identifier that drives the cryptographic accelerator or
+ hardware service module (usually ``pkcs11``). When BIND is
+ built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it
+ defaults to the path of the PKCS#11 provider library specified via
+ ``--with-pkcs11``.
+
+``-l label``
+ This option specifies the label for a key pair in the crypto hardware.
+
+ When BIND 9 is built with OpenSSL-based PKCS#11 support, the label is
+ an arbitrary string that identifies a particular key. It may be
+ preceded by an optional OpenSSL engine name, followed by a colon, as
+ in ``pkcs11:keylabel``.
+
+ When BIND 9 is built with native PKCS#11 support, the label is a
+ PKCS#11 URI string in the format
+ ``pkcs11:keyword\ =value[;\ keyword\ =value;...]``. Keywords
+ include ``token``, which identifies the HSM; ``object``, which identifies
+ the key; and ``pin-source``, which identifies a file from which the
+ HSM's PIN code can be obtained. The label is stored in the
+ on-disk ``private`` file.
+
+ If the label contains a ``pin-source`` field, tools using the
+ generated key files are able to use the HSM for signing and other
+ operations without any need for an operator to manually enter a PIN.
+ Note: Making the HSM's PIN accessible in this manner may reduce the
+ security advantage of using an HSM; use caution
+ with this feature.
+
+``-n nametype``
+ This option specifies the owner type of the key. The value of ``nametype`` must
+ either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY
+ (for a key associated with a host (KEY)), USER (for a key associated
+ with a user (KEY)), or OTHER (DNSKEY). These values are
+ case-insensitive.
+
+``-C``
+ This option enables compatibility mode, which generates an old-style key, without any metadata.
+ By default, ``dnssec-keyfromlabel`` includes the key's creation
+ date in the metadata stored with the private key; other dates may
+ be set there as well, including publication date, activation date, etc. Keys
+ that include this data may be incompatible with older versions of
+ BIND; the ``-C`` option suppresses them.
+
+``-c class``
+ This option indicates that the DNS record containing the key should have the
+ specified class. If not specified, class IN is used.
+
+``-f flag``
+ This option sets the specified flag in the ``flag`` field of the KEY/DNSKEY record.
+ The only recognized flags are KSK (Key-Signing Key) and REVOKE.
+
+``-G``
+ This option generates a key, but does not publish it or sign with it. This option is
+ incompatible with ``-P`` and ``-A``.
+
+``-h``
+ This option prints a short summary of the options and arguments to
+ ``dnssec-keyfromlabel``.
+
+``-K directory``
+ This option sets the directory in which the key files are to be written.
+
+``-k``
+ This option generates KEY records rather than DNSKEY records.
+
+``-L`` ttl
+ This option sets the default TTL to use for this key when it is converted into a
+ DNSKEY RR. This is the TTL used when the key is imported into a zone,
+ unless there was already a DNSKEY RRset in
+ place, in which case the existing TTL would take precedence. Setting
+ the default TTL to ``0`` or ``none`` removes it.
+
+``-p protocol``
+ This option sets the protocol value for the key. The protocol is a number between
+ 0 and 255. The default is 3 (DNSSEC). Other possible values for this
+ argument are listed in :rfc:`2535` and its successors.
+
+``-S key``
+ This option generates a key as an explicit successor to an existing key. The name,
+ algorithm, size, and type of the key are set to match the
+ predecessor. The activation date of the new key is set to the
+ inactivation date of the existing one. The publication date is
+ set to the activation date minus the prepublication interval, which
+ defaults to 30 days.
+
+``-t type``
+ This option indicates the type of the key. ``type`` must be one of AUTHCONF,
+ NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers
+ to the ability to authenticate data, and CONF to the ability to encrypt
+ data.
+
+``-v level``
+ This option sets the debugging level.
+
+``-V``
+ This option prints version information.
+
+``-y``
+ This option allows DNSSEC key files to be generated even if the key ID would
+ collide with that of an existing key, in the event of either key
+ being revoked. (This is only safe to enable if
+ :rfc:`5011` trust anchor maintenance is not used with either of the keys
+ involved.)
+
+Timing Options
+~~~~~~~~~~~~~~
+
+Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
+argument begins with a ``+`` or ``-``, it is interpreted as an offset from
+the present time. For convenience, if such an offset is followed by one
+of the suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, then the offset is
+computed in years (defined as 365 24-hour days, ignoring leap years),
+months (defined as 30 24-hour days), weeks, days, hours, or minutes,
+respectively. Without a suffix, the offset is computed in seconds. To
+explicitly prevent a date from being set, use ``none`` or ``never``.
+
+``-P date/offset``
+ This option sets the date on which a key is to be published to the zone. After
+ that date, the key is included in the zone but is not used
+ to sign it. If not set, and if the ``-G`` option has not been used, the
+ default is the current date.
+
+``-P sync date/offset``
+ This option sets the date on which CDS and CDNSKEY records that match this key
+ are to be published to the zone.
+
+``-A date/offset``
+ This option sets the date on which the key is to be activated. After that date,
+ the key is included in the zone and used to sign it. If not set,
+ and if the ``-G`` option has not been used, the default is the current date.
+
+``-R date/offset``
+ This option sets the date on which the key is to be revoked. After that date, the
+ key is flagged as revoked. It is included in the zone and
+ is used to sign it.
+
+``-I date/offset``
+ This option sets the date on which the key is to be retired. After that date, the
+ key is still included in the zone, but it is not used to
+ sign it.
+
+``-D date/offset``
+ This option sets the date on which the key is to be deleted. After that date, the
+ key is no longer included in the zone. (However, it may remain in the key
+ repository.)
+
+``-D sync date/offset``
+ This option sets the date on which the CDS and CDNSKEY records that match this
+ key are to be deleted.
+
+``-i interval``
+ This option sets the prepublication interval for a key. If set, then the
+ publication and activation dates must be separated by at least this
+ much time. If the activation date is specified but the publication
+ date is not, the publication date defaults to this much time
+ before the activation date; conversely, if the publication date is
+ specified but not the activation date, activation is set to
+ this much time after publication.
+
+ If the key is being created as an explicit successor to another key,
+ then the default prepublication interval is 30 days; otherwise it is
+ zero.
+
+ As with date offsets, if the argument is followed by one of the
+ suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, the interval is
+ measured in years, months, weeks, days, hours, or minutes,
+ respectively. Without a suffix, the interval is measured in seconds.
+
+Generated Key Files
+~~~~~~~~~~~~~~~~~~~
+
+When ``dnssec-keyfromlabel`` completes successfully, it prints a string
+of the form ``Knnnn.+aaa+iiiii`` to the standard output. This is an
+identification string for the key files it has generated.
+
+- ``nnnn`` is the key name.
+
+- ``aaa`` is the numeric representation of the algorithm.
+
+- ``iiiii`` is the key identifier (or footprint).
+
+``dnssec-keyfromlabel`` creates two files, with names based on the
+printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
+``Knnnn.+aaa+iiiii.private`` contains the private key.
+
+The ``.key`` file contains a DNS KEY record that can be inserted into a
+zone file (directly or with an $INCLUDE statement).
+
+The ``.private`` file contains algorithm-specific fields. For obvious
+security reasons, this file does not have general read permission.
+
+See Also
+~~~~~~~~
+
+:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
+:rfc:`4034`, :rfc:`7512`.