dnsmessage

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2024 License: BSD-3-Clause Imports: 1 Imported by: 880

Documentation

Overview

Package dnsmessage provides a mostly RFC 1035 compliant implementation of DNS message packing and unpacking.

The package also supports messages with Extension Mechanisms for DNS (EDNS(0)) as defined in RFC 6891.

This implementation is designed to minimize heap allocations and avoid unnecessary packing and unpacking as much as possible.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotStarted indicates that the prerequisite information isn't
	// available yet because the previous records haven't been appropriately
	// parsed, skipped or finished.
	ErrNotStarted = errors.New("parsing/packing of this type isn't available yet")

	// ErrSectionDone indicated that all records in the section have been
	// parsed or finished.
	ErrSectionDone = errors.New("parsing/packing of this section has completed")
)

Functions

This section is empty.

Types

type AAAAResource 

type AAAAResource struct {
	AAAA [16]byte
}

An AAAAResource is an AAAA Resource record.

func (*AAAAResource) GoString 

func (r *AAAAResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type AResource 

type AResource struct {
	A [4]byte
}

An AResource is an A Resource record.

func (*AResource) GoString 

func (r *AResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

A Builder allows incrementally packing a DNS message.

Example usage: 

buf := make([]byte, 2, 514)
b := NewBuilder(buf, Header{...})
b.EnableCompression()
// Optionally start a section and add things to that section.
// Repeat adding sections as necessary.
buf, err := b.Finish()
// If err is nil, buf[2:] will contain the built bytes.

func NewBuilder 

func NewBuilder(buf []byte, h Header) Builder

NewBuilder creates a new builder with compression disabled.

Note: Most users will want to immediately enable compression with the EnableCompression method. See that method's comment for why you may or may not want to enable compression.

The DNS message is appended to the provided initial buffer buf (which may be nil) as it is built. The final message is returned by the (*Builder).Finish method, which includes buf[:len(buf)] and may return the same underlying array if there was sufficient capacity in the slice.

func (*Builder) AAAAResource 

func (b *Builder) AAAAResource(h ResourceHeader, r AAAAResource) error

AAAAResource adds a single AAAAResource.

func (*Builder) AResource 

func (b *Builder) AResource(h ResourceHeader, r AResource) error

AResource adds a single AResource.

func (*Builder) CNAMEResource 

func (b *Builder) CNAMEResource(h ResourceHeader, r CNAMEResource) error

CNAMEResource adds a single CNAMEResource.

func (*Builder) EnableCompression 

func (b *Builder) EnableCompression()

EnableCompression enables compression in the Builder.

Leaving compression disabled avoids compression related allocations, but can result in larger message sizes. Be careful with this mode as it can cause messages to exceed the UDP size limit.

According to RFC 1035, section 4.1.4, the use of compression is optional, but all implementations must accept both compressed and uncompressed DNS messages.

Compression should be enabled before any sections are added for best results.

func (*Builder) Finish 

func (b *Builder) Finish() ([]byte, error)

Finish ends message building and generates a binary message.

func (*Builder) MXResource 

func (b *Builder) MXResource(h ResourceHeader, r MXResource) error

MXResource adds a single MXResource.

func (*Builder) NSResource 

func (b *Builder) NSResource(h ResourceHeader, r NSResource) error

NSResource adds a single NSResource.

func (*Builder) OPTResource 

func (b *Builder) OPTResource(h ResourceHeader, r OPTResource) error

OPTResource adds a single OPTResource.

func (*Builder) PTRResource 

func (b *Builder) PTRResource(h ResourceHeader, r PTRResource) error

PTRResource adds a single PTRResource.

func (*Builder) Question 

func (b *Builder) Question(q Question) error

Question adds a single Question.

func (*Builder) SOAResource 

func (b *Builder) SOAResource(h ResourceHeader, r SOAResource) error

SOAResource adds a single SOAResource.

func (*Builder) SRVResource 

func (b *Builder) SRVResource(h ResourceHeader, r SRVResource) error

SRVResource adds a single SRVResource.

func (*Builder) StartAdditionals 

func (b *Builder) StartAdditionals() error

StartAdditionals prepares the builder for packing Additionals.

func (*Builder) StartAnswers 

func (b *Builder) StartAnswers() error

StartAnswers prepares the builder for packing Answers.

func (*Builder) StartAuthorities 

func (b *Builder) StartAuthorities() error

StartAuthorities prepares the builder for packing Authorities.

func (*Builder) StartQuestions 

func (b *Builder) StartQuestions() error

StartQuestions prepares the builder for packing Questions.

func (*Builder) TXTResource 

func (b *Builder) TXTResource(h ResourceHeader, r TXTResource) error

TXTResource adds a single TXTResource.

func (*Builder) UnknownResource 

func (b *Builder) UnknownResource(h ResourceHeader, r UnknownResource) error

UnknownResource adds a single UnknownResource.

type CNAMEResource 

type CNAMEResource struct {
	CNAME Name
}

A CNAMEResource is a CNAME Resource record.

func (*CNAMEResource) GoString 

func (r *CNAMEResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Class 

type Class uint16

A Class is a type of network. 

const (
	// ResourceHeader.Class and Question.Class
	ClassINET   Class = 1
	ClassCSNET  Class = 2
	ClassCHAOS  Class = 3
	ClassHESIOD Class = 4

	// Question.Class
	ClassANY Class = 255
)

func (Class) GoString 

func (c Class) GoString() string

GoString implements fmt.GoStringer.GoString.

func (Class) String 

func (c Class) String() string

String implements fmt.Stringer.String. 

type Header struct {
	ID                 uint16
	Response           bool
	OpCode             OpCode
	Authoritative      bool
	Truncated          bool
	RecursionDesired   bool
	RecursionAvailable bool
	AuthenticData      bool
	CheckingDisabled   bool
	RCode              RCode
}

Header is a representation of a DNS message header.

func (*Header) GoString 

func (m *Header) GoString() string

GoString implements fmt.GoStringer.GoString.

type MXResource 

type MXResource struct {
	Pref uint16
	MX   Name
}

An MXResource is an MX Resource record.

func (*MXResource) GoString 

func (r *MXResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Message 

type Message struct {
	Header
	Questions   []Question
	Answers     []Resource
	Authorities []Resource
	Additionals []Resource
}

Message is a representation of a DNS message.

func (*Message) AppendPack 

func (m *Message) AppendPack(b []byte) ([]byte, error)

AppendPack is like Pack but appends the full Message to b and returns the extended buffer.

func (*Message) GoString 

func (m *Message) GoString() string

GoString implements fmt.GoStringer.GoString.

func (*Message) Pack 

func (m *Message) Pack() ([]byte, error)

Pack packs a full Message.

func (*Message) Unpack 

func (m *Message) Unpack(msg []byte) error

Unpack parses a full Message.

type NSResource 

type NSResource struct {
	NS Name
}

An NSResource is an NS Resource record.

func (*NSResource) GoString 

func (r *NSResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Name 

type Name struct {
	Data   [255]byte
	Length uint8
}

A Name is a non-encoded and non-escaped domain name. It is used instead of strings to avoid allocations.

func MustNewName 

func MustNewName(name string) Name

MustNewName creates a new Name from a string and panics on error.

func NewName 

func NewName(name string) (Name, error)

NewName creates a new Name from a string.

func (*Name) GoString 

func (n *Name) GoString() string

GoString implements fmt.GoStringer.GoString.

func (Name) String 

func (n Name) String() string

String implements fmt.Stringer.String.

Note: characters inside the labels are not escaped in any way.

type OPTResource 

type OPTResource struct {
	Options []Option
}

An OPTResource is an OPT pseudo Resource record.

The pseudo resource record is part of the extension mechanisms for DNS as defined in RFC 6891.

func (*OPTResource) GoString 

func (r *OPTResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type OpCode 

type OpCode uint16

An OpCode is a DNS operation code.

func (OpCode) GoString 

func (o OpCode) GoString() string

GoString implements fmt.GoStringer.GoString.

type Option 

type Option struct {
	Code uint16 // option code
	Data []byte
}

An Option represents a DNS message option within OPTResource.

The message option is part of the extension mechanisms for DNS as defined in RFC 6891.

func (*Option) GoString 

func (o *Option) GoString() string

GoString implements fmt.GoStringer.GoString.

type PTRResource 

type PTRResource struct {
	PTR Name
}

A PTRResource is a PTR Resource record.

func (*PTRResource) GoString 

func (r *PTRResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Parser 

type Parser struct {
	// contains filtered or unexported fields
}

A Parser allows incrementally parsing a DNS message.

When parsing is started, the Header is parsed. Next, each Question can be either parsed or skipped. Alternatively, all Questions can be skipped at once. When all Questions have been parsed, attempting to parse Questions will return the ErrSectionDone error. After all Questions have been either parsed or skipped, all Answers, Authorities and Additionals can be either parsed or skipped in the same way, and each type of Resource must be fully parsed or skipped before proceeding to the next type of Resource.

Parser is safe to copy to preserve the parsing state.

Note that there is no requirement to fully skip or parse the message.

Example 
package main

import (
	"fmt"
	"net"
	"strings"

	"golang.org/x/net/dns/dnsmessage"
)

func main() {
	msg := dnsmessage.Message{
		Header: dnsmessage.Header{Response: true, Authoritative: true},
		Questions: []dnsmessage.Question{
			{
				Name:  dnsmessage.MustNewName("foo.bar.example.com."),
				Type:  dnsmessage.TypeA,
				Class: dnsmessage.ClassINET,
			},
			{
				Name:  dnsmessage.MustNewName("bar.example.com."),
				Type:  dnsmessage.TypeA,
				Class: dnsmessage.ClassINET,
			},
		},
		Answers: []dnsmessage.Resource{
			{
				Header: dnsmessage.ResourceHeader{
					Name:  dnsmessage.MustNewName("foo.bar.example.com."),
					Type:  dnsmessage.TypeA,
					Class: dnsmessage.ClassINET,
				},
				Body: &dnsmessage.AResource{A: [4]byte{127, 0, 0, 1}},
			},
			{
				Header: dnsmessage.ResourceHeader{
					Name:  dnsmessage.MustNewName("bar.example.com."),
					Type:  dnsmessage.TypeA,
					Class: dnsmessage.ClassINET,
				},
				Body: &dnsmessage.AResource{A: [4]byte{127, 0, 0, 2}},
			},
		},
	}

	buf, err := msg.Pack()
	if err != nil {
		panic(err)
	}

	wantName := "bar.example.com."

	var p dnsmessage.Parser
	if _, err := p.Start(buf); err != nil {
		panic(err)
	}

	for {
		q, err := p.Question()
		if err == dnsmessage.ErrSectionDone {
			break
		}
		if err != nil {
			panic(err)
		}

		if q.Name.String() != wantName {
			continue
		}

		fmt.Println("Found question for name", wantName)
		if err := p.SkipAllQuestions(); err != nil {
			panic(err)
		}
		break
	}

	var gotIPs []net.IP
	for {
		h, err := p.AnswerHeader()
		if err == dnsmessage.ErrSectionDone {
			break
		}
		if err != nil {
			panic(err)
		}

		if (h.Type != dnsmessage.TypeA && h.Type != dnsmessage.TypeAAAA) || h.Class != dnsmessage.ClassINET {
			continue
		}

		if !strings.EqualFold(h.Name.String(), wantName) {
			if err := p.SkipAnswer(); err != nil {
				panic(err)
			}
			continue
		}

		switch h.Type {
		case dnsmessage.TypeA:
			r, err := p.AResource()
			if err != nil {
				panic(err)
			}
			gotIPs = append(gotIPs, r.A[:])
		case dnsmessage.TypeAAAA:
			r, err := p.AAAAResource()
			if err != nil {
				panic(err)
			}
			gotIPs = append(gotIPs, r.AAAA[:])
		}
	}

	fmt.Printf("Found A/AAAA records for name %s: %v\n", wantName, gotIPs)

}

Output:

Found question for name bar.example.com.
Found A/AAAA records for name bar.example.com.: [127.0.0.2]

func (*Parser) AAAAResource 

func (p *Parser) AAAAResource() (AAAAResource, error)

AAAAResource parses a single AAAAResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) AResource 

func (p *Parser) AResource() (AResource, error)

AResource parses a single AResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) Additional 

func (p *Parser) Additional() (Resource, error)

Additional parses a single Additional Resource.

func (*Parser) AdditionalHeader 

func (p *Parser) AdditionalHeader() (ResourceHeader, error)

AdditionalHeader parses a single Additional ResourceHeader.

func (*Parser) AllAdditionals 

func (p *Parser) AllAdditionals() ([]Resource, error)

AllAdditionals parses all Additional Resources.

func (*Parser) AllAnswers 

func (p *Parser) AllAnswers() ([]Resource, error)

AllAnswers parses all Answer Resources.

func (*Parser) AllAuthorities 

func (p *Parser) AllAuthorities() ([]Resource, error)

AllAuthorities parses all Authority Resources.

func (*Parser) AllQuestions 

func (p *Parser) AllQuestions() ([]Question, error)

AllQuestions parses all Questions.

func (*Parser) Answer 

func (p *Parser) Answer() (Resource, error)

Answer parses a single Answer Resource.

func (*Parser) AnswerHeader 

func (p *Parser) AnswerHeader() (ResourceHeader, error)

AnswerHeader parses a single Answer ResourceHeader.

func (*Parser) Authority 

func (p *Parser) Authority() (Resource, error)

Authority parses a single Authority Resource.

func (*Parser) AuthorityHeader 

func (p *Parser) AuthorityHeader() (ResourceHeader, error)

AuthorityHeader parses a single Authority ResourceHeader.

func (*Parser) CNAMEResource 

func (p *Parser) CNAMEResource() (CNAMEResource, error)

CNAMEResource parses a single CNAMEResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) MXResource 

func (p *Parser) MXResource() (MXResource, error)

MXResource parses a single MXResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) NSResource 

func (p *Parser) NSResource() (NSResource, error)

NSResource parses a single NSResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) OPTResource 

func (p *Parser) OPTResource() (OPTResource, error)

OPTResource parses a single OPTResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) PTRResource 

func (p *Parser) PTRResource() (PTRResource, error)

PTRResource parses a single PTRResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) Question 

