[thirdparty/pdns.git] / docs / dnssec / modes-of-operation.rst

DNSSEC Modes of Operation
=========================

Traditionally, DNSSEC signatures have been added to unsigned zones, and
then this signed zone could be served by any DNSSEC capable
authoritative server. PowerDNS supports this mode fully.

In addition, PowerDNS supports taking care of the signing itself, in
which case PowerDNS operates differently from most tutorials and
handbooks. This mode is easier, however.

For relevant tradeoffs, please see :doc:`../security` and
:doc:`../performance`.

.. _dnssec-online-signing:

Online Signing
--------------

In the simplest situation, there is a single "SQL" database that
contains, in separate tables, all domain data, keying material, and other
DNSSEC related settings.

This database is then replicated to all PowerDNS instances, which all
serve identical records, keys and signatures.

In this mode of operation, care should be taken that the database
replication occurs over a secure network, or over an encrypted
connection. This is because keying material, if intercepted, could be
used to counterfeit DNSSEC data using the original keys.

Such a single replicated database requires no further attention beyond
monitoring already required during non-DNSSEC operations.

Records, Keys, signatures, hashes within PowerDNS in online signing mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Within PowerDNS live signing, keys are stored separately from the zone
records. Zone data are only combined with signatures and keys when
requests come in over the internet.

Each zone can have a number of keys associated with it, with varying key
lengths. Typically 1 or at most 2 of these keys are employed as actual
Zone Signing Keys (ZSKs). During normal operations, this means that only
1 ZSK is 'active', and the other is inactive.

Should it be desired to 'roll over' to a new key, both keys can
temporarily be active (and used for signing), and after a while the old
key can be deactivated. Subsequently it can be removed.

As described above, there are several ways in which DNSSEC can deny the
existence of a record, and this setting, which is also stored away from zone
records, lives with the DNSSEC keying material.

(Hashed) Denial of Existence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PowerDNS supports unhashed secure denial of existence using NSEC
records. These are generated with the help of the (database) backend,
which needs to be able to supply the 'previous' and 'next' records in
canonical ordering.

The Generic SQL Backends have fields that allow them to supply these
relative record names.

In addition, hashed secure denial of existence is supported using NSEC3
records, in two modes, one with help from the database, the other with
the help of some additional calculations.

NSEC3 in 'broad' or 'inclusive' mode works with the aid of the backend,
where the backend should be able to supply the previous and next domain
names in hashed order.

NSEC3 in 'narrow' mode uses additional hashing calculations to provide
hashed secure denial of existence 'on the fly', without further
involving the database.

.. _dnssec-signatures:

Signatures
~~~~~~~~~~

In PowerDNS live signing mode, signatures, as served through RRSIG
records, are calculated on the fly, and heavily cached. All CPU cores
are used for the calculation.

RRSIGs have a validity period, in PowerDNS this period is 3 weeks.
This period starts at most a week in the past, and continues at least a week into the future.
This interval jumps with one-week increments every Thursday.

The time period used is always calculated based on the moment of rollover.
The inception timestamp is the most recent Thursday 00:00:00 UTC, which is exactly one week ago at the moment of rollover.
The expiry timestamp is the Thursday 00:00:00 UTC two weeks later from the moment of rollover.
Graphically, it looks like this::

  RRSIG(1) Inception                                                    RRSIG(1) Expiry
  |                                                                                   |
  v                                                                                   v
  |================================ RRSIG(1) validity ================================|
                              |================================ RRSIG(2) validity ================================|
                              ^                                                                                   ^
                              |                                                                                   |
                              RRSIG(2) Inception                                                    RRSIG(2) Expiry

                              |----- RRSIG(1) served -----|----- RRSIG(2) served -----|

  |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
  thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu
                                                          ^
                                                          |
                                                          RRSIG roll-over(1 to 2)

At all times, only one RRSIG per signed RRset per ZSK is served when responding to clients.

.. note::
  Why Thursday? POSIX-based operating systems count the time
  since GMT midnight January 1st of 1970, which was a Thursday. PowerDNS
  inception/expiration times are generated based on an integral number of
  weeks having passed since the start of the 'epoch'.

