coredns/plugin/dnssec
Miek Gieben 58221f55db
Manual pages (#1346)
* Add manual pages

Generate manual pages from the README and extend README with Name and
Description sections.

The generation requires 'ronn' which may not be available. Just check in
all generated manual pages.
2018-01-04 12:53:07 +00:00
..
black_lies.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
black_lies_test.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
cache.go Remove the word middleware (#1067) 2017-09-14 09:36:06 +01:00
cache_test.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
dnskey.go readme: more tests (#1184) 2017-10-31 07:14:49 +00:00
dnssec.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
dnssec_test.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
handler.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
handler_test.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
README.md Manual pages (#1346) 2018-01-04 12:53:07 +00:00
responsewriter.go plugin/dnssec: implement shotgun from CloudFlare (#1305) 2018-01-03 11:11:56 +00:00
rrsig.go plugin/dnssec; insert and sign DS records (#1153) 2017-10-20 09:22:02 +01:00
setup.go metrics: correctly register all metrics (#1335) 2017-12-27 15:48:14 +00:00
setup_test.go Remove the word middleware (#1067) 2017-09-14 09:36:06 +01:00

dnssec

Name

dnssec - enable on-the-fly DNSSEC signing of served data.

Description

With dnssec any reply that doesn't (or can't) do DNSSEC will get signed on-the-fly. Authenticated denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is not supported.

Syntax

dnssec [ZONES... ] {
    key file KEY...
    cache_capacity CAPACITY
}

The specified key is used for all signing operations. The DNSSEC signing will treat this key a CSK (common signing key), forgoing the ZSK/KSK split. All signing operations are done online. Authenticated denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is not supported.

If multiple dnssec plugins are specified in the same zone, the last one specified will be used (See bugs).

  • ZONES zones that should be signed. If empty, the zones from the configuration block are used.

  • key file indicates that KEY file(s) should be read from disk. When multiple keys are specified, RRsets will be signed with all keys. Generating a key can be done with dnssec-keygen: dnssec-keygen -a ECDSAP256SHA256 <zonename>. A key created for zone A can be safely used for zone B. The name of the key file can be specified as one of the following formats

    • basename of the generated key Kexample.org+013+45330
    • generated public key Kexample.org+013+45330.key
    • generated private key Kexample.org+013+45330.private
  • cache_capacity indicates the capacity of the cache. The dnssec plugin uses a cache to store RRSIGs. The default for CAPACITY is 10000.

Metrics

If monitoring is enabled (via the prometheus directive) then the following metrics are exported:

  • coredns_dnssec_cache_size{type} - total elements in the cache, type is "signature".
  • coredns_dnssec_cache_capacity{type} - total capacity of the cache, type is "signature".
  • coredns_dnssec_cache_hits_total{} - Counter of cache hits.
  • coredns_dnssec_cache_misses_total{} - Counter of cache misses.

Examples

Sign responses for example.org with the key "Kexample.org.+013+45330.key".

example.org {
    dnssec {
        key file Kexample.org.+013+45330
    }
    whoami
}

Sign responses for a kubernetes zone with the key "Kcluster.local+013+45129.key".

cluster.local {
    kubernetes
    dnssec {
      key file Kcluster.local+013+45129
    }
}

Bugs

Multiple dnssec plugins inside one server stanza will silently overwrite earlier ones, here example.org will overwrite the one for cluster.local.

. {
    kubernetes cluster.local
    dnssec cluster.local {
      key file Kcluster.local+013+45129
    }
    dnssec example.org {
      key file Kexample.org.+013+45330
    }
}