DNSSEC: documentation

ref #4

doc/configuration.texi

@@ -13,6 +13,7 @@ In this chapter we provide suggested configurations and explain the meaning of i
 * Enabling zone semantic checks::
 * Creating IXFR differences from zone file changes::
 * Using Response Rate Limiting::
+* Online DNSSEC signing (experimental)::
 @end menu
 
 @node Minimal configuration
@@ -283,3 +284,120 @@ system @{
 	rate-limit-slip 1; # Every response is slipped (default)
 @}
 @end example
+
+@node Online DNSSEC signing (experimental)
+@section Online DNSSEC signing (experimental)
+
+Knot DNS 1.4 is the first release to include online DNSSEC signing feature.
+Online DNSSEC signing is currently highly experimental and there is a lot of
+issues we are working on and limitations we will try to eliminate. By all
+means, anything in the current implementation can change including
+configuration options. We have no intention to maintain backward compatibility.
+
+@subsection Example configuration
+
+The example configuration enables automatic signing for all zones using
+@ref{dnssec-enable} option in the @code{zones} section, but the signing is
+explicitly disabled for zone @code{example.dev} using the same option directly
+in zone configuration. The location of directory with signing keys is set
+globally by option @ref{dnssec-keydir}.
+
+@sp 1
+
+@example
+zones @{
+  dnssec-enable on;
+  dnssec-keydir "/var/lib/knot/keys";
+
+  example.com @{
+    file "example.com.zone";
+  @}
+
+  example.dev @{
+    file "example.dev.zone";
+    dnssec-enable off;
+  @}
+@}
+@end example
+
+@subsection Signing keys
+
+The signing keys can be generated using ISC @code{dnssec-keygen} tool only
+and there are some limitations:
+
+@itemize @bullet
+@item
+Keys for all zones must be placed in one directory.
+
+@item
+Algorithms based on RSA, DSA, and ECDSA are supported, support for GOST
+algorithm not finished yet.
+
+@item
+Only key activation and inactivation time stamps are utilized and defined
+times are used both for key publication and signing. Other timestamps are
+ignored.
+
+@item
+It is required, that both @code{.private} and @code{.key} files for each key
+are available in the key directory in order to use the keys (even for
+verification only).
+
+@item
+There cannot be more than eight active keys per zone.
+
+@end itemize
+
+@sp 1
+
+Example how to generate NSEC3 capable zone signing key (ZSK) and key signing
+key (KSK) for zone @code{example.com}:
+
+@sp 1
+@example
+$ cd /var/lib/knot/keys
+$ dnssec-keygen -3 example.com
+$ dnssec-keygen -3 -f KSK example.com
+@end example
+
+@subsection Signing policy
+
+Currently the signing policy is set hard in the server:
+
+@itemize @bullet
+@item Signature lifetime is 30 days.
+@item Signature is refreshed 2 hours before expiration.
+@end itemize
+
+@subsection Zone signing
+
+The signing process consists of following steps:
+
+@itemize @bullet
+@item
+Fixing @code{NSEC} and @code{NSEC3} records. This is determined by
+@code{NSEC3PARAM} record presence in unsigned zone.
+
+@item
+Updating @code{DNSKEY} records. This also means removing all keys which are
+not present in directory with signing keys.
+
+@item
+Removing expired signatures, invalid signatures, signatures expiring in a short
+time, and signatures with unknown key.
+
+@item
+Creating any missing signatures. @code{DNSKEY} records are signed by both ZSK
+and KSK keys, other records are signed only by ZSK keys.
+
+@item
+SOA record is updated and resigned if any changes were performed.
+
+@end itemize
+
+@sp 1
+
+The zone signing is performed when the zone is loaded into server, on zone
+reload, before any signature is expiring, and after DDNS update. The signing
+can be also forced using @code{signzone} command issued by @code{knotc}, in
+this case all signatures are recreated.

doc/reference.texi

@@ -50,6 +50,8 @@ else.
   [ @code{rate-limit-size} @kbd{integer}@code{;} ]
   [ @code{rate-limit-slip} @kbd{integer}@code{;} ]
   [ @code{max-udp-payload} @kbd{integer}@code{;} ]
+  [ @code{dnssec-enable} ( @code{on} | @code{off} )@code{;} ]
+  [ @code{dnssec-keydir} @kbd{string}@code{;} ]
 @code{@}}
 @end example
 
@@ -73,6 +75,8 @@ else.
 * rate-limit-size::
 * rate-limit-slip::
 * max-udp-payload::
+* dnssec-enable::
+* dnssec-keydir::
 @end menu
 
 @node identity
@@ -271,6 +275,22 @@ Maximum EDNS0 UDP payload size.
 
 Default value: @kbd{4096}
 
+@node dnssec-enable
+@subsubsection dnssec-enable
+@vindex dnssec-enable
+
+Enable DNSSEC signing for all zones.
+
+Default value: @code{on} if @code{dnssec-keydir} is set
+
+@node dnssec-keydir
+@subsubsection dnssec-keydir
+@vindex dnssec-keydir
+
+Location with DNSSEC signing keys.
+
+Default value: not set
+
 @node system Example
 @subsection system Example
 
@@ -731,6 +751,7 @@ The @code{zones} statement contains definition of zones served by Knot DNS.
   [ @code{zonefile-sync} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
   [ @code{ixfr-fslimit} ( @kbd{integer} | @kbd{integer}(@code{k} | @code{M} | @code{G}) )@code{;} ]
   [ @code{ixfr-from-differences} @kbd{boolean}@code{;} ]
+  [ @code{dnssec-enable} ( @code{on} | @code{off} )@code{;} ]
 @end example
 
 @node zones Statement Definition and Grammar
@@ -751,6 +772,7 @@ The @code{zones} statement contains definition of zones served by Knot DNS.
 * notify-retries::
 * zonefile-sync::
 * ixfr-fslimit::
+* dnssec-enable/zone::
 @end menu
 
 @node zone_id
@@ -855,6 +877,14 @@ are 1 to INT_MAX and default value is 5.
 
 @code{ixfr-fslimit} sets a maximum file size for zone's journal in bytes. Possible values are 1 to INT_MAX, with optional suffixes k, m and G. I.e. @emph{1k}, @emph{1m} and @emph{1G} with default value not being set, meaning that journal file can grow without limitations.
 
+@node dnssec-enable/zone
+@subsubsection dnssec-enable
+@vindex dnssec-enable
+
+Enable DNSSEC signing for the zone.
+
+Default value: inherited from global value set in @code{zones} section.
+
 @node zones Example
 @subsection zones Example