~mcf/dnssec-rr

0f581a8430129d0418a457c6722207af17e95d62 — Michael Forney 3 years ago b30fe34 0.1
Add manuals
6 files changed, 355 insertions(+), 0 deletions(-)

M Makefile
A dnskey.1
A ds.1
A nsec.1
A rrsig.1
A tlsa.1
M Makefile => Makefile +3 -0
@@ 4,6 4,7 @@

PREFIX?=/usr/local
BINDIR?=$(PREFIX)/bin
MANDIR?=$(PREFIX)/share/man
CFLAGS+=-Wall -Wpedantic
LDLIBS?=-lbearssl



@@ 40,6 41,8 @@ dnskey.o ds.o nsec.o rrsig.o $(COMMON_OBJ): dnssec.h
install: $(TOOLS)
	mkdir -p $(DESTDIR)$(BINDIR)
	cp $(TOOLS) $(DESTDIR)$(BINDIR)/
	mkdir -p $(DESTDIR)$(MANDIR)/man1
	cp $(TOOLS:%=%.1) $(DESTDIR)$(MANDIR)/man1/

clean:
	rm -f $(TOOLS) $(TOOLS:%=%.o) libcommon.a $(COMMON_OBJ)

A dnskey.1 => dnskey.1 +66 -0
@@ 0,0 1,66 @@
.Dd May 10, 2021
.Dt DNSKEY 1
.Os
.Sh NAME
.Nm dnskey
.Nd generate DNSSEC DNSKEY record
.Sh SYNOPSIS
.Nm dnskey
.Op Fl k
.Op Fl t Ar ttl
.Op Fl c Ar class
.Ar domain
.Ar keyfile
.Sh DESCRIPTION
.Nm
writes a DNSSEC DNSKEY record to standard output.
.Pp
The record is generated with the name
.Ar domain
and public key given by
.Ar keyfile .
.Pp
A DNSKEY record contains a public key that can be used to verify
the signatures of the records in a zone.
If the Secure Entry Point (SEP) flag is set, the key may be used
to verify signatures of the DNSKEY RRset.
Otherwise, it may only be used to verify the signatures of other
record types.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl k
Set the Secure Entry Point (SEP) flag.
.It Fl a
The signature algorithm to use with the key.
This option can be used to disambiguate the hash used with RSA keys.
The following algorithms are supported:
.Bl -bullet -compact
.It
RSASHA1
.It
RSASHA256 (default for RSA keys)
.It
RSASHA512
.It
ECDSAP256SHA256
.It
ECDSAP384SHA384
.El
.It Fl t
The TTL value of the record.
If not specified, the TTL is omitted.
.It Fl c
The record class.
Defaults to IN.
.El
.Sh EXAMPLES
Generate a DNSKEY record with the SEP flag set for the key in key.pem.
.Bd -literal -offset indent
$ dnskey -k example.com. key.pem
example.com.    IN      DNSKEY  257 3 13 vj2jYoUXYP5L/Y3VKwy2tv1lTQKvieaDdg2DpZRItJ0TblzoKoJ+9WQgxi4/mq0JkFUFeltRmhPnhtXoCH7Tfw==
.Ed
.Sh See ALSO
.Xr ds 1 ,
.Xr nsec 1 ,
.Xr rrsig 1 ,
.Xr tlsa 1

A ds.1 => ds.1 +71 -0
@@ 0,0 1,71 @@
.Dd May 9, 2021
.Dt DS 1
.Os
.Sh NAME
.Nm ds
.Nd generate DNSSEC delegation signer record
.Sh SYNOPSIS
.Nm ds
.Op Fl Ar d digest
.Op Fl Ar t ttl
.Op Fl Ar c class
.Ar domain
.Ar keyfile
.Sh DESCRIPTION
.Nm
writes a DNSSEC DS record to standard output.
.Pp
The record is generated for the child zone
.Ar domain
and public key given by
.Ar keyfile .
The child zone should have a corresponding self-signed DNSKEY record
with the Secure Entry Point (SEP) flag set.
.Pp
A DS record is delegates record signing for a sub-zone to a particular
key, establishing a chain of trust from a parent zone to its child.
It contains a signature algorithm identifier, the hash of the public
key, and a
.Dq tag
used to identify the key.
It indicates that the signature of the DNSKEY RRSet of the child
zone may be verified with the described key.
.Pp
DS records are usually configured through a web form provided by
the domain registrar.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d
The digest algorithm to use.
The following algorithms are supported:
.Bl -bullet -compact
.It
SHA1 (1)
.It
SHA256 (2, default)
.It
SHA384 (4)
.El
.It Fl a
The signature algorithm to use with the key.
This option can be used to disambiguate the hash used with RSA keys.
Supported algorithms are the same as in
.Xr dnskey 1 .
.It Fl t
The TTL value of the record.
If not specified, the TTL is omitted.
.It Fl c
The record class.
Defaults to IN.
.El
.Sh EXAMPLES
Generate a DS record for the example.com EC signing key, key.pem:
.Bd -literal -offset indent
$ ds example.com. key.pem
example.com.    IN      DS      32716 13 2 ffd819c99ed62247e5fa61711a53fc0202a35970ca8ec78d874e2667556c594b
.Ed
.Sh SEE ALSO
.Xr dnskey 1 ,
.Xr nsec 1 ,
.Xr rrsig 1 ,
.Xr tlsa 1

