From 6bb7c2b6b5212f662c64946d07764a6a980d7444 Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Wed, 22 Jul 2015 12:37:18 +0200 Subject: [PATCH] Add documentation on CD and DNSKEY * Update pdnssec manpage * Update dnsmetadata page * Add HowTo on CDS key rollover * Add some to the pdnssec manpage to display it better in html --- docs/manpages/pdnssec.1.md | 35 +++++++++++-------- docs/markdown/authoritative/dnssec.md | 35 +------------------ docs/markdown/authoritative/domainmetadata.md | 12 +++++++ docs/markdown/authoritative/howtos.md | 29 +++++++++++++++ docs/mkdocs.yml | 1 + 5 files changed, 64 insertions(+), 48 deletions(-) create mode 100644 docs/markdown/authoritative/howtos.md diff --git a/docs/manpages/pdnssec.1.md b/docs/manpages/pdnssec.1.md index 6569eb83a..867a5f139 100644 --- a/docs/manpages/pdnssec.1.md +++ b/docs/manpages/pdnssec.1.md @@ -88,24 +88,17 @@ remove-zone-key *ZONE* *KEY-ID* set-nsec3 *ZONE* '*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*' [**narrow**] : Sets NSEC3 parameters for this zone. The quoted parameters are 4 values that are used for the the NSEC3PARAM record and decide how NSEC3 records - are created. The NSEC3 parameters must be quoted on the command line. - - *HASH-ALGORITHM* must be 1 (SHA-1). - + are created. The NSEC3 parameters must be quoted on the command line.

+ *HASH-ALGORITHM* must be 1 (SHA-1).

Setting *FLAGS* to 1 enables NSEC3 opt-out operation. Only do this if you - know you need it. - + know you need it.

For *ITERATIONS*, please consult RFC 5155, section 10.3. And be aware - that a high number might overload validating resolvers. - - The *SALT* is a hexadecimal string encoding the bits for the salt. - + that a high number might overload validating resolvers.

+ The *SALT* is a hexadecimal string encoding the bits for the salt.

Setting **narrow** will make PowerDNS send out "white lies" about the next secure record. Instead of looking it up in the database, it will send out - the hash + 1 as the next secure record. - - A sample commandline is: "pdnssec set-nsec3 powerdnssec.org '1 1 1 ab' narrow". - + the hash + 1 as the next secure record.

+ A sample commandline is: "pdnssec set-nsec3 powerdnssec.org '1 1 1 ab' narrow".

