ldnssec-utils/ldnssec-keygen.1

178 lines
4.9 KiB
Groff

.\"
.\" ldnssec-keygen.1
.\" Written in 2021 by Lucas
.\" CC0 1.0 Universal/Public domain - No rights reserved
.\"
.\" To the extent possible under law, the author(s) have dedicated all
.\" copyright and related and neighboring rights to this software to the
.\" public domain worldwide. This software is distributed without any
.\" warranty. You should have received a copy of the CC0 Public Domain
.\" Dedication along with this software. If not, see
.\" <http://creativecommons.org/publicdomain/zero/1.0/>.
.\"
.Dd December 14, 2021
.Dt LDNSSEC-KEYGEN 1
.Os
.Sh NAME
.Nm ldnssec-keygen
.Nd DNSSEC key management utility
.Sh SYNOPSIS
.Nm
.Cm dnskey
.Op Fl d Ar domain
.Op Fl k
.Nm
.Cm ds
.Op Fl a Ar algorithm
.Op Fl d Ar domain
.Nm
.Cm filename
.Op Fl d Ar domain
.Nm
.Cm gen
.Op Fl a Ar algorithm
.Op Fl b Ar bits
.Sh DESCRIPTION
.Nm
is a utiility for managing DNSSEC signing keys.
It allows for generating private keys,
printing the corresponding DS or DNSKEY records for those keys,
and printing a BIND / LDNS filename.
.Bl -tag -width Ds
.It Nm Cm dnskey Oo Fl d Ar domain Oc Oo Fl k Oc
Read a private key from
.Em stdin
and print the corresponding DNSKEY resource record.
If
.Fl d Ar domain
is provided, use
.Ar domain
as the owner name for the resource record.
If
.Fl k
is provided, set the
.Em SEP
flag in the resource record, signalling the key should be used as a
.Em KSK .
.It Nm Cm ds Oo Fl a Ar algorithm Oc Oo Fl d Ar domain Oc
Read a private key from
.Em stdin
and print the corresponding DS resource record.
If
.Fl a Ar algorithm
is provided, use that algorithm for the fingerprint, instead of the default
.Em SHA-256 .
If
.Fl d Ar domain
is provided, use
.Ar domain
as the owner name for the resource record.
.Nm
.Cm ds
will unconditionally treat the provided key as a
.Em KSK .
.It Nm Cm filename Op Fl d Ar domain
Read a private key from
.Em stdin
and print the corresponding base filename for it,
in the same fashion as BIND or LDNS:
.Em K<domain>+<algorithm_id>+<keytag> .
If
.Fl d Ar domain
is provided, use
.Ar domain
as the domain name.
.It Nm Cm gen Oo Fl a Ar algorithm Oc Oo Fl b Ar bits Oc
Generate a private key and print it to
.Em stdout .
If
.Fl a Ar algorithm
is provided, generate a key for
.Ar algorithm
instead of the default of
.Em ECDSAP256SHA256 .
If
.Fl b Ar bits
is provided, generate a key of size
.Ar bits .
Do note that not all the supported algorithms support specifying a key size.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
To create a private key suitable for DNSSEC signing
.Bd -literal -offset indent
$ ldnssec-keygen gen | tee sk
Private-key-format: v1.2
Algorithm: 13 (ECDSAP256SHA256)
PrivateKey: ET6oewFD3NSZ+mKMgN9rWHKRZc9ULiGpILVjrUr+vko=
.Ed
.Pp
Do note that this command doesn't specify the domain the key will be used for,
nor the use for the generated key:
it can be used either as a KSK or a ZSK.
The following commands will define its use.
.Pp
If the generated key will be used as a
.Em ZSK
for the zone
.Em zsk.example. ,
then
.Bd -literal -offset indent
$ ldnssec-keygen filename -d zsk.example. <sk
Kzsk.example.+013+53821
.Ed
.Pp
After checking that there is no colliding keytag between the existing keys,
it can be renamed with
.Bd -literal -offset indent
$ mv sk "$(ldnssec-keygen filename -d zsk.example. <sk).private"
.Ed
.Pp
and the corresponding DNSKEY record can be generated with
.Bd -literal -offset indent
$ ldnssec-keygen dnskey -d zsk.example. <Kzsk.example.+013+53821.private
ksk.example. 3600 IN DNSKEY 256 3 13 g02jgUGsc01VjH2bUM9Dob5ulaA+BuS6krmrXCmI6buHp8+eFESwIGO+m/Vv3WC7pllgyKCCS5Ve9U07QD/3Ag== ;{id = 53821 (zsk), size = 256b}
.Ed
.Pp
If instead the key was intended to be used as a
.Em KSK
for the zone
.Em ksk.example. ,
then
.Bd -literal -offset indent
$ ldnssec-keygen filename -d ksk.example. -k <sk
Kksk.example.+013+53822
.Ed
.Pp
Again,
after checking that there is no colliding keytag between the existing keys,
it can be renamed with
.Bd -literal -offset indent
$ mv sk "$(ldnssec-keygen filename -d ksk.example. -k <sk).private"
.Ed
.Pp
The corresponding DNSKEY record can be generated with
.Bd -literal -offset indent
$ ldnssec-keygen dnskey -d ksk.example. -k <Kksk.example.+013+53822.private
ksk.example. 3600 IN DNSKEY 257 3 13 g02jgUGsc01VjH2bUM9Dob5ulaA+BuS6krmrXCmI6buHp8+eFESwIGO+m/Vv3WC7pllgyKCCS5Ve9U07QD/3Ag== ;{id = 53822 (ksk), size = 256b}
.Ed
.Pp
(notice that the flags field is now 257 instead of 256),
and the DS record can be generated with
.Bd -literal -offset indent
$ ldnssec-keygen ds -d ksk.example. <Kksk.example.+013+53822.private
ksk.example. 3600 IN DS 53822 13 2 a48dcfa340625b26d428c6034d5e679c28ae1ccfcc7cd8b4649287e15306cb7b
.Ed
.Sh AUTHORS
.An Lucas
.Sh LICENSE
.Nm
is in the public domain.
.Pp
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to the
public domain worldwide.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/