README
¶
go-resolver
A Golang DNSSEC validating resolver library implemented on top of miekg/dns.
This package implements DNS lookup functions that perform DNSSEC validation.
Implementation
When querying DNSSEC enabled zones, it performs a full verification of the resource records (RRs) included in the response and validates the chain of trust:
- Requests the desired RRset (along with the corresponding
RRSIGrecord) - Requests the
DNSKEYrecords containing the public ZSK and public KSK (along with theRRSIGfor theDNSKEYRRset) - Performs the cryptographic verification of the
RRSIGof the requested RRset with the public ZSK - Performs the cryptographic verification of the
RRSIGof theDNSKEYRRset with the public KSK - Checks the validity period of the
RRSIGrecords
Following these cryptographic verifications, the package then validates the authentication chain by walking up the delegation chain, checking the public DNSKEY RRs against the DS records in each parent zone, up to the TLD zone. (For a more in-depth description of how DNSSEC works, see this guide.)
In case of any validation errors, the method returns a non-nil err value, and an empty result set.
goresolver does not yet implement denial of existence validation using NSEC or NSEC3 records.
Documentation
import "github.com/peterzen/goresolver"
result, err := resolver.StrictNSQuery("example.com.", dns.TypeMX)
if err != nil {
// handle validation errors
}
goresolver.LookupIP can be used as drop-in replacement to net.LookupIP:
import "github.com/peterzen/goresolver"
ips, err := goresolver.LookupIP("www.example.com")
if err != nil {
// handle validation errors
}
Installation
$ go get -u github.com/peterzen/goresolver
PRs for additional test cases covering less common DNSSEC setups are welcome and much appreciated.
More information
- DNS Security Introduction and Requirements RFC4033
Documentation
¶
Index ¶
- Constants
- Variables
- func NewDNSMessage() *dns.Msg
- type AuthenticationChain
- type RRSet
- type Resolver
- func (resolver *Resolver) LookupIP(qname string) (ips []net.IP, err error)
- func (resolver *Resolver) LookupIPType(qname string, qtype uint16) (ips []net.IP, err error)
- func (resolver *Resolver) LookupIPv4(qname string) (ips []net.IP, err error)
- func (resolver *Resolver) LookupIPv6(qname string) (ips []net.IP, err error)
- func (resolver *Resolver) StrictNSQuery(qname string, qtype uint16) (rrSet []dns.RR, err error)
- type SignedZone
Constants ¶
const (
DefaultTimeout = 5 * time.Second
)
const MaxReturnedIPAddressesCount = 64
Variables ¶
var ( ErrResourceNotSigned = errors.New("resource is not signed with RRSIG") ErrNoResult = errors.New("requested RR not found") ErrNsNotAvailable = errors.New("no name server to answer the question") ErrDnskeyNotAvailable = errors.New("DNSKEY RR does not exist") ErrDsNotAvailable = errors.New("DS RR does not exist") ErrInvalidRRsig = errors.New("invalid RRSIG") ErrRrsigValidationError = errors.New("RR doesn't validate against RRSIG") ErrRrsigValidityPeriod = errors.New("invalid RRSIG validity period") ErrUnknownDsDigestType = errors.New("unknown DS digest type") ErrDsInvalid = errors.New("DS RR does not match DNSKEY") ErrInvalidQuery = errors.New("invalid query input") )
Errors returned by the verification/validation methods at all levels.
Functions ¶
func NewDNSMessage ¶
NewDNSMessage creates and initializes a dns.Msg object, with EDNS enabled and the DO (DNSSEC OK) flag set. It returns a pointer to the created object.
Types ¶
type AuthenticationChain ¶
type AuthenticationChain struct {
// contains filtered or unexported fields
}
AuthenticationChain represents the DNSSEC chain of trust from the queried zone to the root (.) zone. In order for a zone to validate, it is required that each zone in the chain validate against its parent using the DS record.
https://www.ietf.org/rfc/rfc4033.txt
func NewAuthenticationChain ¶
func NewAuthenticationChain() *AuthenticationChain
NewAuthenticationChain initializes an AuthenticationChain object and returns a reference to it.
func (*AuthenticationChain) Populate ¶
func (authChain *AuthenticationChain) Populate(domainName string) error
Populate queries the RRs required for the zone validation It begins the queries at the *domainName* zone and then walks up the delegation tree all the way up to the root zone, thus populating a linked list of SignedZone objects.
func (*AuthenticationChain) Verify ¶
func (authChain *AuthenticationChain) Verify(answerRRset *RRSet) error
Verify uses the zone data in delegationChain to validate the DNSSEC chain of trust. It starts the verification in the RRSet supplied as parameter (verifies the RRSIG on the answer RRs), and, assuming a signature is correct and valid, it walks through the delegationChain checking the RRSIGs on the DNSKEY and DS resource record sets, as well as correctness of each delegation using the lower level methods in SignedZone.
type RRSet ¶
type RRSet struct {
// contains filtered or unexported fields
}
func NewSignedRRSet ¶
func NewSignedRRSet() *RRSet
func (*RRSet) SignerName ¶
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver contains the client configuration for github.com/miekg/dns, the instantiated client and the func that performs the actual queries. queryFn can be used for mocking the actual DNS lookups in the test suite.
func NewResolver ¶
NewResolver initializes the package Resolver instance using the default dnsClientConfig.
func (*Resolver) LookupIPType ¶
Queries an A or AAAA RR
func (*Resolver) LookupIPv4 ¶
func (*Resolver) LookupIPv6 ¶
type SignedZone ¶
type SignedZone struct {
// contains filtered or unexported fields
}
SignedZone represents a DNSSEC-enabled zone, its DNSKEY and DS records
func NewSignedZone ¶
func NewSignedZone(domainName string) *SignedZone
NewSignedZone initializes a new SignedZone and returns it.
Source Files
Directories