**WARNING**: If running in RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will require a DS update in the parent zone. @@ -114,6 +107,20 @@ unset-nsec3 *ZONE* (algorithm 5 or 7), switching from NSEC to NSEC3 will require a DS update at the parent zone! +set-publish-cds *ZONE* [*DIGESTALGOS*] +: Set *ZONE* to respond to queries for its CDS records. the optional argument + *DIGESTALGOS* should be a comma-separated list of DS algorithms to use. By + default, this is 1,2 (SHA1 and SHA2-256). + +set-publish-cdnskey *ZONE* +: Set *ZONE* to publish CDNSKEY records. + +unset-publish-cds *ZONE* +: Set *ZONE* to stop responding to queries for its CDS records. + +unset-publish-cdnskey *ZONE* +: Set *ZONE* to stop publishing CDNSKEY records. + ## TSIG RELATED COMMANDS These commands manipulate TSIG key information in the database. Some commands require an *ALGORITHM*, the following are available: diff --git a/docs/markdown/authoritative/dnssec.md b/docs/markdown/authoritative/dnssec.md index 39d610188..ce380f088 100644 --- a/docs/markdown/authoritative/dnssec.md +++ b/docs/markdown/authoritative/dnssec.md @@ -204,40 +204,7 @@ Precisely speaking, the time period used is always from the start of the previou # `pdnssec` `pdnssec` is a powerful command that is the operator-friendly gateway into PowerDNSSEC configuration. Behind the scenes, `pdnssec` manipulates a PowerDNS backend database, which also means that for many databases, `pdnssec` can be run remotely, and can configure key material on different servers. -The following pdnssec commands are available: - -* `activate-zone-key ZONE KEY-ID`: Activate a key with id KEY-ID within a zone called ZONE. -* `add-zone-key ZONE [ksk|zsk] [bits] [rsasha1|rsasha256|rsasha512|gost|ecdsa256|ecdsa384]`: Create a new key for zone ZONE, and make it a KSK or a ZSK, with the specified algorithm. -* `backend-cmd BACKEND CMD [CMD..]`: Send a text command to a backend for execution. GSQL backends will take SQL commands, other backends may take different things. Be careful! -* `check-zone ZONE`: Check a zone for DNSSEC correctness. Main goals is to check if the auth flag is set correctly. -* `check-all-zones`: Check all zones for DNSSEC correctness. Added in 3.1. -* `deactivate-zone-key ZONE KEY-ID`: Deactivate a key with id KEY-ID within a zone called ZONE. -* `disable-dnssec ZONE`: Deactivate all keys and unset PRESIGNED in ZONE. -* `export-zone-dnskey ZONE KEY-ID`: Export to standard output DNSKEY and DS of key with key id KEY-ID within zone called ZONE. -* `export-zone-key ZONE KEY-ID`: Export to standard output full (private) key with key id KEY-ID within zone called ZONE. The format used is compatible with BIND and NSD/LDNS. -* `hash-zone-record ZONE RECORDNAME`: -This convenience command hashes the name 'recordname' according to the NSEC3 settings of ZONE. Refuses to hash for zones with no NSEC3 settings. -* `import-zone-key ZONE filename [ksk|zsk]`: Import from 'filename' a full (private) key for zone called ZONE. The format used is compatible with BIND and NSD/LDNS. KSK or ZSK specifies the flags this key should have on import. -* `import-zone-key-pem ZONE filename algorithm [ksk|zsk]`: Import from 'filename' a full (private) key in PEM format for zone called ZONE, and assign it an algorithm number. KSK or ZSK specifies the flags this key should have on import. The format used is compatible with 'openssl genrsa', which is also called PEM. -* `generate-zone-key [ksk|zsk] [algorithm] [bits]`: Generate and display a zone key. Can be used when you need to generate a key for some script backend. Does not store the key. -* `rectify-zone ZONE [ZONE ..]`: Calculates the 'ordername' and 'auth' fields for a zone called ZONE so they comply with DNSSEC settings. Can be used to fix up migrated data. Can always safely be run, it does no harm. Multiple zones can be supplied. -* `rectify-all-zones`: Do a rectify-zone for all the zones. Be careful when running this. Only bind and gmysql backends are supported. Added in 3.1. -* `remove-zone-key ZONE KEY-ID`: Remove a key with id KEY-ID from a zone called ZONE. -* `secure-zone ZONE`: Configures a zone called ZONE with reasonable DNSSEC settings. You should manually run `rectify-zone` afterwards. -* `secure-all-zones`: Add keymaterial to all zones. You should manually run `rectify-all-zones` afterwards. The `increase-serial` option increases the SOA serial for new secured zones. -* `set-nsec3 ZONE 'parameters' [narrow]`: Sets NSEC3 parameters for this zone. A sample command line is: `pdnssec set-nsec3 powerdnssec.org '1 0 1 ab' narrow`. The NSEC3 parameters must be quoted on the command line. **Warning**: If running in RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will require a DS update at the parent zone! The NSEC3 fields are: 'algorithm flags iterations salt'. For 'algorithm', currently '1' is the only supported value. Setting 'flags' to 1 enables opt-out operation. Only do this if you know you need it. The salt is hexadecimal. -* `set-presigned ZONE`: Switches zone to presigned operation, utilizing in-zone RRSIGs. -* `show-zone ZONE`: Shows all DNSSEC related settings of a zone called ZONE. -* `unset-nsec3 ZONE`: Converts a zone to NSEC operations. **Warning**: If running in RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will require a DS update at the parent zone! -* `unset-presigned ZONE`: Disables presigned operation for ZONE. -* `import-tsig-key name algorithm key`: Imports a named TSIG key. Use enable/disable-tsig-key to map it to a zone. -* `generate-tsig-key name algorithm`: Creates and stores a named tsig key. -* `delete-tsig-key name`: Deletes a named TSIG key. **Warning**: Does not unmap it from zones. -* `list-tsig-keys`: Shows all TSIG keys from all backends. -* `activate-tsig-key zone name [master|slave]`: activate TSIG key for a zone. Use master on master server, slave on slave server. -* `deactivate-tsig-key zone name [master|slave]`: Deactivate TSIG key for a zone. Use master on master server, slave on slave server. -* `get-meta ZONE [kind kind..]`: Gets one or more meta items for domain ZONE. If no meta keys defined, it retrieves well known meta keys. -* `set-meta ZONE kind [value value ..]`: Clears or sets meta for domain ZONE. You can provide one or more value(s). +For a list of available commands, see the [manpage](../manpages/pdnssec.1.md). # 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. diff --git a/docs/markdown/authoritative/domainmetadata.md b/docs/markdown/authoritative/domainmetadata.md index 72ec344e4..6411d3abf 100644 --- a/docs/markdown/authoritative/domainmetadata.md +++ b/docs/markdown/authoritative/domainmetadata.md @@ -63,6 +63,18 @@ records in the zone. However, if you import a presigned zone using `zone2sql` or PowerDNS will not be able to correctly serve the zone if the imported data is bogus or incomplete. Also see `set-presigned` in [`pdnssec`](dnssec.md#pdnssec). +## PUBLISH_CDNSKEY, PUBLISH_CDS +Whether to publish CDNSKEY and/or CDS recording defined in [RFC 7344](https://tools.ietf.org/html/rfc7344). + +To publish CDNSKEY records of the KSKs for the zone, set `PUBLISH_CDNSKEY` to `1`. + +To publish CDS records for the KSKs in the zone, set `PUBLISH_CDS` to a comma- +separated list of [signature algorithm numbers](http://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml#ds-rr-types-1). + +This metadata can also be set using the [`pdnssec`](dnssec.md#pdnssec) options +`set-publish-cdnskey` and `set-publish-cds`. For an example for an RFC 7344 +key rollover, see the [CDS and CDNSKEY howto](howtos.md#cds-dnskey-key-rollover). + ## SOA-EDIT When serving this zone, modify the SOA serial number in one of several ways. Mostly useful to get slaves to re-transfer a zone regularly to get fresh RRSIGs. diff --git a/docs/markdown/authoritative/howtos.md b/docs/markdown/authoritative/howtos.md new file mode 100644 index 000000000..5fb51c64a --- /dev/null +++ b/docs/markdown/authoritative/howtos.md @@ -0,0 +1,29 @@ +# CDS & CDNSKEY Key Rollover +If the upstream registry supports [RFC 7344](https://tools.ietf.org/html/rfc7344) +key rollovers you can use several [`pdnssec`](dnssec.md#pdnssec) commands to do +this rollover. This HowTo follows the rollover example from the RFCs [Appendix B](https://tools.ietf.org/html/rfc7344#appendix-B). + +We assume the zone name is example.com and is already DNSSEC signed. + +Start by adding a new KSK to the zone: `pdnssec add-zone-key example.com ksk 2048 passive`. +The "passive" means that the key is not used to sign any ZSK records. This limits +the size of `ANY` and DNSKEY responses. + +Publish the CDS records: `pdnssec set-publish-cds example.com`, these records +will tell the parent zone to update its DS records. Now wait for the DS records +to be updated in the parent zone. + +Once the DS records are updated, do the actual key-rollover: `pdnssec activate-zone-key example.com new-key-id` +and `pdnssec deactivate-zone-key example.com old-key-id`. You can get the `new-key-id` +and `old-key-id` by listing them through `pdnssec show-zone example.com`. + +After the rollover, wait *at least* until the TTL on the DNSKEY records have +expired so validating resolvers won't mark the zone as BOGUS. When the wait is +over, delete the old key from the zone: `pdnssec remove-zone-key example.com old-key-id`. +This updates the CDS records to reflect only the new key. + +Wait for the parent to pick up on the CDS change. Once the upstream DS records +show only the DS records for the new KSK, you may disable sending out the CDS +responses: `pdnssec unset-pushish-cds example.com`. + +Done! diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 8655ff774..ca453f812 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -24,6 +24,7 @@ pages: - Domain metadata: authoritative/domainmetadata.md - Dynamic DNS Update: authoritative/dnsupdate.md - GSS-TSIG: authoritative/gss-tsig.md + - Various How To's: authoritative/howtos.md - Internals: authoritative/internals.md - Virtual Hosting: authoritative/virtual.md - Performance Tuning and Monitoring: authoritative/performance.md -- 2.40.0