# Serving authoritative DNSSEC data
-PowerDNS contains support for DNSSEC, enabling the easy serving of DNSSEC secured data, with minimal administrative overhead.
+PowerDNS contains support for DNSSEC, enabling the easy serving of DNSSEC secured
+data, with minimal administrative overhead.
-In PowerDNS, DNS and signatures and keys are (usually) treated as separate entities. The domain & record storage is thus almost completely devoid of DNSSEC record types.
+In PowerDNS, DNS and signatures and keys are (usually) treated as separate
+entities. The domain & record storage is thus almost completely devoid of DNSSEC
+record types.
-Instead, keying material is stored separately, allowing operators to focus on the already complicated task of keeping DNS data correct. In practice, DNSSEC related material is often stored within the same database, but within separate tables.
+Instead, keying material is stored separately, allowing operators to focus on the
+already complicated task of keeping DNS data correct. In practice, DNSSEC related
+material is often stored within the same database, but within separate tables.
-If a DNSSEC configuration is found for a domain, the PowerDNS daemon will provide keys, signatures and (hashed) denials of existence automatically.
+If a DNSSEC configuration is found for a domain, the PowerDNS daemon will provide
+key records, signatures and (hashed) denials of existence automatically.
As an example, securing an existing zone can be as simple as:
$ pdnsutil rectify-zone powerdnssec.org
```
-Alternatively, PowerDNS can serve pre-signed zones, without knowledge of private keys.
+Alternatively, PowerDNS can serve pre-signed zones, without knowledge of
+private keys.
# A brief introduction to DNSSEC
-DNSSEC is a complicated subject, but it is not required to know all the ins and outs of this protocol to be able to use PowerDNS. In this section, we explain the core concepts that are needed to operate a PowerDNSSEC installation.
-
-Zone material is enhanced with signatures using 'keys'. Such a signature (called an RRSIG) is a cryptographic guarantee that the data served is the original data. DNSSEC keys are asymmetric (RSA, DSA or GOST), the public part is published over DNS and is called a DNSKEY record, and is used for verification. The private part is used for signing and is never published.
-
-To make sure that the internet knows that the key that is used for signing is the authentic key, confirmation can be gotten from the parent zone. This means that to become operational, a zone operator will have to publish a representation of the signing key to the parent zone, often a ccTLD or a gTLD. This representation is called a DS record, and is a shorter (hashed) version of the DNSKEY.
-
-Once the parent zone has the DS, and the zone is signed with the DNSSEC key, we are done in theory.
-
-However, for a variety of reasons, most DNSSEC operations run with another layer of keys. The so called 'Key Signing Key' is sent to the parent zone, and this Key Signing Key is used to sign a new set of keys called the Zone Signing Keys.
-
-This setup allows us to change our keys without having to tell the zone operator about it.
-
-A final challenge is how to DNSSEC sign the answer 'no such domain'. In the language of DNS, the way to say 'there is no such domain' (NXDOMAIN) or there is no such record type is to send an empty answer. Such empty answers are universal, and can't be signed.
-
-In DNSSEC parlance we therefore sign a record that says 'there are no domains between A.powerdnssec.org and C.powerdnssec.org'. This securely tells the world that B.powerdnssec.org does not exist. This solution is called NSEC, and is simple but has downsides - it also tells the world exactly which records DO exist.
-
-So alternatively, we can say that if a certain mathematical operation (an 'iterated salted hash') is performed on a question, that no valid answers exist that have as outcome of this operation an answer between two very large numbers. This leads to the same 'proof of non-existence'. This solution is called NSEC3.
-
-A PowerDNS zone can either be operated in NSEC or in one of two NSEC3 modes ('inclusive' and 'narrow').
-
-# Profile, Supported Algorithms, Record Types & Modes of operation
-PowerDNS aims to serve unexciting, standards compliant, DNSSEC information. One goal is to have relevant parts of our output be identical or equivalent to important fellow-traveller software like NLNetLabs' NSD.
-
-Particularly, if a PowerDNS secured zone is transferred via AXFR, it should be able to contain the same records as when that zone was signed using `ldns-signzone` using the same keys and settings.
-
-PowerDNS supports serving pre-signed zones, as well as online ('live') signed operations. In the last case, Signature Rollover and Key Maintenance are fully managed by PowerDNS.
+DNSSEC is a complicated subject, but it is not required to know all the ins and
+outs of this protocol to be able to use PowerDNS. In this section, we explain the
+core concepts that are needed to operate a PowerDNSSEC installation.
+
+Zone material is enhanced with signatures using 'keys'. Such a signature (called
+an RRSIG) is a cryptographic guarantee that the data served is the original data.
+DNSSEC keys are asymmetric (RSA, DSA, ECSDA or GOST), the public part is published
+in DNS and is called a DNSKEY record, and is used for verification. The private
+part is used for signing and is never published.
+
+To make sure that the internet knows that the key that is used for signing is the
+authentic key, confirmation can be gotten from the parent zone. This means that
+to become operational, a zone operator will have to publish a representation of
+the signing key to the parent zone, often a ccTLD or a gTLD. This representation
+is called a DS record, and is a shorter (hashed) version of the DNSKEY.
+
+Once the parent zone has the DS, and the zone is signed with the DNSSEC key, we
+are done in theory.
+
+However, for a variety of reasons, most DNSSEC operations run with another layer
+of keys. The so called 'Key Signing Key' is sent to the parent zone, and this Key
+Signing Key is used to sign a new set of keys called the Zone Signing Keys.
+
+This setup allows us to change our keys without having to tell the zone operator
+about it.
+
+A final challenge is how to DNSSEC sign the answer 'no such domain'. In the
+language of DNS, the way to say 'there is no such domain' (NXDOMAIN) or there is
+no such record type is to send an empty answer. Such empty answers are universal,
+and can't be signed.
+
+In DNSSEC parlance we therefore sign a record that says 'there are no domains
+between A.powerdnssec.org and C.powerdnssec.org'. This securely tells the world
+that B.powerdnssec.org does not exist. This solution is called NSEC, and is
+simple but has downsides - it also tells the world exactly which records DO exist.
+
+So alternatively, we can say that if a certain mathematical operation (an
+'iterated salted hash') is performed on a question, that no valid answers exist
+that have as outcome of this operation an answer between two very large numbers.
+This leads to the same 'proof of non-existence'. This solution is called NSEC3.
+
+A PowerDNS zone can either be operated in NSEC or in one of two NSEC3 modes
+('inclusive' and 'narrow').
+
+# Profile, Supported Algorithms and Record Types
+PowerDNS aims to serve unexciting, standards compliant, DNSSEC information. One
+goal is to have relevant parts of our output be identical or equivalent to important
+fellow-traveller software like NLNetLabs' NSD.
+
+Particularly, if a PowerDNS secured zone is transferred via AXFR, it should be
+able to contain the same records as when that zone was signed using `ldns-signzone`
+using the same keys and settings.
+
+PowerDNS supports serving pre-signed zones, as well as online ('live') signed
+operations. In the last case, Signature Rollover and Key Maintenance are fully
+managed by PowerDNS.
## Supported Algorithms
Supported Algorithms (See the [IANA website](http://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml#dns-sec-alg-numbers-1) for more information):
-- DS records (algorithm 1, 2, 3)
+
- RSASHA1 (algorithm 5, algorithm 7)
- RSASHA256 (algorithm 8)
- RSASHA512 (algorithm 10)
- ECC-GOST (algorithm 12)
- ECDSA (algorithm 13 and 14)
+For the DS records, these [digest algorithms](http://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml#ds-rr-types-1)
+are supported:
+
+- SHA-1 (algorithm 1)
+- SHA-256 (algorithm 2)
+- GOST R 34.11-94 (algorithm 3)
+- SHA-384 (algorithm 4)
+
This corresponds to:
- [RFC 4033](http://tools.ietf.org/html/rfc4033): DNS Security Introduction and Requirements
- [RFC 4034](http://tools.ietf.org/html/rfc4034): Resource Records for the DNS Security Extensions, Protocol Modifications for the DNS Security Extensions
- [RFC 5933](http://tools.ietf.org/html/rfc5933): Use of GOST Signature Algorithms in DNSKEY and RRSIG Resource Records for DNSSEC
- [RFC 6605](http://tools.ietf.org/html/rfc6605): Elliptic Curve Digital Signature Algorithm (DSA) for DNSSEC
-# 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 order to facilitate interoperability with existing technologies, PowerDNS keys
+can be imported and exported in industry standard formats.
-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.
+**Note**: Actual supported algorithms depend on the crypto-libraries PowerDNS was
+compiled against. To check the supported DNSSEC algoritms in your build of PowerDNS,
+run `pdnsutil list-algorithms`.
-For relevant tradeoffs, please see [Security](#security) and [Performance](#performance.html).
+# 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.
-PowerDNS can operate in several modes. 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.
+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.
-This database is then replicated to all PowerDNS instances, which all serve identical records, keys and signatures.
+For relevant tradeoffs, please see [Security](#security) and
+[Performance](#performance.html).
-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.
+## 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.
-Such a single replicated database requires no further attention beyond monitoring already required during non-DNSSEC operations.
+This database is then replicated to all PowerDNS instances, which all serve
+identical records, keys and signatures.
-## PowerDNS 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 or dnssec-signzone.
+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.
-## PowerDNS Front-signing
-As a special feature, PowerDNS can operate as a signing server which operates as a slave to an unsigned master.
+Such a single replicated database requires no further attention beyond monitoring
+already required during non-DNSSEC operations.
-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.
+### 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.
-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.
+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.
-## PowerDNS BIND-mode operation
-Starting with PowerDNS 3.1, the bindbackend can manage keys in an SQLite3 database without launching a separate gsqlite3 backend.
+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 inactivated.
+Subsequently it can be removed.
-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.
+As elucidated above, there are several ways in which DNSSEC can deny the existence
+of a record, and this setting too is stored away from zone records, and lives
+with the DNSSEC keying material.
-After this, you can use "pdnsutil secure-zone" and all other pdnsutil commands on your BIND zones without trouble.
+### (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.
-## PowerDNS hybrid BIND-mode operation
-**Warning**: This mode is only supported in 3.0, 3.0.1 and 3.4.0 and up! In 3.1 to 3.3.1, the bindbackend always did its own key storage. In 3.4.0 and up hybrid bind mode operation is optional and enabled with the bindbackend `hybrid` config option.
+The Generic SQL Backends have fields that allow them to supply these relative
+record names.
-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.
+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.
-However, since PowerDNS supports operation with multiple simultaneous backends, this is not a problem.
+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.
-In hybrid mode, keying material and zone records are stored in different backends. This allows for 'bindbackend' operation in full DNSSEC mode.
+NSEC3 in 'narrow' mode uses additional hashing calculations to provide hashed
+secure denial of existence 'on the fly', without further involving the database.
-To benefit from this mode, include at least one database-based backend in the 'launch' statement. The Generic SQLite backend version 3 (gsqlite3) probably complements BIND mode best, since it does not require a database server process.
+### 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.
-**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');**.
+RRSIGs have a validity period, in PowerDNS by default this period starts at most
+a week in the past, and continues at least a week into the future.
-## Rules for filling out fields in database backends
-**Note**: The BIND Backend automates all the steps outlined below, and does not need 'manual' help
+Precisely speaking, the time period used is always from the start of the previous
+Thursday until the Thursday two weeks later. This two-week interval jumps with
+one-week increments every Thursday.
-In PowerDNS 3.0 and up, two additional fields are important: 'auth' and 'ordername'. These fields are set correctly on an incoming zone transfer, and also by running `pdnsutil rectify-zone`. zone2sql with the --dnssec flag aims to do this too but there are minor bugs in there, so please run `pdnsutil rectify-zone` after `zone2sql`.
+**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'.
-The 'auth' field should be set to '1' for data for which the zone itself is authoritative, which includes the SOA record and its own NS records.
+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.
-The 'auth' field should be 0 however for NS records which are used for delegation, and also for any glue (A, AAAA) records present for this purpose. Do note that the DS record for a secure delegation should be authoritative!
+## 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 or dnssec-signzone.
-The 'ordername' field needs to be filled out depending on the NSEC/NSEC3 mode. When running in NSEC3 'Narrow' mode, the ordername field is ignored and best left empty. In NSEC/NSEC3 mode, the ordername field should be NULL for any glue but filled in for all delegation NS records and all authoritative records. In NSEC3 opt-out mode, ordername is NULL for any glue and insecure delegation NS records, but filled in for secure delegation NS records and all authoritative records.
+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
+[Presigned migration guide](#From-existing-DNSSEC-non-PowerDNS-setups-pre-signed).
-In 'NSEC' mode, it should contain the *relative* part of a domain name, in reverse order, with dots replaced by spaces. So 'www.uk.powerdnssec.org' in the 'powerdnssec.org' zone should have 'uk www' as its ordername.
+## Front-signing
+As a special feature, PowerDNS can operate as a signing server which operates as
+a slave to an unsigned master.
-In 'NSEC3' non-narrow mode, the ordername should contain a lowercase base32hex encoded representation of the salted & iterated hash of the full record name. **pdnsutil hash-zone-record zone record** can be used to calculate this hash.
+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.
-In addition, from 3.2 and up, PowerDNS fully supports empty non-terminals. If you have a zone example.com, and a host a.b.c.example.com in it, rectify-zone (and the AXFR client code) will insert b.c.example.com and c.example.com in the records table with type NULL (SQL NULL, not 'NULL'). Having these entries provides several benefits. We no longer reply NXDOMAIN for these shorter names (this was an RFC violation but not one that caused trouble). But more importantly, to do NSEC3 correctly, we need to be able to prove existence of these shorter names. The type=NULL records entry gives us a place to store the NSEC3 hash of these names.
+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.
-If your frontend does not add empty non-terminal names to records, you will get DNSSEC replies of 3.1-quality, which has served many people well, but we suggest you update your code as soon as possible!
+Signatures and Hashing is similar as described [above](#online-signing)
-If you import presigned zones into your database, please do not import the NSEC or NSEC3 records. PowerDNS will synthesize these itself. Putting them in the database might cause duplicate records in responses. zone2sql filters NSEC and NSEC3 automatically.
+## BIND-mode operation
+Starting with PowerDNS 3.1, the bindbackend can manage keys in an SQLite3 database
+without launching a separate gsqlite3 backend.
-# Migration
-This chapter discusses various migration strategies, from existing PowerDNS setups, from existing unsigned installations and finally from previous non-PowerDNS DNSSEC deployments.
+To use this mode, add [`bind-dnssec-db=/var/db/bind-dnssec-db.sqlite3`](backend-bind.md#bind-dnssec-db)
+to pdns.conf, and run `pdnsutil create-bind-db /var/db/bind-dnssec-db.sqlite3`.
+Then, restart PowerDNS.
-## From an existing PowerDNS installation
-To migrate an existing database-backed PowerDNS installation, a few changes must be made to the database schema. First, the records table gains two new fields: 'auth' and 'ordername'. Some data in a zone, like glue records, should not be signed, and this is signified by setting 'auth' to 0.
+After this, you can use `pdnsutil secure-zone` and all other pdnsutil commands
+on your BIND zones without trouble.
-**Warning**: Once the database schema has been updated, and the relevant `gsql-dnssec` switch has been set, stricter rules apply for filling out the database! The short version is: run `pdnsutil rectify-all-zones`, even those not secured with DNSSEC!
+## Hybrid BIND-mode operation
+**Warning**: This mode is only supported in 3.0, 3.0.1 and 3.4.0 and up! In 3.1
+to 3.3.1, the bindbackend always did its own key storage. In 3.4.0 and up hybrid
+bind mode operation is optional and enabled with the bindbackend [`hybrid`](backend-bind.md#bind-hybrid)
+config option.
-Additionally, NSEC and NSEC3 in non-narrow mode require ordering data in order to perform (hashed) denial of existence. The 'ordername' field is used for this purpose.
+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.
-Finally, two new tables are needed. DNSSEC keying material is stored in the 'cryptokeys' table (in a portable standard format). Domain metadata is stored in the 'domainmetadata' table. This includes NSEC3 settings.
+However, since PowerDNS supports operation with multiple simultaneous backends,
+this is not a problem.
-Once the database schema has been changed for DNSSEC usage (see the relevant backend chapters or [the PowerDNS wiki](http://wiki.powerdns.com/trac/wiki/PDNSUTIL) for the update statements), the `pdnsutil` tool can be used to fill out keying details, and 'rectify' the auth and ordername fields.
+In hybrid mode, keying material and zone records are stored in different backends.
+This allows for 'bindbackend' operation in full DNSSEC mode.
-In short, `pdnsutil secure-zone powerdnssec.org ; pdnsutil rectify-zone powerdnssec.org` will deliver a correctly NSEC signed zone.
+To benefit from this mode, include at least one database-based backend in the
+'launch' statement. The [Generic SQLite backend (gsqlite3)](backend-generic-sqlite.md)
+probably complements BIND mode best, since it does not require a database server
+process.
-In addition, so will the [`zone2sql`](migration.md#zone2sql) import tool when run with the `--dnssec` flag.
+**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:
-## From existing non-DNSSEC non-PowerDNS setups
+```
+insert into domains (name, type) values ('powerdnssec.org', 'NATIVE');
+```
-TBD, see [Migration](migration.md).
+# `pdnsutil`
+`pdnsutil` (previously called `pdnssec`) is a powerful command that is the
+operator-friendly gateway into PowerDNS configuration. Behind the scenes,
+`pdnsutil` manipulates a PowerDNS backend database, which also means that for
+many databases, `pdnsutil` can be run remotely, and can configure key material
+on different servers.
-## From existing DNSSEC non-PowerDNS setups, pre-signed
-Industry standard signed zones can be served natively by PowerDNS, without changes. In such cases, signing happens externally to PowerDNS, possibly via OpenDNSSEC, ldns-sign or dnssec-sign.
+For a list of available commands, see the [manpage](../manpages/pdnsutil.1.md).
-PowerDNS needs to know if a zone should receive DNSSEC processing. To configure, run `pdnsutil set-presigned zone`.
+## DNSSEC Defaults
+Since version 4.0, when securing a zone using `pdnsutil secure-zone`, a single
+ECDSA (algorithm 13, ECDSAP256SHA256) key is generated that is used as ZSK.
+Before 4.0, 3 RSA (algorithm 8) keys were generated, one as the KSK and two ZSKs.
+As all keys are online in the database, it made no sense to have this split-key
+setup.
-**Warning** Right now, you will also need to configure NSEC(3) settings for pre-signed zones using `pdnsutil set-nsec3`. Default is NSEC, in which case no further configuration is necessary.
+The default negative answer strategy is NSEC.
-## From existing DNSSEC non-PowerDNS setups, live signing
-The `pdnsutil` tool features the option to import zone keys in the industry standard private key format, version 1.2. To import an existing KSK, use `pdnsutil import-zone-key zonename filename KSK`, replace KSK by ZSK for a Zone Signing Key.
+**Note**: not all registrars support algorithm 13.
-If all keys are imported using this tool, a zone will serve mostly identical records to before, with the important change that the RRSIG inception dates will be different.
+# Migration
+This chapter discusses various migration strategies, from existing PowerDNS setups,
+from existing unsigned installations and finally from previous non-PowerDNS
+DNSSEC deployments.
-**Note**: Within PowerDNS, the 'algorithm' for RSASHA1 keys is modulated based on the NSEC3 setting. So if an algorithm=7 key is imported in a zone with no configured NSEC3, it will appear as algorithm 5!
+## From an existing PowerDNS installation
+To migrate an existing database-backed PowerDNS installation, ensure you are
+running at least PowerDNS 3.3.3 and preferably 3.4 or newer.
-# 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.
+If you run an older version of PowerDNS, please upgrade to 3.4 and apply all the
+changes in database schemas as shown in the [upgrade documentation](upgrading.md).
-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.
+**Warning**: Once the relevant `backend-dnssec` switch has been set, stricter
+rules apply for filling out the database! The short version is: run
+`pdnsutil rectify-all-zones`, even those not secured with DNSSEC! For more
+information, see the [DNSSEC documentation for Generic SQL backends](backend-generic-sql.md#handeling-dnssec-signed-zones).
-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 inactivated. Subsequently it can be removed.
+To deliver a correctly signed zone with the [DNSSEC defaults](#dnssec-defaults),
+invoke:
-As elucidated above, there are several ways in which DNSSEC can deny the existence of a record, and this setting too is stored away from zone records, and lives with the DNSSEC keying material.
+```
+pdnsutil secure-zone ZONE
+```
-In order to facilitate interoperability with existing technologies, PowerDNS keys can be imported and exported in industry standard formats.
+To view the DS records for this zone (to transfer to the parent zone), run
-Keys and hashes are configured using the 'pdnsutil' tool, which is described next.
+```
+pdnsutil show-zone ZONE
+```
-## (Hashed) Denial of Existence
+For a more traditional setup with a KSK and a ZSK, use the following sequence
+of commands:
-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.
+```
+pdnsutil add-zone-key ZONE ksk 2048 active rsasha256
+pdnsutil add-zone-key ZONE zsk 1024 active rsasha256
+pdnsutil add-zone-key ZONE zsk 1024 inactive rsasha256
+```
-The Generic SQL Backends have fields that allow them to supply these relative record names.
+This will add a 2048-bit RSA Key Signing Key and two 1024-bit RSA Zone Signing Keys.
+One of the ZSKs is inactive and can be rolled to if needed.
-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.
+## From existing non-DNSSEC non-PowerDNS setups
+It is recommended to [migrate to PowerDNS](migration.md) before securing your
+zones. After that, see the instructions [above](#from-an-existing-PowerDNS-installation).
-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.
+## From existing DNSSEC non-PowerDNS setups, pre-signed
+Industry standard signed zones can be served natively by PowerDNS, without
+changes. In such cases, signing happens externally to PowerDNS, possibly via
+OpenDNSSEC, ldns-sign or dnssec-sign.
-NSEC3 in 'narrow' mode uses additional hashing calculations to provide hashed secure denial of existence 'on the fly', without further involving the database.
+PowerDNS needs to know if a zone should receive DNSSEC processing. To configure,
+run `pdnsutil set-presigned ZONE`.
-## 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.
+If you import presigned zones into your database, please do not import the NSEC
+or NSEC3 records. PowerDNS will synthesize these itself. Putting them in the
+database might cause duplicate records in responses. [`zone2sql`](migration.md#zone2sql)
+filters NSEC and NSEC3 automatically.
-RRSIGs have a validity period, in PowerDNS by default this period starts at most a week in the past, and continues at least a week into the future.
+**Warning** Right now, you will also need to configure NSEC(3) settings for
+pre-signed zones using `pdnsutil set-nsec3`. Default is NSEC, in which case no
+further configuration is necessary.
-Precisely speaking, the time period used is always from the start of the previous Thursday until the Thursday two weeks later. This two-week interval jumps with one-week increments every Thursday.
+## From existing DNSSEC non-PowerDNS setups, live signing
+The `pdnsutil` tool features the option to import zone keys in the industry
+standard private key format, version 1.2. To import an existing KSK, use
-**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'.
+```
+pdnsutil import-zone-key ZONE FILENAME ksk
+```
-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.
+replace 'ksk' by 'zsk' for a Zone Signing Key.
-# `pdnsutil`
-`pdnsutil` (previously called `pdnssec`) is a powerful command that is the operator-friendly gateway into PowerDNS configuration. Behind the scenes, `pdnsutil` manipulates a PowerDNS backend database, which also means that for many databases, `pdnsutil` can be run remotely, and can configure key material on different servers.
+If all keys are imported using this tool, a zone will serve mostly identical
+records to before, with the important change that the RRSIG inception dates will
+be different.
-For a list of available commands, see the [manpage](../manpages/pdnsutil.1.md).
+**Note**: Within PowerDNS, the 'algorithm' for RSASHA1 keys is modulated based
+on the NSEC3 setting. So if an algorithm=7 key is imported in a zone with no
+configured NSEC3, it will appear as algorithm 5!
# DNSSEC advice & precautions
-DNSSEC is a major change in the way DNS works. Furthermore, there is a bewildering array of settings that can be configured.
-
-It is well possible to configure DNSSEC in such a way that your domain will not operate reliably, or even, at all.
+DNSSEC is a major change in the way DNS works. Furthermore, there is a bewildering
+array of settings that can be configured.
-We advise operators to stick to the keying defaults of `pdnsutil secure-zone`: RSASHA256 (algorithm 8), 1 Key Signing Key of 2048 bits and 1 active Zone Signing Key of 1024 bits.
+It is well possible to configure DNSSEC in such a way that your domain will not
+operate reliably, or even, at all. We advise operators to stick to the keying
+defaults of `pdnsutil secure-zone`.
-While the 'GOST' and 'ECDSA' algorithms are better choices in theory, not many DNSSEC resolvers can validate answers signed with such keys. Much the same goes for RSASHA512, except that it does not offer better performance either.
+**Note**: GOST may be more widely available in Russia, because it might be
+mandatory to implement this regional standard there.
-**Note**: GOST may be more widely available in Russia, because it might be mandatory to implement this regional standard there.
+It is possible to operate a zone with different keying algorithms simultaneously,
+but it has also been observed that this is not reliable.
-It is possible to operate a zone with different keying algorithms simultaneously, but it has also been observed that this is not reliable.
-
-Depending on your master/slave setup, you may need to tinker with SOA-EDIT on your master.
+Depending on your master/slave setup, you may need to tinker with the
+[`SOA-EDIT`](domainmetadata.md#soa-edit) metadata on your master. This is described
+in the [operational instructions](#soa-edit) below.
## Packet sizes, fragments, TCP/IP service
-DNSSEC answers contain (bulky) keying material and signatures, and are therefore a lot larger than regular DNS answers. Normal DNS responses almost always fit in the 'magical' 512 byte limit previously imposed on DNS.
+DNSSEC answers contain (bulky) keying material and signatures, and are therefore
+a lot larger than regular DNS answers. Normal DNS responses almost always fit in
+the 'magical' 512 byte limit previously imposed on DNS.
In order to support DNSSEC, operators must make sure that their network allows for:
-- >512 byte UDP packets on port 53
+- Larger than 512 byte UDP packets on port 53
- Fragmented UDP packets
- ICMP packets related to fragmentation
- TCP queries on port 53
- EDNS0 queries/responses (filtered by some firewalls)
-If any of the conditions outlined above is not met, DNSSEC service will suffer or be completely unavailable.
+If any of the conditions outlined above is not met, DNSSEC service will suffer
+or be completely unavailable.
-In addition, the larger your DNS answers, the more critical the above becomes. It is therefore advised not to provision too many keys, or keys that are unnecessarily large.
+In addition, the larger your DNS answers, the more critical the above becomes.
+It is therefore advised not to provision too many keys, or keys that are
+unnecessarily large.
# Operational instructions
-In this chapter various DNSSEC transitions are discussed, and how to execute them within PowerDNS.
+Several How to's describe operational practices with DNSSEC:
+
+* [KSK Rollover](howtos.md#ksk-rollover)
+* [ZSK Rollover](howtos.md#zsk-rollover)
+
+Below, frequently used commands are described:
## Publishing a DS
-To publish a DS to a parent zone, utilize 'pdnsutil show-zone' and take the DS from its output, and transfer it securely to your parent zone.
+To publish a DS to a parent zone, utilize `pdnsutil show-zone` and take the DS
+from its output, and transfer it securely to your parent zone.
-## ZSK rollover
+## Going insecure
```
-$ pdnsutil activate-zone-key ZONE next-key-id
-$ pdnsutil deactivate-zone-key ZONE prev-key-id
-$ pdnsutil remove-zone-key ZONE prev-key-id
+pdnsutil disable-dnssec ZONE
```
-## KSK rollover
+**Warning**: Going insecure with a zone that has a DS record in the parent zone
+will make the zone BOGUS. Make sure the parent zone removes the DS record *before*
+going insecure.
+
+## Setting the NSEC modes and parameters
+As stated earlier, PowerDNS uses NSEC by default. If you want to use NSEC3 instead,
+issue:
+
```
-pdnsutil add-zone-key ZONE ksk
-pdnsutil show-zone ZONE
+pdnsutil set-nsec3 ZONE [PARAMETERS]
```
-Communicate duplicate DS
+e.g.
```
-pdnsutil activate-zone-key ZONE next-key-id
-pdnsutil deactivate-zone-key ZONE prev-key-id
-pdnsutil remove-zone-key ZONE prev-key-id
+pdnsutil set-nsec3 example.net '1 0 1 ab'
```
-## Going insecure
-`pdnsutil disable-dnssec ZONE`
+The quoted part is the content of the NSEC3PARAM records, as defined in [RFC 5155
+](https://tools.ietf.org/html/rfc5155#section-4), in order:
-## NSEC(3) change
-This section describes how to change NSEC(3) parameters when they are already set.
+* Hash algorithm, should always be `1` (SHA1)
+* Flags, set to `1` for [NSEC3 Opt-out](https://tools.ietf.org/html/rfc5155#section-6), this best set as `0`
+* Number of iterations of the hash function, read [RFC 5155, Section 10.3](https://tools.ietf.org/html/rfc5155#section-6) for recommendations
+* Salt (in hexadecimal) to apply during hashing
+
+To convert a zone from NSEC3 to NSEC operations, run:
-**Warning**: The following instructions might not be correct or complete!
```
-pdnsutil set-nsec3 ZONE 'parameters'
-pdnsutil show-zone ZONE
+pdnsutil unset-nsec3 ZONE
```
-Communicate duplicate DS.
+**Warning**: Don't change from NSEC to NSEC3 (or the other way around) for zones
+with algorithm 5 (RSASHA1), 6 (DSA-NSEC3-SHA1) or 7 (RSASHA1-NSEC3-SHA1).
+
+## SOA-EDIT: ensure signature freshness on slaves
+As RRSIGs can expire, slave servers need to know when to re-transfer the zone. In
+most implementations (BIND, NSD), this is done by re-signing the full zone outside
+of the nameserver, increasing the SOA serial and serving the new zone on the master.
+
+With PowerDNS in Live-signing mode, the SOA serial is not increased by default
+when the RRSIG dates are rolled.
+
+For zones that use [native](modes-of-operation.md#native-operation) replication
+PowerDNS will serve valid RRSIGs on all servers.
+
+For [master](modes-of-operation.md#master-operation) zones (where replication
+happens by means of AXFR), PowerDNS slaves will automatically re-transfer the zone
+when it notices the RRSIGs have changed, even when the SOA serial is not increased.
+This ensures the zone never serves old signatures.
+
+If your DNS setup uses non-PowerDNS slaves, the slaves need to know when the
+signatures have been updated. This can be accomplished by setting the
+[SOA-EDIT](domainmetadata.md#soa-edit) metadata for DNSSEC signed zones. This
+value controls how the value of the SOA serial is modified by PowerDNS.
+
+**Note**: The SOA serial in the datastore will be untouched, SOA-EDIT is applied
+to DNS answers with the SOA record.
-For further details, please see [the `pdnsutil`](#pdnsutil) documentation.
+The [`default-soa-edit`](settings.md#default-soa-edit) or [`default-soa-edit-signed`](settings.md#default-soa-edit-signed)
+configuration options can instead be set to ensure SOA-EDIT is set for every zone.
+
+### Possible SOA-EDIT values
+The 'inception' refers to the time the RRSIGs got updated in
+[live-signing mode](#online-signing). This happens every week (see [Signatures](#signatures)).
+The inception time does not depend on local timezone, but some modes below will
+use localtime for representation.
+
+#### INCREMENT-WEEKS
+Increments the serial with the number of weeks since the UNIX epoch. This should
+work in every setup; but the result won't look like YYYYMMDDSS anymore.
+
+For example: a serial of 12345678 will become 12348079 on Wednesday 13th of January
+2016 (2401 weeks after the epoch).
+
+#### INCEPTION-EPOCH
+Sets the new SOA serial number to the maximum of the old SOA serial number, and
+age in seconds of the last inception. This requires your backend zone to use the
+number of seconds since the UNIX epoch as SOA serial. The result is still the age
+in seconds of the last change to the zone, either by operator changes to the zone
+or the 'addition' of new RRSIGs.
+
+As an example, a serial of 12345678 becomes 1452124800 on Wednesday 13th of January
+2016.
+
+#### INCEPTION-INCREMENT
+Uses YYYYMMDDSS format for SOA serial numbers. If the SOA serial from the backend
+is within two days after inception, it gets incremented by two (the backend should
+keep SS below 98). Otherwise it uses the maximum of the backend SOA serial number
+and inception time in YYYYMMDD01 format. This requires your backend zone to use
+YYYYMMDDSS as SOA serial format. Uses localtime to find the day for inception time.
+
+This changes a serial of 2015120810 to 2016010701 on Wednesday 13th of January
+2016.
+
+#### INCEPTION (not recommended)
+Sets the SOA serial to the last inception time in YYYYMMDD01 format. Uses localtime
+to find the day for inception time.
+
+**Warning**: The SOA serial will only change on inception day, so changes to the
+zone will get visible on slaves only on the following inception day.
+
+#### INCEPTION-WEEK (not recommended)
+Sets the SOA serial to the number of weeks since the epoch, which is the last
+inception time in weeks.
+
+**Warning**: Same problem as INCEPTION.
+
+#### EPOCH
+Sets the SOA serial to the number of seconds since the epoch.
+
+**Warning**: Don't combine this with AXFR - the slaves would keep refreshing all
+the time. If you need fast updates, sync the backend databases directly with
+incremental updates (or use the same database server on the slaves)
+
+#### NONE
+Ignore [`default-soa-edit`](settings.md#default-soa-edit) and/or
+[`default-soa-edit-signed`](settings.md#default-soa-edit-signed) setings.
# PKCS\#11 support
**Note**: This feature is experimental, and not ready for production. Use at your own risk!
**Note**: As of version 4.0, slot IDs are deprecated, and you are expected to use slot label instead
-To enable it, compile PowerDNS Authoritative Server using --enable-experimental-pkcs11 flag on configure. This requires you to have p11-kit libraries and headers.
+To enable it, compile PowerDNS Authoritative Server using
+`--enable-experimental-pkcs11` flag on configure. This requires you to have
+p11-kit libraries and headers.
-You can also log on to the tokens after starting server, in this case you need to edit your PKCS#11 cryptokey record and remove PIN or set it empty. PIN is required
-for assigning keys to zone.
+You can also log on to the tokens after starting server, in this case you need
+to edit your PKCS#11 cryptokey record and remove PIN or set it empty. PIN is
+required for assigning keys to zone.
-Instructions on how to setup SoftHSM to work with the feature after compilation on ubuntu/debian (tested with Ubuntu 12 and 14).
-- apt-get install softhsm p11-kit opensc
+## Using with SoftHSM
+To test this feature, a software HSM can be used. It is **not recommended** to
+use this in production.
+
+Instructions on how to setup SoftHSM to work with the feature after compilation
+on ubuntu/debian (tested with Ubuntu 12 and 14).
+- `apt-get install softhsm p11-kit opensc`
- create directory /etc/pkcs11/modules
- Add file called 'softhsm' there with (on newer versions, use softhsm.module)
-
```
module: /home/cmouse/softhsm/lib/softhsm/libsofthsm.so
managed: yes
```
-
-- Verify it works
-
- ```
- p11-kit -l
- ```
-
+- Verify it works: `p11-kit -l`
- Create at least two tokens (ksk and zsk) with (slot-number starts from 0)
```
- SoftHSM signatures are fast enough to be used in live environment.
-Instructions on how to use CryptAS [`Athena IDProtect Key USB Token V2J`](http://www.cryptoshop.com/products/smartcards/idprotect-key-j-laser.html) Smart Card token on Ubuntu 14.
+## Using CryptAS
+Instructions on how to use CryptAS [`Athena IDProtect Key USB Token V2J`](http://www.cryptoshop.com/products/smartcards/idprotect-key-j-laser.html)
+Smart Card token on Ubuntu 14.
- install the manufacturer`s support software on your system and initialize the Smart Card token as per instructions (do not use PIV).
- apt-get install p11-kit opensc
- create directory /etc/pkcs11/modules
- Note that the physical token is pretty slow, so you have to use it as hidden master. It has been observed to produce about 1.5signatures/second.
# Secure transfers
-From 3.3.1 and up, PowerDNS support secure DNSSEC transfers as described in [draft-koch-dnsop-dnssec-operator-change](https://datatracker.ietf.org/doc/draft-koch-dnsop-dnssec-operator-change/). If the [`direct-dnskey`](settings.md#direct-dnskey) option is enabled the foreign DNSKEY records stored in the database are added to the keyset and signed with the KSK. Without the direct-dnskey option DNSKEY records in the database are silently ignored.
+From 3.3.1 and up, PowerDNS support secure DNSSEC transfers as described in
+[draft-koch-dnsop-dnssec-operator-change](https://datatracker.ietf.org/doc/draft-koch-dnsop-dnssec-operator-change/).
+If the [`direct-dnskey`](settings.md#direct-dnskey) option is enabled the foreign
+DNSKEY records stored in the database are added to the keyset and signed with the
+KSK. Without the direct-dnskey option DNSKEY records in the database are silently
+ignored.
# Security
-During typical PowerDNS operation, the private part of the signing keys are 'online', which can be compared to operating an HTTPS server, where the certificate is available on the webserver for cryptographic purposes.
+During typical PowerDNS operation, the private part of the signing keys are
+'online', which can be compared to operating an HTTPS server, where the
+private key is available on the webserver for cryptographic purposes.
-In some settings, having such (private) keying material available online is considered undesirable. In this case, consider running in pre-signed mode.
+In some settings, having such (private) keying material available online is
+considered undesirable. In this case, consider running in pre-signed mode.
# Performance
-DNSSEC has a performance impact, mostly measured in terms of additional memory used for the signature caches. In addition, on startup or AXFR-serving, a lot of signing needs to happen.
+DNSSEC has a performance impact, mostly measured in terms of additional memory
+used for the signature caches. In addition, on startup or AXFR-serving, a lot of
+signing needs to happen.
-Please see [Large Scale DNSSEC Best Current Practices](http://wiki.powerdns.com/trac/wiki/LargeScaleDNSSECBCP) for the most up to date information.
+Most best practices are documented in [RFC 6781](https://tools.ietf.org/html/rfc6781).
# Thanks to, acknowledgements
-PowerDNS has been made possible by the help & contributions of many people. We would like to thank:
+PowerDNS DNSSEC has been made possible by the help & contributions of many people.
+We would like to thank:
- Peter Koch (DENIC)
- Olaf Kolkman (NLNetLabs)
projects / pdns / commitdiff