Documentation
¶
Overview ¶
Package dnssec implements DNSSEC validation per RFC 4033, 4034, 4035, and 5155.
This package provides cryptographic validation of DNS responses using DNSSEC signatures. It validates chains of trust from configured trust anchors down to target domains, verifies RRSIGs, and handles authenticated denial of existence (NSEC/NSEC3).
Example usage:
// Create trust anchor store
trustAnchors, err := dnssec.NewTrustAnchorStore(nil) // Uses default root anchors
if err != nil {
log.Fatal(err)
}
// Initialize:
validator := dnssec.NewValidator(
ctx,
trustAnchors,
logger,
upstream,
1, // cacheExpirationHours
10, // maxChainDepth
150, // maxNSEC3Iterations
30, // maxUpstreamQueries
3600, // clockSkewToleranceSec
)
// Validate a response
result := validator.ValidateResponse(ctx, response, question)
switch result {
case dnssec.ValidationResultSecure:
// Response is cryptographically validated
case dnssec.ValidationResultInsecure:
// Unsigned zone (no DNSSEC)
case dnssec.ValidationResultBogus:
// Invalid DNSSEC (should reject)
case dnssec.ValidationResultIndeterminate:
// Could not complete validation
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidValidationResult = fmt.Errorf("not a valid ValidationResult, try [%s]", strings.Join(_ValidationResultNames, ", "))
Functions ¶
func ValidationResultNames ¶
func ValidationResultNames() []string
ValidationResultNames returns a list of possible string values of ValidationResult.
func WithClientContext ¶ added in v0.32.0
func WithClientContext(ctx context.Context, ip net.IP, names []string, clientID string) context.Context
WithClientContext returns a context carrying the originating client's identity so DNSSEC auxiliary queries issued during validation preserve it. Called by the DNSSEC resolver before validating a response.
Types ¶
type Resolver ¶
type Resolver interface {
Resolve(ctx context.Context, request *model.Request) (*model.Response, error)
}
Resolver is the interface for DNS resolution (minimal interface to avoid import cycles)
type TrustAnchor ¶
TrustAnchor represents a DNSSEC trust anchor (DNSKEY record)
type TrustAnchorStore ¶
type TrustAnchorStore struct {
// contains filtered or unexported fields
}
TrustAnchorStore manages DNSSEC trust anchors
func NewTrustAnchorStore ¶
func NewTrustAnchorStore(customAnchors []string) (*TrustAnchorStore, error)
NewTrustAnchorStore creates a new trust anchor store with the given trust anchors.
If customAnchors is empty, the default root KSK trust anchors from IANA are used. Custom anchors should be DNSKEY records in zone file format, with the SEP (KSK) flag set.
Example anchor format:
". 172800 IN DNSKEY 257 3 8 AwEAAaz/tAm8yTn4Mfeh5eyI96WSVexTBAvk..."
Parameters:
- customAnchors: List of DNSKEY record strings to use as trust anchors (optional)
Returns a configured trust anchor store or an error if any anchor is invalid.
func (*TrustAnchorStore) AddTrustAnchor ¶
func (s *TrustAnchorStore) AddTrustAnchor(anchorStr string) error
AddTrustAnchor adds a trust anchor from a DNSKEY record string.
func (*TrustAnchorStore) GetRootTrustAnchors ¶
func (s *TrustAnchorStore) GetRootTrustAnchors() []*TrustAnchor
GetRootTrustAnchors returns trust anchors for the root zone
func (*TrustAnchorStore) GetTrustAnchors ¶
func (s *TrustAnchorStore) GetTrustAnchors(domain string) []*TrustAnchor
GetTrustAnchors returns trust anchors for a domain
func (*TrustAnchorStore) HasTrustAnchor ¶
func (s *TrustAnchorStore) HasTrustAnchor(domain string) bool
HasTrustAnchor returns true if the store has a trust anchor for the domain
type ValidationResult ¶
type ValidationResult int
ValidationResult represents the result of DNSSEC validation ENUM( Secure // Valid DNSSEC signatures and chain of trust Insecure // No DNSSEC (unsigned zone) Bogus // Invalid DNSSEC (failed validation) Indeterminate // Validation could not be completed )
const ( // ValidationResultSecure is a ValidationResult of type Secure. // Valid DNSSEC signatures and chain of trust ValidationResultSecure ValidationResult = iota // ValidationResultInsecure is a ValidationResult of type Insecure. // No DNSSEC (unsigned zone) ValidationResultInsecure // ValidationResultBogus is a ValidationResult of type Bogus. // Invalid DNSSEC (failed validation) ValidationResultBogus // ValidationResultIndeterminate is a ValidationResult of type Indeterminate. // Validation could not be completed ValidationResultIndeterminate )
func ParseValidationResult ¶
func ParseValidationResult(name string) (ValidationResult, error)
ParseValidationResult attempts to convert a string to a ValidationResult.
func ValidationResultValues ¶
func ValidationResultValues() []ValidationResult
ValidationResultValues returns a list of the values for ValidationResult
func (*ValidationResult) AppendText ¶
func (x *ValidationResult) AppendText(b []byte) ([]byte, error)
AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.
Implementations must not retain b, nor mutate any bytes within b[:len(b)].
func (ValidationResult) IsValid ¶
func (x ValidationResult) IsValid() bool
IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values
func (ValidationResult) MarshalText ¶
func (x ValidationResult) MarshalText() ([]byte, error)
MarshalText implements the text marshaller method.
func (ValidationResult) String ¶
func (x ValidationResult) String() string
String implements the Stringer interface.
func (*ValidationResult) UnmarshalText ¶
func (x *ValidationResult) UnmarshalText(text []byte) error
UnmarshalText implements the text unmarshaller method.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator validates DNSSEC signatures and chains of trust
func NewValidator ¶
func NewValidator( ctx context.Context, trustAnchors *TrustAnchorStore, logger *logrus.Entry, upstream Resolver, cacheExpirationHours uint, maxChainDepth uint, maxNSEC3Iterations uint, maxUpstreamQueries uint, clockSkewToleranceSec uint, ) *Validator
NewValidator creates a new DNSSEC validator with the given configuration.
Parameters:
- ctx: Context for the validator lifecycle (used for cache cleanup)
- trustAnchors: Trust anchor store containing root and/or zone-specific DNSSEC trust anchors
- logger: Logger for validation events and debugging
- upstream: Resolver to use for querying DNSKEY and DS records
- cacheExpirationHours: How long to cache validation results (0 defaults to 1 hour)
- maxChainDepth: Maximum domain label depth to validate (0 defaults to 10, prevents DoS)
- maxNSEC3Iterations: Maximum NSEC3 iterations (0 defaults to 150, prevents DoS)
- maxUpstreamQueries: Maximum upstream queries per validation (0 defaults to 30, prevents DoS)
- clockSkewToleranceSec: Clock skew tolerance in seconds (0 defaults to 3600 = 1 hour)
Returns a configured Validator ready for use.
func (*Validator) ValidateResponse ¶
func (v *Validator) ValidateResponse( ctx context.Context, response *dns.Msg, question dns.Question, ) ValidationResult
ValidateResponse validates a DNS response's DNSSEC signatures according to RFC 4035.
This function performs the following validation steps:
- Checks if the response contains DNSSEC signatures (RRSIG records)
- If unsigned, returns ValidationResultInsecure
- If signed, validates all RRsets in the answer section: - Verifies RRSIG signatures match the RRset data - Validates signature time windows (inception/expiration) - Walks the chain of trust from root to the domain - Verifies DNSKEYs against DS records or trust anchors
- Returns ValidationResultSecure if all checks pass
- Returns ValidationResultBogus if validation fails
Parameters:
- ctx: Context for the validation operation
- response: DNS response message to validate
- question: Original DNS question for context
Returns one of: ValidationResultSecure, ValidationResultInsecure, ValidationResultBogus, or ValidationResultIndeterminate
Source Files