func (p *Parser) Question() (Question, error)

Question parses a single Question.

func (*Parser) SOAResource 

func (p *Parser) SOAResource() (SOAResource, error)

SOAResource parses a single SOAResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) SRVResource 

func (p *Parser) SRVResource() (SRVResource, error)

SRVResource parses a single SRVResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) SkipAdditional 

func (p *Parser) SkipAdditional() error

SkipAdditional skips a single Additional Resource.

It does not perform a complete validation of the resource header, which means it may return a nil error when the [AdditionalHeader] would actually return an error.

func (*Parser) SkipAllAdditionals 

func (p *Parser) SkipAllAdditionals() error

SkipAllAdditionals skips all Additional Resources.

func (*Parser) SkipAllAnswers 

func (p *Parser) SkipAllAnswers() error

SkipAllAnswers skips all Answer Resources.

func (*Parser) SkipAllAuthorities 

func (p *Parser) SkipAllAuthorities() error

SkipAllAuthorities skips all Authority Resources.

func (*Parser) SkipAllQuestions 

func (p *Parser) SkipAllQuestions() error

SkipAllQuestions skips all Questions.

func (*Parser) SkipAnswer 

func (p *Parser) SkipAnswer() error

SkipAnswer skips a single Answer Resource.

It does not perform a complete validation of the resource header, which means it may return a nil error when the [AnswerHeader] would actually return an error.