PowerDNS also serves the DNSKEY records in live-signing mode. Their TTL
is derived from the SOA records *minimum* field. When using NSEC3, the
TTL of the NSEC3PARAM record is also derived from that field.

Pre-signed records
------------------

In this mode, PowerDNS serves zones that already contain DNSSEC records.
Such zones can either be slaved from a remote master, or can be signed
using tools like OpenDNSSEC, ldns-signzone, and dnssec-signzone.

Even in this mode, PowerDNS will synthesize NSEC(3) records itself
because of its architecture. RRSIGs of these NSEC(3) will still need to
be imported. See the :ref:`Presigned migration guide <dnssec-migration-presigned>`.

Front-signing
-------------

As a special feature, PowerDNS can operate as a signing server which
operates as a slave to an unsigned master.

In this way, if keying material is available for an unsigned zone that
is retrieved from a master server, this keying material will be used
when serving data from this zone.

As part of the zone retrieval, the equivalent of
``pdnsutil rectify-zone`` is run to make sure that all DNSSEC-related
fields are set correctly in the backend.

Signed AXFR
-----------

An outgoing zone transfer from a signing master contains all information
required for the receiving party to rectify the zone without knowing the
keys, such as signed NSEC3 records for empty non-terminals. The zone is
not required to be rectified on the master.

Signatures and Hashing is similar as described in :ref:`dnssec-online-signing`.

.. _dnssec-modes-bind-mode:

BIND-mode operation
-------------------

The :doc:`bindbackend <../backends/bind>` can manage keys in an
SQLite3 database without launching a separate gsqlite3 backend.

To use this mode, add
``bind-dnssec-db=/var/db/bind-dnssec-db.sqlite3`` to pdns.conf, and run
``pdnsutil create-bind-db /var/db/bind-dnssec-db.sqlite3``. Then,
restart PowerDNS.

.. note::
  This sqlite database is different from the database used for the regular :doc:`SQLite 3 backend <../backends/generic-sqlite3>`.

After this, you can use ``pdnsutil secure-zone`` and all other pdnsutil
commands on your BIND zones without trouble.

.. _dnssec-modes-hybrid-bind:

Hybrid BIND-mode operation
--------------------------

PowerDNS can also operate based on 'BIND'-style zone & configuration
files. This 'bindbackend' has full knowledge of DNSSEC, but has no
native way of storing keying material.

However, since PowerDNS supports operation with multiple simultaneous
backends, this is not a problem.

In hybrid mode, keying material and zone records are stored in different
backends. This allows for 'bindbackend' operation in full DNSSEC mode.

To benefit from this mode, include at least one database-based backend
in the :ref:`setting-launch` statement. See the :doc:`backend specific documentation <../backends/index>`
on how to initialize the database and backend.

.. warning::
  For now, it is necessary to execute a manual SQL 'insert'
  into the domains table of the backend hosting the keying material. This
  is needed to generate a zone-id for the relevant domain. Sample SQL
  statement::

      insert into domains (name, type) values ('powerdnssec.org', 'NATIVE');

The :doc:`SQLite 3 backend <../backends/generic-sqlite3>` probably complements BIND mode best, since it does not require a database server process.

.. note::
  The sqlite3 database must be created using the normal schema for this backend.
  The database created with ``pdnsutil create-bind-db`` will not work in this backend.
Commit	Line	Data
0e2063c3 PL	1	DNSSEC Modes of Operation
	2	=========================
	3
	4	Traditionally, DNSSEC signatures have been added to unsigned zones, and
	5	then this signed zone could be served by any DNSSEC capable
	6	authoritative server. PowerDNS supports this mode fully.
	7
	8	In addition, PowerDNS supports taking care of the signing itself, in
	9	which case PowerDNS operates differently from most tutorials and
c57de37a	10	handbooks. This mode is easier, however.
0e2063c3 PL	11
	12	For relevant tradeoffs, please see :doc:`../security` and
	13	:doc:`../performance`.
	14
	15	.. _dnssec-online-signing:
	16
	17	Online Signing
	18	--------------
	19
	20	In the simplest situation, there is a single "SQL" database that