A nsec.1 => nsec.1 +36 -0
@@ 0,0 1,36 @@
.Dd May 10, 2021
.Dt NSEC 1
.Os
.Sh NAME
.Nm nsec
.Nd generate NSEC records for a zone
.Sh SYNOPSIS
.Nm nsec
.Op Ar zonefile
.Sh DESCRIPTION
.Nm
writes DNSSEC NSEC records for a zone to standard output.
.Pp
The records are generated for the zone described in
.Ar zonefile ,
which must be in the format described by RFC 1035.
.Pp
An NSEC record lists the record types available at a particular
name, and the next valid name in the zone.
It is used to fill in the gaps between the valid records in a zone
and is returned alongside its signature in NXDOMAIN responses to
prove the absence of the requested record.
.Sh OPTIONS
None.
.Sh EXAMPLES
Generate NSEC records for the example.com zone:
.Bd -literal -offset indent
$ nsec example.com.zone
example.com.    1200    IN      NSEC    ns1.example.com. A NS SOA RRSIG NSEC DNSKEY
ns1.example.com.        1200    IN      NSEC    example.com. A RRSIG NSEC
.Ed
.Sh SEE ALSO
.Xr dnskey 1 ,
.Xr ds 1 ,
.Xr rrsig 1 ,
.Xr tlsa 1

A rrsig.1 => rrsig.1 +67 -0
@@ 0,0 1,67 @@
.Dd May 10, 2021
.Dt RRSIG 1
.Os
.Sh NAME
.Nm rrsig
.Nd generate RRSIG records for a zone
.Sh SYNOPSIS
.Nm rrsig
.Op Fl kz
.Op Fl s Ar start
.Op Fl e Ar end
.Ar keyfile
.Op Ar zonefile
.Sh DESCRIPTION
.Nm
signs the records in a zone and writes DNSSEC RRSIG records to standard output.
.Pp
The signatures are generated for the zone described in
.Ar zonefile ,
which must be in the format described by RFC 1035.
.Pp
An RRSIG record contains a signature for a set of DNS records
(RRset), all with the same name and type.
These records are returned along with the results of a query and
the signatures can be verified with the public keys in the DNSKEY
records for the domain.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl k
Sign the DNSKEY records in the zone.
The key in
.Ar keyfile
must have a DNSKEY record in the zone with the SEP flag set.
.It Fl z
Sign the non-DNSKEY records in the zone.
The key in
.Ar keyfile
must have a DNSKEY record in the zone.
.It Fl s
The unix time at which the signature becomes valid.
.It Fl e
The unix time after which the signature is no longer valid.
.El
.Pp
If neither
.Fl k
or
.Fl z
is specified, all records in the zone are signed.
.Sh EXAMPLES
Sign the records in the example.com zone with the key in key.pem
.Bd -literal -offset indent
$ rrsig key.pem example.com.zone
example.com.    86400   IN      RRSIG   SOA 13 2 86400 20200616002419 20200517002419 32716 example.com. pT8tmBBTpTG139CBJbN1MbshvygYyaiNn713gmvMw2Y/C2dTwGSZwuriXOk7luLb+Ej9OHvcjgaNaVzWnu5IiQ==
example.com.    86400   IN      RRSIG   A 13 2 86400 20200616002419 20200517002419 32716 example.com. ziulNlLfYTwUO0VGiVW4TSR3Pfg8j/RhUhuWCbL2rn9PVBUIr3P0ql5JHkfskfCy9BNDIW7rSIWxwuLBULfudw==
example.com.    86400   IN      RRSIG   NS 13 2 86400 20200616002419 20200517002419 32716 example.com. 9FdDokZ6RWGcAZTgpB430T71t9NZWeCZLTqxkeDyi77vxDt5eRwCNdzdDIEYaChGIfX6NBcrFIZ9Arz7vEA+ww==
example.com.    1200    IN      RRSIG   NSEC 13 2 1200 20200616002419 20200517002419 32716 example.com. QeClnuEuVdq0Wppv+kH0DNR3huWFw7Rack0ZuFRqEpRLfVx/NTaaieHBax4SJTgecaF2MgpT+f/yJsRe/rsr3g==
example.com.    86400   IN      RRSIG   DNSKEY 13 2 86400 20200616002419 20200517002419 32716 example.com. ypFHj/ttCnJkzOsCSj+SM+pU7yj9jfT7IaHZpotrU1ITOQBj2x+5nhQSj7dAbi21N4Vjie1rS5vx7E6T2g0msg==
ns1.example.com.        86400   IN      RRSIG   A 13 3 86400 20200616002419 20200517002419 32716 example.com. /M9W4asOST8JuRfibKA0hf780GX3HglEsgB1PoNuV2PCK5sTXWKVexb7wfxAeBAK/gDsLy3HQIPH2im6iRuI9g==
ns1.example.com.        1200    IN      RRSIG   NSEC 13 3 1200 20200616002419 20200517002419 32716
example.com. Mph6z5j6ZePdrxoO/vBr1rwA76a/0lpkUEfsiNWOtELtoPCNRrhRDxvQWM/mPfRw+plfzFXqANymU5shvPwZZA==
.Ed
.Sh SEE ALSO
.Xr dnskey 1 ,
.Xr ds 1 ,
.Xr rrsig 1 ,
.Xr tlsa 1