func (*Parser) SkipAuthority 

func (p *Parser) SkipAuthority() error

SkipAuthority skips a single Authority Resource.

It does not perform a complete validation of the resource header, which means it may return a nil error when the [AuthorityHeader] would actually return an error.

func (*Parser) SkipQuestion 

func (p *Parser) SkipQuestion() error

SkipQuestion skips a single Question.

func (*Parser) Start 

func (p *Parser) Start(msg []byte) (Header, error)

Start parses the header and enables the parsing of Questions.

func (*Parser) TXTResource 

func (p *Parser) TXTResource() (TXTResource, error)

TXTResource parses a single TXTResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) UnknownResource 

func (p *Parser) UnknownResource() (UnknownResource, error)

UnknownResource parses a single UnknownResource.

One of the XXXHeader methods must have been called before calling this method.

type Question 

type Question struct {
	Name  Name
	Type  Type
	Class Class
}

A Question is a DNS query.

func (*Question) GoString 

func (q *Question) GoString() string

GoString implements fmt.GoStringer.GoString.

type RCode 

type RCode uint16

An RCode is a DNS response status code. 

const (
	RCodeSuccess        RCode = 0 // NoError
	RCodeFormatError    RCode = 1 // FormErr
	RCodeServerFailure  RCode = 2 // ServFail
	RCodeNameError      RCode = 3 // NXDomain
	RCodeNotImplemented RCode = 4 // NotImp
	RCodeRefused        RCode = 5 // Refused
)

