...

Package dnsmessage

import "vendor/golang.org/x/net/dns/dnsmessage"
Overview
Index

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 ▾

Variables
type AAAAResource
    func (r *AAAAResource) GoString() string
type AResource
    func (r *AResource) GoString() string
type Builder
    func NewBuilder(buf []byte, h Header) Builder
    func (b *Builder) AAAAResource(h ResourceHeader, r AAAAResource) error
    func (b *Builder) AResource(h ResourceHeader, r AResource) error
    func (b *Builder) CNAMEResource(h ResourceHeader, r CNAMEResource) error
    func (b *Builder) EnableCompression()
    func (b *Builder) Finish() ([]byte, error)
    func (b *Builder) MXResource(h ResourceHeader, r MXResource) error
    func (b *Builder) NSResource(h ResourceHeader, r NSResource) error
    func (b *Builder) OPTResource(h ResourceHeader, r OPTResource) error
    func (b *Builder) PTRResource(h ResourceHeader, r PTRResource) error
    func (b *Builder) Question(q Question) error
    func (b *Builder) SOAResource(h ResourceHeader, r SOAResource) error
    func (b *Builder) SRVResource(h ResourceHeader, r SRVResource) error
    func (b *Builder) StartAdditionals() error
    func (b *Builder) StartAnswers() error
    func (b *Builder) StartAuthorities() error
    func (b *Builder) StartQuestions() error
    func (b *Builder) TXTResource(h ResourceHeader, r TXTResource) error
    func (b *Builder) UnknownResource(h ResourceHeader, r UnknownResource) error
type CNAMEResource
    func (r *CNAMEResource) GoString() string
type Class
    func (c Class) GoString() string
    func (c Class) String() string
type Header
    func (m *Header) GoString() string
type MXResource
    func (r *MXResource) GoString() string
type Message
    func (m *Message) AppendPack(b []byte) ([]byte, error)
    func (m *Message) GoString() string
    func (m *Message) Pack() ([]byte, error)
    func (m *Message) Unpack(msg []byte) error
type NSResource
    func (r *NSResource) GoString() string
type Name
    func MustNewName(name string) Name
    func NewName(name string) (Name, error)
    func (n *Name) GoString() string
    func (n Name) String() string
type OPTResource
    func (r *OPTResource) GoString() string
type OpCode
    func (o OpCode) GoString() string
type Option
    func (o *Option) GoString() string
type PTRResource
    func (r *PTRResource) GoString() string
type Parser
    func (p *Parser) AAAAResource() (AAAAResource, error)
    func (p *Parser) AResource() (AResource, error)
    func (p *Parser) Additional() (Resource, error)
    func (p *Parser) AdditionalHeader() (ResourceHeader, error)
    func (p *Parser) AllAdditionals() ([]Resource, error)
    func (p *Parser) AllAnswers() ([]Resource, error)
    func (p *Parser) AllAuthorities() ([]Resource, error)
    func (p *Parser) AllQuestions() ([]Question, error)
    func (p *Parser) Answer() (Resource, error)
    func (p *Parser) AnswerHeader() (ResourceHeader, error)
    func (p *Parser) Authority() (Resource, error)
    func (p *Parser) AuthorityHeader() (ResourceHeader, error)
    func (p *Parser) CNAMEResource() (CNAMEResource, error)
    func (p *Parser) MXResource() (MXResource, error)
    func (p *Parser) NSResource() (NSResource, error)
    func (p *Parser) OPTResource() (OPTResource, error)
    func (p *Parser) PTRResource() (PTRResource, error)
    func (p *Parser) Question() (Question, error)
    func (p *Parser) SOAResource() (SOAResource, error)
    func (p *Parser) SRVResource() (SRVResource, error)
    func (p *Parser) SkipAdditional() error
    func (p *Parser) SkipAllAdditionals() error
    func (p *Parser) SkipAllAnswers() error
    func (p *Parser) SkipAllAuthorities() error
    func (p *Parser) SkipAllQuestions() error
    func (p *Parser) SkipAnswer() error
    func (p *Parser) SkipAuthority() error
    func (p *Parser) SkipQuestion() error
    func (p *Parser) Start(msg []byte) (Header, error)
    func (p *Parser) TXTResource() (TXTResource, error)
    func (p *Parser) UnknownResource() (UnknownResource, error)