3938a65b	21	contains, in separate tables, all domain data, keying material, and other
0e2063c3 PL	22	DNSSEC related settings.
	23
	24	This database is then replicated to all PowerDNS instances, which all
	25	serve identical records, keys and signatures.
	26
	27	In this mode of operation, care should be taken that the database
	28	replication occurs over a secure network, or over an encrypted
	29	connection. This is because keying material, if intercepted, could be
	30	used to counterfeit DNSSEC data using the original keys.
	31
	32	Such a single replicated database requires no further attention beyond
	33	monitoring already required during non-DNSSEC operations.
	34
	35	Records, Keys, signatures, hashes within PowerDNS in online signing mode
	36	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	37
	38	Within PowerDNS live signing, keys are stored separately from the zone
	39	records. Zone data are only combined with signatures and keys when
	40	requests come in over the internet.
	41
	42	Each zone can have a number of keys associated with it, with varying key
	43	lengths. Typically 1 or at most 2 of these keys are employed as actual
	44	Zone Signing Keys (ZSKs). During normal operations, this means that only
	45	1 ZSK is 'active', and the other is inactive.
	46
	47	Should it be desired to 'roll over' to a new key, both keys can
	48	temporarily be active (and used for signing), and after a while the old
1feba35e	49	key can be deactivated. Subsequently it can be removed.
0e2063c3	50
f00c8667	51	As described above, there are several ways in which DNSSEC can deny the
774871ac JS	52	existence of a record, and this setting, which is also stored away from zone
774871ac JS	53	records, lives with the DNSSEC keying material.
0e2063c3 PL	54
	55	(Hashed) Denial of Existence
	56	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	57
	58	PowerDNS supports unhashed secure denial of existence using NSEC
	59	records. These are generated with the help of the (database) backend,
	60	which needs to be able to supply the 'previous' and 'next' records in
	61	canonical ordering.
	62
	63	The Generic SQL Backends have fields that allow them to supply these
	64	relative record names.
	65
	66	In addition, hashed secure denial of existence is supported using NSEC3
	67	records, in two modes, one with help from the database, the other with
	68	the help of some additional calculations.
	69
	70	NSEC3 in 'broad' or 'inclusive' mode works with the aid of the backend,
	71	where the backend should be able to supply the previous and next domain
	72	names in hashed order.
	73
	74	NSEC3 in 'narrow' mode uses additional hashing calculations to provide
	75	hashed secure denial of existence 'on the fly', without further
	76	involving the database.
	77
	78	.. _dnssec-signatures:
	79
	80	Signatures
	81	~~~~~~~~~~
	82
	83	In PowerDNS live signing mode, signatures, as served through RRSIG
	84	records, are calculated on the fly, and heavily cached. All CPU cores
	85	are used for the calculation.
	86
929f34c4 PL	87	RRSIGs have a validity period, in PowerDNS this period is 3 weeks.
	88	This period starts at most a week in the past, and continues at least a week into the future.
	89	This interval jumps with one-week increments every Thursday.
	90
	91	The time period used is always calculated based on the moment of rollover.
	92	The inception timestamp is the most recent Thursday 00:00:00 UTC, which is exactly one week ago at the moment of rollover.
	93	The expiry timestamp is the Thursday 00:00:00 UTC two weeks later from the moment of rollover.
	94	Graphically, it looks like this::
	95
	96	RRSIG(1) Inception RRSIG(1) Expiry
	97	\| \|
	98	v v
	99	\|================================ RRSIG(1) validity ================================\|
	100	\|================================ RRSIG(2) validity ================================\|
	101	^ ^
	102	\| \|
	103	RRSIG(2) Inception RRSIG(2) Expiry
	104
	105	\|----- RRSIG(1) served -----\|----- RRSIG(2) served -----\|
	106
	107	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	108	thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu fri sat sun mon tue wed thu
	109	^
	110	\|
	111	RRSIG roll-over(1 to 2)
	112
	113	At all times, only one RRSIG per signed RRset per ZSK is served when responding to clients.