Header.RCode values.

func (RCode) GoString 

func (r RCode) GoString() string

GoString implements fmt.GoStringer.GoString.

func (RCode) String 

func (r RCode) String() string

String implements fmt.Stringer.String.

type Resource 

type Resource struct {
	Header ResourceHeader
	Body   ResourceBody
}

A Resource is a DNS resource record.

func (*Resource) GoString 

func (r *Resource) GoString() string

type ResourceBody 

type ResourceBody interface {

	// GoString implements fmt.GoStringer.GoString.
	GoString() string
	// contains filtered or unexported methods
}

A ResourceBody is a DNS resource record minus the header.

type ResourceHeader 

type ResourceHeader struct {
	// Name is the domain name for which this resource record pertains.
	Name Name

	// Type is the type of DNS resource record.
	//
	// This field will be set automatically during packing.
	Type Type

	// Class is the class of network to which this DNS resource record
	// pertains.
	Class Class

	// TTL is the length of time (measured in seconds) which this resource
	// record is valid for (time to live). All Resources in a set should
	// have the same TTL (RFC 2181 Section 5.2).
	TTL uint32

	// Length is the length of data in the resource record after the header.
	//
	// This field will be set automatically during packing.
	Length uint16
}

A ResourceHeader is the header of a DNS resource record. There are many types of DNS resource records, but they all share the same header.

