dnssec

README

dnssec

Name

dnssec - enables 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.

This plugin can only be used once per Server Block.

Syntax

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

The signing behavior depends on the keys specified. If multiple keys are specified of which there is at least one key with the SEP bit set and at least one key with the SEP bit unset, signing will happen in split ZSK/KSK mode. DNSKEY records will be signed with all keys that have the SEP bit set. All other records will be signed with all keys that do not have the SEP bit set.

In any other case, each specified key will be treated as 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 in 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 plugin) then the following metrics are exported:

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

The label server indicated the server handling the request, see the metrics plugin for details.

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
    }
}

Documentation

Overview

Package dnssec implements a plugin that signs responses on-the-fly using NSEC black lies.

Index

• type DNSKEY
  • func ParseKeyFile(pubFile, privFile string) (*DNSKEY, error)
• type Dnssec
  • func New(zones []string, keys []*DNSKEY, splitkeys bool, next plugin.Handler, ...) Dnssec
  • func (d Dnssec) Name() string
  • func (d Dnssec) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (d Dnssec) Sign(state request.Request, now time.Time, server string) *dns.Msg
• type ResponseWriter
  • func (d *ResponseWriter) Write(buf []byte) (int, error)
  • func (d *ResponseWriter) WriteMsg(res *dns.Msg) error

Types

type DNSKEY

type DNSKEY struct {
	K *dns.DNSKEY
	D *dns.DS
	// contains filtered or unexported fields
}

DNSKEY holds a DNSSEC public and private key used for on-the-fly signing.

func ParseKeyFile

func ParseKeyFile(pubFile, privFile string) (*DNSKEY, error)

ParseKeyFile read a DNSSEC keyfile as generated by dnssec-keygen or other utilities. It adds ".key" for the public key and ".private" for the private key.

type Dnssec

type Dnssec struct {
	Next plugin.Handler
	// contains filtered or unexported fields
}

Dnssec signs the reply on-the-fly.

func New

func New(zones []string, keys []*DNSKEY, splitkeys bool, next plugin.Handler, c *cache.Cache) Dnssec

New returns a new Dnssec.

func (Dnssec) Name

func (d Dnssec) Name() string

Name implements the Handler interface.

func (Dnssec) ServeDNS

func (d Dnssec) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the plugin.Handler interface.

func (Dnssec) Sign

func (d Dnssec) Sign(state request.Request, now time.Time, server string) *dns.Msg

Sign signs the message in state. it takes care of negative or nodata responses. It uses NSEC black lies for authenticated denial of existence. For delegations it will insert DS records and sign those. Signatures will be cached for a short while. By default we sign for 8 days, starting 3 hours ago.

type ResponseWriter

type ResponseWriter struct {
	dns.ResponseWriter
	// contains filtered or unexported fields
}

ResponseWriter signs the response on the fly.

func (*ResponseWriter) Write

func (d *ResponseWriter) Write(buf []byte) (int, error)

Write implements the dns.ResponseWriter interface.

func (*ResponseWriter) WriteMsg

func (d *ResponseWriter) WriteMsg(res *dns.Msg) error

WriteMsg implements the dns.ResponseWriter interface.