0e2063c3 PL	114
	115	.. note::
	116	Why Thursday? POSIX-based operating systems count the time
	117	since GMT midnight January 1st of 1970, which was a Thursday. PowerDNS
	118	inception/expiration times are generated based on an integral number of
	119	weeks having passed since the start of the 'epoch'.
	120
	121	PowerDNS also serves the DNSKEY records in live-signing mode. Their TTL
	122	is derived from the SOA records minimum field. When using NSEC3, the
	123	TTL of the NSEC3PARAM record is also derived from that field.
	124
	125	Pre-signed records
	126	------------------
	127
	128	In this mode, PowerDNS serves zones that already contain DNSSEC records.
	129	Such zones can either be slaved from a remote master, or can be signed
483f79f0	130	using tools like OpenDNSSEC, ldns-signzone, and dnssec-signzone.
0e2063c3 PL	131
	132	Even in this mode, PowerDNS will synthesize NSEC(3) records itself
	133	because of its architecture. RRSIGs of these NSEC(3) will still need to
	134	be imported. See the :ref:`Presigned migration guide <dnssec-migration-presigned>`.
	135
	136	Front-signing
	137	-------------
	138
	139	As a special feature, PowerDNS can operate as a signing server which
	140	operates as a slave to an unsigned master.
	141
	142	In this way, if keying material is available for an unsigned zone that
	143	is retrieved from a master server, this keying material will be used
	144	when serving data from this zone.
	145
	146	As part of the zone retrieval, the equivalent of
	147	``pdnsutil rectify-zone`` is run to make sure that all DNSSEC-related
	148	fields are set correctly in the backend.
	149
	150	Signed AXFR
	151	-----------
	152
	153	An outgoing zone transfer from a signing master contains all information
	154	required for the receiving party to rectify the zone without knowing the
	155	keys, such as signed NSEC3 records for empty non-terminals. The zone is
	156	not required to be rectified on the master.
	157
	158	Signatures and Hashing is similar as described in :ref:`dnssec-online-signing`.
	159
4b72bcf9 PL	160	.. _dnssec-modes-bind-mode:
4b72bcf9 PL	161
0e2063c3 PL	162	BIND-mode operation
	163	-------------------
	164
	165	The :doc:`bindbackend <../backends/bind>` can manage keys in an
	166	SQLite3 database without launching a separate gsqlite3 backend.
	167
	168	To use this mode, add
	169	``bind-dnssec-db=/var/db/bind-dnssec-db.sqlite3`` to pdns.conf, and run
	170	``pdnsutil create-bind-db /var/db/bind-dnssec-db.sqlite3``. Then,
	171	restart PowerDNS.
	172
4b72bcf9 PL	173	.. note::
	174	This sqlite database is different from the database used for the regular :doc:`SQLite 3 backend <../backends/generic-sqlite3>`.
	175
0e2063c3 PL	176	After this, you can use ``pdnsutil secure-zone`` and all other pdnsutil
	177	commands on your BIND zones without trouble.
	178
	179	.. _dnssec-modes-hybrid-bind:
	180
	181	Hybrid BIND-mode operation
	182	--------------------------
	183
	184	PowerDNS can also operate based on 'BIND'-style zone & configuration
	185	files. This 'bindbackend' has full knowledge of DNSSEC, but has no
	186	native way of storing keying material.
	187
	188	However, since PowerDNS supports operation with multiple simultaneous
	189	backends, this is not a problem.
	190
	191	In hybrid mode, keying material and zone records are stored in different
	192	backends. This allows for 'bindbackend' operation in full DNSSEC mode.
	193
	194	To benefit from this mode, include at least one database-based backend
4b72bcf9 PL	195	in the :ref:`setting-launch` statement. See the :doc:`backend specific documentation <../backends/index>`
4b72bcf9 PL	196	on how to initialize the database and backend.
0e2063c3 PL	197
	198	.. warning::
	199	For now, it is necessary to execute a manual SQL 'insert'
	200	into the domains table of the backend hosting the keying material. This
	201	is needed to generate a zone-id for the relevant domain. Sample SQL
	202	statement::
	203
	204	insert into domains (name, type) values ('powerdnssec.org', 'NATIVE');
4b72bcf9 PL	205
	206	The :doc:`SQLite 3 backend <../backends/generic-sqlite3>` probably complements BIND mode best, since it does not require a database server process.
	207
	208	.. note::
	209	The sqlite3 database must be created using the normal schema for this backend.
	210	The database created with ``pdnsutil create-bind-db`` will not work in this backend.