From 1e3e61ba53ad2ef12b48a2b32190ece06e2b6203 Mon Sep 17 00:00:00 2001 From: Mark Andrews Date: Thu, 5 Jun 2025 15:33:35 +1000 Subject: [PATCH] Update man pages for deprecated algorithms --- bin/dnssec/dnssec-dsfromkey.rst | 69 +++++++++++++++++------------- bin/dnssec/dnssec-keyfromlabel.rst | 32 ++++++++------ bin/dnssec/dnssec-keygen.rst | 25 ++++++----- 3 files changed, 71 insertions(+), 55 deletions(-) diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index 9ca025a319..b23dff6164 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -32,30 +32,34 @@ Synopsis Description ~~~~~~~~~~~ -The :program:`dnssec-dsfromkey` command outputs DS (Delegation Signer) resource records -(RRs), or CDS (Child DS) RRs with the :option:`-C` option. +The :program:`dnssec-dsfromkey` command outputs DS (Delegation +Signer) resource records (RRs), or CDS (Child DS) RRs with the +:option:`-C` option. By default, only KSKs are converted (keys with flags = 257). The -:option:`-A` option includes ZSKs (flags = 256). Revoked keys are never -included. +:option:`-A` option includes ZSKs (flags = 256). Revoked keys are +never included. The input keys can be specified in a number of ways: -By default, :program:`dnssec-dsfromkey` reads a key file named in the format -``Knnnn.+aaa+iiiii.key``, as generated by :iscman:`dnssec-keygen`. +By default, :program:`dnssec-dsfromkey` reads a key file named in +the format ``Knnnn.+aaa+iiiii.key``, as generated by +:iscman:`dnssec-keygen`. -With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone -file or partial zone file (which can contain just the DNSKEY records). +With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` +reads keys from a zone file or partial zone file (which can contain +just the DNSKEY records). -With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file, -as generated by :iscman:`dnssec-keygen` :option:`-C`. +With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a +``keyset-`` file, as generated by :iscman:`dnssec-keygen` :option:`-C`. Options ~~~~~~~ .. option:: -1 - This option is an abbreviation for :option:`-a SHA1 <-a>`. + This option is an abbreviation for :option:`-a SHA1 <-a>`. This + digest is deprecated. .. option:: -2 @@ -63,24 +67,26 @@ Options .. option:: -a algorithm - This option specifies a digest algorithm to use when converting DNSKEY records to - DS records. This option can be repeated, so that multiple DS records - are created for each DNSKEY record. + This option specifies a digest algorithm to use when converting + DNSKEY records to DS records. This option can be repeated, so + that multiple DS records are created for each DNSKEY record. - The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values - are case-insensitive, and the hyphen may be omitted. If no algorithm - is specified, the default is SHA-256. + The algorithm must be one of SHA-1 (deprecated), SHA-256, or + SHA-384. These values are case-insensitive, and the hyphen may + be omitted. If no algorithm is specified, the default is SHA-256. .. option:: -A - This option indicates that ZSKs are to be included when generating DS records. Without this option, only - keys which have the KSK flag set are converted to DS records and - printed. This option is only useful in :option:`-f` zone file mode. + This option indicates that ZSKs are to be included when generating + DS records. Without this option, only keys which have the KSK + flag set are converted to DS records and printed. This option + is only useful in :option:`-f` zone file mode. .. option:: -c class - This option specifies the DNS class; the default is IN. This option is only useful in :option:`-s` keyset - or :option:`-f` zone file mode. + This option specifies the DNS class; the default is IN. This + option is only useful in :option:`-s` keyset or :option:`-f` + zone file mode. .. option:: -C @@ -88,10 +94,10 @@ Options .. option:: -f file - This option sets zone file mode, in which the final dnsname argument of :program:`dnssec-dsfromkey` is the - DNS domain name of a zone whose master file can be read from - ``file``. If the zone name is the same as ``file``, then it may be - omitted. + This option sets zone file mode, in which the final dnsname + argument of :program:`dnssec-dsfromkey` is the DNS domain name + of a zone whose master file can be read from ``file``. If the + zone name is the same as ``file``, then it may be omitted. If ``file`` is ``-``, then the zone data is read from the standard input. This makes it possible to use the output of the :iscman:`dig` @@ -105,16 +111,19 @@ Options .. option:: -K directory - This option tells BIND 9 to look for key files or ``keyset-`` files in ``directory``. + This option tells BIND 9 to look for key files or ``keyset-`` + files in ``directory``. .. option:: -s - This option enables keyset mode, in which the final dnsname argument from :program:`dnssec-dsfromkey` is the DNS - domain name used to locate a ``keyset-`` file. + This option enables keyset mode, in which the final dnsname + argument from :program:`dnssec-dsfromkey` is the DNS domain name + used to locate a ``keyset-`` file. .. option:: -T TTL - This option specifies the TTL of the DS records. By default the TTL is omitted. + This option specifies the TTL of the DS records. By default the + TTL is omitted. .. option:: -v level diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 64d0ec720d..3e1814512d 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -41,27 +41,31 @@ Options .. option:: -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. + This option selects the cryptographic algorithm. The value of + ``algorithm`` must be one of RSASHA1 (deprecated), NSEC3RSASHA1 + (deprecated), 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 :option:`-3` - option, then NSEC3RSASHA1 is used instead. + These values are case-insensitive. In some cases, abbreviations + are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 + for ECDSAP384SHA384. If RSASHA1 (deprecated) is specified along + with the :option:`-3` option, then NSEC3RSASHA1 (deprecated) is + used instead. - This option is mandatory except when using the - :option:`-S` option, which copies the algorithm from the predecessory key. + This option is mandatory except when using the :option:`-S` + option, which copies the algorithm from the predecessory key. .. versionchanged:: 9.12.0 - The default value RSASHA1 for newly generated keys was removed. + The default value RSASHA1 (deprecated) for newly generated + keys was removed. .. option:: -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. + 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 + (deprecated) algorithm. .. option:: -l label diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index ef12dbb134..6f828c292b 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -38,21 +38,24 @@ Options .. option:: -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 selected; for example, - ``dnssec-keygen -3 -a RSASHA1`` specifies the NSEC3RSASHA1 algorithm. + 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 selected; for + example, ``dnssec-keygen -3 -a RSASHA1`` specifies the NSEC3RSASHA1 + (deprecated) algorithm. .. option:: -a algorithm - This option selects the cryptographic algorithm. For DNSSEC keys, the value of - ``algorithm`` must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, - RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. + This option selects the cryptographic algorithm. For DNSSEC keys, + the value of ``algorithm`` must be one of RSASHA1 (deprecated), + NSEC3RSASHA1 (deprecated), 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 :option:`-3` - option, NSEC3RSASHA1 is used instead. + These values are case-insensitive. In some cases, abbreviations + are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 + for ECDSAP384SHA384. If RSASHA1 (deprecated) is specified along + with the :option:`-3` option, NSEC3RSASHA1 (deprecated) is used + instead. This parameter *must* be specified except when using the :option:`-S` option, which copies the algorithm from the predecessor key.