type Question
    func (q *Question) GoString() string
type RCode
    func (r RCode) GoString() string
    func (r RCode) String() string
type Resource
    func (r *Resource) GoString() string
type ResourceBody
type ResourceHeader
    func (h *ResourceHeader) DNSSECAllowed() bool
    func (h *ResourceHeader) ExtendedRCode(rcode RCode) RCode
    func (h *ResourceHeader) GoString() string
    func (h *ResourceHeader) SetEDNS0(udpPayloadLen int, extRCode RCode, dnssecOK bool) error
type SOAResource
    func (r *SOAResource) GoString() string
type SRVResource
    func (r *SRVResource) GoString() string
type TXTResource
    func (r *TXTResource) GoString() string
type Type
    func (t Type) GoString() string
    func (t Type) String() string
type UnknownResource
    func (r *UnknownResource) GoString() string

Package files

message.go

Variables

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")
)

type AAAAResource

An AAAAResource is an AAAA Resource record.

type AAAAResource struct {
    AAAA [16]byte
}

func (*AAAAResource) GoString

func (r *AAAAResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type AResource

An AResource is an A Resource record.

type AResource struct {
    A [4]byte
}

func (*AResource) GoString

func (r *AResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Builder

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.
type Builder struct {
    // contains filtered or unexported fields
}

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

A CNAMEResource is a CNAME Resource record.

type CNAMEResource struct {
    CNAME Name
}

func (*CNAMEResource) GoString

func (r *CNAMEResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Class

A Class is a type of network.

type Class uint16
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.

Header is a representation of a DNS message header.

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

func (*Header) GoString

func (m *Header) GoString() string

GoString implements fmt.GoStringer.GoString.

type MXResource

An MXResource is an MX Resource record.

type MXResource struct {
    Pref uint16
    MX   Name
}

func (*MXResource) GoString

func (r *MXResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Message

Message is a representation of a DNS message.

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

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

An NSResource is an NS Resource record.

type NSResource struct {
    NS Name
}

func (*NSResource) GoString

func (r *NSResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Name

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

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

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

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.

type OPTResource struct {
    Options []Option
}

func (*OPTResource) GoString

func (r *OPTResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type OpCode

An OpCode is a DNS operation code.

type OpCode uint16

func (OpCode) GoString

func (o OpCode) GoString() string

GoString implements fmt.GoStringer.GoString.

type Option

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.

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

func (*Option) GoString

func (o *Option) GoString() string

GoString implements fmt.GoStringer.GoString.

type PTRResource

A PTRResource is a PTR Resource record.

type PTRResource struct {
    PTR Name
}

func (*PTRResource) GoString

func (r *PTRResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Parser

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.

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

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

A Question is a DNS query.

type Question struct {
    Name  Name
    Type  Type
    Class Class
}

func (*Question) GoString

func (q *Question) GoString() string

GoString implements fmt.GoStringer.GoString.

type RCode

An RCode is a DNS response status code.

type RCode uint16

Header.RCode values.

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
)

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

A Resource is a DNS resource record.

type Resource struct {
    Header ResourceHeader
    Body   ResourceBody
}

func (*Resource) GoString

func (r *Resource) GoString() string

type ResourceBody

A ResourceBody is a DNS resource record minus the header.

type ResourceBody interface {

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

type ResourceHeader

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.

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
}

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

An SOAResource is an SOA Resource record.

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
}

func (*SOAResource) GoString

func (r *SOAResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type SRVResource

An SRVResource is an SRV Resource record.

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

func (*SRVResource) GoString

func (r *SRVResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type TXTResource

A TXTResource is a TXT Resource record.

type TXTResource struct {
    TXT []string
}

func (*TXTResource) GoString

func (r *TXTResource) GoString() string

GoString implements fmt.GoStringer.GoString.

type Type

A Type is a type of DNS request and response.

type Type uint16
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

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

type UnknownResource struct {
    Type Type
    Data []byte
}

func (*UnknownResource) GoString

func (r *UnknownResource) GoString() string

GoString implements fmt.GoStringer.GoString.