A tlsa.1 => tlsa.1 +112 -0
@@ 0,0 1,112 @@
.Dd May 10, 2021
.Dt TLSA 1
.Os
.Sh NAME
.Nm tlsa
.Nd generate DANE TLSA record
.Sh SYNOPSIS
.Nm tlsa
.Op Fl u Ar usage
.Op Fl s Ar selector
.Op Fl m Ar match
.Op Fl t Ar ttl
.Op Fl c Ar class
.Ar domain
.Ar certfile
.Sh DESCRIPTION
.Nm
writes a DANE TLSA record to standard output.
.Pp
The record is generated with the name
.Ar domain
using the certificate in
.Ar certfile .
.Pp
A TLSA record specifies the TLS certificate validation policy for
the server running on the port and transport protocol given in the
name prefix.
The prefix is formed by the prepending the decimal port number and
protocol name to the domain name, each as their own label beginning
with
.Sq _ .
For example, an HTTPS server running on www.example.com TCP port
443 would use the name _443._tcp.www.example.com.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl u
The usage type of the record, specifying how the TLS certificate
should be validated.
Possible values are:
.Bl -tag -width "pkix-ta (0)"
.It Cm pkix-ta (0)
Standard PKIX certificate validation, except that the specified certificate
.Em must
match a certificate authority (CA) in the server's certificate chain.
.It Cm pkix-ee (1)
Standard PKIX certificate validation, except that the specified certificate
.Em must
match the end-entity (EE) in the server's certificate chain.
.It Cm dane-ta (2)
The certificate
.Em must
match a certificate authority (CA) in the server's certificate chain.
The CA need not be part of the client's trusted CA set.
.It Cm dane-ee (3)
The certificate
.Em must
match the end-entity (EE) in the server's certificate chain.
PKIX validation is skipped.
.El
.Pp
The default is 
.Cm dane-ee .
.It Fl s
The selector of the record, specifying which part of the TLS
certificate should be matched against.
Possible values are:
.Bl -tag -width "pubkey (1)"
.It Cm cert (0)
Match the full Certificate.
.It Cm pubkey (1)
Match only the SubjectPublicKeyInfo substructure of the Certificate.
.El
.Pp
The default is
.Cm pubkey .
.It Fl m
The matching type of the record, specifying how the certificate
association data is presented.
Possible values are:
.Bl -tag -width "sha256 (1)"
.It Cm exact (0)
The selected part of the certificate is presented in-full as the
certificate association data.
.It Cm sha256 (1)
The SHA256 hash of the selected part of the certificate is used as
the certificate association data.
.It Cm sha512 (2)
The SHA512 hash of the selected part of the certificate is used as
the certificate association data.
.El
.Pp
The default is
.Cm sha256 .
.It Fl t
The TTL value of the record.
If not specified, the TTL is omitted.
.It Fl c
The record class.
Defaults to IN.
.El
.Sh EXAMPLES
Generate a TLSA record for an HTTPS server running on example.com
TCP port 443:
.Bd -literal -offset indent
$ tlsa _443._tcp.www.example.com. cert.pem
_443._tcp.www.example.com.	IN	TLSA	3 1 1 8bd1da95272f7fa4ffb24137fc0ed03aae67e5c4d8b3c50734e1050a7920b922
.Ed
.Sh SEE ALSO
.Xr dnskey 1 ,
.Xr ds 1 ,
.Xr nsec 1 ,
.Xr rrsig 1