func (*ResourceHeader) DNSSECAllowed 

func (h *ResourceHeader) DNSSECAllowed() bool

DNSSECAllowed reports whether the DNSSEC OK bit is set.

func (*ResourceHeader) ExtendedRCode 

func (h *ResourceHeader) ExtendedRCode(rcode RCode) RCode

ExtendedRCode returns an extended RCode.

The provided rcode must be the RCode in DNS message header.

func (*ResourceHeader) GoString 

func (h *ResourceHeader) GoString() string

GoString implements fmt.GoStringer.GoString.

func (*ResourceHeader) SetEDNS0 

func (h *ResourceHeader) SetEDNS0(udpPayloadLen int, extRCode RCode, dnssecOK bool) error

SetEDNS0 configures h for EDNS(0).

The provided extRCode must be an extended RCode.

type SOAResource 

type SOAResource struct {
	NS      Name
	MBox    Name
	Serial  uint32
	Refresh uint32
	Retry   uint32
	Expire  uint32

	// MinTTL the is the default TTL of Resources records which did not
	// contain a TTL value and the TTL of negative responses. (RFC 2308
	// Section 4)
	MinTTL uint32
}

An SOAResource is an SOA Resource record.

func (*SOAResource) GoString 

func (r *SOAResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type SRVResource 

type SRVResource struct {
	Priority uint16
	Weight   uint16
	Port     uint16
	Target   Name // Not compressed as per RFC 2782.
}

An SRVResource is an SRV Resource record.

func (*SRVResource) GoString 

func (r *SRVResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type TXTResource 

type TXTResource struct {
	TXT []string
}

A TXTResource is a TXT Resource record.

func (*TXTResource) GoString 

func (r *TXTResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Type 

type Type uint16

A Type is a type of DNS request and response. 

const (
	// ResourceHeader.Type and Question.Type
	TypeA     Type = 1
	TypeNS    Type = 2
	TypeCNAME Type = 5
	TypeSOA   Type = 6
	TypePTR   Type = 12
	TypeMX    Type = 15
	TypeTXT   Type = 16
	TypeAAAA  Type = 28
	TypeSRV   Type = 33
	TypeOPT   Type = 41

	// Question.Type
	TypeWKS   Type = 11
	TypeHINFO Type = 13
	TypeMINFO Type = 14
	TypeAXFR  Type = 252
	TypeALL   Type = 255
)

func (Type) GoString 

func (t Type) GoString() string

GoString implements fmt.GoStringer.GoString.

func (Type) String 

func (t Type) String() string

String implements fmt.Stringer.String.

type UnknownResource 

type UnknownResource struct {
	Type Type
	Data []byte
}

An UnknownResource is a catch-all container for unknown record types.

func (*UnknownResource) GoString 

func (r *UnknownResource) GoString() string

GoString implements fmt.GoStringer.GoString.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.